From 48f2770e4e8854e046f659e96c4257d4e4190dcd Mon Sep 17 00:00:00 2001 From: Adam Barth Date: Mon, 1 May 2017 12:18:30 -0700 Subject: [PATCH] Add missing docs (#9696) --- .../lib/src/services/text_formatter.dart | 97 ++++++++++--------- 1 file changed, 51 insertions(+), 46 deletions(-) diff --git a/packages/flutter/lib/src/services/text_formatter.dart b/packages/flutter/lib/src/services/text_formatter.dart index 77773ab2eb..e8887d5f10 100644 --- a/packages/flutter/lib/src/services/text_formatter.dart +++ b/packages/flutter/lib/src/services/text_formatter.dart @@ -4,23 +4,23 @@ import 'package:flutter/services.dart'; -/// A [TextInputFormatter] can be optionally injected into an [EditableText] +/// A [TextInputFormatter] can be optionally injected into an [EditableText] /// to provide as-you-type validation and formatting of the text being edited. -/// +/// /// Text modification should only be applied when text is being committed by the -/// IME and not on text under composition (i.e. when -/// [TextEditingValue.composing] is collapsed). -/// -/// Concrete implementations [BlacklistingTextInputFormatter], which removes -/// blacklisted characters upon edit commit, and +/// IME and not on text under composition (i.e., only when +/// [TextEditingValue.composing] is collapsed). +/// +/// Concrete implementations [BlacklistingTextInputFormatter], which removes +/// blacklisted characters upon edit commit, and /// [WhitelistingTextInputFormatter], which only allows entries of whitelisted -/// characters, are provided. -/// -/// To create custom formatters, extend the [TextInputFormatter] class and +/// characters, are provided. +/// +/// To create custom formatters, extend the [TextInputFormatter] class and /// implement the [formatEditUpdate] method. -/// +/// /// See also: -/// +/// /// * [EditableText] on which the formatting apply. /// * [BlacklistingTextInputFormatter], a provided formatter for blacklisting /// characters. @@ -28,14 +28,14 @@ import 'package:flutter/services.dart'; /// characters. abstract class TextInputFormatter { /// Called when text is being typed or cut/copy/pasted in the [EditableText]. - /// + /// /// You can override the resulting text based on the previous text value and /// the incoming new text value. - /// + /// /// When formatters are chained, `oldValue` reflects the initial value of /// [TextEditingValue] at the beginning of the chain. TextEditingValue formatEditUpdate( - TextEditingValue oldValue, + TextEditingValue oldValue, TextEditingValue newValue ); @@ -48,50 +48,52 @@ abstract class TextInputFormatter { } } -/// Function signature expected for creating custom [TextInputFormatter] +/// Function signature expected for creating custom [TextInputFormatter] /// shorthands via [TextInputFormatter.withFunction]; typedef TextEditingValue TextInputFormatFunction( - TextEditingValue oldValue, + TextEditingValue oldValue, TextEditingValue newValue, ); /// Wiring for [TextInputFormatter.withFunction]. class _SimpleTextInputFormatter extends TextInputFormatter { - _SimpleTextInputFormatter(this.formatFunction) : + _SimpleTextInputFormatter(this.formatFunction) : assert(formatFunction != null); final TextInputFormatFunction formatFunction; - + @override TextEditingValue formatEditUpdate( - TextEditingValue oldValue, + TextEditingValue oldValue, TextEditingValue newValue ) { return formatFunction(oldValue, newValue); } } -/// A [TextInputFormatter] that prevents the insertion of blacklisted +/// A [TextInputFormatter] that prevents the insertion of blacklisted /// characters patterns. -/// -/// Instances of blacklisted characters found in the new [TextEditingValue]s -/// will be replaced with the [replacementString] which defaults to ``. -/// +/// +/// Instances of blacklisted characters found in the new [TextEditingValue]s +/// will be replaced with the [replacementString] which defaults to the empty +/// string. +/// /// Since this formatter only removes characters from the text, it attempts to /// preserve the existing [TextEditingValue.selection] to values it would now /// fall at with the removed characters. -/// +/// /// See also: -/// -/// * [TextInputFormatter]. -/// * [WhitelistingTextInputFormatter]. +/// +/// * [WhitelistingTextInputFormatter], which uses a whitelist instead of a +/// blacklist. class BlacklistingTextInputFormatter extends TextInputFormatter { + /// Creates a formatter that prevents the insertion of blacklisted characters patterns. + /// + /// The [blacklistedPattern] must not be null. BlacklistingTextInputFormatter( - this.blacklistedPattern, - { - this.replacementString: '', - } - ) : assert(blacklistedPattern != null); + this.blacklistedPattern, { + this.replacementString: '', + }) : assert(blacklistedPattern != null); /// A [Pattern] to match and replace incoming [TextEditingValue]s. final Pattern blacklistedPattern; @@ -105,7 +107,7 @@ class BlacklistingTextInputFormatter extends TextInputFormatter { TextEditingValue newValue, ) { return _selectionAwareTextManipulation( - newValue, + newValue, (String substring) { return substring.replaceAll(blacklistedPattern, replacementString); }, @@ -117,23 +119,26 @@ class BlacklistingTextInputFormatter extends TextInputFormatter { = new BlacklistingTextInputFormatter(new RegExp(r'\n')); } -/// A [TextInputFormatter] that allows only the insertion of whitelisted +/// A [TextInputFormatter] that allows only the insertion of whitelisted /// characters patterns. -/// +/// /// Since this formatter only removes characters from the text, it attempts to /// preserve the existing [TextEditingValue.selection] to values it would now /// fall at with the removed characters. -/// +/// /// See also: -/// -/// * [TextInputFormatter]. -/// * [BlacklistingTextInputFormatter]. +/// +/// * [BlacklistingTextInputFormatter], which uses a blacklist instead of a +/// whitelist. class WhitelistingTextInputFormatter extends TextInputFormatter { - WhitelistingTextInputFormatter(this.whitelistedPattern) : + /// Creates a formatter that allows only the insertion of whitelisted characters patterns. + /// + /// The [blacklistedPattern] must not be null. + WhitelistingTextInputFormatter(this.whitelistedPattern) : assert(whitelistedPattern != null); /// A [Pattern] to extract all instances of allowed characters. - /// + /// /// [RegExp] with multiple groups is not supported. final Pattern whitelistedPattern; @@ -143,7 +148,7 @@ class WhitelistingTextInputFormatter extends TextInputFormatter { TextEditingValue newValue, ) { return _selectionAwareTextManipulation( - newValue, + newValue, (String substring) { return whitelistedPattern .allMatches(substring) @@ -186,8 +191,8 @@ TextEditingValue _selectionAwareTextManipulation( } return new TextEditingValue( text: manipulatedText, - selection: manipulatedSelection ?? const TextSelection.collapsed(offset: -1), - composing: manipulatedText == value.text + selection: manipulatedSelection ?? const TextSelection.collapsed(offset: -1), + composing: manipulatedText == value.text ? value.composing : TextRange.empty, );