[PATCH 2/3] protocol: document wl_pointer, wl_keyboard, wl_touch

Kristian Høgsberg hoegsberg at gmail.com
Wed Apr 3 12:24:00 PDT 2013


On Tue, Apr 02, 2013 at 10:23:29AM +1000, Peter Hutterer wrote:
> On Tue, Apr 02, 2013 at 09:58:17AM +1000, Peter Hutterer wrote:
> > Most of this should be clear, but let's spell a few things out.
> > 
> > Signed-off-by: Peter Hutterer <peter.hutterer at who-t.net>
> > ---
> 
> ok, now seeing that Matthias has worked on this as well, there's going to be
> some overlap so best to ignore this one I guess.

I think I managed to merge in your additional descriptions, but give
it a look-over to see if it looks right.

Kristian


> Cheers,
>    Peter
> 
> >  protocol/wayland.xml | 69 ++++++++++++++++++++++++++++++++++++++++------------
> >  1 file changed, 54 insertions(+), 15 deletions(-)
> > 
> > diff --git a/protocol/wayland.xml b/protocol/wayland.xml
> > index 4750115..ac560b2 100644
> > --- a/protocol/wayland.xml
> > +++ b/protocol/wayland.xml
> > @@ -1002,6 +1002,13 @@
> >    </interface>
> >  
> >    <interface name="wl_pointer" version="1">
> > +    <description summary="pointer input device">
> > +      A pointer input device is a device that is usually represented by a
> > +      visible cursor. Pointer input devices include mice,
> > +      trackballs, touchpads, etc. A multi-touch device is not a
> > +      wl_pointer device, see wl_touch.
> > +    </description>
> > +
> >      <request name="set_cursor">
> >        <description summary="set the pointer surface">
> >  	Set the pointer surface, i.e., the surface that contains the
> > @@ -1034,8 +1041,8 @@
> >  
> >        <arg name="serial" type="uint"/>
> >        <arg name="surface" type="object" interface="wl_surface" allow-null="true"/>
> > -      <arg name="hotspot_x" type="int"/>
> > -      <arg name="hotspot_y" type="int"/>
> > +      <arg name="hotspot_x" type="fixed" summary="x coordinate in surface-relative coordinates"/>
> > +      <arg name="hotspot_y" type="fixed" summary="y coordinate in surface-relative coordinates"/>
> >      </request>
> >  
> >      <event name="enter">
> > @@ -1048,8 +1055,8 @@
> >  
> >        <arg name="serial" type="uint"/>
> >        <arg name="surface" type="object" interface="wl_surface"/>
> > -      <arg name="surface_x" type="fixed"/>
> > -      <arg name="surface_y" type="fixed"/>
> > +      <arg name="surface_x" type="fixed" summary="x coordinate in surface-relative coordinates"/>
> > +      <arg name="surface_y" type="fixed" summary="y coordinate in surface-relative coordinates"/>
> >      </event>
> >  
> >      <event name="leave">
> > @@ -1066,8 +1073,8 @@
> >        </description>
> >  
> >        <arg name="time" type="uint"/>
> > -      <arg name="surface_x" type="fixed"/>
> > -      <arg name="surface_y" type="fixed"/>
> > +      <arg name="surface_x" type="fixed" summary="x coordinate in surface-relative coordinates"/>
> > +      <arg name="surface_y" type="fixed" summary="y coordinate in surface-relative coordinates"/>
> >      </event>
> >  
> >      <enum name="button_state">
> > @@ -1125,6 +1132,8 @@
> >  
> >    <interface name="wl_keyboard" version="1">
> >      <description summary="keyboard input device">
> > +      A keyboard input device is a device that emits wl_keyboard::key events,
> > +      representing a physical or logical change in that key's state.
> >      </description>
> >  
> >      <enum name="keymap_format">
> > @@ -1146,12 +1155,20 @@
> >      </event>
> >  
> >      <event name="enter">
> > +      <description summary="keyboard focus enter">
> > +        This event notifies the client that the keyboard focus has been set
> > +        to the surface.
> > +      </description>
> >        <arg name="serial" type="uint"/>
> >        <arg name="surface" type="object" interface="wl_surface"/>
> > -      <arg name="keys" type="array"/>
> > +      <arg name="keys" type="array" summary="keys currently down"/>
> >      </event>
> >  
> >      <event name="leave">
> > +      <description summary="keyboard focus enter">
> > +        This event notifies the client that the keyboard focus has left the
> > +        last surface entered.
> > +      </description>
> >        <arg name="serial" type="uint"/>
> >        <arg name="surface" type="object" interface="wl_surface"/>
> >      </event>
> > @@ -1191,28 +1208,47 @@
> >  
> >    <interface name="wl_touch" version="1">
> >      <description summary="touch screen input device">
> > +      A touch screen input device is a direct-touch device that is not
> > +      represented by a visible cursor. More than one touch point may be
> > +      active at any time. Touch devices include touch screens and
> > +      multi-touch-capable devices, but exclude touchpads. Touchpads are
> > +      wl_pointer devices.
> >      </description>
> >  
> >      <event name="down">
> > +      <description summary="begin of a touch event sequence">
> > +	A new touch point has appeared on the surface. This touch point is
> > +	assigned a unique @id. Future events from this touchpoint reference
> > +	this ID. The ID ceases to be valid after a touch up event and may be
> > +	re-used in the future.
> > +      </description>
> >        <arg name="serial" type="uint"/>
> >        <arg name="time" type="uint"/>
> >        <arg name="surface" type="object" interface="wl_surface"/>
> > -      <arg name="id" type="int" />
> > -      <arg name="x" type="fixed" />
> > -      <arg name="y" type="fixed" />
> > +      <arg name="id" type="int" summary="the unique ID of this touch point"/>
> > +      <arg name="x" type="fixed" summary="x coordinate in surface-relative coordinates"/>
> > +      <arg name="y" type="fixed" summary="y coordinate in surface-relative coordinates"/>
> >      </event>
> >  
> >      <event name="up">
> > +      <description summary="end of a touch event sequence">
> > +	The touch point has disappeared. No further events will be sent for
> > +	this touchpoint and the touch point's ID is released and may be
> > +	re-used in a future touch down event.
> > +      </description>
> >        <arg name="serial" type="uint"/>
> >        <arg name="time" type="uint"/>
> > -      <arg name="id" type="int" />
> > +      <arg name="id" type="int" summary="the unique ID of this touch point"/>
> >      </event>
> >  
> >      <event name="motion">
> > +      <description summary="end of a touch event sequence">
> > +	A touchpoint has changed coordinates.
> > +      </description>
> >        <arg name="time" type="uint"/>
> > -      <arg name="id" type="int" />
> > -      <arg name="x" type="fixed" />
> > -      <arg name="y" type="fixed" />
> > +      <arg name="id" type="int" summary="the unique ID of this touch point"/>
> > +      <arg name="x" type="fixed" summary="x coordinate in surface-relative coordinates"/>
> > +      <arg name="y" type="fixed" summary="y coordinate in surface-relative coordinates"/>
> >      </event>
> >  
> >      <event name="frame">
> > @@ -1225,7 +1261,10 @@
> >        <description summary="touch session cancelled">
> >  	Sent if the compositor decides the touch stream is a global
> >  	gesture. No further events are sent to the clients from that
> > -	particular gesture.
> > +	particular gesture. Touch cancellation applies to all touch points
> > +	currently active on this client's surface. The client is
> > +	responsible for finalizing the touch points, future touch points on
> > +	this surface may re-use the touch point ID.
> >        </description>
> >      </event>
> >    </interface>
> > -- 
> > 1.8.1.4
> > 
> _______________________________________________
> wayland-devel mailing list
> wayland-devel at lists.freedesktop.org
> http://lists.freedesktop.org/mailman/listinfo/wayland-devel


More information about the wayland-devel mailing list