fdo-mirrors/wayland-protocols
1
0
Fork 0
mirror of https://gitlab.freedesktop.org/wayland/wayland-protocols.git synced 2025-12-28 16:50:18 +01:00
Code Issues Projects Releases Packages Wiki Activity Actions

tablet: Add pad support to the tablet protocol

Browse source 
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 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@gnome.org>
Signed-off-by: Peter Hutterer <peter.hutterer@who-t.net>
Reviewed-by: Jason Gerecke <jason.gerecke@wacom.com>
Reviewed-by: Bryce Harrington <bryce@osg.samsung.com>
Reviewed-by: Jonas Ådahl <jadahl@gmail.com>
This commit is contained in:
Carlos Garnacho 2016-07-11 17:13:36 +02:00 • committed by Jonas Ådahl
parent 8123c92b6f
commit 24eb6700e4
1 changed files with 540 additions and 0 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

540
unstable/tablet/tablet-unstable-v2.xml
View file

@ -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 contained 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, 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>