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

Carlos Garnacho carlosg at gnome.org
Tue Jun 28 21:21:50 UTC 2016


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 groups, effectively sets of button/ring/strip
configurations. Those groups may have multiple modes each, so that
users/clients may map several actions to a single element.

Signed-off-by: Carlos Garnacho <carlosg at gnome.org>
Signed-off-by: Peter Hutterer <peter.hutterer at who-t.net>
Reviewed-by: Jason Gerecke <jason.gerecke at wacom.com>
---

Changes since v3:

- Added wp_tablet_pad_group, this divides buttons/strips/rings into subsets,
  groups may have separate modes which are announced through a mode_switch
  event.
- Added serial argument to the set_feedback requests, to be obtained from
  the wp_tablet_pad_group.mode_switch events.
- Now that groups announce the buttons belonging to those, the
  wp_tablet_pad.buttons_reserved event has been removed in favor of implicit
  information (i.e. buttons not belonging to any group are reserved by the
  compositor).
- Added wp_tablet_pad.path event, similar to wp_tablet.path
- Button indices are now explicitly mentioned in docs where relevant
- Fixed several typos and improved docs here and there

 unstable/tablet/tablet-unstable-v2.xml | 546 ++++++++++++++++++++++++++++++++-
 1 file changed, 543 insertions(+), 3 deletions(-)

diff --git a/unstable/tablet/tablet-unstable-v2.xml b/unstable/tablet/tablet-unstable-v2.xml
index 5248c64..63172e2 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. 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">
@@ -508,9 +524,9 @@
       <description summary="Wheel delta event">
 	Sent whenever the wheel on the tool emits an event. This event
 	contains two values for the same axis change. The degrees value is
-	in degrees in the same orientation as the wl_pointer.vertical_scroll
-	axis. The clicks value is in discrete logical clicks of the mouse
-	wheel. This value may be zero if the movement of the wheel was less
+	in the same orientation as the wl_pointer.vertical_scroll axis. The
+	clicks value is in discrete logical clicks of the mouse wheel. This
+	value may be zero if the movement of the wheel was less
 	than one logical click.
 
 	Clients should choose either value and avoid mixing degrees and
@@ -636,4 +652,528 @@
     </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 a UTF-8 encoded string to be
+	associated with this ring, and is considered user-visible; general
+	internationalization rules apply.
+
+	The serial argument will be that of the last
+	wp_tablet_pad_group.mode_switch event received for the group of this
+	ring. Requests providing other serials than the most recent one will be
+	ignored.
+      </description>
+      <arg name="description" type="string" summary="ring description"/>
+      <arg name="serial" type="uint" summary="serial of the mode switch event"/>
+    </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="degrees" type="fixed" summary="the current angle in degrees"/>
+    </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>
+    </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, and compositors may use this
+	information to offer visual feedback about the button layout
+	(eg. on-screen displays).
+
+	The provided string 'description' is a UTF-8 encoded string to be
+	associated with this ring, and is considered user-visible; general
+	internationalization rules apply.
+
+	The serial argument will be that of the last
+	wp_tablet_pad_group.mode_switch event received for the group of this
+	strip. Requests providing other serials than the most recent one will be
+	ignored.
+      </description>
+      <arg name="description" type="string" summary="strip description"/>
+      <arg name="serial" type="uint" summary="serial of the mode switch event"/>
+    </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>
+    </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_group_v2" version="2">
+    <description summary="a set of buttons, rings and strips">
+      A pad group describes a distinct (sub)set of buttons, rings and strips
+      present in the tablet. The criteria of this grouping is usually positional,
+      eg. if a tablet has buttons on left and right sides, 2 groups will be
+      presented. Clients should perform no further assumptions on the actual
+      position of each group.
+
+      Pad groups will announce their features during pad initialization. Between
+      the corresponding wp_tablet_pad.group event and wp_tablet_pad_group.done, the
+      pad group will announce the buttons, rings and strips comprised in it,
+      plus the number of supported modes.
+
+      Modes are a mechanism to allow multiple groups of actions for every element
+      in the pad group. The number of groups and available modes in each is
+      persistent across device plugs. The current mode is user-switchable and
+      compositor-global, it will be announced through the
+      wp_tablet_pad_group.mode_switch event both after wp_tablet_pad.enter, and
+      whenever it is switched.
+
+      The current mode logically applies to all elements in the pad group,
+      although it is at clients' discretion whether to actually perform different
+      actions, and/or issue the respective .set_feedback requests to notify the
+      compositor.
+    </description>
+
+    <request name="destroy" type="destructor">
+      <description summary="destroy the pad object">
+	Destroy the wp_tablet_pad_group object. Objects created from this object
+	are unaffected and should be destroyed separately.
+      </description>
+    </request>
+
+    <event name="buttons">
+      <description summary="buttons announced">
+	Sent on wp_tablet_pad_group initialization to announce the available
+	buttons in the group. Button indices start at 0, a button may only be
+	in one group at a time.
+
+	This event is first sent in the initial burst of events before the
+	wp_tablet_pad_group.done event.
+
+	Some buttons are reserved by the compositor. These buttons may not be
+	assigned to any wp_tablet_pad_group. Compositors may broadcast this
+	event in the case of changes to the mapping of these reserved buttons.
+	If the compositor happens to reserve all buttons in a group, this event
+	will be sent with an empty array.
+      </description>
+      <arg name="buttons" type="array" summary="buttons in this group"/>
+    </event>
+
+    <event name="ring">
+      <description summary="ring announced">
+	Sent on wp_tablet_pad_group initialization to announce available rings.
+	One event is sent for each ring available on this pad group.
+
+	This event is sent in the initial burst of events before the
+	wp_tablet_pad_group.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 group.
+
+	This event is sent in the initial burst of events before the
+	wp_tablet_pad_group.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="modes">
+      <description summary="mode-switch ability announced">
+	Sent on wp_tablet_pad_group initialization to announce that the pad
+	group 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_group.mode_switch event to toggle between these
+	configurations. Mode indices start at 0.
+
+	Switching modes is compositor-dependent. See the
+	wp_tablet_pad_group.mode_switch event for more details.
+
+	This event is sent in the initial burst of events before the
+	wp_tablet_pad_group.done event. This event is only sent when more than
+	more than one mode is available.
+      </description>
+      <arg name="modes" type="uint" summary="the number of modes"/>
+    </event>
+
+    <event name="done">
+      <description summary="tablet group description events sequence complete">
+	This event is sent immediately to signal the end of the initial
+	burst of descriptive events. A client may consider the static
+	description of the tablet to be complete and finalize initialization
+	of the tablet group.
+      </description>
+    </event>
+
+    <event name="mode_switch">
+      <description summary="mode switch event">
+	Notification that the mode was switched.
+
+	A mode applies to all buttons, rings and strips in a group
+	simultaneously, 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. Mode
+	indices start at 0.
+
+	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
+	controlled by one or more physical buttons. For example, on a Wacom
+	Intuos Pro, the button inside the ring may be assigned to switch
+	between modes.
+
+	The current mode is compositor-global, the compositor will also send
+	this event after wp_tablet_pad.enter on each group in order to notify
+	of the current mode. Groups that only feature one mode will use mode=0
+	when emitting this event.
+
+	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 strip 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"/>
+    </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.
+
+      All pad features (buttons, rings and strips) are logically divided into
+      groups and all pads have at least one group. The available groups are
+      notified through the wp_tablet_pad.group event; the compositor will
+      emit one event per group before emitting wp_tablet_pad.done.
+
+      Groups may have multiple modes. Modes allow clients to map multiple
+      actions to a single pad feature. Only one mode can be active per group,
+      although different groups may have different active modes.
+    </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).
+
+	Button indices start at 0. Setting the feedback string on a button
+	that is reserved by the compositor (i.e. not belonging to any
+	wp_tablet_pad_group) does not generate an error but the compositor
+	is free to ignore the request.
+
+	The provided string 'description' is a UTF-8 encoded string to be
+	associated with this ring, and is considered user-visible; general
+	internationalization rules apply.
+
+	The serial argument will be that of the last
+	wp_tablet_pad_group.mode_switch event received for the group of this
+	button. Requests providing other serials than the most recent one will
+	be ignored.
+      </description>
+      <arg name="button" type="uint" summary="button index"/>
+      <arg name="description" type="string" summary="button description"/>
+      <arg name="serial" type="uint" summary="serial of the mode switch event"/>
+    </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="group">
+      <description summary="group announced">
+	Sent on wp_tablet_pad initialization to announce available groups.
+	One event is sent for each pad group available.
+
+	This event is sent in the initial burst of events before the
+	wp_tablet_pad.done event. At least one group will be announced.
+      </description>
+      <arg name="pad_group" type="new_id" interface="zwp_tablet_pad_group_v2"/>
+    </event>
+
+    <event name="path">
+      <description summary="path to the device">
+	A system-specific device path that indicates which device is behind
+	this wp_tablet_pad. This information may be used to gather additional
+	information about the device, e.g. through libwacom.
+
+	The format of the path is unspecified, it may be a device node, a
+	sysfs path, or some other identifier. It is up to the client to
+	identify the string provided.
+
+	This event is sent in the initial burst of events before the
+	wp_tablet_pad.done event.
+      </description>
+      <arg name="path" type="string" summary="path to local device"/>
+    </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="uint" summary="the number of buttons"/>
+    </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 that caused 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="the index of the button that changed state"/>
+      <arg name="state" type="uint" enum="button_state"/>
+    </event>
+
+    <event name="enter">
+      <description summary="enter event">
+	Notification that this pad is focused on the specified surface.
+      </description>
+      <arg name="serial" type="uint" summary="serial number of the enter event"/>
+      <arg name="tablet" type="object" interface="zwp_tablet_v2" summary="the tablet the pad is attached to"/>
+      <arg name="surface" type="object" interface="wl_surface" summary="surface the pad is focused on"/>
+    </event>
+
+    <event name="leave">
+      <description summary="enter event">
+	Notification that this pad is no longer focused on the specified
+	surface.
+      </description>
+      <arg name="serial" type="uint" summary="serial number of the leave event"/>
+      <arg name="surface" type="object" interface="wl_surface" summary="surface the pad is no longer focused on"/>
+    </event>
+
+    <event name="removed">
+      <description summary="pad removed event">
+	Sent when the pad has been removed from the system. When a tablet
+	is removed its pad(s) will be removed too.
+
+	When this event is received, the client must wp_tablet_pad.destroy
+	the object, and chain-destroy all groups, rings and strips that have
+	been offered by this pad.
+      </description>
+    </event>
+  </interface>
+
 </protocol>
-- 
2.7.4



More information about the wayland-devel mailing list