Input method contexts do not keep state after deactivation and should be
destroyed after deactivation is handled.
+ Text is generally UTF-8 encoded, indices and lengths are in bytes.
+
Serials are used to synchronize the state between the text input and
an input method. New serials are sent by the text input in the
commit_state request and are used by the input method to indicate
<request name="destroy" type="destructor"/>
<request name="commit_string">
<description summary="commit string">
- Send the commit string text to the applications text model and
- set the cursor at index (as byte index) relative to the
- beginning of inserted text.
+ Send the commit string text for insertion to the application.
+
+ The text to commit could be either just a single character after a key
+ press or the result of some composing (pre-edit). It could be also an
+ empty text when some text should be removed (see
+ delete_surrounding_text) or when the input cursor should be moved (see
+ cursor_position).
+
+ Any previously set composing text will be removed.
</description>
- <arg name="serial" type="uint"/>
+ <arg name="serial" type="uint" summary="serial of the latest known text input state"/>
<arg name="text" type="string"/>
</request>
<request name="preedit_string">
<description summary="pre-edit string">
- Send the pre-edit string text to the applications text model. The commit
- text can be used to replace the preedit text on reset (for example on
- unfocus).
+ Send the pre-edit string text to the application text input.
+
+ The commit text can be used to replace the preedit text on reset (for
+ example on unfocus).
+
+ Also previously sent preedit_style and preedit_cursor requests are
+ processed bt the text_input also.
</description>
- <arg name="serial" type="uint"/>
+ <arg name="serial" type="uint" summary="serial of the latest known text input state"/>
<arg name="text" type="string"/>
<arg name="commit" type="string"/>
</request>
<request name="preedit_styling">
<description summary="pre-edit styling">
Sets styling information on composing text. The style is applied for
- length (in bytes) characters from index relative to the beginning of the
- composing text (as byte index). Multiple styles can be applied to a
- composing text.
+ length in bytes from index relative to the beginning of
+ the composing text (as byte offset). Multiple styles can
+ be applied to a composing text.
This request should be sent before sending preedit_string request.
</description>
</request>
<request name="preedit_cursor">
<description summary="pre-edit cursor">
- Sets the cursor position inside the composing text (as byte index)
+ Sets the cursor position inside the composing text (as byte offset)
relative to the start of the composing text.
+ When index is negative no cursor should be displayed.
+
This request should be sent before sending preedit_string request.
</description>
<arg name="index" type="int"/>
</request>
<request name="delete_surrounding_text">
+ <description summary="delete text">
+
+
+ This request will be handled on text_input side as part of a directly
+ following commit_string request.
+ </description>
<arg name="index" type="int"/>
<arg name="length" type="uint"/>
</request>
<request name="cursor_position">
+ <description summary="set cursor to a new position">
+ Sets the cursor and anchor to a new position. Index is the new cursor
+ position in bytess (when >= 0 relative to the end of inserted text
+ else relative to beginning of inserted text). Anchor is the new anchor
+ position in bytes (when >= 0 relative to the end of inserted text, else
+ relative to beginning of inserted text). When there should be no
+ selected text anchor should be the same as index.
+
+ This request will be handled on text_input side as part of a directly
+ following commit_string request.
+ </description>
<arg name="index" type="int"/>
<arg name="anchor" type="int"/>
</request>
delete_surrounfing_text, etc. The key event follows the wl_keyboard key
event convention. Sym is a XKB keysym, state a wl_keyboard key_state.
</description>
- <arg name="serial" type="uint"/>
+ <arg name="serial" type="uint" summary="serial of the latest known text input state"/>
<arg name="time" type="uint"/>
<arg name="sym" type="uint"/>
<arg name="state" type="uint"/>
<arg name="keyboard" type="new_id" interface="wl_keyboard"/>
</request>
<request name="key">
- <arg name="serial" type="uint"/>
- <arg name="time" type="uint"/>
- <arg name="key" type="uint"/>
- <arg name="state" type="uint"/>
+ <description summary="forward key event">
+ Should be used when filtering key events with grab_keyboard.
+
+ When the wl_keyboard::key event is not processed by the input
+ method itself and should be sent to the client instead, forward it
+ with this request. The arguments should be the ones from the
+ wl_keyboard::key event.
+
+ For generating custom key events use the keysym request instead.
+ </description>
+ <arg name="serial" type="uint" summary="serial from wl_keyboard::key"/>
+ <arg name="time" type="uint" summary="time from wl_keyboard::key"/>
+ <arg name="key" type="uint" summary="key from wl_keyboard::key"/>
+ <arg name="state" type="uint" summary="state from wl_keyboard::key"/>
</request>
<request name="modifiers">
- <arg name="serial" type="uint"/>
- <arg name="mods_depressed" type="uint"/>
- <arg name="mods_latched" type="uint"/>
- <arg name="mods_locked" type="uint"/>
- <arg name="group" type="uint"/>
+ <description summary="forward modifiers event">
+ Should be used when filtering key events with grab_keyboard.
+
+ When the wl_keyboard::modifiers event should be also send to the
+ client, forward it with this request. The arguments should be the ones
+ from the wl_keyboard::modifiers event.
+ </description>
+ <arg name="serial" type="uint" summary="serial from wl_keyboard::modifiers"/>
+ <arg name="mods_depressed" type="uint" summary="mods_depressed from wl_keyboard::modifiers"/>
+ <arg name="mods_latched" type="uint" summary="mods_latched from wl_keyboard::modifiers"/>
+ <arg name="mods_locked" type="uint" summary="mods_locked from wl_keyboard::modifiers"/>
+ <arg name="group" type="uint" summary="group from wl_keyboard::modifiers"/>
</request>
<request name="language">
- <arg name="serial" type="uint"/>
+ <arg name="serial" type="uint" summary="serial of the latest known text input state"/>
<arg name="language" type="string"/>
</request>
<request name="text_direction">
- <arg name="serial" type="uint"/>
+ <arg name="serial" type="uint" summary="serial of the latest known text input state"/>
<arg name="direction" type="uint"/>
</request>
<event name="surrounding_text">
<arg name="index" type="uint"/>
</event>
<event name="commit_state">
- <arg name="serial" type="uint"/>
+ <arg name="serial" type="uint" summary="serial of text input state"/>
</event>
<event name="preferred_language">
<arg name="language" type="string"/>
for applications to directly process hardware key events and compose text
out of them.
+ Text is generally UTF-8 encoded, indices and lengths are in bytes.
+
Serials are used to synchronize the state between the text input and
an input method. New serials are sent by the text input in the
commit_state request and are used by the input method to indicate
</request>
<request name="set_surrounding_text">
<description summary="sets the surrounding text">
- Sets the plain surrounding text around the input position. Cursor is the
- byte index within the surrounding text. Anchor is the byte index of the
+ Sets the plain surrounding text around the input position. Text is
+ UTF-8 encoded. Cursor is the byte offset within the
+ surrounding text. Anchor is the byte offset of the
selection anchor within the surrounding text. If there is no selected
- text anchor then it is the same as cursor.
+ text anchor is the same as cursor.
</description>
<arg name="text" type="string"/>
<arg name="cursor" type="uint"/>
be removed.
The commit text can be used to replace the preedit text on reset
- (for example on unfocus).
+ (for example on unfocus).
+
+ The text input should also handle all preedit_style and preedit_cursor
+ events occuring directly before preedit_string.
</description>
<arg name="serial" type="uint" summary="serial of the latest known text input state"/>
<arg name="text" type="string"/>
<event name="preedit_styling">
<description summary="pre-edit styling">
Sets styling information on composing text. The style is applied for
- length (in bytes) characters from index relative to the beginning of
- the composing text (as byte index). Multiple styles can be applied
- to a composing text.
+ length bytes from index relative to the beginning of the composing
+ text (as byte offset). Multiple styles can
+ be applied to a composing text by sending multiple preedit_styling
+ events.
- This event should be handled as part of a following preedit_string
- event.
+ This event is handled as part of a following preedit_string event.
</description>
<arg name="index" type="uint"/>
<arg name="length" type="uint"/>
</event>
<event name="preedit_cursor">
<description summary="pre-edit cursor">
- Sets the cursor position inside the composing text (as byte index)
- relative to the start of the composing text.
+ Sets the cursor position inside the composing text (as byte
+ offset) relative to the start of the composing text. When index is a
+ negative number no cursor is shown.
- This event should be handled as part of a following preedit_string
- event.
+ This event is handled as part of a following preedit_string event.
</description>
<arg name="index" type="int"/>
</event>
<description summary="commit">
Notify when text should be inserted into the editor widget. The text to
commit could be either just a single character after a key press or the
- result of some composing (pre-edit). It also sets the new cursor
- position (as byte index) relative to the beginning of inserted text.
+ result of some composing (pre-edit). It could be also an empty text
+ when some text should be removed (see delete_surrounding_text) or when
+ the input cursor should be moved (see cursor_position).
Any previously set composing text should be removed.
</description>
</event>
<event name="cursor_position">
<description summary="set cursor to new position">
- Notify when the cursor or anchor position should be modified. It
- should take effect after the next commit_string event.
+ Notify when the cursor or anchor position should be modified.
+
+ This event should be handled as part of a following commit_string
+ event.
</description>
<arg name="index" type="int"/>
<arg name="anchor" type="int"/>
<event name="delete_surrounding_text">
<description summary="delete surrounding text">
Notify when the text around the current cursor position should be
- deleted. Index is relative to the current cursor (as byte index).
+ deleted.
+
+ Index is relative to the current cursor (in bytes).
Length is the length of deleted text (in bytes).
+
+ This event should be handled as part of a following commit_string
+ event.
</description>
<arg name="index" type="int"/>
<arg name="length" type="uint"/>
<description summary="keysym">
Notify when a key event was sent. Key events should not be used
for normal text input operations, which should be done with
- commit_string, delete_surrounfing_text, etc. The key event follows
+ commit_string, delete_surrounding_text, etc. The key event follows
the wl_keyboard key event convention. Sym is a XKB keysym, state a
wl_keyboard key_state. Modifiers are a mask for effective modifiers
(where the modifier indices are set by the modifiers_map event)