1179 lines
50 KiB
XML
1179 lines
50 KiB
XML
|
<?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>
|