Interface TextInputClient

All Known Implementing Classes:
CodeView, 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_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:

    • KEY_RIGHT

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

    • KEY_UP

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

    • KEY_DOWN

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

    • KEY_HOME

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

    • KEY_END

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

    • KEY_PAGE_UP

      static final int KEY_PAGE_UP
      Key command: page up.
      See Also:

    • KEY_PAGE_DOWN

      static final int KEY_PAGE_DOWN
      Key command: page down.
      See Also:

    • KEY_BACKSPACE

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

    • KEY_DELETE

      static final int KEY_DELETE
      Key command: delete forward.
      See Also:

    • KEY_ESCAPE

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

    • KEY_COPY

      static final int KEY_COPY
      Key command: copy the selection.
      See Also:

    • KEY_CUT

      static final int KEY_CUT
      Key command: cut the selection.
      See Also:

    • KEY_PASTE

      static final int KEY_PASTE
      Key command: paste the clipboard.
      See Also:

    • KEY_SELECT_ALL

      static final int KEY_SELECT_ALL
      Key command: select all.
      See Also:

    • KEY_UNDO

      static final int KEY_UNDO
      Key command: undo.
      See Also:

    • KEY_REDO

      static final int KEY_REDO
      Key command: redo.
      See Also:

    • MOD_SHIFT

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

    • MOD_CTRL

      static final int MOD_CTRL
      Modifier bit: control or command held.
      See Also:

    • MOD_ALT

      static final int MOD_ALT
      Modifier bit: alt / option held.
      See Also:

  • 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).