text: Improve protocol documentation.

Signed-off-by: Jan Arne Petersen <jpetersen@openismus.com>

2 files changed, 106 insertions, 44 deletions

diff --git a/protocol/input-method.xml b/protocol/input-method.xml
index 4ccb08e1..41369ef0 100644
--- a/protocol/input-method.xml
+++ b/protocol/input-method.xml
@@ -34,6 +34,8 @@
       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
@@ -44,29 +46,39 @@
     <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>
@@ -76,18 +88,37 @@
     </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>
@@ -101,7 +132,7 @@
         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"/>
@@ -117,24 +148,41 @@
        <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">
@@ -160,7 +208,7 @@
       <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"/>
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)