diff options
Diffstat (limited to 'protocol/text.xml')
| -rw-r--r-- | protocol/text.xml | 52 |
1 files changed, 33 insertions, 19 deletions
diff --git a/protocol/text.xml b/protocol/text.xml index 508c3153..1b5284dc 100644 --- a/protocol/text.xml +++ b/protocol/text.xml @@ -39,6 +39,8 @@ 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 @@ -85,10 +87,11 @@ </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"/> @@ -208,7 +211,10 @@ 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"/> @@ -227,12 +233,12 @@ <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"/> @@ -240,11 +246,11 @@ </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> @@ -252,8 +258,9 @@ <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> @@ -262,8 +269,10 @@ </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"/> @@ -271,8 +280,13 @@ <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"/> @@ -281,7 +295,7 @@ <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) |