diff options
authorJan Arne Petersen <>2012-09-12 22:55:14 (GMT)
committerKristian Høgsberg <>2012-09-13 20:34:18 (GMT)
commit7bbdffabc7a44e727833253878293e33bcfdab24 (patch)
parent495cc2484e267f0ad187972a28a61daaaa7a64ce (diff)
text: Improve text protocol documentation
Add some missing descriptions to the text protocol file.
1 files changed, 32 insertions, 3 deletions
diff --git a/protocol/text.xml b/protocol/text.xml
index eded1c8..857fd83 100644
--- a/protocol/text.xml
+++ b/protocol/text.xml
@@ -40,9 +40,9 @@
<request name="set_surrounding_text">
<description summary="sets the surrounding text">
Sets the plain surrounding text around the input position. Cursor is the
- position within the surrounding text. Anchor is the position of the
+ byte index within the surrounding text. Anchor is the byte index of the
selection anchor within the surrounding text. If there is no selected
- text anchor is the same as cursor.
+ text anchor is the same as cursor.
<arg name="text" type="string"/>
<arg name="cursor" type="uint"/>
@@ -68,7 +68,12 @@
<arg name="seat" type="object" interface="wl_seat"/>
<request name="reset">
- </request>
+ <description summary="reset">
+ Should be called by an editor widget when the input state should
+ be reseted, for example after the text was changed outside of the
+ normal input method flow.
+ </description>
+ </request>
<request name="set_micro_focus">
<arg name="x" type="int"/>
<arg name="y" type="int"/>
@@ -79,19 +84,43 @@
<request name="set_content_type"/>
<event name="commit_string">
+ <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 inserted text.
+ </description>
<arg name="text" type="string"/>
<arg name="index" type="uint"/>
<event name="preedit_string">
+ <description summary="pre-edit">
+ Notify when a new composing text (pre-edit) should be set around the
+ current cursor position. Any previously set composing text should
+ be removed. It also sets the cursor positon (as byte index) relative
+ to the start of the composing text.
+ </description>
<arg name="text" type="string"/>
<arg name="index" type="uint"/>
<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).
+ Length is the length of deleted text (as bytes).
+ </description>
<arg name="index" type="int"/>
<arg name="length" type="uint"/>
<event name="preedit_styling"/>
<event name="key">
+ <description summary="key">
+ 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
+ the wl_keyboard key event convention. Key is a XKB keycode, state a
+ wl_keyboard key_state.
+ </description>
<arg name="key" type="uint"/>
<arg name="state" type="uint"/>