@@ -196,6 +196,14 @@ class _RenderCompositionCallback extends RenderProxyBox {
196196/// between the framework and the input method. Consider using
197197/// [TextInputFormatter] s instead for as-you-type text modification.
198198///
199+ /// [TextInputFormatter] s, such as those supplied to
200+ /// [EditableText.inputFormatters] , only run when the user changes the text in
201+ /// the text field, for example using the keyboard or the text selection menu.
202+ /// They don't run when the text is changed programmatically through this
203+ /// controller, such as by setting [value] or [text] , or by calling [clear] .
204+ /// If a programmatically set value needs to be formatted, apply the
205+ /// formatting manually before updating the controller.
206+ ///
199207/// If both the [text] and [selection] properties need to be changed, set the
200208/// controller's [value] instead. Setting [text] will clear the selection
201209/// and composing range.
@@ -273,6 +281,9 @@ class TextEditingController extends ValueNotifier<TextEditingValue> {
273281 /// this value should only be set between frames, e.g. in response to user
274282 /// actions, not during the build, layout, or paint phases. This property can
275283 /// be set from a listener added to this [TextEditingController] .
284+ ///
285+ /// Setting this does not run [TextInputFormatter] s. See the discussion at
286+ /// [TextEditingController] .
276287 set text (String newText) {
277288 value = value.copyWith (
278289 text: newText,
@@ -281,6 +292,8 @@ class TextEditingController extends ValueNotifier<TextEditingValue> {
281292 );
282293 }
283294
295+ /// Setting this does not run [TextInputFormatter] s. See the discussion at
296+ /// [TextEditingController] .
284297 @override
285298 set value (TextEditingValue newValue) {
286299 assert (
@@ -342,6 +355,9 @@ class TextEditingController extends ValueNotifier<TextEditingValue> {
342355 ///
343356 /// If the new selection is outside the composing range, the composing range is
344357 /// cleared.
358+ ///
359+ /// Setting this does not run [TextInputFormatter] s. See the discussion at
360+ /// [TextEditingController] .
345361 set selection (TextSelection newSelection) {
346362 if (text.length < newSelection.end || text.length < newSelection.start) {
347363 throw FlutterError ('invalid text selection: $newSelection ' );
@@ -362,11 +378,8 @@ class TextEditingController extends ValueNotifier<TextEditingValue> {
362378 /// this method should only be called between frames, e.g. in response to user
363379 /// actions, not during the build, layout, or paint phases.
364380 ///
365- /// This method does not trigger [TextInputFormatter] s. Input formatters only
366- /// run on user input (e.g., from the onscreen or physical keyboard), not on
367- /// programmatic changes to the controller's value. If you need to keep
368- /// formatter state in sync with the controller, do so manually after calling
369- /// this method.
381+ /// Calling this method does not run [TextInputFormatter] s. See the
382+ /// discussion at [TextEditingController] .
370383 void clear () {
371384 value = const TextEditingValue (selection: TextSelection .collapsed (offset: 0 ));
372385 }
@@ -381,6 +394,9 @@ class TextEditingController extends ValueNotifier<TextEditingValue> {
381394 /// that they need to update (it calls [notifyListeners] ). For this reason,
382395 /// this method should only be called between frames, e.g. in response to user
383396 /// actions, not during the build, layout, or paint phases.
397+ ///
398+ /// Calling this method does not run [TextInputFormatter] s. See the
399+ /// discussion at [TextEditingController] .
384400 void clearComposing () {
385401 value = value.copyWith (composing: TextRange .empty);
386402 }
0 commit comments