| <?xml version="1.0" encoding="UTF-8"?> |
| <protocol name="tablet_unstable_v2"> |
| |
| <copyright> |
| Copyright 2014 © Stephen "Lyude" Chandler Paul |
| Copyright 2015-2016 © Red Hat, Inc. |
| |
| Permission is hereby granted, free of charge, to any person |
| obtaining a copy of this software and associated documentation files |
| (the "Software"), to deal in the Software without restriction, |
| including without limitation the rights to use, copy, modify, merge, |
| publish, distribute, sublicense, and/or sell copies of the Software, |
| and to permit persons to whom the Software is furnished to do so, |
| subject to the following conditions: |
| |
| The above copyright notice and this permission notice (including the |
| next paragraph) shall be included in all copies or substantial |
| portions of the Software. |
| |
| THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, |
| EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF |
| MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND |
| NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS |
| BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN |
| ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN |
| CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE |
| SOFTWARE. |
| </copyright> |
| |
| <description summary="Wayland protocol for graphics tablets"> |
| This description provides a high-level overview of the interplay between |
| the interfaces defined this protocol. For details, see the protocol |
| specification. |
| |
| More than one tablet may exist, and device-specifics matter. Tablets are |
| not represented by a single virtual device like wl_pointer. A client |
| binds to the tablet manager object which is just a proxy object. From |
| that, the client requests wp_tablet_manager.get_tablet_seat(wl_seat) |
| and that returns the actual interface that has all the tablets. With |
| this indirection, we can avoid merging wp_tablet into the actual Wayland |
| protocol, a long-term benefit. |
| |
| The wp_tablet_seat sends a "tablet added" event for each tablet |
| connected. That event is followed by descriptive events about the |
| hardware; currently that includes events for name, vid/pid and |
| a wp_tablet.path event that describes a local path. This path can be |
| used to uniquely identify a tablet or get more information through |
| libwacom. Emulated or nested tablets can skip any of those, e.g. a |
| virtual tablet may not have a vid/pid. The sequence of descriptive |
| events is terminated by a wp_tablet.done event to signal that a client |
| may now finalize any initialization for that tablet. |
| |
| Events from tablets require a tool in proximity. Tools are also managed |
| by the tablet seat; a "tool added" event is sent whenever a tool is new |
| to the compositor. That event is followed by a number of descriptive |
| events about the hardware; currently that includes capabilities, |
| hardware id and serial number, and tool type. Similar to the tablet |
| interface, a wp_tablet_tool.done event is sent to terminate that initial |
| sequence. |
| |
| Any event from a tool happens on the wp_tablet_tool interface. When the |
| tool gets into proximity of the tablet, a proximity_in event is sent on |
| the wp_tablet_tool interface, listing the tablet and the surface. That |
| event is followed by a motion event with the coordinates. After that, |
| it's the usual motion, axis, button, etc. events. The protocol's |
| serialisation means events are grouped by wp_tablet_tool.frame events. |
| |
| Two special events (that don't exist in X) are down and up. They signal |
| "tip touching the surface". For tablets without real proximity |
| detection, the sequence is: proximity_in, motion, down, frame. |
| |
| When the tool leaves proximity, a proximity_out event is sent. If any |
| button is still down, a button release event is sent before this |
| proximity event. These button events are sent in the same frame as the |
| proximity event to signal to the client that the buttons were held when |
| the tool left proximity. |
| |
| If the tool moves out of the surface but stays in proximity (i.e. |
| between windows), compositor-specific grab policies apply. This usually |
| means that the proximity-out is delayed until all buttons are released. |
| |
| Moving a tool physically from one tablet to the other has no real effect |
| on the protocol, since we already have the tool object from the "tool |
| added" event. All the information is already there and the proximity |
| events on both tablets are all a client needs to reconstruct what |
| happened. |
| |
| Some extra axes are normalized, i.e. the client knows the range as |
| specified in the protocol (e.g. [0, 65535]), the granularity however is |
| unknown. The current normalized axes are pressure, distance, and slider. |
| |
| Other extra axes are in physical units as specified in the protocol. |
| The current extra axes with physical units are tilt, rotation and |
| wheel rotation. |
| |
| Since tablets work independently of the pointer controlled by the mouse, |
| the focus handling is independent too and controlled by proximity. |
| The wp_tablet_tool.set_cursor request sets a tool-specific cursor. |
| This cursor surface may be the same as the mouse cursor, and it may be |
| the same across tools but it is possible to be more fine-grained. For |
| example, a client may set different cursors for the pen and eraser. |
| |
| Tools are generally independent of tablets and it is |
| compositor-specific policy when a tool can be removed. Common approaches |
| will likely include some form of removing a tool when all tablets the |
| tool was used on are removed. |
| |
| Warning! The protocol described in this file is experimental and |
| backward incompatible changes may be made. Backward compatible changes |
| may be added together with the corresponding interface version bump. |
| Backward incompatible changes are done by bumping the version number in |
| the protocol and interface names and resetting the interface version. |
| Once the protocol is to be declared stable, the 'z' prefix and the |
| version number in the protocol and interface names are removed and the |
| interface version number is reset. |
| </description> |
| |
| <interface name="zwp_tablet_manager_v2" version="1"> |
| <description summary="controller object for graphic tablet devices"> |
| An object that provides access to the graphics tablets available on this |
| system. All tablets are associated with a seat, to get access to the |
| actual tablets, use wp_tablet_manager.get_tablet_seat. |
| </description> |
| |
| <request name="get_tablet_seat"> |
| <description summary="get the tablet seat"> |
| Get the wp_tablet_seat object for the given seat. This object |
| provides access to all graphics tablets in this seat. |
| </description> |
| <arg name="tablet_seat" type="new_id" interface="zwp_tablet_seat_v2"/> |
| <arg name="seat" type="object" interface="wl_seat" summary="The wl_seat object to retrieve the tablets for" /> |
| </request> |
| |
| <request name="destroy" type="destructor"> |
| <description summary="release the memory for the tablet manager object"> |
| Destroy the wp_tablet_manager object. Objects created from this |
| object are unaffected and should be destroyed separately. |
| </description> |
| </request> |
| </interface> |
| |
| <interface name="zwp_tablet_seat_v2" version="1"> |
| <description summary="controller object for graphic tablet devices of a seat"> |
| An object that provides access to the graphics tablets available on this |
| seat. After binding to this interface, the compositor sends a set of |
| wp_tablet_seat.tablet_added and wp_tablet_seat.tool_added events. |
| </description> |
| |
| <request name="destroy" type="destructor"> |
| <description summary="release the memory for the tablet seat object"> |
| Destroy the wp_tablet_seat object. Objects created from this |
| object are unaffected and should be destroyed separately. |
| </description> |
| </request> |
| |
| <event name="tablet_added"> |
| <description summary="new device notification"> |
| This event is sent whenever a new tablet becomes available on this |
| seat. This event only provides the object id of the tablet, any |
| static information about the tablet (device name, vid/pid, etc.) is |
| sent through the wp_tablet interface. |
| </description> |
| <arg name="id" type="new_id" interface="zwp_tablet_v2" summary="the newly added graphics tablet"/> |
| </event> |
| |
| <event name="tool_added"> |
| <description summary="a new tool has been used with a tablet"> |
| This event is sent whenever a tool that has not previously been used |
| with a tablet comes into use. This event only provides the object id |
| of the tool; any static information about the tool (capabilities, |
| type, etc.) is sent through the wp_tablet_tool interface. |
| </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"> |
| <description summary="a physical tablet tool"> |
| An object that represents a physical tool that has been, or is |
| currently in use with a tablet in this seat. Each wp_tablet_tool |
| object stays valid until the client destroys it; the compositor |
| reuses the wp_tablet_tool object to indicate that the object's |
| respective physical tool has come into proximity of a tablet again. |
| |
| A wp_tablet_tool object's relation to a physical tool depends on the |
| tablet's ability to report serial numbers. If the tablet supports |
| this capability, then the object represents a specific physical tool |
| and can be identified even when used on multiple tablets. |
| |
| A tablet tool has a number of static characteristics, e.g. tool type, |
| hardware_serial and capabilities. These capabilities are sent in an |
| event sequence after the wp_tablet_seat.tool_added event before any |
| actual events from this tool. This initial event sequence is |
| terminated by a wp_tablet_tool.done event. |
| |
| Tablet tool events are grouped by wp_tablet_tool.frame events. |
| Any events received before a wp_tablet_tool.frame event should be |
| considered part of the same hardware state change. |
| </description> |
| |
| <request name="set_cursor"> |
| <description summary="set the tablet tool's surface"> |
| Sets the surface of the cursor used for this tool on the given |
| tablet. This request only takes effect if the tool is in proximity |
| of one of the requesting client's surfaces or the surface parameter |
| is the current pointer surface. If there was a previous surface set |
| with this request it is replaced. If surface is NULL, the cursor |
| image is hidden. |
| |
| The parameters hotspot_x and hotspot_y define the position of the |
| pointer surface relative to the pointer location. Its top-left corner |
| is always at (x, y) - (hotspot_x, hotspot_y), where (x, y) are the |
| coordinates of the pointer location, in surface-local coordinates. |
| |
| On surface.attach requests to the pointer surface, hotspot_x and |
| hotspot_y are decremented by the x and y parameters passed to the |
| request. Attach must be confirmed by wl_surface.commit as usual. |
| |
| The hotspot can also be updated by passing the currently set pointer |
| surface to this request with new values for hotspot_x and hotspot_y. |
| |
| The current and pending input regions of the wl_surface are cleared, |
| and wl_surface.set_input_region is ignored until the wl_surface is no |
| longer used as the cursor. When the use as a cursor ends, the current |
| and pending input regions become undefined, and the wl_surface is |
| unmapped. |
| |
| This request gives the surface the role of a wp_tablet_tool cursor. A |
| surface may only ever be used as the cursor surface for one |
| wp_tablet_tool. If the surface already has another role or has |
| previously been used as cursor surface for a different tool, a |
| protocol error is raised. |
| </description> |
| <arg name="serial" type="uint" summary="serial of the enter event"/> |
| <arg name="surface" type="object" interface="wl_surface" allow-null="true"/> |
| <arg name="hotspot_x" type="int" summary="surface-local x coordinate"/> |
| <arg name="hotspot_y" type="int" summary="surface-local y coordinate"/> |
| </request> |
| |
| <request name="destroy" type="destructor"> |
| <description summary="destroy the tool object"> |
| This destroys the client's resource for this tool object. |
| </description> |
| </request> |
| |
| <enum name="type"> |
| <description summary="a physical tool type"> |
| Describes the physical type of a tool. The physical type of a tool |
| generally defines its base usage. |
| |
| The mouse tool represents a mouse-shaped tool that is not a relative |
| device but bound to the tablet's surface, providing absolute |
| coordinates. |
| |
| The lens tool is a mouse-shaped tool with an attached lens to |
| provide precision focus. |
| </description> |
| <entry name="pen" value="0x140" summary="Pen"/> |
| <entry name="eraser" value="0x141" summary="Eraser"/> |
| <entry name="brush" value="0x142" summary="Brush"/> |
| <entry name="pencil" value="0x143" summary="Pencil"/> |
| <entry name="airbrush" value="0x144" summary="Airbrush"/> |
| <entry name="finger" value="0x145" summary="Finger"/> |
| <entry name="mouse" value="0x146" summary="Mouse"/> |
| <entry name="lens" value="0x147" summary="Lens"/> |
| </enum> |
| |
| <event name="type"> |
| <description summary="tool type"> |
| The tool type is the high-level type of the tool and usually decides |
| the interaction expected from this tool. |
| |
| This event is sent in the initial burst of events before the |
| wp_tablet_tool.done event. |
| </description> |
| <arg name="tool_type" type="uint" enum="type" summary="the physical tool type"/> |
| </event> |
| |
| <event name="hardware_serial"> |
| <description summary="unique hardware serial number of the tool"> |
| If the physical tool can be identified by a unique 64-bit serial |
| number, this event notifies the client of this serial number. |
| |
| If multiple tablets are available in the same seat and the tool is |
| uniquely identifiable by the serial number, that tool may move |
| between tablets. |
| |
| Otherwise, if the tool has no serial number and this event is |
| missing, the tool is tied to the tablet it first comes into |
| proximity with. Even if the physical tool is used on multiple |
| tablets, separate wp_tablet_tool objects will be created, one per |
| tablet. |
| |
| This event is sent in the initial burst of events before the |
| wp_tablet_tool.done event. |
| </description> |
| <arg name="hardware_serial_hi" type="uint" summary="the unique serial number of the tool, most significant bits"/> |
| <arg name="hardware_serial_lo" type="uint" summary="the unique serial number of the tool, least significant bits"/> |
| </event> |
| |
| <event name="hardware_id_wacom"> |
| <description summary="hardware id notification in Wacom's format"> |
| This event notifies the client of a hardware id available on this tool. |
| |
| The hardware id is a device-specific 64-bit id that provides extra |
| information about the tool in use, beyond the wl_tool.type |
| enumeration. The format of the id is specific to tablets made by |
| Wacom Inc. For example, the hardware id of a Wacom Grip |
| Pen (a stylus) is 0x802. |
| |
| This event is sent in the initial burst of events before the |
| wp_tablet_tool.done event. |
| </description> |
| <arg name="hardware_id_hi" type="uint" summary="the hardware id, most significant bits"/> |
| <arg name="hardware_id_lo" type="uint" summary="the hardware id, least significant bits"/> |
| </event> |
| |
| <enum name="capability"> |
| <description summary="capability flags for a tool"> |
| Describes extra capabilities on a tablet. |
| |
| Any tool must provide x and y values, extra axes are |
| device-specific. |
| </description> |
| <entry name="tilt" value="1" summary="Tilt axes"/> |
| <entry name="pressure" value="2" summary="Pressure axis"/> |
| <entry name="distance" value="3" summary="Distance axis"/> |
| <entry name="rotation" value="4" summary="Z-rotation axis"/> |
| <entry name="slider" value="5" summary="Slider axis"/> |
| <entry name="wheel" value="6" summary="Wheel axis"/> |
| </enum> |
| |
| <event name="capability"> |
| <description summary="tool capability notification"> |
| This event notifies the client of any capabilities of this tool, |
| beyond the main set of x/y axes and tip up/down detection. |
| |
| One event is sent for each extra capability available on this tool. |
| |
| This event is sent in the initial burst of events before the |
| wp_tablet_tool.done event. |
| </description> |
| <arg name="capability" type="uint" enum="capability" summary="the capability"/> |
| </event> |
| |
| <event name="done"> |
| <description summary="tool description events sequence complete"> |
| This event signals the end of the initial burst of descriptive |
| events. A client may consider the static description of the tool to |
| be complete and finalize initialization of the tool. |
| </description> |
| </event> |
| |
| <event name="removed"> |
| <description summary="tool removed"> |
| This event is sent when the tool is removed from the system and will |
| send no further events. Should the physical tool come back into |
| proximity later, a new wp_tablet_tool object will be created. |
| |
| It is compositor-dependent when a tool is removed. A compositor may |
| remove a tool on proximity out, tablet removal or any other reason. |
| A compositor may also keep a tool alive until shutdown. |
| |
| If the tool is currently in proximity, a proximity_out event will be |
| sent before the removed event. See wp_tablet_tool.proximity_out for |
| the handling of any buttons logically down. |
| |
| When this event is received, the client must wp_tablet_tool.destroy |
| the object. |
| </description> |
| </event> |
| |
| <event name="proximity_in"> |
| <description summary="proximity in event"> |
| Notification that this tool is focused on a certain surface. |
| |
| This event can be received when the tool has moved from one surface to |
| another, or when the tool has come back into proximity above the |
| surface. |
| |
| If any button is logically down when the tool comes into proximity, |
| the respective button event is sent after the proximity_in event but |
| within the same frame as the proximity_in event. |
| </description> |
| <arg name="serial" type="uint"/> |
| <arg name="tablet" type="object" interface="zwp_tablet_v2" summary="The tablet the tool is in proximity of"/> |
| <arg name="surface" type="object" interface="wl_surface" summary="The current surface the tablet tool is over"/> |
| </event> |
| |
| <event name="proximity_out"> |
| <description summary="proximity out event"> |
| Notification that this tool has either left proximity, or is no |
| longer focused on a certain surface. |
| |
| When the tablet tool leaves proximity of the tablet, button release |
| events are sent for each button that was held down at the time of |
| leaving proximity. These events are sent before the proximity_out |
| event but within the same wp_tablet.frame. |
| |
| If the tool stays within proximity of the tablet, but the focus |
| changes from one surface to another, a button release event may not |
| be sent until the button is actually released or the tool leaves the |
| proximity of the tablet. |
| </description> |
| </event> |
| |
| <event name="down"> |
| <description summary="tablet tool is making contact"> |
| Sent whenever the tablet tool comes in contact with the surface of the |
| tablet. |
| |
| If the tool is already in contact with the tablet when entering the |
| input region, the client owning said region will receive a |
| wp_tablet.proximity_in event, followed by a wp_tablet.down |
| event and a wp_tablet.frame event. |
| |
| Note that this event describes logical contact, not physical |
| contact. On some devices, a compositor may not consider a tool in |
| logical contact until a minimum physical pressure threshold is |
| exceeded. |
| </description> |
| <arg name="serial" type="uint"/> |
| </event> |
| |
| <event name="up"> |
| <description summary="tablet tool is no longer making contact"> |
| Sent whenever the tablet tool stops making contact with the surface of |
| the tablet, or when the tablet tool moves out of the input region |
| and the compositor grab (if any) is dismissed. |
| |
| If the tablet tool moves out of the input region while in contact |
| with the surface of the tablet and the compositor does not have an |
| ongoing grab on the surface, the client owning said region will |
| receive a wp_tablet.up event, followed by a wp_tablet.proximity_out |
| event and a wp_tablet.frame event. If the compositor has an ongoing |
| grab on this device, this event sequence is sent whenever the grab |
| is dismissed in the future. |
| |
| Note that this event describes logical contact, not physical |
| contact. On some devices, a compositor may not consider a tool out |
| of logical contact until physical pressure falls below a specific |
| threshold. |
| </description> |
| </event> |
| |
| <event name="motion"> |
| <description summary="motion event"> |
| Sent whenever a tablet tool moves. |
| </description> |
| <arg name="x" type="fixed" summary="surface-local x coordinate"/> |
| <arg name="y" type="fixed" summary="surface-local y coordinate"/> |
| </event> |
| |
| <event name="pressure"> |
| <description summary="pressure change event"> |
| Sent whenever the pressure axis on a tool changes. The value of this |
| event is normalized to a value between 0 and 65535. |
| |
| Note that pressure may be nonzero even when a tool is not in logical |
| contact. See the down and up events for more details. |
| </description> |
| <arg name="pressure" type="uint" summary="The current pressure value"/> |
| </event> |
| |
| <event name="distance"> |
| <description summary="distance change event"> |
| Sent whenever the distance axis on a tool changes. The value of this |
| event is normalized to a value between 0 and 65535. |
| |
| Note that distance may be nonzero even when a tool is not in logical |
| contact. See the down and up events for more details. |
| </description> |
| <arg name="distance" type="uint" summary="The current distance value"/> |
| </event> |
| |
| <event name="tilt"> |
| <description summary="tilt change event"> |
| Sent whenever one or both of the tilt axes on a tool change. Each tilt |
| value is in degrees, relative to the z-axis of the tablet. |
| The angle is positive when the top of a tool tilts along the |
| positive x or y axis. |
| </description> |
| <arg name="tilt_x" type="fixed" summary="The current value of the X tilt axis"/> |
| <arg name="tilt_y" type="fixed" summary="The current value of the Y tilt axis"/> |
| </event> |
| |
| <event name="rotation"> |
| <description summary="z-rotation change event"> |
| Sent whenever the z-rotation axis on the tool changes. The |
| rotation value is in degrees clockwise from the tool's |
| logical neutral position. |
| </description> |
| <arg name="degrees" type="fixed" summary="The current rotation of the Z axis"/> |
| </event> |
| |
| <event name="slider"> |
| <description summary="Slider position change event"> |
| Sent whenever the slider position on the tool changes. The |
| value is normalized between -65535 and 65535, with 0 as the logical |
| neutral position of the slider. |
| |
| The slider is available on e.g. the Wacom Airbrush tool. |
| </description> |
| <arg name="position" type="int" summary="The current position of slider"/> |
| </event> |
| |
| <event name="wheel"> |
| <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 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 |
| than one logical click. |
| |
| Clients should choose either value and avoid mixing degrees and |
| clicks. The compositor may accumulate values smaller than a logical |
| click and emulate click events when a certain threshold is met. |
| Thus, wl_tablet_tool.wheel events with non-zero clicks values may |
| have different degrees values. |
| </description> |
| <arg name="degrees" type="fixed" summary="The wheel delta in degrees"/> |
| <arg name="clicks" type="int" summary="The wheel delta in discrete clicks"/> |
| </event> |
| |
| <enum name="button_state"> |
| <description summary="physical button state"> |
| Describes the physical state of a button that produced the button event. |
| </description> |
| <entry name="released" value="0" summary="button is not pressed"/> |
| <entry name="pressed" value="1" summary="button is pressed"/> |
| </enum> |
| |
| <event name="button"> |
| <description summary="button event"> |
| Sent whenever a button on the tool is pressed or released. |
| |
| If a button is held down when the tool moves in or out of proximity, |
| button events are generated by the compositor. See |
| wp_tablet_tool.proximity_in and wp_tablet_tool.proximity_out for |
| details. |
| </description> |
| <arg name="serial" type="uint"/> |
| <arg name="button" type="uint" summary="The button whose state has changed"/> |
| <arg name="state" type="uint" enum="button_state" summary="Whether the button was pressed or released"/> |
| </event> |
| |
| <event name="frame"> |
| <description summary="frame event"> |
| Marks the end of a series of axis and/or button updates from the |
| tablet. The Wayland protocol requires axis updates to be sent |
| sequentially, however all events within a frame should be considered |
| one hardware event. |
| </description> |
| <arg name="time" type="uint" summary="The time of the event with millisecond granularity"/> |
| </event> |
| |
| <enum name="error"> |
| <entry name="role" value="0" summary="given wl_surface has another role"/> |
| </enum> |
| </interface> |
| |
| <interface name="zwp_tablet_v2" version="1"> |
| <description summary="graphics tablet device"> |
| The wp_tablet interface represents one graphics tablet device. The |
| tablet interface itself does not generate events; all events are |
| generated by wp_tablet_tool objects when in proximity above a tablet. |
| |
| A tablet has a number of static characteristics, e.g. device name and |
| pid/vid. These capabilities are sent in an event sequence after the |
| wp_tablet_seat.tablet_added event. This initial event sequence is |
| terminated by a wp_tablet.done event. |
| </description> |
| |
| <request name="destroy" type="destructor"> |
| <description summary="destroy the tablet object"> |
| This destroys the client's resource for this tablet object. |
| </description> |
| </request> |
| |
| <event name="name"> |
| <description summary="tablet device name"> |
| This event is sent in the initial burst of events before the |
| wp_tablet.done event. |
| </description> |
| <arg name="name" type="string" summary="the device name"/> |
| </event> |
| |
| <event name="id"> |
| <description summary="tablet device USB vendor/product id"> |
| This event is sent in the initial burst of events before the |
| wp_tablet.done event. |
| </description> |
| <arg name="vid" type="uint" summary="USB vendor id"/> |
| <arg name="pid" type="uint" summary="USB product id"/> |
| </event> |
| |
| <event name="path"> |
| <description summary="path to the device"> |
| A system-specific device path that indicates which device is behind |
| this wp_tablet. This information may be used to gather additional |
| information about the device, e.g. through libwacom. |
| |
| A device may have more than one device path. If so, multiple |
| wp_tablet.path events are sent. A device may be emulated and not |
| have a device path, and in that case this event will not be sent. |
| |
| 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.done event. |
| </description> |
| <arg name="path" type="string" summary="path to local device"/> |
| </event> |
| |
| <event name="done"> |
| <description summary="tablet 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. |
| </description> |
| </event> |
| |
| <event name="removed"> |
| <description summary="tablet removed event"> |
| Sent when the tablet has been removed from the system. When a tablet |
| is removed, some tools may be removed. |
| |
| When this event is received, the client must wp_tablet.destroy |
| the object. |
| </description> |
| </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> |