# Interface TextInputClient

All Known Implementing Classes:
  `CodeView, EditField, EditorView, RichView`

public interface TextInputClient

A low level text input client, the counterpart to a platform text input source (soft keyboard, IME, autocorrect and hardware keyboard). A component that wants to own text editing itself - rendering text with its own `Graphics` code instead of a native text widget - implements this interface and binds it through `com.codename1.impl.CodenameOneImplementation#startTextInput`. From then on the platform routes committed text, IME composition (marked text), deletions and key commands directly into the client, and the client answers back with the surrounding text and caret geometry the platform needs to place candidate windows, the selection loupe and predictions.

This is the same pattern high end custom editors use (a hidden input surface driving a custom rendered document). Codename One's pure `RichTextArea` / `CodeEditor` are the primary consumers, but the API is deliberately general so any component can capture raw text input.

All offsets exchanged with the platform are UTF-16 character indices. All callbacks are delivered on the EDT.

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `static final int`
  `KEY_BACKSPACE`
  Key command: delete backward (backspace) when not expressed as a surrounding text deletion.
  `static final int`
  `KEY_COPY`
  Key command: copy the selection.
  `static final int`
  `KEY_CUT`
  Key command: cut the selection.
  `static final int`
  `KEY_DELETE`
  Key command: delete forward.
  `static final int`
  `KEY_DOWN`
  Key command: move / extend down a line.
  `static final int`
  `KEY_END`
  Key command: move / extend to the end of the line.
  `static final int`
  `KEY_ESCAPE`
  Key command: dismiss / cancel (escape).
  `static final int`
  `KEY_HOME`
  Key command: move / extend to the start of the line.
  `static final int`
  `KEY_LEFT`
  Key command: move / extend to the left.
  `static final int`
  `KEY_PAGE_DOWN`
  Key command: page down.
  `static final int`
  `KEY_PAGE_UP`
  Key command: page up.
  `static final int`
  `KEY_PASTE`
  Key command: paste the clipboard.
  `static final int`
  `KEY_REDO`
  Key command: redo.
  `static final int`
  `KEY_RIGHT`
  Key command: move / extend to the right.
  `static final int`
  `KEY_SELECT_ALL`
  Key command: select all.
  `static final int`
  `KEY_TAB`
  Key command: tab.
  `static final int`
  `KEY_UNDO`
  Key command: undo.
  `static final int`
  `KEY_UP`
  Key command: move / extend up a line.
  `static final int`
  `MOD_ALT`
  Modifier bit: alt / option held.
  `static final int`
  `MOD_CTRL`
  Modifier bit: control or command held.
  `static final int`
  `MOD_SHIFT`
  Modifier bit: shift held (used to extend a selection).

- ## Method Summary

  Modifier and Type
  Method
  Description
  `void`
  `commitText(String text)`
  Commits final text at the caret, replacing the active selection.
  `void`
  `deleteSurroundingText(int before, int after)`
  Deletes text around the caret, the primary deletion path used by soft keyboards.
  `void`
  `finishComposing()`
  Finalizes any active IME composition, committing the current marked text.
  `int[]`
  `getCaretRect()`
  Returns the caret rectangle in absolute screen pixels `{x, y, width, height}`, used by the platform to anchor the IME candidate window and the selection loupe near the rendered caret.
  `TextInputConfig`
  `getConfig()`
  Returns the configuration describing the desired keyboard type and input behavior.
  `TextInputState`
  `getEditingState()`
  Returns the current editing state (surrounding text, selection and composition) so the platform can seed autocorrect and prediction.
  `int`
  `getTextLength()`
  Returns the total number of UTF-16 characters in the document.
  `String`
  `getTextRange(int start, int end)`
  Returns the text in `[start, end)`.
  `void`
  `inputFocusGained()`
  Notifies the client that it gained the platform input focus (became first responder).
  `void`
  `inputFocusLost()`
  Notifies the client that it lost the platform input focus.
  `int`
  `offsetAtPoint(int x, int y)`
  Returns the document offset nearest an absolute screen point (pixels).
  `void`
  `onEditorAction(int action)`
  Delivers the keyboard return key action (done / next / search / send) configured through `TextInputConfig`.
  `void`
  `onKeyCommand(int command, int modifiers)`
  Delivers a non text key command (navigation, deletion, clipboard, undo).
  `int[]`
  `rectForOffset(int offset)`
  Returns the caret rectangle for an arbitrary offset in absolute screen pixels `{x, y, w, h}`.
  `void`
  `replaceRange(int start, int end, String text)`
  Replaces the range `[start, end)` with `text` (a direct, range based edit from the platform).
  `int[]`
  `selectionRects(int start, int end)`
  Returns the selection rectangles covering `[start, end)` as a flat array of absolute-pixel rectangles `{x, y, w, h, x, y, w, h, ...}` (one entry per visual line the range spans).
  `void`
  `setComposingText(String text, int relativeCaret)`
  Updates the in progress IME composition (marked text) at the caret.
  `void`
  `setSelectionRange(int start, int end)`
  Sets the selection to `[start, end)` (a caret when equal).

- ## Field Details

  - ### KEY_LEFT

    static final int KEY_LEFT
    Key command: move / extend to the left.
    See Also:
      - Constant Field Values

  - ### KEY_RIGHT

    static final int KEY_RIGHT
    Key command: move / extend to the right.
    See Also:
      - Constant Field Values

  - ### KEY_UP

    static final int KEY_UP
    Key command: move / extend up a line.
    See Also:
      - Constant Field Values

  - ### KEY_DOWN

    static final int KEY_DOWN
    Key command: move / extend down a line.
    See Also:
      - Constant Field Values

  - ### KEY_HOME

    static final int KEY_HOME
    Key command: move / extend to the start of the line.
    See Also:
      - Constant Field Values

  - ### KEY_END

    static final int KEY_END
    Key command: move / extend to the end of the line.
    See Also:
      - Constant Field Values

  - ### KEY_PAGE_UP

    static final int KEY_PAGE_UP
    Key command: page up.
    See Also:
      - Constant Field Values

  - ### KEY_PAGE_DOWN

    static final int KEY_PAGE_DOWN
    Key command: page down.
    See Also:
      - Constant Field Values

  - ### KEY_BACKSPACE

    static final int KEY_BACKSPACE
    Key command: delete backward (backspace) when not expressed as a surrounding text deletion.
    See Also:
      - Constant Field Values

  - ### KEY_DELETE

    static final int KEY_DELETE
    Key command: delete forward.
    See Also:
      - Constant Field Values

  - ### KEY_ESCAPE

    static final int KEY_ESCAPE
    Key command: dismiss / cancel (escape).
    See Also:
      - Constant Field Values

  - ### KEY_COPY

    static final int KEY_COPY
    Key command: copy the selection.
    See Also:
      - Constant Field Values

  - ### KEY_CUT

    static final int KEY_CUT
    Key command: cut the selection.
    See Also:
      - Constant Field Values

  - ### KEY_PASTE

    static final int KEY_PASTE
    Key command: paste the clipboard.
    See Also:
      - Constant Field Values

  - ### KEY_SELECT_ALL

    static final int KEY_SELECT_ALL
    Key command: select all.
    See Also:
      - Constant Field Values

  - ### KEY_UNDO

    static final int KEY_UNDO
    Key command: undo.
    See Also:
      - Constant Field Values

  - ### KEY_REDO

    static final int KEY_REDO
    Key command: redo.
    See Also:
      - Constant Field Values

  - ### KEY_TAB

    static final int KEY_TAB
    Key command: tab. With `#MOD_SHIFT` this is a dedent (shift-tab); otherwise an indent. A plain editor with no indentation behavior may treat it as inserting a tab character.
    See Also:
      - Constant Field Values

  - ### MOD_SHIFT

    static final int MOD_SHIFT
    Modifier bit: shift held (used to extend a selection).
    See Also:
      - Constant Field Values

  - ### MOD_CTRL

    static final int MOD_CTRL
    Modifier bit: control or command held.
    See Also:
      - Constant Field Values

  - ### MOD_ALT

    static final int MOD_ALT
    Modifier bit: alt / option held.
    See Also:
      - Constant Field Values

- ## Method Details

  - ### commitText

    void commitText(String text)

    Commits final text at the caret, replacing the active selection. This is the normal path for a typed character, an accepted autocorrect suggestion, dictation and paste.

    ###### Parameters

    - `text`: the committed text

  - ### setComposingText

    void setComposingText(String text, int relativeCaret)

    Updates the in progress IME composition (marked text) at the caret. The composing text is not yet final and is typically rendered underlined; it is replaced on the next `#setComposingText` and finalized by `#finishComposing`.

    ###### Parameters

    - `text`: the current marked text

    - `relativeCaret`: caret position relative to the marked text (platform convention)

  - ### finishComposing

    void finishComposing()
    Finalizes any active IME composition, committing the current marked text.

  - ### deleteSurroundingText

    void deleteSurroundingText(int before, int after)

    Deletes text around the caret, the primary deletion path used by soft keyboards.

    ###### Parameters

    - `before`: number of UTF-16 units to delete before the caret

    - `after`: number of UTF-16 units to delete after the caret

  - ### onKeyCommand

    void onKeyCommand(int command, int modifiers)

    Delivers a non text key command (navigation, deletion, clipboard, undo). Text producing keys are delivered through `#commitText` instead.

    ###### Parameters

    - `command`: one of the `KEY_*` constants

    - `modifiers`: a bit mask of the `MOD_*` constants

  - ### onEditorAction

    void onEditorAction(int action)

    Delivers the keyboard return key action (done / next / search / send) configured through `TextInputConfig`.

    ###### Parameters

    - `action`: one of the `TextInputConfig` `ACTION_*` constants

  - ### getEditingState

    TextInputState getEditingState()
    Returns the current editing state (surrounding text, selection and composition) so the platform can seed autocorrect and prediction. May return a window around the caret for very large documents.

  - ### getCaretRect

    int[] getCaretRect()
    Returns the caret rectangle in absolute screen pixels `{x, y, width, height}`, used by the platform to anchor the IME candidate window and the selection loupe near the rendered caret.

  - ### getConfig

    TextInputConfig getConfig()
    Returns the configuration describing the desired keyboard type and input behavior.

  - ### inputFocusGained

    void inputFocusGained()
    Notifies the client that it gained the platform input focus (became first responder).

  - ### inputFocusLost

    void inputFocusLost()
    Notifies the client that it lost the platform input focus.

  - ### getTextLength

    int getTextLength()
    Returns the total number of UTF-16 characters in the document.

  - ### getTextRange

    String getTextRange(int start, int end)
    Returns the text in `[start, end)`.

  - ### rectForOffset

    int[] rectForOffset(int offset)
    Returns the caret rectangle for an arbitrary offset in absolute screen pixels `{x, y, w, h}`.

  - ### offsetAtPoint

    int offsetAtPoint(int x, int y)
    Returns the document offset nearest an absolute screen point (pixels).

  - ### selectionRects

    int[] selectionRects(int start, int end)
    Returns the selection rectangles covering `[start, end)` as a flat array of absolute-pixel rectangles `{x, y, w, h, x, y, w, h, ...}` (one entry per visual line the range spans).

  - ### replaceRange

    void replaceRange(int start, int end, String text)
    Replaces the range `[start, end)` with `text` (a direct, range based edit from the platform).

  - ### setSelectionRange

    void setSelectionRange(int start, int end)
    Sets the selection to `[start, end)` (a caret when equal).