[RFC wayland-protocols] Add pad support to the tablet protocol

Mon Mar 7 01:46:31 UTC 2016

On Fri, Mar 04, 2016 at 01:40:09PM -0800, Bryce Harrington wrote:
> On Wed, Mar 02, 2016 at 11:06:52AM +1000, Peter Hutterer wrote:
> > From: Carlos Garnacho <carlosg at gnome.org>
> > 
> > The pad's interface is similar to the tool interface, a client is notified of
> > the pad after the tablet_added event.
> > 
> > The pad has three functionalities: buttons, rings and strips.
> > Buttons are fairly straightforward, rings and strips are separate interfaces
> > with a pointer-axis-like source/value/frame events.
> > The two interfaces are effectively identical but for the actual value they
> > send (degrees vs normalized position).
> > 
> > Specific to the pad device is the set_feedback request which enables a client
> > to set a user-defined string to display for an OSD on the current mappings.
> > This request is available for buttons, rings and strips.
> > 
> > Finally, the pad supports "modes", effectively sets of button/ring/strip
> > configurations.
> > 
> > Signed-off-by: Carlos Garnacho <carlosg at gnome.org>
> > Signed-off-by: Peter Hutterer <peter.hutterer at who-t.net>
> > ---
> > First version of a tablet pad protocol to use the buttons on the pad itself
> > and the rings/strips, if any.
> > 
> > A couple of comments to keep in mind:
> > * frame events are inside ring/strip. a pad.frame would be nicer but that
> >   would require mixing events from interface, I don't think that's a good
> >   idea.
> > * the modes are simply sent as numbers and we expect the clients to update
> >   accordingly. This comes with a couple of side-effects, unsure at this
> >   point whether they're features or drawbacks :)
> >   * if a client doesn't use mode switching we'll still see the LEDs cycle on
> >     mode button press.
> >   * the set_feedback requests is for the current mode only, the compositor
> >     cannot know the various strings until it cycled through all modes. this
> >     may be an issue.
> >   * the button list is not mode-specific. a button that is mapped to a
> >     compositor function in one specific mode only will still appear in the
> >     list and a client may want to set features for it. There is no feedback
> >     to the client that this doesn't work. The same goes for the ring/strip
> >     if they're to be mapped to compositor actions.
> > * given the limitations of the linux/input.h event codes I'm tempted to
> >   switch to simple button numbers for pad buttons.
> > 
> >  unstable/tablet/tablet-unstable-v1.xml | 424 ++++++++++++++++++++++++++++++++-
> >  1 file changed, 422 insertions(+), 2 deletions(-)
> > 
> > diff --git a/unstable/tablet/tablet-unstable-v1.xml b/unstable/tablet/tablet-unstable-v1.xml
> > index 988f949..e23c09a 100644
> > --- a/unstable/tablet/tablet-unstable-v1.xml
> > +++ b/unstable/tablet/tablet-unstable-v1.xml
> > @@ -112,7 +112,7 @@
> >      version number in the protocol and interface names are removed and the
> >      interface version number is reset.
> >    </description>
> > -  <interface name="zwp_tablet_manager_v1" version="1">
> > +  <interface name="zwp_tablet_manager_v1" version="2">
> >      <description summary="controller object for graphic tablet devices">
> >        An object that provides access to the graphics tablets available on this
> >        system. Any tablet is associated with a seat, to get access to the
> > @@ -136,7 +136,7 @@
> >      </request>
> >    </interface>
> >  
> > -  <interface name="zwp_tablet_seat_v1" version="1">
> > +  <interface name="zwp_tablet_seat_v1" version="2">
> >      <description summary="controller object for graphic tablet devices of a seat">
> >        An object that provides access to the graphics tablets available on this
> >        seat. After binding to this interface, the compositor sends a set of
> > @@ -169,6 +169,23 @@
> >        </description>
> >        <arg name="id" type="new_id" interface="zwp_tablet_tool_v1" summary="the newly added tablet tool"/>
> >      </event>
> > +
> > +    <!-- version 2 additions -->
> > +
> > +    <event name="pad_added" since="2">
> > +      <description summary="new pad notification">
> > +	This event is sent whenever a new pad is known to the system. Typically,
> > +	pads are physically attached to tablets and a pad_added event is
> > +	sent immediately after the wp_tablet_seat.tablet_added.
> > +	However, some standalone pad devices logically attach to tablets at
> > +	runtime, the client must wait for wp_tablet_pad.enter to know the
> > +	tablet a pad is attached to.
> > +
> > +	This event only provides the object id of the pad, any further features
> > +	(buttons, strips, rings) is send through the wp_tablet_pad interface.
> 
> is sent

all the typos/rewordings fixed as requested unless otherwise commented
below.

> > +      </description>
> > +      <arg name="id" type="new_id" interface="zwp_tablet_pad_v1" summary="the newly added pad"/>
> > +    </event>
> >    </interface>
> >  
> >    <interface name="zwp_tablet_tool_v1" version="1">
> > @@ -619,4 +636,407 @@
> >        </description>
> >      </event>
> >    </interface>
> > +
> > +  <interface name="zwp_tablet_pad_ring_v1" version="2">
> > +    <description summary="pad ring">
> > +      A circular interaction area.
> > +
> > +      Events on a ring are logically grouped by the wl_tablet_pad_ring.frame
> > +      event.
> > +    </description>
> 
> Could you elaborate here on what exactly a 'ring' is?  I assume it's the
> ipod style dial thingee, although from the other events I gather it's
> related to text input in some fashion?  Even if it might be remedial, a
> definition of the term would likely be beneficial at this point.

it's the touch ring on the Intuos Pro series, present on all devices since
the Intuos 4 and on most Cintiq devices. The thing is, the ring on a tablet
pad is a well-known entity, describing it here is a bit like describing what
a wheel is in the mouse context. It should be handled as a special entity so
by the time you're implementing pad support you should know what the ring is
anyway :)
As for the hardware: yes, they're and ipod-like touch ring that sends
positional information. what you do with that information is up to the
client, you could map it to scroll for example.

Here's a picture of the I5 ring:
http://www.edensart.com/assets/images_computer_articles/full/intuos5_ring_full.jpg

> Here too a basic definition of what a strip is would be nice.  "A linear
> interaction area" gives me a clue, but I'm not visualizing it exactly or
> connecting it to UI I'm already familiar with.  (So I'm a luddite...)

see above, pretty much, the strip which is present on the Intuos3 and some
of the Cintiqs and is a linear touch surface. otherwise identical to the
ring.

> > +    <enum name="button_state" since="2">
> > +      <description summary="physical button state">
> > +	Describes the physical state of a button which provoked the button
> > +	event.
> 
> which invoked the ?
> 
> (Although I do like the mental imagery of provoking button events...)

this one I'll leave as-is until we fix the core protocol (the wording is the
same there, so let's fix all in one go)

> > +      </description>
> > +      <entry name="released" value="0" summary="The button is not pressed"/>
> > +      <entry name="pressed" value="1" summary="The button is pressed"/>
> > +    </enum>
> > +
> > +    <event name="button" since="2">
> > +      <description summary="physical button state">
> > +	Sent whenever the physical state of a button changes.
> > +      </description>
> > +      <arg name="time" type="uint" summary="The time of the event with millisecond granularity"/>
> 
> Do you mean to say, "The time of the event in milliseconds"?

here too: this is almost what the core protocol says. I'm happy to change it to
something but these are things that we should agree on and change across all
protocols to have the same phrasing.

Cheers,
  Peter