Skip to content

Commit e684e62

Browse files
committed
Move input formatter discussion to TextEditingController class docs
1 parent fe1578b commit e684e62

1 file changed

Lines changed: 21 additions & 5 deletions

File tree

‎packages/flutter/lib/src/widgets/editable_text.dart‎

Lines changed: 21 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -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

Comments
 (0)