diff options
Diffstat (limited to 'unstable/tablet')
| -rw-r--r-- | unstable/tablet/tablet-unstable-v2.xml | 540 |
1 files changed, 540 insertions, 0 deletions
diff --git a/unstable/tablet/tablet-unstable-v2.xml b/unstable/tablet/tablet-unstable-v2.xml index 77b185c..728a3df 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 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> |