TextInput class

An low-level interface to the system's text input control.

To start interacting with the system's text input control, call attach to establish a TextInputConnection between the system's text input control and a TextInputClient. The majority of commands available for interacting with the text input control reside in the returned TextInputConnection. The communication between the system text input and the TextInputClient is asynchronous.

The platform text input plugin (which represents the system's text input) and the TextInputClient usually maintain their own text editing states (TextEditingValue) separately. They must be kept in sync as long as the TextInputClient is connected. The following methods can be used to send TextEditingValue to update the other party, when either party's text editing states change:

• The TextInput.attach method allows a TextInputClient to establish a connection to the text input. An optional field in its configuration parameter can be used to specify an initial value for the platform text input plugin's TextEditingValue.

• The TextInputClient sends its TextEditingValue to the platform text input plugin using TextInputConnection.setEditingState.

• The platform text input plugin sends its TextEditingValue to the connected TextInputClient via a "TextInput.setEditingState" message.

• When autofill happens on a disconnected TextInputClient, the platform text input plugin sends the TextEditingValue to the connected TextInputClient's AutofillScope, and the AutofillScope will further relay the value to the correct TextInputClient.

When synchronizing the TextEditingValues, the communication may get stuck in an infinite when both parties are trying to send their own update. To mitigate the problem, only TextInputClients are allowed to alter the received TextEditingValues while platform text input plugins are to accept the received TextEditingValues unmodified. More specifically:

• When a TextInputClient receives a new TextEditingValue from the platform text input plugin, it's allowed to modify the value (for example, apply TextInputFormatters). If it decides to do so, it must send the updated TextEditingValue back to the platform text input plugin to keep the TextEditingValues in sync.

• When the platform text input plugin receives a new value from the connected TextInputClient, it must accept the new value as-is, to avoid sending back an updated value.

See also:

• TextField, a widget in which the user may enter text.
• EditableText, a TextInputClient that connects to TextInput when it wants to take user input from the keyboard.