[PATCH] text: Improve text protocol documentation

[Kristian Høgsberg]

On Thu, Sep 13, 2012 at 12:55:14AM +0200, Jan Arne Petersen wrote:
> From: Jan Arne Petersen <jpetersen at openismus.com>
> 
> Add some missing descriptions to the text protocol file.

Thanks, that looks better.

Kristian

> ---
>  protocol/text.xml | 35 ++++++++++++++++++++++++++++++++---
>  1 file 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.
>        </description>
>        <arg name="text" type="string"/>
>        <arg name="cursor" type="uint"/>
> @@ -68,7 +68,12 @@
>        <arg name="seat" type="object" interface="wl_seat"/>
>      </request>
>      <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>
>      <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>
>      <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>
>      <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"/>
>      </event>
> -- 
> 1.7.11.4
> 
> _______________________________________________
> wayland-devel mailing list
> wayland-devel at lists.freedesktop.org
> http://lists.freedesktop.org/mailman/listinfo/wayland-devel