[PATCH v3 wayland-protocols 4/4] tablet: Add pad support to the tablet protocol

Thu May 12 01:12:54 UTC 2016

On Wed, May 11, 2016 at 11:44:45AM -0700, Jason Gerecke wrote:
> On Tue, May 10, 2016 at 7:51 PM, Peter Hutterer
> <peter.hutterer at who-t.net> 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).
> >
> > Buttons are sequentially indexed starting with zero, unlike other protocols
> > where a linux/input.h-style semantic event code is used. Since we expect all
> > buttons to have client-specific functionality, an additional event tells the
> > client when a given button index is not available, usually because the
> > compositor assignes some function to it (e.g. mode switching, see below).
> >
> > 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>
> > ---
> > Changes to v2:
> > - change to v2 of the protocol
> > - various comments and suggestions for improved wording incorporated
> > - ring is in wl_fixed degrees now (was int, in 0.01 of a degree)
> > - button events changed to sequential indices
> > - new buttons_reserved event
> >
> >  unstable/tablet/tablet-unstable-v2.xml | 436 +++++++++++++++++++++++++++++++++
> >  1 file changed, 436 insertions(+)
> >
> > diff --git a/unstable/tablet/tablet-unstable-v2.xml b/unstable/tablet/tablet-unstable-v2.xml

[...]

> > +    <request name="set_feedback">
> > +      <description summary="set compositor feedback">
> > +       Requests the compositor to use the provided feedback string
> > +       associated with this button. This request should be issued
> > +       immediately after a wp_tablet_pad.enter event or whenever a button
> > +       is mapped to a different action.
> > +
> > +       Clients are encouraged to provide context-aware descriptions for
> > +       the actions associated with each button, and compositors may use
> > +       this information to offer visual feedback on the button layout
> > +       (e.g. on-screen displays).
> > +
> > +       The provided string 'description' is an UTF-8 encoded string to be
> > +       associated with this ring, and is considered user visible; general
> > +       internationalization rules apply.
> > +      </description>
> > +      <arg name="button" type="uint" summary="button code"/>
> 
> The pad protocol doesn't use codes anymore. Perhaps change the summary
> of this argument to "button index" and mention that indices start at
> zero like in "buttons_reserved".

added the diff below:

diff --git a/unstable/tablet/tablet-unstable-v2.xml b/unstable/tablet/tablet-unstable-v2.xml
index 85a8f40..67c1134 100644
--- a/unstable/tablet/tablet-unstable-v2.xml
+++ b/unstable/tablet/tablet-unstable-v2.xml
@@ -897,11 +897,16 @@
 	this information to offer visual feedback on the button layout
 	(e.g. on-screen displays).
 
+	Button indices start at 0. Setting the feedback string on a button
+	that is reserved by the compositor (see
+	wp_tablet_pad.buttons_reserved) does not generate an error but the
+	compositor is free to ignore such a feedback string.
+
 	The provided string 'description' is an UTF-8 encoded string to be
 	associated with this ring, and is considered user visible; general
 	internationalization rules apply.
       </description>
-      <arg name="button" type="uint" summary="button code"/>
+      <arg name="button" type="uint" summary="button index"/>
       <arg name="description" type="string" summary="button description"/>
     </request>
 

> > +
> > +    <event name="buttons_reserved">
> > +      <description summary="reserved button indices">
> > +       Sent on wp_tablet_pad initialization and/or at a later time to notify the
> > +       client of reserved buttons.
> > +
> > +       Compositors may consume some buttons for global actions, those
> > +       global actions will not trigger wl_tablet_pad.button events (e.g.
> > +       the button to switch between modes, if any). This event notifies the
> > +       client that some button indices are reserved by the compositor and
> > +       will not generate events visible to the client. Button indices start
> > +       at 0.
> > +
> > +       This event may is sent in the initial burst of events before the
> > +       wp_tablet_pad.done event and/or at any later time when the
> > +       compositor changes the list of reserved buttons. This event is only
> > +       sent when the compositor reserves at least one button.
> 
> What happens when the number of buttons reserved by the compositor
> drops from nonzero to zero? Shouldn't this event be sent then as well
> (with a zero-length array)?

good point, added:

 +         When the number of reserved buttons drops to zero, the
 +         buttons_reserved array is an empty array.

> 
> > +    <event name="modes">
> > +      <description summary="mode-switch ability announced">
> > +       Sent on wp_tablet_pad initialization to announce that the pad
> > +       may switch between modes. A client may use a mode to store a
> > +       specific configuration for buttons, rings and strips and use the
> > +       wl_tablet_pad.mode event to toggle between these configurations.
> > +
> > +       Switching modes is compositor-dependent. See the wp_tablet_pad.mode
> > +       event for more details.
> > +
> > +       This event is sent in the initial burst of events before the
> > +       wp_tablet_pad.done event.
> > +      </description>
> > +      <arg name="modes" type="uint" summary="the number of modes"/>
> > +    </event>
> > +
> > +    <event name="done">
> > +      <description summary="pad description event sequence complete">
> > +       This event signals the end of the initial burst of descriptive
> > +       events. A client may consider the static description of the pad to
> > +       be complete and finalize initialization of the pad.
> > +      </description>
> > +    </event>
> > +
> > +    <enum name="button_state">
> > +      <description summary="physical button state">
> > +       Describes the physical state of a button which provoked the button
> > +       event.
> > +      </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">
> > +      <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"/>
> > +      <arg name="button" type="uint" summary="button pressed"/>
> 
> "button pressed" could be a bit more clear. Perhaps something similar
> to what you use for "set_feedback".

Changed to "the index of the button that changed state" which is a bit
clumsy but at least non-ambiguous.


> > +    <event name="mode">
> > +      <description summary="mode switch event">
> > +       Notification that the mode was switched.
> > +
> > +       A mode applies to all buttons, rings and strips but a client is not
> > +       required to assign different actions for each mode. For example, a
> > +       client may have mode-specific button mappings but map the ring to
> > +       vertical scrolling in all modes.
> > +
> > +       Switching modes is compositor-dependent. The compositor may provide
> > +       visual cues to the client about the mode, e.g. by toggling LEDs on
> > +       the tablet device. Mode-switching may be software-controlled or by
> > +       assigning one or more physical buttons. For example, on a Wacom
> > +       Intuos Pro, the button inside the ring may be assigned to switch
> > +       between modes.
> > +
> > +       If a button action in the new mode differs from the action in the
> > +       previous mode, the client should immediately issue a
> > +       wp_tablet_pad.set_feedback request for each changed button.
> > +
> > +       If a ring or button action in the new mode differs from the action
> > +       in the previous mode, the client should immediately issue a
> > +       wp_tablet_ring.set_feedback or wp_tablet_strip.set_feedback request
> > +       for each changed ring or strip.
> > +      </description>
> > +      <arg name="time" type="uint" summary="the time of the event with millisecond granularity"/>
> > +      <arg name="serial" type="uint"/>
> > +      <arg name="mode" type="uint" summary="the new mode of the pad"/>
> 
> Would be good to mention that the mode is zero-indexed (assuming it is).

added here and in the modes event, thanks.

Cheers,
   Peter
