[PATCH 14/21] docs: Improve the wl_seat protocol docs

[Kristian Høgsberg]

On Sat, Mar 30, 2013 at 01:11:40AM -0400, matthias.clasen at gmail.com wrote:
> From: Matthias Clasen <mclasen at redhat.com>
> 
> Expand the main description and tell if requests don't have
> an effect.
> ---
>  protocol/wayland.xml | 35 ++++++++++++++++++++++-------------
>  1 file changed, 22 insertions(+), 13 deletions(-)
> 
> diff --git a/protocol/wayland.xml b/protocol/wayland.xml
> index 3e674f3..442862d 100644
> --- a/protocol/wayland.xml
> +++ b/protocol/wayland.xml
> @@ -1105,28 +1105,28 @@
>     </interface>
>  
>    <interface name="wl_seat" version="1">
> -    <description summary="seat">
> -      A group of keyboards, pointer (mice, for example) and touch
> -      devices . This object is published as a global during start up,
> -      or when such a device is hot plugged.  A seat typically has a
> -      pointer and maintains a keyboard_focus and a pointer_focus.
> +    <description summary="group of input devices">
> +      A seat is a group of keyboards, pointer (mice, for example) and
> +      touch devices. This object is published as a global during
> +      start up, or when such a device is hot plugged.  A seat typically
> +      has a pointer and maintains a keyboard focus, a pointer focus and
> +      a touch focus.
>      </description>

There's no touch focus.  The focus for wl_pointer is there to let the
client keep track of when the pointer is in or out of its window.
wl_touch is exclusively touchscreens and there is no concept of focus.
Instead we have touch down (when you put your finger down), touch
motion (when you move the finger) and then touch up (releasing the
finger).

>      <enum name="capability">
>        <description summary="seat capability bitmask">
>          This is a bitmask of capabilities this seat has; if a member is
> -	set, then it is present on the seat.
> +        set, then it is present on the seat.
>        </description>
> -      <entry name="pointer" value="1" summary="wl_pointer"/>
> -      <entry name="keyboard" value="2" summary="wl_keyboard"/>
> -      <entry name="touch" value="4" summary="wl_touch"/>
> +      <entry name="pointer" value="1" summary="The seat has pointer devices"/>
> +      <entry name="keyboard" value="2" summary="The seat has one or more keyboards"/>
> +      <entry name="touch" value="4" summary="The seat has touch devices"/>
>      </enum>
>  
> -
>      <event name="capabilities">
>        <description summary="seat capabilities changed">
>          This is emitted whenever a seat gains or loses the pointer,
> -	keyboard or touch capabilities.  The argument is a wl_seat_caps_mask
> +	keyboard or touch capabilities.  The argument is a capability
>  	enum containing the complete set of capabilities this seat has.
>        </description>
>        <arg name="capabilities" type="uint"/>
> @@ -1136,22 +1136,31 @@
>        <description summary="return pointer object">
>          The ID provided will be initialized to the wl_pointer interface
>  	for this seat.
> +
> +        This request only takes effect if the seat has the pointer
> +        capability.
>        </description>
>        <arg name="id" type="new_id" interface="wl_pointer"/>
>      </request>
>  
>      <request name="get_keyboard">
> -      <description summary="return pointer object">
> +      <description summary="return keyboard object">
>          The ID provided will be initialized to the wl_keyboard interface
>  	for this seat.
> +
> +        This request only takes effect if the seat has the keyboard
> +        capability.
>        </description>
>        <arg name="id" type="new_id" interface="wl_keyboard"/>
>      </request>
>  
>      <request name="get_touch">
> -      <description summary="return pointer object">
> +      <description summary="return touch object">
>          The ID provided will be initialized to the wl_touch interface
>  	for this seat.
> +
> +        This request only takes effect if the seat has the touch
> +        capability.
>        </description>
>        <arg name="id" type="new_id" interface="wl_touch"/>
>      </request>
> -- 
> 1.8.1.4
> 
> _______________________________________________
> wayland-devel mailing list
> wayland-devel at lists.freedesktop.org
> http://lists.freedesktop.org/mailman/listinfo/wayland-devel