Fuchsia's text APIs mediate between clients which provide text input field implementations (e.g. Web text input) as well as clients participating in text entry (e.g. on-screen keyboards).
A client, e.g. Chromium runner, is presenting a text input field to the user.
Another client, e.g. Flutter runner, has an on-screen keyboard implementation that should be used to edit the text inside the text input field.
Fuchsia provides a TextInputContext protocol for Flutter-based on-screen keyboard to be notified about a text field being focused and ready for input.
When Chromium's input field is focused, Chromium runner connects to the TextInputContextManager FIDL protocol and calls the CreateNewFocusedField() method on it. This method creates a TextField endpoint and returns it to Chromium runner. After that, this TextField is marked as focused and is propagated to other clients, including Flutter runner, as a “hanging get” response to TextInputContext.WatchFocusedTextField().
Note that Chromium runner and Flutter runner now have the same API to the TextField and should use the same methods for updating it collaboratively.
Assuming TextField is made available to Flutter-based on-screen keyboard, it invokes TextField.WatchState to receive current TextFieldState. Upon receiving and processing the response, another request for state should be scheduled using same TextField.WatchState. This request follows recommended approach for “hanging get” FIDL calls and will only be resolved when text field state changes.
TextFieldState holds revision property that is incremented each time text field state changes, for example text is modified.
To query current text in the text field, TextField.GetContents() method could be used. As a parameter, it takes most recent revision and Range and returns a string of Unicode code points entered.
The base implementation relies on the client to ensure that text content wasn't changes since last edit. Practically it means that client should always have most recent TextInputState.revision and update text field contents using TextField.GetContents each time revision changes.
To insert new character into the text field, TextField.Replace() should be used. It takes Range and a string, and replaces the characters inside the Range with the string provided.
If the Range is 0-length, the string is inserted into text field at the index provided in Range.
If the Range provides empty string, the text inside Range is deleted.