From 0bca44cf8d9bbb2d7793f21650885fca2b825820 Mon Sep 17 00:00:00 2001 From: Justin McCandless Date: Fri, 25 Sep 2020 16:06:32 -0700 Subject: [PATCH] Update docs about complex character support (#66582) Simple docs fix for characters. --- .../flutter/lib/src/cupertino/text_field.dart | 27 +-------------- .../flutter/lib/src/material/text_field.dart | 27 +-------------- .../lib/src/services/text_formatter.dart | 33 ++++++++++--------- 3 files changed, 20 insertions(+), 67 deletions(-) diff --git a/packages/flutter/lib/src/cupertino/text_field.dart b/packages/flutter/lib/src/cupertino/text_field.dart index e1e7e787a0f..53ed766043f 100644 --- a/packages/flutter/lib/src/cupertino/text_field.dart +++ b/packages/flutter/lib/src/cupertino/text_field.dart @@ -482,32 +482,7 @@ class CupertinoTextField extends StatefulWidget { /// Whitespace characters (e.g. newline, space, tab) are included in the /// character count. /// - /// ## Limitations - /// - /// The CupertinoTextField does not currently count Unicode grapheme clusters - /// (i.e. characters visible to the user), it counts Unicode scalar values, - /// which leaves out a number of useful possible characters (like many emoji - /// and composed characters), so this will be inaccurate in the presence of - /// those characters. If you expect to encounter these kinds of characters, be - /// generous in the maxLength used. - /// - /// For instance, the character "ΓΆ" can be represented as '\u{006F}\u{0308}', - /// which is the letter "o" followed by a composed diaeresis "Β¨", or it can - /// be represented as '\u{00F6}', which is the Unicode scalar value "LATIN - /// SMALL LETTER O WITH DIAERESIS". In the first case, the text field will - /// count two characters, and the second case will be counted as one - /// character, even though the user can see no difference in the input. - /// - /// Similarly, some emoji are represented by multiple scalar values. The - /// Unicode "THUMBS UP SIGN + MEDIUM SKIN TONE MODIFIER", "πŸ‘πŸ½", should be - /// counted as a single character, but because it is a combination of two - /// Unicode scalar values, '\u{1F44D}\u{1F3FD}', it is counted as two - /// characters. - /// - /// See also: - /// - /// * [LengthLimitingTextInputFormatter] for more information on how it - /// counts characters, and how it may differ from the intuitive meaning. + /// {@macro flutter.services.lengthLimitingTextInputFormatter.maxLength} final int? maxLength; /// If true, prevents the field from allowing more than [maxLength] diff --git a/packages/flutter/lib/src/material/text_field.dart b/packages/flutter/lib/src/material/text_field.dart index 20649766407..d4d1d686dcd 100644 --- a/packages/flutter/lib/src/material/text_field.dart +++ b/packages/flutter/lib/src/material/text_field.dart @@ -578,32 +578,7 @@ class TextField extends StatefulWidget { /// to the [decoration]'s [InputDecoration.errorStyle] when the limit is /// exceeded. /// - /// ## Limitations - /// - /// The text field does not currently count Unicode grapheme clusters (i.e. - /// characters visible to the user), it counts Unicode scalar values, which - /// leaves out a number of useful possible characters (like many emoji and - /// composed characters), so this will be inaccurate in the presence of those - /// characters. If you expect to encounter these kinds of characters, be - /// generous in the maxLength used. - /// - /// For instance, the character "ΓΆ" can be represented as '\u{006F}\u{0308}', - /// which is the letter "o" followed by a composed diaeresis "Β¨", or it can - /// be represented as '\u{00F6}', which is the Unicode scalar value "LATIN - /// SMALL LETTER O WITH DIAERESIS". In the first case, the text field will - /// count two characters, and the second case will be counted as one - /// character, even though the user can see no difference in the input. - /// - /// Similarly, some emoji are represented by multiple scalar values. The - /// Unicode "THUMBS UP SIGN + MEDIUM SKIN TONE MODIFIER", "πŸ‘πŸ½", should be - /// counted as a single character, but because it is a combination of two - /// Unicode scalar values, '\u{1F44D}\u{1F3FD}', it is counted as two - /// characters. - /// - /// See also: - /// - /// * [LengthLimitingTextInputFormatter] for more information on how it - /// counts characters, and how it may differ from the intuitive meaning. + /// {@macro flutter.services.lengthLimitingTextInputFormatter.maxLength} final int maxLength; /// If true, prevents the field from allowing more than [maxLength] diff --git a/packages/flutter/lib/src/services/text_formatter.dart b/packages/flutter/lib/src/services/text_formatter.dart index f4aec42e24d..03a0078a074 100644 --- a/packages/flutter/lib/src/services/text_formatter.dart +++ b/packages/flutter/lib/src/services/text_formatter.dart @@ -316,31 +316,33 @@ class LengthLimitingTextInputFormatter extends TextInputFormatter { LengthLimitingTextInputFormatter(this.maxLength) : assert(maxLength == null || maxLength == -1 || maxLength > 0); - /// The limit on the number of characters (i.e. Unicode scalar values) this formatter + /// The limit on the number of user-perceived characters that this formatter /// will allow. /// /// The value must be null or greater than zero. If it is null or -1, then no /// limit is enforced. /// - /// This formatter does not currently count Unicode grapheme clusters (i.e. - /// characters visible to the user), it counts Unicode scalar values, which leaves - /// out a number of useful possible characters (like many emoji and composed - /// characters), so this will be inaccurate in the presence of those - /// characters. If you expect to encounter these kinds of characters, be - /// generous in the maxLength used. + /// {@template flutter.services.lengthLimitingTextInputFormatter.maxLength} + /// ## Characters + /// + /// For a specific definition of what is considered a character, see the + /// [characters](https://pub.dev/packages/characters) package on Pub, which is + /// what Flutter uses to delineate characters. In general, even complex + /// characters like surrogate pairs and extended grapheme clusters are + /// correctly interpreted by Flutter as each being a single user-perceived + /// character. /// /// For instance, the character "ΓΆ" can be represented as '\u{006F}\u{0308}', /// which is the letter "o" followed by a composed diaeresis "Β¨", or it can /// be represented as '\u{00F6}', which is the Unicode scalar value "LATIN - /// SMALL LETTER O WITH DIAERESIS". In the first case, the text field will - /// count two characters, and the second case will be counted as one - /// character, even though the user can see no difference in the input. + /// SMALL LETTER O WITH DIAERESIS". It will be counted as a single character + /// in both cases. /// /// Similarly, some emoji are represented by multiple scalar values. The - /// Unicode "THUMBS UP SIGN + MEDIUM SKIN TONE MODIFIER", "πŸ‘πŸ½", should be - /// counted as a single character, but because it is a combination of two - /// Unicode scalar values, '\u{1F44D}\u{1F3FD}', it is counted as two - /// characters. + /// Unicode "THUMBS UP SIGN + MEDIUM SKIN TONE MODIFIER", "πŸ‘πŸ½"is counted as + /// a single character, even though it is a combination of two Unicode scalar + /// values, '\u{1F44D}\u{1F3FD}'. + /// {@endtemplate} /// /// ### Composing text behaviors /// @@ -352,7 +354,8 @@ class LengthLimitingTextInputFormatter extends TextInputFormatter { /// composing is not allowed. final int? maxLength; - /// Truncate the given TextEditingValue to maxLength characters. + /// Truncate the given TextEditingValue to maxLength user-perceived + /// characters. /// /// See also: /// * [Dart's characters package](https://pub.dev/packages/characters).