[PATCH v4 wayland-protocols 4/4] tablet: Add pad support to the tablet protocol
Carlos Garnacho
carlosg at gnome.org
Thu Jun 30 11:10:33 UTC 2016
Hi!,
On Thu, Jun 30, 2016 at 6:27 AM, Jonas Ådahl <jadahl at gmail.com> wrote:
> On Tue, Jun 28, 2016 at 11:21:50PM +0200, 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>
>> ---
>>
>> 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
>
> This change seems unrelated.
It indeed is...
>
>> 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.
>
> Here it says that the serial must come from the mode_switch event, but
> at the same time it says the request should be issued immediately after
> the enter event. This creates an impossible requirement as the
> mode_switch event will come after the enter event.
Oh, right. That's a leftover from the earlier drafts which had
client-local mode tracking. This should always be sent after
.mode_switch events (although you'll certainly get one after .enter).
I'm changing the first paragraph to:
"... This request should be issued 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"
Same for strips/buttons.
>
>> + </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"/>
>
> Should add the enum attribute here.
Yup, done.
>
>> + </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">
>
> The version should stay "1" here I suppose. The _v2 version patches has
> not been merged, so this new addition would just be part of the backward
> incompatible _v2 update.
Oops, yeah, didn't notice this is already addressed in patches 1 to 3
from the previous series from Peter. Changed locally all over the
place.
>
>> + <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.
>
> Same here about enter vs mode_switch event triggering the request.
Yup.
>
>> + </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"/>
>
> Missing enum attribute.
Already added :).
>
>> + </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">
>
> Same here about versioning.
>
>> + <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.
>
> The last sentence is redundant. It already says that there'll be one
> event per ring, thus no rings, no events. It also makes it slightly
> unclear (by the description alone) whethere multiple rings will result
> in multiple events.
Agreed, removed. As for the last part... I guess the "One event is
sent for each ring available..." bit makes it clear enough already?
>
>> + </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.
>
> Same here about reduncancy and possible confusion.
Yup.
>
>> + </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
>
> Isn't it just seat global? And why would this event be on the pad group
> and not on the seat wide interface?
perhaps I should expand that first phrase :).
The extent of the current mode is pretty much group local, it only
affects the buttons/rings/strips that have been announced through this
group.
However, the current mode of every given group is global to all
clients. If you have a client focused with a group in mode=1, focus
another client, switch that group to mode=3 and go back to the first
client, you'll receive a .mode_switch with mode=3 after
wp_tablet_pad.enter.
This could be considered similar to keyboard modifiers, you don't
reset those (eg. caps lock) when focusing another client, the current
state is rather propagated to the newly focused client.
I'm replacing the beginning of that paragraph with this:
"Compositors will globally track the current mode that every
wp_tablet_pad_group has. This event will also be sent after
wp_tablet_pad.enter for all groups in the pad in order to..."
>
> On the other hand, in the pad group interface it says that "The current
> mode logically applies to all elements in the pad group", which sounds a
> bit contradicting.
After the explanation and the change above, does this make more sense
to you now?
>
>> + 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">
>
> Here again about versioning.
>
>> + <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.
>
> This is contradictive with the above text saying that the current mode
> is compositor-wide.
Same than above, after the rewording above, do you see any change needed here?
>
>> + </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.
>
> Same here about enter vs mode_switch event.
>
>> + </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.
>
> Does this mean the objects are destroyed in the order they are created,
> i.e. parent first, then children? In other protocols, the opposite has
> been enforced, i.e. child objects are destroyed before parent objects.
Oh, this can be surely inverted, changing locally.
Cheers,
Carlos
More information about the wayland-devel
mailing list