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

Wed May 11 14:20:15 UTC 2016

On May 10, 2016, at 9: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>

Hi Carlos and Peter,
I have some suggestions and corrections, noted inline below.

yong

> ---
> 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

This event only provides the object id of the pad. All further pad features

> +	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

a UTF-8

> +	associated with this ring, and is considered user visible; general

user-visible or perhaps just "and is visible by the user;"

> +	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"/>

Perhaps the summary should mention units, eg "the current angle in degrees,"
similar to the wheel event's degrees arg summary.

> +    </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.

Single paragraph, or premature line break after "terminated."?

> +
> +	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.

Minor nit: put "event." on the previous line.

> +
> +	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,

Double space should be single, consistent with everything else.

> +	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

, and compositors may

> +	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

a UTF-8

> +	associated with this ring, and is considered user visible; general
> +	internationalization rules apply.

user-visible or perhaps just "and is visible by the user;"

> +      </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

Double space should be single, consistent with everything else.

> +	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,

Double space should be single, consistent with everything else.

> +	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

a UTF-8

> +	associated with this ring, and is considered user visible; general
> +	internationalization rules apply.

user-visible or perhaps just "and is visible by the user;"

> +      </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

and 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

"This event may be sent" or "This event is sent".

> +	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">
> +      <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.

"a button that caused" or "that invoked" may be more appropriate here.
(But definitely "that" instead of "which.")

> +      </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"/>
> +      <arg name="state" type="uint" enum="button_state"/>
> +    </event>
> +
> +    <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

A mode applies to all buttons, rings and strips simultaneously, but
(Helps clarify)

> +	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

software-controlled or controlled by one or more physical buttons.

> +	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

If a ring or strip 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"/>

summary="serial number of the mode switch event"
(matches wayland.xml)

> +      <arg name="mode" type="uint" summary="the new mode of the pad"/>
> +    </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"
(matches wayland.xml)

> +      <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="the 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"/>
> +      <arg name="surface" type="object" interface="wl_surface"/>

      <arg name="serial" type="uint" summary="serial number of the leave event"/>
      <arg name="surface" type="object" interface="wl_surface" summary="the 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 wp_tablet_pad_strip.destroy/wp_tablet_pad_ring.destroy
> +	on all strips/rings offered by this pad.
> +      </description>
> +    </event>
> +  </interface>
> +
> </protocol>
> -- 
> 2.7.4