mirror of
https://gitlab.freedesktop.org/wayland/wayland-protocols.git
synced 2026-05-03 17:08:08 +02:00
Merge branch 'wip/tablet-updates' into 'main'
Draft: tablet: add support for scrolling, relative dials and bustype See merge request wayland/wayland-protocols!285
This commit is contained in:
Peter Hutterer
commit
e2182900d4
1 changed files with 324 additions and 12 deletions
|
|
@ -3,7 +3,7 @@
|
|||
|
||||
<copyright>
|
||||
Copyright 2014 © Stephen "Lyude" Chandler Paul
|
||||
Copyright 2015-2016 © Red Hat, Inc.
|
||||
Copyright 2015-2024 © Red Hat, Inc.
|
||||
|
||||
Permission is hereby granted, free of charge, to any person
|
||||
obtaining a copy of this software and associated documentation files
|
||||
|
|
@ -110,7 +110,7 @@
|
|||
canonical version can be found in the stable/ directory.
|
||||
</description>
|
||||
|
||||
<interface name="zwp_tablet_manager_v2" version="1">
|
||||
<interface name="zwp_tablet_manager_v2" version="2">
|
||||
<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
|
||||
|
|
@ -134,7 +134,7 @@
|
|||
</request>
|
||||
</interface>
|
||||
|
||||
<interface name="zwp_tablet_seat_v2" version="1">
|
||||
<interface name="zwp_tablet_seat_v2" version="2">
|
||||
<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
|
||||
|
|
@ -185,7 +185,7 @@
|
|||
</event>
|
||||
</interface>
|
||||
|
||||
<interface name="zwp_tablet_tool_v2" version="1">
|
||||
<interface name="zwp_tablet_tool_v2" version="2">
|
||||
<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
|
||||
|
|
@ -569,9 +569,110 @@
|
|||
<enum name="error">
|
||||
<entry name="role" value="0" summary="given wl_surface has another role"/>
|
||||
</enum>
|
||||
|
||||
<!-- version 2 -->
|
||||
<event name="scroll" since="2">
|
||||
<description summary="scroll event">
|
||||
Scroll event notification.
|
||||
|
||||
This event indicates a logical scroll motion along the x and/or y axis.
|
||||
The x and y values are relative deltas of the scroll motion in a coordinate
|
||||
space identical to those of motion events. When applicable, a client can
|
||||
transform its content relative to the scroll distance.
|
||||
|
||||
A compositor must not send a scroll event with both x and y on zero.
|
||||
|
||||
A scroll event may occur outside a scroll_start/scroll_stop sequence to
|
||||
indicate it is a standalone event. This may happen if the compositor is
|
||||
unable to detect boundary conditions (e.g. finger down or button down) and
|
||||
can thus only provide the scroll events. It is up to the client on how to
|
||||
process these events (e.g. whether to provide kinetic scrolling).
|
||||
|
||||
If a scroll_start event is sent by the compositor, all scroll events until
|
||||
a subsequent scroll_stop are part of the same scroll gesture.
|
||||
|
||||
The timestamp of this event is that of the corresponding frame event.
|
||||
|
||||
The scroll and scroll_v120 events are mutually exclusive and must
|
||||
not occur in the same frame.
|
||||
</description>
|
||||
<arg name="x" type="fixed" summary="length of vector in surface-local coordinate space"/>
|
||||
<arg name="y" type="fixed" summary="length of vector in surface-local coordinate space"/>
|
||||
</event>
|
||||
|
||||
<event name="scroll_v120" since="2">
|
||||
<description summary="high-resolution scroll event">
|
||||
Discrete high-resolution scroll information.
|
||||
|
||||
The values of this event is interpreted identical to the
|
||||
wl_pointer.axis_value120 event as of wl_pointer version 8.
|
||||
|
||||
A compositor must not send a scroll_v120 event with both x and y on zero.
|
||||
|
||||
This event carries high-resolution wheel scroll information,
|
||||
with each multiple of 120 representing one logical scroll step
|
||||
(a wheel detent). For example, an scroll_v120 value of 30 is one
|
||||
quarter of a logical scroll step in the positive direction, a value of
|
||||
-240 are two logical scroll steps in the negative direction within the
|
||||
same hardware event.
|
||||
Clients that rely on discrete scrolling should accumulate the
|
||||
values to multiples of 120 before processing the event.
|
||||
|
||||
The timestamp of this event is that of the corresponding frame event.
|
||||
|
||||
The scroll and scroll_v120 events are mutually exclusive and must
|
||||
not occur in the same frame.
|
||||
|
||||
scroll_v120 events may be part of a scroll_start/scroll_stop sequence and follow
|
||||
the same semantics as the scroll event. See the scroll event documentation for
|
||||
details.
|
||||
</description>
|
||||
<arg name="x" type="int" summary="scroll distance as fraction of 120"/>
|
||||
<arg name="y" type="int" summary="scroll distance as fraction of 120"/>
|
||||
</event>
|
||||
|
||||
<event name="scroll_start" since="2">
|
||||
<description summary="scroll sequence start event">
|
||||
Notification about the start of a logical scroll sequence.
|
||||
|
||||
This event signals that a user has initiated a scroll sequence (e.g. by
|
||||
touching a scrollable hardware surface or pressing a button).
|
||||
Such a sequence must comprise of exactly one scroll_start event
|
||||
followed by zero or more scroll or scroll_v120 events and then exactly one
|
||||
scroll_stop event.
|
||||
|
||||
The timestamp of this event is that of the corresponding frame event.
|
||||
|
||||
A scroll_start event may occur in the same frame as a scroll and scroll_v120 event.
|
||||
A scroll_start event may occur in the same frame as a scroll_stop event.
|
||||
</description>
|
||||
<arg name="serial" type="uint" summary="serial of the scroll_start event"/>
|
||||
</event>
|
||||
|
||||
<event name="scroll_stop" since="2">
|
||||
<description summary="scroll sequence stop event">
|
||||
Notification about the end of a logical scroll sequence.
|
||||
|
||||
This event signals that a user has stopped interacting with a scroll sequence
|
||||
(e.g. by lifting a finger or releasing a button).
|
||||
Such a sequence must comprise of exactly one scroll_start event
|
||||
followed by zero or more scroll or scroll_v120 events and then exactly one
|
||||
scroll_stop event.
|
||||
|
||||
If cancelled is nonzero, the scroll sequence was cancelled and a client should
|
||||
attempt to undo any state changes made by this seqeuence.
|
||||
|
||||
The timestamp of this event is that of the corresponding frame event.
|
||||
|
||||
A scroll_stop event may occur in the same frame as a scroll and scroll_v120 event.
|
||||
A scroll_stop event may occur in the same frame as a scroll_start event.
|
||||
</description>
|
||||
<arg name="serial" type="uint" summary="serial of the scroll_stop event"/>
|
||||
<arg name="cancelled" type="uint" summary="this scroll sequence was cancelled"/>
|
||||
</event>
|
||||
</interface>
|
||||
|
||||
<interface name="zwp_tablet_v2" version="1">
|
||||
<interface name="zwp_tablet_v2" version="2">
|
||||
<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
|
||||
|
|
@ -653,9 +754,21 @@
|
|||
the object.
|
||||
</description>
|
||||
</event>
|
||||
|
||||
<!-- Version 2 -->
|
||||
<event name="bustype" since="2">
|
||||
<description summary="tablet device bus type">
|
||||
The bustype argument is one of the BUS_ defines in the Linux kernel's
|
||||
linux/input.h
|
||||
|
||||
This event is sent in the initial burst of events before the
|
||||
wp_tablet.done event.
|
||||
</description>
|
||||
<arg name="bustype" type="uint" summary="Bus type"/>
|
||||
</event>
|
||||
</interface>
|
||||
|
||||
<interface name="zwp_tablet_pad_ring_v2" version="1">
|
||||
<interface name="zwp_tablet_pad_ring_v2" version="2">
|
||||
<description summary="pad ring">
|
||||
A circular interaction area, such as the touch ring on the Wacom Intuos
|
||||
Pro series tablets.
|
||||
|
|
@ -769,7 +882,7 @@
|
|||
</event>
|
||||
</interface>
|
||||
|
||||
<interface name="zwp_tablet_pad_strip_v2" version="1">
|
||||
<interface name="zwp_tablet_pad_strip_v2" version="2">
|
||||
<description summary="pad strip">
|
||||
A linear interaction area, such as the strips found in Wacom Cintiq
|
||||
models.
|
||||
|
|
@ -885,7 +998,7 @@
|
|||
</event>
|
||||
</interface>
|
||||
|
||||
<interface name="zwp_tablet_pad_group_v2" version="1">
|
||||
<interface name="zwp_tablet_pad_group_v2" version="2">
|
||||
<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,
|
||||
|
|
@ -1018,11 +1131,24 @@
|
|||
<arg name="serial" type="uint"/>
|
||||
<arg name="mode" type="uint" summary="the new mode of the pad"/>
|
||||
</event>
|
||||
|
||||
<!-- version 2 -->
|
||||
|
||||
<event name="dial">
|
||||
<description summary="dial announced">
|
||||
Sent on wp_tablet_pad initialization to announce available dials.
|
||||
One event is sent for each dial 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="dial" type="new_id" interface="zwp_tablet_pad_dial_v2"/>
|
||||
</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
|
||||
<interface name="zwp_tablet_pad_v2" version="2">
|
||||
<description summary="a set of buttons, rings, strips and dials">
|
||||
A pad device is a set of buttons, rings, strips and dials
|
||||
usually physically present on the tablet device itself. Some
|
||||
exceptions exist where the pad device is physically detached, e.g. the
|
||||
Wacom ExpressKey Remote.
|
||||
|
|
@ -1036,7 +1162,7 @@
|
|||
This initial event sequence is terminated by a wp_tablet_pad.done
|
||||
event.
|
||||
|
||||
All pad features (buttons, rings and strips) are logically divided into
|
||||
All pad features (buttons, rings, strips and dials) 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.
|
||||
|
|
@ -1178,5 +1304,191 @@
|
|||
the pad itself.
|
||||
</description>
|
||||
</event>
|
||||
|
||||
<!-- version 2 -->
|
||||
<event name="frame" since="2">
|
||||
<description summary="frame event">
|
||||
Marks the end of a series of axis and/or button updates from the
|
||||
pad. 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>
|
||||
|
||||
<event name="scroll" since="2">
|
||||
<description summary="scroll event">
|
||||
Scroll event notification.
|
||||
|
||||
This event indicates a logical scroll motion along the x and/or y axis.
|
||||
The x and y values are relative deltas of the scroll motion in a coordinate
|
||||
space identical to those of motion events. When applicable, a client can
|
||||
transform its content relative to the scroll distance.
|
||||
|
||||
A compositor must not send a scroll event with both x and y on zero.
|
||||
|
||||
A scroll event may occur outside a scroll_start/scroll_stop sequence to
|
||||
indicate it is a standalone event. This may happen if the compositor is
|
||||
unable to detect boundary conditions (e.g. finger down or button down) and
|
||||
can thus only provide the scroll events. It is up to the client on how to
|
||||
process these events (e.g. whether to provide kinetic scrolling).
|
||||
|
||||
If a scroll_start event is sent by the compositor, all scroll events until
|
||||
a subsequent scroll_stop are part of the same scroll gesture.
|
||||
|
||||
The timestamp of this event is that of the corresponding frame event.
|
||||
|
||||
The scroll and scroll_v120 events are mutually exclusive and must
|
||||
not occur in the same frame.
|
||||
</description>
|
||||
<arg name="x" type="fixed" summary="length of vector in surface-local coordinate space"/>
|
||||
<arg name="y" type="fixed" summary="length of vector in surface-local coordinate space"/>
|
||||
</event>
|
||||
|
||||
<event name="scroll_v120" since="2">
|
||||
<description summary="high-resolution scroll event">
|
||||
Discrete high-resolution scroll information.
|
||||
|
||||
The values of this event is interpreted identical to the
|
||||
wl_pointer.axis_value120 event as of wl_pointer version 8.
|
||||
|
||||
A compositor must not send a scroll_v120 event with both x and y on zero.
|
||||
|
||||
This event carries high-resolution wheel scroll information,
|
||||
with each multiple of 120 representing one logical scroll step
|
||||
(a wheel detent). For example, an scroll_v120 value of 30 is one
|
||||
quarter of a logical scroll step in the positive direction, a value of
|
||||
-240 are two logical scroll steps in the negative direction within the
|
||||
same hardware event.
|
||||
Clients that rely on discrete scrolling should accumulate the
|
||||
values to multiples of 120 before processing the event.
|
||||
|
||||
The timestamp of this event is that of the corresponding frame event.
|
||||
|
||||
The scroll and scroll_v120 events are mutually exclusive and must
|
||||
not occur in the same frame.
|
||||
|
||||
scroll_v120 events may be part of a scroll_start/scroll_stop sequence and follow
|
||||
the same semantics as the scroll event. See the scroll event documentation for
|
||||
details.
|
||||
</description>
|
||||
<arg name="x" type="int" summary="scroll distance as fraction of 120"/>
|
||||
<arg name="y" type="int" summary="scroll distance as fraction of 120"/>
|
||||
</event>
|
||||
|
||||
<event name="scroll_start" since="2">
|
||||
<description summary="scroll sequence start event">
|
||||
Notification about the start of a logical scroll sequence.
|
||||
|
||||
This event signals that a user has initiated a scroll sequence (e.g. by
|
||||
touching a scrollable hardware surface or pressing a button).
|
||||
Such a sequence must comprise of exactly one scroll_start event
|
||||
followed by zero or more scroll or scroll_v120 events and then exactly one
|
||||
scroll_stop event.
|
||||
|
||||
The timestamp of this event is that of the corresponding frame event.
|
||||
|
||||
A scroll_start event may occur in the same frame as a scroll and scroll_v120 event.
|
||||
A scroll_start event may occur in the same frame as a scroll_stop event.
|
||||
</description>
|
||||
<arg name="serial" type="uint" summary="serial of the scroll_start event"/>
|
||||
</event>
|
||||
|
||||
<event name="scroll_stop" since="2">
|
||||
<description summary="scroll sequence stop event">
|
||||
Notification about the end of a logical scroll sequence.
|
||||
|
||||
This event signals that a user has stopped interacting with a scroll sequence
|
||||
(e.g. by lifting a finger or releasing a button).
|
||||
Such a sequence must comprise of exactly one scroll_start event
|
||||
followed by zero or more scroll or scroll_v120 events and then exactly one
|
||||
scroll_stop event.
|
||||
|
||||
If cancelled is nonzero, the scroll sequence was cancelled and a client should
|
||||
attempt to undo any state changes made by this seqeuence.
|
||||
|
||||
The timestamp of this event is that of the corresponding frame event.
|
||||
|
||||
A scroll_stop event may occur in the same frame as a scroll and scroll_v120 event.
|
||||
A scroll_stop event may occur in the same frame as a scroll_start event.
|
||||
</description>
|
||||
<arg name="serial" type="uint" summary="serial of the scroll_stop event"/>
|
||||
<arg name="cancelled" type="uint" summary="this scroll sequence was cancelled"/>
|
||||
</event>
|
||||
|
||||
</interface>
|
||||
|
||||
<interface name="zwp_tablet_pad_dial_v2" version="2">
|
||||
<description summary="pad dial">
|
||||
A rotatary control, such as a dial or a wheel.
|
||||
|
||||
Events on a dial are logically grouped by the wl_tablet_pad_dial.frame
|
||||
event.
|
||||
</description>
|
||||
|
||||
<request name="set_feedback">
|
||||
<description summary="set compositor feedback">
|
||||
Requests the compositor to use the provided feedback string
|
||||
associated with this dial. This request should be issued immediately
|
||||
after a wp_tablet_pad_group.mode_switch event from the corresponding
|
||||
group is received, or whenever the dial 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 dial, 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
|
||||
dial. Requests providing other serials than the most recent one will be
|
||||
ignored.
|
||||
</description>
|
||||
<arg name="description" type="string" summary="dial description"/>
|
||||
<arg name="serial" type="uint" summary="serial of the mode switch event"/>
|
||||
</request>
|
||||
|
||||
<request name="destroy" type="destructor">
|
||||
<description summary="destroy the dial object">
|
||||
This destroys the client's resource for this dial object.
|
||||
</description>
|
||||
</request>
|
||||
|
||||
<event name="delta">
|
||||
<description summary="delta movement">
|
||||
Sent whenever the position on a dial changes.
|
||||
|
||||
This event carries the wheel delta as multiples or fractions
|
||||
of 120 with each multiple of 120 representing one logical wheel detent.
|
||||
For example, an axis_value120 of 30 is one quarter of
|
||||
a logical wheel step in the positive direction, a value120 of
|
||||
-240 are two logical wheel steps in the negative direction within the
|
||||
same hardware event. See the wl_pointer.axis_value120 for more details.
|
||||
|
||||
The value120 must not be zero.
|
||||
</description>
|
||||
<arg name="value120" type="int" summary="rotation distance as fraction of 120"/>
|
||||
</event>
|
||||
|
||||
<event name="frame">
|
||||
<description summary="end of a dial event sequence">
|
||||
Indicates the end of a set of events that represent one logical
|
||||
hardware dial event. A client is expected to accumulate the data
|
||||
in all events within the frame before proceeding.
|
||||
|
||||
All wp_tablet_pad_dial events before a wp_tablet_pad_dial.frame event belong
|
||||
logically together.
|
||||
|
||||
A wp_tablet_pad_dial.frame event is sent for every logical event
|
||||
group, even if the group only contains a single wp_tablet_pad_dial
|
||||
event. Specifically, a client may get a sequence: delta, frame,
|
||||
delta, frame, etc.
|
||||
</description>
|
||||
<arg name="time" type="uint" summary="timestamp with millisecond granularity"/>
|
||||
</event>
|
||||
</interface>
|
||||
</protocol>
|
||||
|
|
|
|||
Loading…
Add table
Reference in a new issue