# Text Input

## How are key events sent from the keyboard?

* `SystemChannels.keyEvent` exposes a messaging channel that receives raw key data whenever the platform produces keyboard events.
* `RawKeyboard` subscribes to this channel and forwards incoming messages as `RawKeyEvent` instances (which encapsulate `RawKeyEventData`). Physical and logical interpretations of the event are exposed via `RawKeyEvent.physicalKey` and `RawKeyEvent.logicalKey`, respectively. The character produced is available as `RawKeyEvent.character` but only for `RawKeyDownEvent` events. This field accounts for modifier keys / past keystrokes producing null for invalid combinations or a dart string, otherwise.
* The physical key identifies the actual position of the key that was struck, expressed as the equivalent key on a standard `QWERTY` keyboard. The logical key ignores position, taking into account any mappings or layout changes to produce the actual key the user intended.
* Subclasses of `RawKeyEventData` interpret platform-specific data to categorize the keystroke in a portable way (`RawKeyEventDataAndroid`, `RawKeyEventDataMacOs`)

## What is an `IME`?

* `IME` stands for “input method editor,” which corresponds to any sort of on-screen text editing interface, such as the software keyboard. There can only be one active `IME` at a time.

## How does `Flutter` interact with `IMEs`?

* `SystemChannels.textInput` exposes a method channel that implements a transactional interface for interacting with an `IME`. Operations are scoped to a given transaction (client), which is implicit once created. Outbound methods support configuring the `IME`, showing/hiding UI, and update editing state (including selections); inbound methods handle `IME` actions and editing changes. Convenient wrappers for this protocol make much of this seamless.

## What are the building blocks for interacting with an `IME`?

* `TextInput.attach` federates access to the `IME`, setting the current client (transaction) that can interact with the keyboard.
* `TextInputClient` is an interface to receive information from the `IME`. Once attached, clients are notified via method invocation when actions are invoked, the editing value is updated, or the cursor is moved.
* `TextInputConnection` is returned by `TextInput.attach` and allows the `IME` to be altered. In particular, the editing state can be changed, the `IME` shown, and the connection closed. Once closed, if no other client attaches within the current animation frame, the `IME` will also be hidden. 
* `TextInputConfiguration` encapsulates configuration data sent to the `IME` when a client attaches. This includes the desired input type (e.g., “datetime”, “`emailAddress`”, “phone”) for which to optimize the `IME`, whether to enable autocorrect, whether to obscure input, the default action, capitalization mode (`TextCapitalization`), and more. 
* `TextInputAction` enumerates the set of special actions supported on all platforms (e.g., “`emergencyCall`”, “done”, “next”). Actions may only be used on platforms that support them. Actions have no intrinsic meaning; developers determine how to respond to actions themselves.
* `TextEditingValue` represents the current text, selection, and composing state (range being edited) for a run of text.
* `RawFloatingCursorPoint` represents the position of the “floating cursor” on `iOS`, a special cursor that appears when the user force presses the keyboard. Its position is reported via the client, including state changes (`RawFloatingCursorDragState`).