public interface TextInputClient

Known subtypesEditField, CodeView, EditorView, RichView

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.

Fields

`public static final int KEY_LEFT = 1`	Key command: move / extend to the left.
`public static final int KEY_RIGHT = 2`	Key command: move / extend to the right.
`public static final int KEY_UP = 3`	Key command: move / extend up a line.
`public static final int KEY_DOWN = 4`	Key command: move / extend down a line.
`public static final int KEY_HOME = 5`	Key command: move / extend to the start of the line.
`public static final int KEY_END = 6`	Key command: move / extend to the end of the line.
`public static final int KEY_PAGE_UP = 7`	Key command: page up.
`public static final int KEY_PAGE_DOWN = 8`	Key command: page down.
`public static final int KEY_BACKSPACE = 9`	Key command: delete backward (backspace) when not expressed as a surrounding text deletion.
`public static final int KEY_DELETE = 10`	Key command: delete forward.
`public static final int KEY_ESCAPE = 11`	Key command: dismiss / cancel (escape).
`public static final int KEY_COPY = 12`	Key command: copy the selection.
`public static final int KEY_CUT = 13`	Key command: cut the selection.
`public static final int KEY_PASTE = 14`	Key command: paste the clipboard.
`public static final int KEY_SELECT_ALL = 15`	Key command: select all.
`public static final int KEY_UNDO = 16`	Key command: undo.
`public static final int KEY_REDO = 17`	Key command: redo.
`public static final int KEY_TAB = 18`	Key command: tab.
`public static final int MOD_SHIFT = 1`	Modifier bit: shift held (used to extend a selection).
`public static final int MOD_CTRL = 2`	Modifier bit: control or command held.
`public static final int MOD_ALT = 4`	Modifier bit: alt / option held.

Methods

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

Field details

KEY_LEFT

public static final int KEY_LEFT = 1

Key command: move / extend to the left.

KEY_RIGHT

public static final int KEY_RIGHT = 2

Key command: move / extend to the right.

KEY_UP

public static final int KEY_UP = 3

Key command: move / extend up a line.

KEY_DOWN

public static final int KEY_DOWN = 4

Key command: move / extend down a line.

KEY_HOME

public static final int KEY_HOME = 5

Key command: move / extend to the start of the line.

KEY_END

public static final int KEY_END = 6

Key command: move / extend to the end of the line.

KEY_PAGE_UP

public static final int KEY_PAGE_UP = 7

Key command: page up.

KEY_PAGE_DOWN

public static final int KEY_PAGE_DOWN = 8

Key command: page down.

KEY_BACKSPACE

public static final int KEY_BACKSPACE = 9

Key command: delete backward (backspace) when not expressed as a surrounding text deletion.

KEY_DELETE

public static final int KEY_DELETE = 10

Key command: delete forward.

KEY_ESCAPE

public static final int KEY_ESCAPE = 11

Key command: dismiss / cancel (escape).

KEY_COPY

public static final int KEY_COPY = 12

Key command: copy the selection.

KEY_CUT

public static final int KEY_CUT = 13

Key command: cut the selection.

KEY_PASTE

public static final int KEY_PASTE = 14

Key command: paste the clipboard.

KEY_SELECT_ALL

public static final int KEY_SELECT_ALL = 15

Key command: select all.

KEY_UNDO

public static final int KEY_UNDO = 16

Key command: undo.

KEY_REDO

public static final int KEY_REDO = 17

Key command: redo.

KEY_TAB

public static final int KEY_TAB = 18

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.

MOD_SHIFT

public static final int MOD_SHIFT = 1

Modifier bit: shift held (used to extend a selection).

MOD_CTRL

public static final int MOD_CTRL = 2

Modifier bit: control or command held.

MOD_ALT

public static final int MOD_ALT = 4

Modifier bit: alt / option held.

Method details

commitText

public abstract 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 String: the committed text

setComposingText

public abstract 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 String: the current marked text
relativeCaret int: caret position relative to the marked text (platform convention)

finishComposing

public abstract void finishComposing()

Finalizes any active IME composition, committing the current marked text.

deleteSurroundingText

public abstract void deleteSurroundingText(int before, int after)

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

Parameters

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

onKeyCommand

public abstract 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 int: one of the KEY_* constants
modifiers int: a bit mask of the MOD_* constants

onEditorAction

public abstract void onEditorAction(int action)

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

Parameters

action int: one of the TextInputConfig ACTION_* constants

getEditingState

public abstract 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

public abstract 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

public abstract TextInputConfig getConfig()

Returns the configuration describing the desired keyboard type and input behavior.

inputFocusGained

public abstract void inputFocusGained()

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

inputFocusLost

public abstract void inputFocusLost()

Notifies the client that it lost the platform input focus.

getTextLength

public abstract int getTextLength()

Returns the total number of UTF-16 characters in the document.

getTextRange

public abstract String getTextRange(int start, int end)

Returns the text in [start, end).

rectForOffset

public abstract int[] rectForOffset(int offset)

Returns the caret rectangle for an arbitrary offset in absolute screen pixels {x, y, w, h}.

offsetAtPoint

public abstract int offsetAtPoint(int x, int y)

Returns the document offset nearest an absolute screen point (pixels).

selectionRects

public abstract 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

public abstract void replaceRange(int start, int end, String text)

Replaces the range [start, end) with text (a direct, range based edit from the platform).

setSelectionRange

public abstract void setSelectionRange(int start, int end)

Sets the selection to [start, end) (a caret when equal).