Skip to content

Commit bfb0f31

Browse files
committed
Add breaking change page for the soft hyphen character
Adds a breaking change page for flutter/flutter#196152, which adds a hyphenCharacter parameter to TextStyle.getParagraphStyle.
1 parent 3667d0e commit bfb0f31

2 files changed

Lines changed: 125 additions & 0 deletions

File tree

‎sites/docs/src/content/release/breaking-changes/index.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -41,6 +41,7 @@ They're sorted by release and listed in alphabetical order:
4141
* [Restrict Android engine flags in release mode][]
4242
* [Soft hyphens render at line breaks][]
4343
* [Stricter Android `Intent` verification for app entrypoints][]
44+
* [TextStyle.getParagraphStyle has a new hyphenCharacter parameter][]
4445
* [Web `viewport-fit=cover` `SafeArea` support][]
4546
* [WidgetSpan order in right-to-left text][]
4647

@@ -49,6 +50,7 @@ They're sorted by release and listed in alphabetical order:
4950
[Restrict Android engine flags in release mode]: /release/breaking-changes/restrict-android-engine-flags-release-mode
5051
[Soft hyphens render at line breaks]: /release/breaking-changes/soft-hyphen-rendering
5152
[Stricter Android `Intent` verification for app entrypoints]: /release/breaking-changes/stricter-android-entrypoint-intent-verification
53+
[TextStyle.getParagraphStyle has a new hyphenCharacter parameter]: /release/breaking-changes/soft-hyphen-character
5254
[Web `viewport-fit=cover` `SafeArea` support]: /release/breaking-changes/viewport-fit-cover-safe-area
5355
[WidgetSpan order in right-to-left text]: /release/breaking-changes/widgetspan-rtl-bidi-order
5456

Lines changed: 123 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,123 @@
1+
---
2+
title: TextStyle.getParagraphStyle has a new hyphenCharacter parameter
3+
description: >-
4+
Apps can choose the string drawn at a soft hyphen line break,
5+
and classes that override TextStyle.getParagraphStyle
6+
must accept a new hyphenCharacter parameter.
7+
---
8+
9+
{% render "docs/breaking-changes.md" %}
10+
11+
## Summary
12+
13+
A new `hyphenCharacter` parameter chooses the string drawn
14+
at the end of a line that breaks at a soft hyphen (U+00AD).
15+
[`TextStyle.getParagraphStyle`][] has the new parameter,
16+
so classes that override `getParagraphStyle` must add it.
17+
Rendering doesn't change unless you set the parameter.
18+
19+
## Background
20+
21+
When a line breaks at a soft hyphen,
22+
Flutter draws a hyphen-minus ("-") at the end of the line,
23+
as described in [Soft hyphens render at line breaks][].
24+
Some languages and designs need a different string there,
25+
such as a Unicode hyphen (U+2010) or nothing at all.
26+
27+
The new `hyphenCharacter` parameter on [`Text`][], [`RichText`][],
28+
[`TextPainter`][], and `dart:ui`'s [`ParagraphStyle`][]
29+
takes the string to draw:
30+
31+
* `null` (the default) draws a hyphen-minus, as before.
32+
* A non-empty string is drawn instead.
33+
Line breaking leaves room for it,
34+
so a longer string can move a break earlier.
35+
* The empty string draws nothing,
36+
but the line still breaks at the soft hyphen.
37+
38+
The string is shaped in the style of the text before it,
39+
so keep it short and make sure that text's font supports it.
40+
It has no effect when `hyphens` is `Hyphens.hidden`.
41+
Widgets built on `EditableText`, such as `TextField` and `SelectableText`,
42+
don't have a `hyphenCharacter` parameter yet.
43+
44+
`TextStyle.getParagraphStyle` gained an optional
45+
`hyphenCharacter` parameter.
46+
Because Dart requires an override to accept every parameter
47+
of the method it overrides, a class that overrides `getParagraphStyle`
48+
no longer compiles until it adds the parameter.
49+
This mostly affects test doubles and proxies of `TextStyle`,
50+
not typical app code.
51+
52+
## Migration guide
53+
54+
If you override `TextStyle.getParagraphStyle`, add the new parameter.
55+
56+
Code before migration:
57+
58+
```dart
59+
@override
60+
ui.ParagraphStyle getParagraphStyle({
61+
TextAlign? textAlign,
62+
// ...
63+
Hyphens? hyphens,
64+
Locale? locale,
65+
// ...other parameters...
66+
}) {
67+
// ...
68+
}
69+
```
70+
71+
Code after migration:
72+
73+
```dart
74+
@override
75+
ui.ParagraphStyle getParagraphStyle({
76+
TextAlign? textAlign,
77+
// ...
78+
Hyphens? hyphens,
79+
String? hyphenCharacter,
80+
Locale? locale,
81+
// ...other parameters...
82+
}) {
83+
// ...
84+
}
85+
```
86+
87+
If your override forwards to another `getParagraphStyle`
88+
or constructs a `ParagraphStyle`, pass `hyphenCharacter` through.
89+
Otherwise, accepting and ignoring the parameter is enough.
90+
91+
## Timeline
92+
93+
Landed in version: Not yet<br>
94+
In stable release: Not yet
95+
96+
## References
97+
98+
API documentation:
99+
100+
* [`ParagraphStyle`][]
101+
* [`RichText`][]
102+
* [`Text`][]
103+
* [`TextPainter`][]
104+
* [`TextStyle.getParagraphStyle`][]
105+
106+
Relevant issues:
107+
108+
* [Support customizing the soft-hyphen character/string][issue-189617]
109+
110+
Relevant PRs:
111+
112+
* [Add ParagraphStyle.hyphenCharacter to dart:ui][pr-195345]
113+
* [Add hyphenCharacter to TextPainter, RenderParagraph, RichText and Text][pr-196152]
114+
115+
[Soft hyphens render at line breaks]: /release/breaking-changes/soft-hyphen-rendering
116+
[`ParagraphStyle`]: {{site.api}}/flutter/dart-ui/ParagraphStyle-class.html
117+
[`RichText`]: {{site.api}}/flutter/widgets/RichText-class.html
118+
[`Text`]: {{site.api}}/flutter/widgets/Text-class.html
119+
[`TextPainter`]: {{site.api}}/flutter/painting/TextPainter-class.html
120+
[`TextStyle.getParagraphStyle`]: {{site.api}}/flutter/painting/TextStyle/getParagraphStyle.html
121+
[issue-189617]: {{site.repo.flutter}}/issues/189617
122+
[pr-195345]: {{site.repo.flutter}}/pull/195345
123+
[pr-196152]: {{site.repo.flutter}}/pull/196152

0 commit comments

Comments
 (0)