GeezerVison is showing api.flutter.dev — TextEditingController class - widgets library - Dart API

TextEditingController class

A controller for an editable text field.

Whenever the user modifies a text field with an associated TextEditingController, the text field updates value and the controller notifies its listeners. Listeners can then read the text and selection properties to learn what the user has typed or how the selection has been updated.

Similarly, if you modify the text or selection properties, the text field will be notified and will update itself appropriately.

A TextEditingController can also be used to provide an initial value for a text field. If you build a text field with a controller that already has text, the text field will use that text as its initial value.

The value (as well as text and selection) of this controller can be updated from within a listener added to this controller. Be aware of infinite loops since the listener will also be notified of the changes made from within itself. Modifying the composing region from within a listener can also have a bad interaction with some input methods. Gboard, for example, will try to restore the composing region of the text if it was modified programmatically, creating an infinite loop of communications between the framework and the input method. Consider using TextInputFormatters instead for as-you-type text modification.

TextInputFormatters, such as those supplied to EditableText.inputFormatters, only run when the user changes the text in the text field, for example using the keyboard or the text selection menu. They don't run when the text is changed programmatically through this controller, such as by setting value or text, or by calling clear. If a programmatically set value needs to be formatted, apply the formatting manually before updating the controller.

If both the text and selection properties need to be changed, set the controller's value instead. Setting text will clear the selection and composing range.

Remember to dispose of the TextEditingController when it is no longer needed. This will ensure we discard any resources used by the object.

This example creates a TextField with a TextEditingController whose change listener forces the entered text to be lower case and keeps the cursor at the end of the input.

link

To create a local project with this code sample, run:
flutter create --sample=widgets.TextEditingController.1 mysample

Constructors

TextEditingController({String? text}): Creates a controller for an editable text field, with no initial selection.
TextEditingController.fromValue(TextEditingValue? value): Creates a controller for an editable text field from an initial TextEditingValue.

Properties

hashCode → int: The hash code for this object.
no setterinherited
hasListeners → bool: Whether any listeners are currently registered.
no setterinherited
runtimeType → Type: A representation of the runtime type of the object.
no setterinherited
selection ↔ TextSelection: The currently selected range within text.
getter/setter pair
text ↔ String: The current string the user is editing.
getter/setter pair
value ↔ TextEditingValue: The current value stored in this notifier.
getter/setter pairinherited-getteroverride-setter

Methods

addListener(VoidCallback listener) → void: Register a closure to be called when the object changes.
inherited
buildTextSpan({required BuildContext context, TextStyle? style, required bool withComposing}) → TextSpan: Builds TextSpan from current editing value.
clear() → void: Set the value to empty.
clearComposing() → void: Set the composing region to an empty range.
dispose() → void: Discards any resources used by the object.
inherited
noSuchMethod(Invocation invocation) → dynamic: Invoked when a nonexistent method or property is accessed.
inherited
notifyListeners() → void: Call all the registered listeners.
inherited
removeListener(VoidCallback listener) → void: Remove a previously registered closure from the list of closures that are notified when the object changes.
inherited
toString() → String: A string representation of this object.
inherited

Operators

operator ==(Object other) → bool: The equality operator.
inherited