Skip to content

Commit 3c54508

Browse files
authored
Support soft hyphen (U+00AD) rendering with a Hyphens API (flutter#185152)
## Summary Adds visible soft hyphen (U+00AD) rendering at line breaks, with a new `Hyphens` API to opt out. Fixes flutter#18443 on native platforms; web rendering is tracked in flutter#193506. A line break that falls on a soft hyphen now renders a visible `-` by default. A new `Hyphens { manual, hidden }` enum controls this: - `Hyphens.manual` (default): render a hyphen at the break. - `Hyphens.hidden`: don't render the hyphen. The soft hyphen is still a break opportunity. `hyphens` is a parameter on `Text` / `RichText`, `TextPainter`, `RenderParagraph`, `TextStyle.getParagraphStyle` and `dart:ui`'s `ParagraphStyle`, following `textAlign` / `maxLines`. It is not a `TextStyle` field. Customizing the hyphen string is deferred to flutter#189617. Design doc: [flutter.dev/go/soft-hyphens](https://flutter.dev/go/soft-hyphens) (tracking issue flutter#185154). ## Background Flutter already breaks lines at U+00AD but never draws the hyphen, so it behaves like a zero-width space. This change doesn't add any new break opportunities or change where lines break, but the rendered hyphen makes its line wider, so it can change `Paragraph.longestLine` and the size of text laid out with `TextWidthBasis.longestLine`. The Skia side landed in [`98daf58d`](google/skia@98daf58d4c) (Skia CL [1208837](https://skia-review.googlesource.com/c/skia/+/1208837)), behind `ParagraphStyle::setRenderSoftHyphens(bool)`, which defaults to `false` for other Skia clients. ## Changes **Engine** - `txt::ParagraphStyle` gains a `render_soft_hyphens` flag (default `true`), which `ParagraphBuilderSkia::TxtToSkia` forwards to `setRenderSoftHyphens`. The Impeller interop toolkit builds `txt::ParagraphStyle` too, so it also gets the new default. - `paragraph_builder.cc` decodes `ParagraphStyle.hyphens` from the FFI buffer (mask bit 13, slot 7). - `dart:ui` adds the public `Hyphens` enum and `ParagraphStyle.hyphens`. The web `dart:ui` accepts and stores the value; web rendering is flutter#193506. **Framework** - `Hyphens` is re-exported from `dart:ui` via `painting/basic_types.dart`. - `hyphens` is threaded through `TextStyle.getParagraphStyle` → `TextPainter` → `RenderParagraph` → `RichText` → `Text` / `Text.rich`, including the selectable-text path. ## Breaking change - **API:** adding `hyphens` to `TextStyle.getParagraphStyle` breaks classes that override it. In practice that's test doubles like the `_TextStyleProxy` in `test/material/theme_test.dart`, updated here; material_ui's copy was removed in flutter/packages#12728. The fix is to add `Hyphens? hyphens` to the override. Migration guide: flutter/website#13945. - **Rendering:** text containing U+00AD now shows a hyphen at soft-hyphen line breaks by default. `Hyphens.hidden` restores the old look. ## Known limitations - The hyphen is appended after line breaking, so a line can exceed `maxWidth` by the hyphen's advance. - The rendered hyphen isn't included in selection highlight rects (flutter#189234). - `EditableText` (and so `TextField`) and `SelectableText` don't take a `hyphens` parameter yet, so they always render the hyphen. - Skia also draws the hyphen when a line ends in U+00AD without breaking there (text ending in U+00AD, or U+00AD right before a space or newline). The Skia fix is in review ([CL 1378356](https://skia-review.googlesource.com/c/skia/+/1378356)) and will come in with a Skia roll once it lands. ## Test plan - [ ] `paragraph_builder_skia_tests.cc::RenderSoftHyphensEnabled`: `render_soft_hyphens` maps onto Skia in both states - [ ] `testing/dart/text_test.dart`: `ParagraphStyle.hyphens` encodes and round-trips in `toString` - [ ] `testing/dart/paragraph_test.dart`: `ParagraphStyle.hyphens` reaches the text layout (a line that breaks at a soft hyphen is wider with `manual` than with `hidden`, and unset matches `manual`), which covers decoding the setting in the engine - [ ] `test/widgets/rich_text_test.dart`: `RichText` exposes `hyphens` via `debugFillProperties` - [ ] `test/widgets/text_test.dart`: `Text` forwards `hyphens` to `RenderParagraph` (incl. selectable path); default resolves to `Hyphens.manual` - [ ] `test/rendering/paragraph_test.dart`: `RenderParagraph.hyphens` setter triggers relayout - [ ] `test/painting/text_painter_test.dart`: `TextPainter.hyphens` setter; the same width check through `TextPainter`, and changing `hyphens` after layout changes the width - [ ] Google internal testing - [ ] Manual smoke: `Text('inter\u00ADnational')` in a narrow container shows `inter-` / `national`
1 parent fbb2851 commit 3c54508

28 files changed

Lines changed: 337 additions & 18 deletions

‎engine/src/flutter/lib/ui/text.dart‎

Lines changed: 29 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1327,6 +1327,20 @@ enum TextAlign {
13271327
end,
13281328
}
13291329

1330+
/// The behavior of soft hyphens (U+00AD) at a line break.
1331+
///
1332+
/// This does not change where lines break, since Flutter always treats U+00AD
1333+
/// as a line-break opportunity.
1334+
enum Hyphens {
1335+
/// A hyphen glyph is rendered at the end of a line that breaks on a soft
1336+
/// hyphen (U+00AD). Soft hyphens elsewhere remain invisible.
1337+
manual,
1338+
1339+
/// No hyphen glyph is rendered for soft hyphens. The line still breaks at
1340+
/// U+00AD; only the glyph is suppressed.
1341+
hidden,
1342+
}
1343+
13301344
/// A horizontal line used for aligning text.
13311345
enum TextBaseline {
13321346
/// The horizontal line used to align the bottom of glyphs for alphabetic characters.
@@ -1937,6 +1951,8 @@ class TextStyle {
19371951
//
19381952
// - Element 6: The encoded value of |textHeightBehavior|, except its leading
19391953
// distribution.
1954+
//
1955+
// - Element 7: The enum index of the |hyphens|.
19401956
Int32List _encodeParagraphStyle(
19411957
TextAlign? textAlign,
19421958
TextDirection? textDirection,
@@ -1950,8 +1966,9 @@ Int32List _encodeParagraphStyle(
19501966
StrutStyle? strutStyle,
19511967
String? ellipsis,
19521968
Locale? locale,
1969+
Hyphens? hyphens,
19531970
) {
1954-
final result = Int32List(7); // also update paragraph_builder.cc
1971+
final result = Int32List(8); // also update paragraph_builder.cc
19551972
if (textAlign != null) {
19561973
result[0] |= 1 << 1;
19571974
result[1] = textAlign.index;
@@ -2002,6 +2019,10 @@ Int32List _encodeParagraphStyle(
20022019
result[0] |= 1 << 12;
20032020
// Passed separately to native.
20042021
}
2022+
if (hyphens != null) {
2023+
result[0] |= 1 << 13;
2024+
result[7] = hyphens.index;
2025+
}
20052026
return result;
20062027
}
20072028

@@ -2068,6 +2089,9 @@ class ParagraphStyle {
20682089
/// considered equivalent and turn off this behavior.
20692090
///
20702091
/// * `locale`: The locale used to select region-specific glyphs.
2092+
///
2093+
/// * `hyphens`: Whether to render a hyphen glyph for soft hyphens (U+00AD)
2094+
/// that fall at a line break. Defaults to [Hyphens.manual].
20712095
ParagraphStyle({
20722096
TextAlign? textAlign,
20732097
TextDirection? textDirection,
@@ -2081,6 +2105,7 @@ class ParagraphStyle {
20812105
StrutStyle? strutStyle,
20822106
String? ellipsis,
20832107
Locale? locale,
2108+
Hyphens? hyphens,
20842109
}) : _encoded = _encodeParagraphStyle(
20852110
textAlign,
20862111
textDirection,
@@ -2094,6 +2119,7 @@ class ParagraphStyle {
20942119
strutStyle,
20952120
ellipsis,
20962121
locale,
2122+
hyphens,
20972123
),
20982124
_fontFamily = fontFamily,
20992125
_fontSize = fontSize,
@@ -2157,7 +2183,8 @@ class ParagraphStyle {
21572183
'height: ${_encoded[0] & 0x200 == 0x200 ? "${_height}x" : "unspecified"}, '
21582184
'strutStyle: ${_encoded[0] & 0x400 == 0x400 ? _strutStyle : "unspecified"}, '
21592185
'ellipsis: ${_encoded[0] & 0x800 == 0x800 ? '"$_ellipsis"' : "unspecified"}, '
2160-
'locale: ${_encoded[0] & 0x1000 == 0x1000 ? _locale : "unspecified"}'
2186+
'locale: ${_encoded[0] & 0x1000 == 0x1000 ? _locale : "unspecified"}, '
2187+
'hyphens: ${_encoded[0] & 0x2000 == 0x2000 ? Hyphens.values[_encoded[7]] : "unspecified"}'
21612188
')';
21622189
}
21632190
}

‎engine/src/flutter/lib/ui/text/paragraph_builder.cc‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -90,6 +90,11 @@ const int kPSHeightIndex = 9;
9090
const int kPSStrutStyleIndex = 10;
9191
const int kPSEllipsisIndex = 11;
9292
const int kPSLocaleIndex = 12;
93+
// render_soft_hyphens is the first field whose mask bit and encode slot differ:
94+
// it claims the next free mask bit (13), but stores its value in the next free
95+
// encode slot (7), since slots 7-12 are reused only as mask-bit positions.
96+
const int kPSRenderSoftHyphensIndex = 13;
97+
const int kPSRenderSoftHyphensEncodeIndex = 7;
9398

9499
const int kPSTextAlignMask = 1 << kPSTextAlignIndex;
95100
const int kPSTextDirectionMask = 1 << kPSTextDirectionIndex;
@@ -103,6 +108,7 @@ const int kPSTextHeightBehaviorMask = 1 << kPSTextHeightBehaviorIndex;
103108
const int kPSStrutStyleMask = 1 << kPSStrutStyleIndex;
104109
const int kPSEllipsisMask = 1 << kPSEllipsisIndex;
105110
const int kPSLocaleMask = 1 << kPSLocaleIndex;
111+
const int kPSRenderSoftHyphensMask = 1 << kPSRenderSoftHyphensIndex;
106112

107113
// TextShadows decoding
108114

@@ -273,6 +279,12 @@ ParagraphBuilder::ParagraphBuilder(
273279
if (mask & kPSMaxLinesMask) {
274280
style.max_lines = encoded[kPSMaxLinesIndex];
275281
}
282+
283+
if (mask & kPSRenderSoftHyphensMask) {
284+
// Hyphens.manual (0) renders the soft hyphen glyph; Hyphens.hidden (1)
285+
// suppresses it.
286+
style.render_soft_hyphens = encoded[kPSRenderSoftHyphensEncodeIndex] == 0;
287+
}
276288
}
277289

278290
if (mask & kPSStrutStyleMask) {

‎engine/src/flutter/lib/web_ui/lib/src/engine/canvaskit/renderer.dart‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -412,6 +412,7 @@ class CanvasKitRenderer extends Renderer {
412412
ui.StrutStyle? strutStyle,
413413
String? ellipsis,
414414
ui.Locale? locale,
415+
ui.Hyphens? hyphens,
415416
}) => isWebParagraphEnabled
416417
? WebParagraphStyle(
417418
textAlign: textAlign,
@@ -426,6 +427,7 @@ class CanvasKitRenderer extends Renderer {
426427
strutStyle: strutStyle as WebStrutStyle?,
427428
ellipsis: ellipsis,
428429
locale: locale,
430+
hyphens: hyphens,
429431
)
430432
: CkParagraphStyle(
431433
textAlign: textAlign,
@@ -440,6 +442,7 @@ class CanvasKitRenderer extends Renderer {
440442
strutStyle: strutStyle,
441443
ellipsis: ellipsis,
442444
locale: locale,
445+
hyphens: hyphens,
443446
);
444447

445448
@override

‎engine/src/flutter/lib/web_ui/lib/src/engine/canvaskit/text.dart‎

Lines changed: 16 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -33,6 +33,7 @@ class CkParagraphStyle implements ui.ParagraphStyle {
3333
ui.StrutStyle? strutStyle,
3434
String? ellipsis,
3535
ui.Locale? locale,
36+
ui.Hyphens? hyphens,
3637
}) : skParagraphStyle = toSkParagraphStyle(
3738
textAlign,
3839
textDirection,
@@ -59,7 +60,8 @@ class CkParagraphStyle implements ui.ParagraphStyle {
5960
_textHeightBehavior = textHeightBehavior,
6061
_strutStyle = strutStyle,
6162
_ellipsis = ellipsis,
62-
_locale = locale;
63+
_locale = locale,
64+
_hyphens = hyphens;
6365

6466
final SkParagraphStyle skParagraphStyle;
6567

@@ -76,6 +78,14 @@ class CkParagraphStyle implements ui.ParagraphStyle {
7678
final ui.StrutStyle? _strutStyle;
7779
final String? _ellipsis;
7880
final ui.Locale? _locale;
81+
// TODO(dbebawy): hyphens is accepted and stored but not honored here yet.
82+
// Neither Hyphens.manual nor Hyphens.hidden takes effect on CanvasKit until a
83+
// renderSoftHyphens setter is exposed on the CanvasKit ParagraphStyle binding
84+
// (the native engine wires this via SkParagraph::setRenderSoftHyphens).
85+
// https://github.com/flutter/flutter/issues/193506
86+
// Customizing the hyphen string is separate future work:
87+
// https://github.com/flutter/flutter/issues/189617
88+
final ui.Hyphens? _hyphens;
7989

8090
static SkTextStyleProperties toSkTextStyleProperties(
8191
String? fontFamily,
@@ -263,7 +273,8 @@ class CkParagraphStyle implements ui.ParagraphStyle {
263273
other._textHeightBehavior == _textHeightBehavior &&
264274
other._strutStyle == _strutStyle &&
265275
other._ellipsis == _ellipsis &&
266-
other._locale == _locale;
276+
other._locale == _locale &&
277+
other._hyphens == _hyphens;
267278
}
268279

269280
@override
@@ -282,6 +293,7 @@ class CkParagraphStyle implements ui.ParagraphStyle {
282293
_strutStyle,
283294
_ellipsis,
284295
_locale,
296+
_hyphens,
285297
);
286298
}
287299

@@ -304,7 +316,8 @@ class CkParagraphStyle implements ui.ParagraphStyle {
304316
'height: ${height != null ? "${height.toStringAsFixed(1)}x" : "unspecified"}, '
305317
'strutStyle: ${_strutStyle ?? "unspecified"}, '
306318
'ellipsis: ${_ellipsis != null ? '"$_ellipsis"' : "unspecified"}, '
307-
'locale: ${_locale ?? "unspecified"}'
319+
'locale: ${_locale ?? "unspecified"}, '
320+
'hyphens: ${_hyphens ?? "unspecified"}'
308321
')';
309322
return true;
310323
}());

‎engine/src/flutter/lib/web_ui/lib/src/engine/renderer.dart‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -389,6 +389,7 @@ abstract class Renderer {
389389
ui.StrutStyle? strutStyle,
390390
String? ellipsis,
391391
ui.Locale? locale,
392+
ui.Hyphens? hyphens,
392393
});
393394

394395
ui.StrutStyle createStrutStyle({

‎engine/src/flutter/lib/web_ui/lib/src/engine/skwasm/skwasm_impl/paragraph.dart‎

Lines changed: 16 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -746,6 +746,7 @@ class SkwasmParagraphStyle implements ui.ParagraphStyle {
746746
ui.StrutStyle? strutStyle,
747747
String? ellipsis,
748748
ui.Locale? locale,
749+
ui.Hyphens? hyphens,
749750
}) : _textAlign = textAlign,
750751
_textDirection = textDirection,
751752
_maxLines = maxLines,
@@ -757,7 +758,8 @@ class SkwasmParagraphStyle implements ui.ParagraphStyle {
757758
_fontStyle = fontStyle,
758759
_strutStyle = strutStyle,
759760
_ellipsis = ellipsis,
760-
_locale = locale;
761+
_locale = locale,
762+
_hyphens = hyphens;
761763

762764
(ParagraphStyleHandle, SkwasmNativeTextStyle) createNative() {
763765
final ParagraphStyleHandle handle = paragraphStyleCreate();
@@ -855,6 +857,14 @@ class SkwasmParagraphStyle implements ui.ParagraphStyle {
855857
final ui.StrutStyle? _strutStyle;
856858
final String? _ellipsis;
857859
final ui.Locale? _locale;
860+
// TODO(dbebawy): hyphens is accepted and stored but not honored here yet.
861+
// Neither Hyphens.manual nor Hyphens.hidden takes effect on Skwasm until a
862+
// renderSoftHyphens setter is exposed on the Skwasm ParagraphStyle binding
863+
// (the native engine wires this via SkParagraph::setRenderSoftHyphens).
864+
// https://github.com/flutter/flutter/issues/193506
865+
// Customizing the hyphen string is separate future work:
866+
// https://github.com/flutter/flutter/issues/189617
867+
final ui.Hyphens? _hyphens;
858868

859869
@override
860870
bool operator ==(Object other) {
@@ -876,7 +886,8 @@ class SkwasmParagraphStyle implements ui.ParagraphStyle {
876886
other._textHeightBehavior == _textHeightBehavior &&
877887
other._strutStyle == _strutStyle &&
878888
other._ellipsis == _ellipsis &&
879-
other._locale == _locale;
889+
other._locale == _locale &&
890+
other._hyphens == _hyphens;
880891
}
881892

882893
@override
@@ -894,6 +905,7 @@ class SkwasmParagraphStyle implements ui.ParagraphStyle {
894905
_strutStyle,
895906
_ellipsis,
896907
_locale,
908+
_hyphens,
897909
);
898910
}
899911

@@ -916,7 +928,8 @@ class SkwasmParagraphStyle implements ui.ParagraphStyle {
916928
'height: ${height != null ? "${height.toStringAsFixed(1)}x" : "unspecified"}, '
917929
'strutStyle: ${_strutStyle ?? "unspecified"}, '
918930
'ellipsis: ${_ellipsis != null ? '"$_ellipsis"' : "unspecified"}, '
919-
'locale: ${_locale ?? "unspecified"}'
931+
'locale: ${_locale ?? "unspecified"}, '
932+
'hyphens: ${_hyphens ?? "unspecified"}'
920933
')';
921934
return true;
922935
}());

‎engine/src/flutter/lib/web_ui/lib/src/engine/skwasm/skwasm_impl/renderer.dart‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -178,6 +178,7 @@ class SkwasmRenderer extends Renderer {
178178
ui.StrutStyle? strutStyle,
179179
String? ellipsis,
180180
ui.Locale? locale,
181+
ui.Hyphens? hyphens,
181182
}) => SkwasmParagraphStyle(
182183
textAlign: textAlign,
183184
textDirection: textDirection,
@@ -191,6 +192,7 @@ class SkwasmRenderer extends Renderer {
191192
strutStyle: strutStyle,
192193
ellipsis: ellipsis,
193194
locale: locale,
195+
hyphens: hyphens,
194196
);
195197

196198
@override

‎engine/src/flutter/lib/web_ui/lib/src/engine/skwasm/skwasm_stub/renderer.dart‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -162,6 +162,7 @@ class SkwasmRenderer extends Renderer {
162162
ui.StrutStyle? strutStyle,
163163
String? ellipsis,
164164
ui.Locale? locale,
165+
ui.Hyphens? hyphens,
165166
}) {
166167
throw UnimplementedError('Skwasm not implemented on this platform.');
167168
}

‎engine/src/flutter/lib/web_ui/lib/src/engine/web_paragraph/paragraph.dart‎

Lines changed: 10 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -36,6 +36,7 @@ class WebParagraphStyle implements ui.ParagraphStyle {
3636
ui.Color? color,
3737
ui.StrutStyle? strutStyle,
3838
this.textHeightBehavior,
39+
this.hyphens,
3940
}) : _strutStyle = strutStyle as WebStrutStyle?,
4041
_textStyle = WebTextStyle(
4142
fontFamily: fontFamily,
@@ -60,6 +61,11 @@ class WebParagraphStyle implements ui.ParagraphStyle {
6061

6162
final ui.TextHeightBehavior? textHeightBehavior;
6263

64+
// TODO(dbebawy): honor hyphens in the pure-Dart line-breaker/painter (no
65+
// soft-hyphen glyph emitted at a break yet). Accepted and stored for now.
66+
// https://github.com/flutter/flutter/issues/193506
67+
final ui.Hyphens? hyphens;
68+
6369
WebStrutStyle? get strutStyle => _strutStyle;
6470
final WebStrutStyle? _strutStyle;
6571

@@ -78,7 +84,8 @@ class WebParagraphStyle implements ui.ParagraphStyle {
7884
ellipsis == other.ellipsis &&
7985
textHeightBehavior == other.textHeightBehavior &&
8086
_strutStyle == other._strutStyle &&
81-
_textStyle == other._textStyle;
87+
_textStyle == other._textStyle &&
88+
hyphens == other.hyphens;
8289
}
8390

8491
@override
@@ -91,6 +98,7 @@ class WebParagraphStyle implements ui.ParagraphStyle {
9198
textHeightBehavior,
9299
_strutStyle,
93100
_textStyle,
101+
hyphens,
94102
);
95103
}
96104

@@ -105,6 +113,7 @@ class WebParagraphStyle implements ui.ParagraphStyle {
105113
'maxLines: $maxLines, '
106114
'ellipsis: $ellipsis, '
107115
'textHeightBehavior: $textHeightBehavior, '
116+
'hyphens: $hyphens, '
108117
'strutStyle: $_strutStyle, '
109118
'textAlign: $textAlign'
110119
'textStyle: $_textStyle'

‎engine/src/flutter/lib/web_ui/lib/text.dart‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -381,6 +381,7 @@ abstract class ParagraphStyle {
381381
StrutStyle? strutStyle,
382382
String? ellipsis,
383383
Locale? locale,
384+
Hyphens? hyphens,
384385
}) => engine.renderer.createParagraphStyle(
385386
textAlign: textAlign,
386387
textDirection: textDirection,
@@ -394,6 +395,7 @@ abstract class ParagraphStyle {
394395
strutStyle: strutStyle,
395396
ellipsis: ellipsis,
396397
locale: locale,
398+
hyphens: hyphens,
397399
);
398400
}
399401

@@ -459,6 +461,9 @@ abstract class StrutStyle {
459461
// The order of this enum must match the order of the values in TextDirection.h's TextDirection.
460462
enum TextDirection { rtl, ltr }
461463

464+
/// The behavior of soft hyphens (U+00AD) at a line break.
465+
enum Hyphens { manual, hidden }
466+
462467
class TextBox {
463468
const TextBox.fromLTRBD(this.left, this.top, this.right, this.bottom, this.direction);
464469
final double left;

0 commit comments

Comments
 (0)