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

Mon May 16 23:30:03 UTC 2016

Hey :),

On Wed, May 11, 2016 at 4:51 AM, 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
> index d3f57ff..388b4d2 100644
> --- a/unstable/tablet/tablet-unstable-v2.xml
> +++ b/unstable/tablet/tablet-unstable-v2.xml
> @@ -172,6 +172,22 @@
>        </description>
>        <arg name="id" type="new_id" interface="zwp_tablet_tool_v2" summary="the newly added tablet tool"/>
>      </event>
> +
> +    <event name="pad_added">
> +      <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, and 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; and all further
> +       features (buttons, strips, rings) are sent through the wp_tablet_pad
> +       interface.
> +      </description>
> +      <arg name="id" type="new_id" interface="zwp_tablet_pad_v2" summary="the newly added pad"/>
> +    </event>
>    </interface>
>
>    <interface name="zwp_tablet_tool_v2" version="1">
> @@ -636,4 +652,424 @@
>      </event>
>    </interface>
>
> +  <interface name="zwp_tablet_pad_ring_v2" version="1">
> +    <description summary="pad ring">
> +      A circular interaction area.
> +
> +      Events on a ring are logically grouped by the wl_tablet_pad_ring.frame
> +      event.
> +    </description>
> +
> +    <request name="set_feedback">
> +      <description summary="set compositor feedback">
> +       Request that the compositor use the provided feedback string
> +       associated with this ring. This request should be issued immediately
> +       after a wp_tablet_pad.enter, or whenever the ring is mapped to a
> +       different action.
> +
> +       Clients are encouraged to provide context-aware descriptions for
> +       the actions associated with the ring; compositors may use this
> +       information to offer visual feedback about the button layout
> +       (eg. 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="description" type="string" summary="ring description"/>
> +    </request>
> +
> +    <request name="destroy" type="destructor">
> +      <description summary="destroy the ring object">
> +       This destroys the client's resource for this ring object.
> +      </description>
> +    </request>
> +
> +    <enum name="source">
> +      <description summary="ring axis source">
> +       Describes the source types for ring events. This indicates to the
> +       client how a ring event was physically generated; a client may
> +       adjust the user interface accordingly. For example, events
> +       from a "finger" source may trigger kinetic scrolling.
> +      </description>
> +      <entry name="finger" value="1" summary="finger"/>
> +    </enum>
> +
> +    <event name="source">
> +      <description summary="ring event source">
> +       Source information for ring events.
> +
> +       This event does not occur on its own. It is sent before a
> +       wp_tablet_pad_ring.frame event and carries the source information
> +       for all events within that frame.
> +
> +       The source specifies how this event was generated. If the source is
> +       wp_tablet_pad_ring.source.finger, a wp_tablet_pad_ring.stop event
> +       will be sent when the user lifts the finger off the device.
> +
> +       This event is optional. If the source is unknown for an interaction,
> +       no event is sent.
> +      </description>
> +      <arg name="source" type="uint" summary="the event source"/>
> +    </event>
> +
> +    <event name="angle">
> +      <description summary="angle changed">
> +       Sent whenever the angle on a ring changes.
> +
> +       The angle is provided in degrees clockwise from the logical
> +       north of the ring in the pad's current rotation.
> +      </description>
> +      <arg name="angle" type="fixed" summary="the current angle"/>
> +    </event>
> +
> +    <event name="stop">
> +      <description summary="interaction stopped">
> +       Stop notification for ring events.
> +
> +       For some wp_tablet_pad_ring.source types, a wp_tablet_pad_ring.stop
> +       event is sent to notify a client that the interaction with the ring
> +       has terminated.
> +       This enables the client to implement kinetic scrolling.
> +       See the wp_tablet_pad_ring.source documentation for information on
> +       when this event may be generated.
> +
> +       Any wp_tablet_pad_ring.angle events with the same source after this
> +       event should be considered as the start of a new interaction.
> +      </description>
> +      <arg name="source" type="uint" enum="source" summary="the event source"/>
> +    </event>
> +
> +    <event name="frame">
> +      <description summary="end of a ring event sequence">
> +       Indicates the end of a set of ring events that logically belong
> +       together. A client is expected to accumulate the data in all events
> +       within the frame before proceeding.
> +
> +       All wp_tablet_pad_ring events before a wp_tablet_pad_ring.frame event belong
> +       logically together. For example, on termination of a finger interaction
> +       on a ring the compositor will send a wp_tablet_pad_ring.source event,
> +       a wp_tablet_pad_ring.stop event and a wp_tablet_pad_ring.frame
> +       event.
> +
> +       A wp_tablet_pad_ring.frame event is sent for every logical event
> +       group, even if the group only contains a single wp_tablet_pad_ring
> +       event.  Specifically, a client may get a sequence: angle, frame,
> +       angle, frame, etc.
> +      </description>
> +      <arg name="time" type="uint" summary="timestamp with millisecond granularity"/>
> +    </event>
> +  </interface>
> +
> +  <interface name="zwp_tablet_pad_strip_v2" version="2">
> +    <description summary="pad strip">
> +      A linear interaction area.
> +
> +      Events on a strip are logically grouped by the wl_tablet_pad_strip.frame
> +      event.
> +    </description>
> +
> +    <request name="set_feedback">
> +      <description summary="set compositor feedback">
> +       Requests the compositor to use the provided feedback string
> +       associated with this strip. This request should be issued
> +       immediately after a wp_tablet_pad.enter, or whenever the strip is
> +       mapped to a different action.
> +
> +       Clients are encouraged to provide context-aware descriptions for
> +       the actions associated with the strip, compositors may use this
> +       information to offer visual feedback about the button layout
> +       (eg. 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="description" type="string" summary="strip description"/>
> +    </request>
> +
> +    <request name="destroy" type="destructor">
> +      <description summary="destroy the strip object">
> +       This destroys the client's resource for this strip object.
> +      </description>
> +    </request>
> +
> +    <enum name="source">
> +      <description summary="strip axis source">
> +       Describes the source types for strip events. This indicates to the
> +       client how a strip event was physically generated; a client may
> +       adjust the user interface accordingly. For example, events
> +       from a "finger" source may trigger kinetic scrolling.
> +      </description>
> +      <entry name="finger" value="1" summary="finger"/>
> +    </enum>
> +
> +    <event name="source">
> +      <description summary="strip event source">
> +       Source information for strip events.
> +
> +       This event does not occur on its own. It is sent before a
> +       wp_tablet_pad_strip.frame event and carries the source information
> +       for all events within that frame.
> +
> +       The source specifies how this event was generated. If the source is
> +       wp_tablet_pad_strip.source.finger, a wp_tablet_pad_strip.stop event
> +       will be sent when the user lifts their finger off the device.
> +
> +       This event is optional. If the source is unknown for an interaction,
> +       no event is sent.
> +      </description>
> +      <arg name="source" type="uint" summary="the event source"/>
> +    </event>
> +
> +    <event name="position">
> +      <description summary="position changed">
> +       Sent whenever the position on a strip changes.
> +
> +       The position is normalized to a range of [0, 65535], the 0-value
> +       represents the top-most and/or left-most position of the strip in
> +       the pad's current rotation.
> +      </description>
> +      <arg name="position" type="uint" summary="the current position"/>
> +    </event>
> +
> +    <event name="stop">
> +      <description summary="interaction stopped">
> +       Stop notification for strip events.
> +
> +       For some wp_tablet_pad_strip.source types, a wp_tablet_pad_strip.stop
> +       event is sent to notify a client that the interaction with the strip
> +       has terminated. This enables the client to implement kinetic
> +       scrolling.  See the wp_tablet_pad_strip.source documentation for
> +       information on when this event may be generated.
> +
> +       Any wp_tablet_pad_strip.position events with the same source after this
> +       event should be considered as the start of a new interaction.
> +      </description>
> +      <arg name="source" type="uint" enum="source" summary="the event source"/>
> +    </event>
> +
> +    <event name="frame">
> +      <description summary="end of a strip event sequence">
> +       Indicates the end of a set of events that represent one logical
> +       hardware strip event. A client is expected to accumulate the data
> +       in all events within the frame before proceeding.
> +
> +       All wp_tablet_pad_strip events before a wp_tablet_pad_strip.frame event belong
> +       logically together. For example, on termination of a finger interaction
> +       on a strip the compositor will send a wp_tablet_pad_strip.source event,
> +       a wp_tablet_pad_strip.stop event and a wp_tablet_pad_strip.frame
> +       event.
> +
> +       A wp_tablet_pad_strip.frame event is sent for every logical event
> +       group, even if the group only contains a single wp_tablet_pad_strip
> +       event.  Specifically, a client may get a sequence: position, frame,
> +       position, frame, etc.
> +      </description>
> +      <arg name="time" type="uint" summary="timestamp with millisecond granularity"/>
> +    </event>
> +  </interface>
> +
> +  <interface name="zwp_tablet_pad_v2" version="2">
> +    <description summary="a set of buttons, rings and strips">
> +      A pad device is a set of buttons, rings and strips
> +      usually physically present on the tablet device itself. Some
> +      exceptions exist where the pad device is physically detached, e.g. the
> +      Wacom ExpressKey Remote.
> +
> +      Pad devices have no axes that control the cursor and are generally
> +      auxiliary devices to the tool devices used on the tablet surface.
> +
> +      A pad device has a number of static characteristics, e.g. the number
> +      of rings. These capabilities are sent in an event sequence after the
> +      wp_tablet_seat.pad_added event before any actual events from this pad.
> +      This initial event sequence is terminated by a wp_tablet_pad.done
> +      event.
> +    </description>
> +
> +    <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"/>
> +      <arg name="description" type="string" summary="button description"/>
> +    </request>
> +
> +    <request name="destroy" type="destructor">
> +      <description summary="destroy the pad object">
> +       Destroy the wp_tablet_pad object. Objects created from this object
> +       are unaffected and should be destroyed separately.
> +      </description>
> +    </request>
> +
> +    <event name="ring">
> +      <description summary="ring announced">
> +       Sent on wp_tablet_pad initialization to announce available rings.
> +       One event is sent for each ring available on this pad.
> +
> +       This event is sent in the initial burst of events before the
> +       wp_tablet_pad.done event. This event is only sent when at least one
> +       ring is available.
> +      </description>
> +      <arg name="ring" type="new_id" interface="zwp_tablet_pad_ring_v2"/>
> +    </event>
> +
> +    <event name="strip">
> +      <description summary="strip announced">
> +       Sent on wp_tablet_pad initialization to announce available strips.
> +       One event is sent for each strip available on this pad.
> +
> +       This event is sent in the initial burst of events before the
> +       wp_tablet_pad.done event. This event is only sent when at least one
> +       strip is available.
> +      </description>
> +      <arg name="strip" type="new_id" interface="zwp_tablet_pad_strip_v2"/>
> +    </event>
> +
> +    <event name="buttons">
> +      <description summary="buttons announced">
> +       Sent on wp_tablet_pad initialization to announce the available
> +       buttons.
> +
> +       This event is sent in the initial burst of events before the
> +       wp_tablet_pad.done event. This event is only sent when at least one
> +       button is available.
> +      </description>
> +      <arg name="buttons" type="int" summary="the number of buttons"/>
> +    </event>
> +
> +    <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.
> +      </description>
> +      <arg name="buttons_reserved" type="array" summary="the reserved button indices"/>
> +    </event>
> +
> +    <event name="modes">

After some hands-on experience, I see this API in libwacom:

int libwacom_get_ring_num_modes(const WacomDevice *device);
int libwacom_get_ring2_num_modes(const WacomDevice *device);
int libwacom_get_strips_num_modes(const WacomDevice *device);

This makes me think, are there devices with more than one of these
modes? In that case I guess would be better to move .modes and .mode
to wp_tablet_pad_ring/strip than exposing the NxM combinations here. I
guess it also means renouncing to making these modes affect anything
else than the ring/strip.

If we move these events there, I wonder if we better add .done events
there too, or it suffices with wp_tablet_pad.done. I'd expect all
device characteristics to be announced before wp_tablet_pad.done
anyway.

Cheers,
  Carlos