# Interface WaylandTextInput.IMEListener

Enclosing interface:
  `WaylandTextInput`

public static interface WaylandTextInput.IMEListener
Interface describing a listener for `WaylandTextInput`.

Beware: Unfortunately, this API is rather complex. Documentation might be misleading, incorrect, or just plainly incomplete at this point in time. This is mainly due to me barely understanding it myself. Please bear with me: I'll fix it at a later point in time - promise! Until then, read the wayland documentation, I guess.

## Method Summary

Modifier and Type
Method
Description
`void`
`commitText(@Nullable String commitText)`
Commit a `String` to insert at the cursor.
`void`
`deleteSurroundingText(int beforeLength, int afterLength)`
Delete text near the cursor.
`void`
`done()`
Commit all incoming text changes from the wayland compositor.
`void`
`leave()`
Describes that the editing surface lost focus, possibly because the user focused another tab.
`void`
`preeditText(@Nullable String preeditText, int cursorBegin, int cursorEnd)`
Sets the pre-edit text.

## Method Details

### commitText

void commitText(@Nullable @Nullable String commitText)
Commit a `String` to insert at the cursor. Note that the value should only be applied on `done()`. See the wayland documentation for more information. This method corresponds to the `commit_string` event.

Calling this method overwrites all previously applied commit strings. Calling `done()` or `leave()` resets either.

Parameters:
  `commitText` - The `String` to commit when `done()` is called.
Implementation Specification:
  Due to how IMEs may composit text input, it is possible for the input string to be more than one character large. However, for most latin-based languages, the string will only have a single character.
Implementation Notice:
  Due to how cstrings are interpreted, the parameter `commitText` can never be an empty string. A null parameter is instead used to describe no commit text (i.e. an empty string).

### deleteSurroundingText

void deleteSurroundingText(int beforeLength, int afterLength)
Delete text near the cursor.

If pre-edit text is defined using `preeditText(String, int, int)`, then said event needs to be taken in account. That being said, the order of `done()` should be kept in mind.

Like `commitText(String)`, this event should only be fully processed once `done()` is invoked. Calling `leave()` would discard the event.

Parameters:
  `beforeLength` - The amount of characters to remove before the cursor.
  `afterLength` - The amount of characters to remove after the cursor.

### done

void done()
Commit all incoming text changes from the wayland compositor.

Calling `done()` multiple times in a row will have no effect, as calling `done()` will reset all staged changes (e.g. `commitText(String)` or `deleteSurroundingText(int, int)`).

The order in which staged changes should be processed is defined by the wayland protocol as follows:

1. Remove previously applied pre-edit text

If no pre-edit text has been staged, the pre-edit text should be assumed to be equal to an empty/null string with `cursorBegin`/`cursorEnd` of `0`.

### leave

void leave()
Describes that the editing surface lost focus, possibly because the user focused another tab.

As a result, the pre-edit text needs to be discarded, as well as all other staged events. This event is similar to `done()`, except that instead of switching one set of double-buffered values, it discards them. Some events such as `deleteSurroundingText(int, int)`, and `commitText(String)` shouldn't be rewound, provided they have already been applied using `done()`.

### preeditText

void preeditText(@Nullable @Nullable String preeditText, int cursorBegin, int cursorEnd)
Sets the pre-edit text. This event is fired as part of composing multi-character sequences, or when condensing multiple characters into a single glyph (e.g. for Chinese or Japanese input).

The pre-edit text should be rendered as part of the string, but at the same time also treated distinctively, in particularly concerning `leave()`. Or in other words, the pre-edit text may get discarded at any time.

The `cursorBegin` and `cursorEnd` arguments define the length and position of the selection cursor. If `cursorBegin` and `cursorEnd` are both `-1`, then the cursor should be disabled. `cursorBegin` and `cursorEnd` are 0-indexed with 0 representing the start of the pre-edit text sequence. Other out-of-bounds values are not permitted.

Beware: The active pre-edit text will remain set until `done()` is invoked. Until then this method should just plainly stage the pre-edit text, overwriting previously staged text. Invoking `done()` or `leave()` will clear all staged pre-edit text, with `leave()` further clearing all active pre-edit text.

Parameters:
  `preeditText` - The pre-edit text to use. May be `null` if there is no such text.
  `cursorBegin` - The start index of the cursor. May be `-1` alongside `cursorEnd` to disable the cursor.
  `cursorEnd` - The end index of the cursor. May be `-1` alongside `cursorEnd` to disable the cursor.
Implementation Notice:
  Due to how cstrings are interpreted, the parameter `preeditText` can never be an empty string. A null parameter is instead used to describe no pre-edit text (i.e. an empty string).