[PATCH wayland-protocols v5 4/4] tablet: Add pad support to the tablet protocol
Jason Gerecke
killertofu at gmail.com
Mon Jul 11 19:20:30 UTC 2016
On 07/11/2016 08:13 AM, Carlos Garnacho wrote:
> 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>
> ---
> unstable/tablet/tablet-unstable-v2.xml | 540 +++++++++++++++++++++++++++++++++
> 1 file changed, 540 insertions(+)
>
> diff --git a/unstable/tablet/tablet-unstable-v2.xml b/unstable/tablet/tablet-unstable-v2.xml
> index 77b185c..2cc3a92 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">
> @@ -636,4 +652,528 @@
> </event>
> </interface>
>
> + <interface name="zwp_tablet_pad_ring_v2" version="1">
> + <description summary="pad ring">
> + A circular interaction area, such as the touch ring on the Wacom Intuos
> + Pro series tablets.
> +
> + 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_group.mode_switch event from the corresponding
> + group is received, or whenever the ring is mapped to a different
> + action. See wp_tablet_pad_group.mode_switch for more details.
> +
> + 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" enum="source" 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="1">
> + <description summary="pad strip">
> + A linear interaction area, such as the strips found in Wacom Cintiq
> + models.
> +
> + 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_group.mode_switch event from the corresponding
> + group is received, or whenever the strip is mapped to a different
> + action. See wp_tablet_pad_group.mode_switch for more details.
> +
> + 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" enum="source" 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="1">
> + <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 the left and right side, 2 groups will be
> + presented. The physical arrangement of groups is undisclosed and may
> + change on the fly.
> +
> + 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,
Nit: s/comprised/contained/ (or, alternately, "that comprise it")
Thanks for sending out the update with the global language removed.
Looks good to me! :)
Reviewed-Hopefully-For-The-Last-Time-By: Jason Gerecke
<jason.gerecke at wacom.com>
Jason
---
Now instead of four in the eights place /
you’ve got three, ‘Cause you added one /
(That is to say, eight) to the two, /
But you can’t take seven from three, /
So you look at the sixty-fours....
> + 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, it
> + will be announced through the wp_tablet_pad_group.mode_switch event both
> + whenever it is switched, and after wp_tablet_pad.enter.
> +
> + 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. See the wp_tablet_pad_group.mode_switch event for more details.
> + </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.
> + </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.
> + </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 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="1">
> + <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_group.mode_switch event from the corresponding
> + group is received, or whenever a button is mapped to a different
> + action. See wp_tablet_pad_group.mode_switch for more details.
> +
> + 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 destroy all rings, strips
> + and groups that were offered by this pad, and issue wp_tablet_pad.destroy
> + the pad itself.
> + </description>
> + </event>
> + </interface>
> </protocol>
>
More information about the wayland-devel
mailing list