IME

Introduction

It's easy to enter text if you have a physical keyboard and use a language with a character set that fits into keyboard keys with 1-3 modifier keys. You just get keystrokes and append characters at the end of your textbox.

However there are languages with thousands of characters, there are new modern ways to enter text without a keyboard (voice recognition, handwriting recognition, on-screen keyboards) and modern ways of typing assistance (automatic completion, automatic correction, etc) that require more tight and complex integration of your textbox and the OS. The OS component that handles the text input is called Input Method. One of the earliest input methods in Microsoft Windows was called "Input Method Editor", so IME acronym got associated with input methods in general.

Text input components in Avalonia

Text View - a control that displays text and wants to receive text input

Input Method (IM) - a ITextInputMethodImpl implementation provided by the TopLevel. Represents the OS component responsible for text input.

Input Method Client (IM Client) - a component that manages interaction with a text input capable control and the rest of the advanced text input system. It's responsible for providing information about the visual and internal states of the text view.

TextInputMethodManager (Input Manager) - Avalonia component responsible for mediating between IM, IM Client and Avalonia control trees. It's responsible for detecting if the currently focused view wants text input at all, for querying for various text view properties, tracking focus rects and other tasks that would have to be implemented by individual IM components otherwise

IM activation scenario

1. A control receives input focus
2. Input Manager triggers TextInputMethodClientRequested routed event on the focused control
3. Input Manager checks if IM Client was provided by any of the TextInputMethodClientRequested handlers, if none is provided the IM enters deactivated state (SetActive(false) is called on IM)
4. Input Manager triggers TextInputOptionsQueryEvent routed event to gather text input options (auto-capitalization, on-screen keyboard type, whether the text being inputed is a password and shouldn't be added to a dictionary, etc)
5. Input Manager Resets the IM, passes text input options (SetOptions)
6. Input Manager enters cursor rect tracking state: it automatically tracks the text view position relatively to the TopLevel and the input rect provided by IM client
7. Input Manager activates the IM (SetActive(true) is called). From this moment IM is allowed to intercept any user input required for text input (usually it's just keyboard, but in case of writing recognition it could be pen input as well) and should show on-screen keyboard if needed.