pointer-gestures-unstable-v1.xml RawHistoryFolder

1<?xml version="1.0" encoding="UTF-8"?>
2<protocol name="pointer_gestures_unstable_v1">
3  <copyright>
4    Copyright © 2015, 2021 Red Hat Inc.
5
6    Permission to use, copy, modify, distribute, and sell this
7    software and its documentation for any purpose is hereby granted
8    without fee, provided that the above copyright notice appear in
9    all copies and that both that copyright notice and this permission
10    notice appear in supporting documentation, and that the name of
11    the copyright holders not be used in advertising or publicity
12    pertaining to distribution of the software without specific,
13    written prior permission.  The copyright holders make no
14    representations about the suitability of this software for any
15    purpose.  It is provided "as is" without express or implied
16    warranty.
17
18    THE COPYRIGHT HOLDERS DISCLAIM ALL WARRANTIES WITH REGARD TO THIS
19    SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND
20    FITNESS, IN NO EVENT SHALL THE COPYRIGHT HOLDERS BE LIABLE FOR ANY
21    SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
22    WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN
23    AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION,
24    ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF
25    THIS SOFTWARE.
26  </copyright>
27
28  <interface name="zwp_pointer_gestures_v1" version="3">
29    <description summary="touchpad gestures">
30      A global interface to provide semantic touchpad gestures for a given
31      pointer.
32
33      Three gestures are currently supported: swipe, pinch, and hold.
34      Pinch and swipe gestures follow a three-stage cycle: begin, update,
35      end. Hold gestures follow a two-stage cycle: begin and end. All
36      gestures are identified by a unique id.
37
38      Warning! The protocol described in this file is experimental and
39      backward incompatible changes may be made. Backward compatible changes
40      may be added together with the corresponding interface version bump.
41      Backward incompatible changes are done by bumping the version number in
42      the protocol and interface names and resetting the interface version.
43      Once the protocol is to be declared stable, the 'z' prefix and the
44      version number in the protocol and interface names are removed and the
45      interface version number is reset.
46    </description>
47
48    <request name="get_swipe_gesture">
49      <description summary="get swipe gesture">
50	Create a swipe gesture object. See the
51	wl_pointer_gesture_swipe interface for details.
52      </description>
53      <arg name="id" type="new_id" interface="zwp_pointer_gesture_swipe_v1"/>
54      <arg name="pointer" type="object" interface="wl_pointer"/>
55    </request>
56
57    <request name="get_pinch_gesture">
58      <description summary="get pinch gesture">
59	Create a pinch gesture object. See the
60	wl_pointer_gesture_pinch interface for details.
61      </description>
62      <arg name="id" type="new_id" interface="zwp_pointer_gesture_pinch_v1"/>
63      <arg name="pointer" type="object" interface="wl_pointer"/>
64    </request>
65
66    <!-- Version 2 additions -->
67
68    <request name="release" type="destructor" since="2">
69      <description summary="destroy the pointer gesture object">
70	Destroy the pointer gesture object. Swipe, pinch and hold objects
71	created via this gesture object remain valid.
72      </description>
73    </request>
74
75    <!-- Version 3 additions -->
76
77    <request name="get_hold_gesture" since="3">
78      <description summary="get hold gesture">
79	Create a hold gesture object. See the
80	wl_pointer_gesture_hold interface for details.
81      </description>
82      <arg name="id" type="new_id" interface="zwp_pointer_gesture_hold_v1"/>
83      <arg name="pointer" type="object" interface="wl_pointer"/>
84    </request>
85
86  </interface>
87
88  <interface name="zwp_pointer_gesture_swipe_v1" version="3">
89    <description summary="a swipe gesture object">
90      A swipe gesture object notifies a client about a multi-finger swipe
91      gesture detected on an indirect input device such as a touchpad.
92      The gesture is usually initiated by multiple fingers moving in the
93      same direction but once initiated the direction may change.
94      The precise conditions of when such a gesture is detected are
95      implementation-dependent.
96
97      A gesture consists of three stages: begin, update (optional) and end.
98      There cannot be multiple simultaneous hold, pinch or swipe gestures on a
99      same pointer/seat, how compositors prevent these situations is
100      implementation-dependent.
101
102      A gesture may be cancelled by the compositor or the hardware.
103      Clients should not consider performing permanent or irreversible
104      actions until the end of a gesture has been received.
105    </description>
106
107    <request name="destroy" type="destructor">
108      <description summary="destroy the pointer swipe gesture object"/>
109    </request>
110
111    <event name="begin">
112      <description summary="multi-finger swipe begin">
113	This event is sent when a multi-finger swipe gesture is detected
114	on the device.
115      </description>
116      <arg name="serial" type="uint"/>
117      <arg name="time" type="uint" summary="timestamp with millisecond granularity"/>
118      <arg name="surface" type="object" interface="wl_surface"/>
119      <arg name="fingers" type="uint" summary="number of fingers"/>
120    </event>
121
122    <event name="update">
123      <description summary="multi-finger swipe motion">
124	This event is sent when a multi-finger swipe gesture changes the
125	position of the logical center.
126
127	The dx and dy coordinates are relative coordinates of the logical
128	center of the gesture compared to the previous event.
129      </description>
130      <arg name="time" type="uint" summary="timestamp with millisecond granularity"/>
131      <arg name="dx" type="fixed" summary="delta x coordinate in surface coordinate space"/>
132      <arg name="dy" type="fixed" summary="delta y coordinate in surface coordinate space"/>
133    </event>
134
135    <event name="end">
136      <description summary="multi-finger swipe end">
137	This event is sent when a multi-finger swipe gesture ceases to
138	be valid. This may happen when one or more fingers are lifted or
139	the gesture is cancelled.
140
141	When a gesture is cancelled, the client should undo state changes
142	caused by this gesture. What causes a gesture to be cancelled is
143	implementation-dependent.
144      </description>
145      <arg name="serial" type="uint"/>
146      <arg name="time" type="uint" summary="timestamp with millisecond granularity"/>
147      <arg name="cancelled" type="int" summary="1 if the gesture was cancelled, 0 otherwise"/>
148    </event>
149  </interface>
150
151  <interface name="zwp_pointer_gesture_pinch_v1" version="3">
152    <description summary="a pinch gesture object">
153      A pinch gesture object notifies a client about a multi-finger pinch
154      gesture detected on an indirect input device such as a touchpad.
155      The gesture is usually initiated by multiple fingers moving towards
156      each other or away from each other, or by two or more fingers rotating
157      around a logical center of gravity. The precise conditions of when
158      such a gesture is detected are implementation-dependent.
159
160      A gesture consists of three stages: begin, update (optional) and end.
161      There cannot be multiple simultaneous hold, pinch or swipe gestures on a
162      same pointer/seat, how compositors prevent these situations is
163      implementation-dependent.
164
165      A gesture may be cancelled by the compositor or the hardware.
166      Clients should not consider performing permanent or irreversible
167      actions until the end of a gesture has been received.
168    </description>
169
170    <request name="destroy" type="destructor">
171      <description summary="destroy the pinch gesture object"/>
172    </request>
173
174    <event name="begin">
175      <description summary="multi-finger pinch begin">
176	This event is sent when a multi-finger pinch gesture is detected
177	on the device.
178      </description>
179      <arg name="serial" type="uint"/>
180      <arg name="time" type="uint" summary="timestamp with millisecond granularity"/>
181      <arg name="surface" type="object" interface="wl_surface"/>
182      <arg name="fingers" type="uint" summary="number of fingers"/>
183    </event>
184
185    <event name="update">
186      <description summary="multi-finger pinch motion">
187	This event is sent when a multi-finger pinch gesture changes the
188	position of the logical center, the rotation or the relative scale.
189
190	The dx and dy coordinates are relative coordinates in the
191	surface coordinate space of the logical center of the gesture.
192
193	The scale factor is an absolute scale compared to the
194	pointer_gesture_pinch.begin event, e.g. a scale of 2 means the fingers
195	are now twice as far apart as on pointer_gesture_pinch.begin.
196
197	The rotation is the relative angle in degrees clockwise compared to the previous
198	pointer_gesture_pinch.begin or pointer_gesture_pinch.update event.
199      </description>
200      <arg name="time" type="uint" summary="timestamp with millisecond granularity"/>
201      <arg name="dx" type="fixed" summary="delta x coordinate in surface coordinate space"/>
202      <arg name="dy" type="fixed" summary="delta y coordinate in surface coordinate space"/>
203      <arg name="scale" type="fixed" summary="scale relative to the initial finger position"/>
204      <arg name="rotation" type="fixed" summary="angle in degrees cw relative to the previous event"/>
205    </event>
206
207    <event name="end">
208      <description summary="multi-finger pinch end">
209	This event is sent when a multi-finger pinch gesture ceases to
210	be valid. This may happen when one or more fingers are lifted or
211	the gesture is cancelled.
212
213	When a gesture is cancelled, the client should undo state changes
214	caused by this gesture. What causes a gesture to be cancelled is
215	implementation-dependent.
216      </description>
217      <arg name="serial" type="uint"/>
218      <arg name="time" type="uint" summary="timestamp with millisecond granularity"/>
219      <arg name="cancelled" type="int" summary="1 if the gesture was cancelled, 0 otherwise"/>
220    </event>
221
222  </interface>
223
224  <interface name="zwp_pointer_gesture_hold_v1" version="3">
225    <description summary="a hold gesture object">
226      A hold gesture object notifies a client about a single- or
227      multi-finger hold gesture detected on an indirect input device such as
228      a touchpad. The gesture is usually initiated by one or more fingers
229      being held down without significant movement. The precise conditions
230      of when such a gesture is detected are implementation-dependent.
231
232      In particular, this gesture may be used to cancel kinetic scrolling.
233
234      A hold gesture consists of two stages: begin and end. Unlike pinch and
235      swipe there is no update stage.
236      There cannot be multiple simultaneous hold, pinch or swipe gestures on a
237      same pointer/seat, how compositors prevent these situations is
238      implementation-dependent.
239
240      A gesture may be cancelled by the compositor or the hardware.
241      Clients should not consider performing permanent or irreversible
242      actions until the end of a gesture has been received.
243    </description>
244
245    <request name="destroy" type="destructor" since="3">
246      <description summary="destroy the hold gesture object"/>
247    </request>
248
249    <event name="begin" since="3">
250      <description summary="multi-finger hold begin">
251	This event is sent when a hold gesture is detected on the device.
252      </description>
253      <arg name="serial" type="uint"/>
254      <arg name="time" type="uint" summary="timestamp with millisecond granularity"/>
255      <arg name="surface" type="object" interface="wl_surface"/>
256      <arg name="fingers" type="uint" summary="number of fingers"/>
257    </event>
258
259    <event name="end" since="3">
260      <description summary="multi-finger hold end">
261	This event is sent when a hold gesture ceases to
262	be valid. This may happen when the holding fingers are lifted or
263	the gesture is cancelled, for example if the fingers move past an
264	implementation-defined threshold, the finger count changes or the hold
265	gesture changes into a different type of gesture.
266
267	When a gesture is cancelled, the client may need to undo state changes
268	caused by this gesture. What causes a gesture to be cancelled is
269	implementation-dependent.
270      </description>
271      <arg name="serial" type="uint"/>
272      <arg name="time" type="uint" summary="timestamp with millisecond granularity"/>
273      <arg name="cancelled" type="int" summary="1 if the gesture was cancelled, 0 otherwise"/>
274    </event>
275
276  </interface>
277</protocol>