diff options
Diffstat (limited to 'protocols/tablet-unstable-v2.xml')
| -rw-r--r-- | protocols/tablet-unstable-v2.xml | 1178 |
1 files changed, 0 insertions, 1178 deletions
diff --git a/protocols/tablet-unstable-v2.xml b/protocols/tablet-unstable-v2.xml deleted file mode 100644 index b286d964..00000000 --- a/protocols/tablet-unstable-v2.xml +++ /dev/null @@ -1,1178 +0,0 @@ -<?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> |