1/*
2 SPDX-FileCopyrightText: 2016 Martin Gräßlin <mgraesslin@kde.org>
3
4 SPDX-License-Identifier: LGPL-2.1-only OR LGPL-3.0-only OR LicenseRef-KDE-Accepted-LGPL
5*/
6#ifndef KWAYLAND_CLIENT_POINTERGESTURES_H
7#define KWAYLAND_CLIENT_POINTERGESTURES_H
8
9#include <QObject>
10#include <QPointer>
11
12#include "KWayland/Client/kwaylandclient_export.h"
13
14struct zwp_pointer_gestures_v1;
15struct zwp_pointer_gesture_swipe_v1;
16struct zwp_pointer_gesture_pinch_v1;
17
18class QSizeF;
19
20namespace KWayland
21{
22namespace Client
23{
24class EventQueue;
25class PointerPinchGesture;
26class Pointer;
27class Surface;
28class PointerSwipeGesture;
29
30/**
31 * @short Wrapper for the zwp_pointer_gestures_v1 interface.
32 *
33 * This class provides a convenient wrapper for the zwp_pointer_gestures_v1 interface.
34 *
35 * To use this class one needs to interact with the Registry. There are two
36 * possible ways to create the PointerGestures interface:
37 * @code
38 * PointerGestures *c = registry->createPointerGestures(name, version);
39 * @endcode
40 *
41 * This creates the PointerGestures and sets it up directly. As an alternative this
42 * can also be done in a more low level way:
43 * @code
44 * PointerGestures *c = new PointerGestures;
45 * c->setup(registry->bindPointerGestures(name, version));
46 * @endcode
47 *
48 * The PointerGestures can be used as a drop-in replacement for any zwp_pointer_gestures_v1
49 * pointer as it provides matching cast operators.
50 *
51 * @see Registry
52 * @see PointerSwipeGesture
53 * @see PointerPinchGesture
54 * @since 5.29
55 **/
56class KWAYLANDCLIENT_EXPORT PointerGestures : public QObject
57{
58 Q_OBJECT
59public:
60 /**
61 * Creates a new PointerGestures.
62 * Note: after constructing the PointerGestures it is not yet valid and one needs
63 * to call setup. In order to get a ready to use PointerGestures prefer using
64 * Registry::createPointerGestures.
65 **/
66 explicit PointerGestures(QObject *parent = nullptr);
67 ~PointerGestures() override;
68
69 /**
70 * Setup this PointerGestures to manage the @p pointergestures.
71 * When using Registry::createPointerGestures there is no need to call this
72 * method.
73 **/
74 void setup(zwp_pointer_gestures_v1 *pointergestures);
75 /**
76 * @returns @c true if managing a zwp_pointer_gestures_v1.
77 **/
78 bool isValid() const;
79 /**
80 * Releases the zwp_pointer_gestures_v1 interface.
81 * After the interface has been released the PointerGestures instance is no
82 * longer valid and can be setup with another zwp_pointer_gestures_v1 interface.
83 **/
84 void release();
85 /**
86 * Destroys the data held by this PointerGestures.
87 * This method is supposed to be used when the connection to the Wayland
88 * server goes away. If the connection is not valid anymore, it's not
89 * possible to call release anymore as that calls into the Wayland
90 * connection and the call would fail. This method cleans up the data, so
91 * that the instance can be deleted or set up to a new zwp_pointer_gestures_v1 interface
92 * once there is a new connection available.
93 *
94 * This method is automatically invoked when the Registry which created this
95 * PointerGestures gets destroyed.
96 * @endcode
97 *
98 * @see release
99 **/
100 void destroy();
101
102 /**
103 * Sets the @p queue to use for creating objects with this PointerGestures.
104 **/
105 void setEventQueue(EventQueue *queue);
106 /**
107 * @returns The event queue to use for creating objects with this PointerGestures.
108 **/
109 EventQueue *eventQueue();
110
111 /**
112 * Creates a PointerSwipeGesture for the given @p pointer with the @p parent.
113 **/
114 PointerSwipeGesture *createSwipeGesture(Pointer *pointer, QObject *parent = nullptr);
115
116 /**
117 * Creates a PointerPinchGesture for the given @p pointer with the @p parent.
118 **/
119 PointerPinchGesture *createPinchGesture(Pointer *pointer, QObject *parent = nullptr);
120
121 operator zwp_pointer_gestures_v1 *();
122 operator zwp_pointer_gestures_v1 *() const;
123
124Q_SIGNALS:
125 /**
126 * The corresponding global for this interface on the Registry got removed.
127 *
128 * This signal gets only emitted if the PointerGestures got created by
129 * Registry::createPointerGestures
130 **/
131 void removed();
132
133private:
134 class Private;
135 QScopedPointer<Private> d;
136};
137
138/**
139 * This class is a wrapper for the zwp_pointer_gesture_swipe_v1 protocol.
140 *
141 * A PointerSwipeGesture object notifies a client about a multi-finger swipe
142 * gesture detected on an indirect input device such as a touchpad.
143 * The gesture is usually initiated by multiple fingers moving in the
144 * same direction but once initiated the direction may change.
145 * The precise conditions of when such a gesture is detected are
146 * implementation-dependent.
147 *
148 * A gesture consists of three stages: begin, update (optional) and end.
149 * There cannot be multiple simultaneous pinch or swipe gestures on the
150 * same pointer/seat, how compositors prevent these situations is
151 * implementation-dependent.
152 *
153 * A gesture may be cancelled by the compositor or the hardware.
154 * Clients should not consider performing permanent or irreversible
155 * actions until the end of a gesture has been received.
156 *
157 * @see PointerGestures
158 * @see PointerPinchGesture
159 * @since 5.29
160 **/
161class KWAYLANDCLIENT_EXPORT PointerSwipeGesture : public QObject
162{
163 Q_OBJECT
164public:
165 ~PointerSwipeGesture() override;
166
167 /**
168 * Setup this PointerSwipeGesture to manage the @p pointerswipegesture.
169 * When using PointerGestures::createPointerSwipeGesture there is no need to call this
170 * method.
171 **/
172 void setup(zwp_pointer_gesture_swipe_v1 *pointerswipegesture);
173 /**
174 * @returns @c true if managing a zwp_pointer_gesture_swipe_v1.
175 **/
176 bool isValid() const;
177 /**
178 * Releases the zwp_pointer_gesture_swipe_v1 interface.
179 * After the interface has been released the PointerSwipeGesture instance is no
180 * longer valid and can be setup with another zwp_pointer_gesture_swipe_v1 interface.
181 **/
182 void release();
183 /**
184 * Destroys the data held by this PointerSwipeGesture.
185 * This method is supposed to be used when the connection to the Wayland
186 * server goes away. If the connection is not valid anymore, it's not
187 * possible to call release anymore as that calls into the Wayland
188 * connection and the call would fail. This method cleans up the data, so
189 * that the instance can be deleted or set up to a new zwp_pointer_gesture_swipe_v1 interface
190 * once there is a new connection available.
191 *
192 * It is suggested to connect this method to ConnectionThread::connectionDied:
193 * @code
194 * connect(connection, &ConnectionThread::connectionDied, pointerswipegesture, &PointerSwipeGesture::destroy);
195 * @endcode
196 *
197 * @see release
198 **/
199 void destroy();
200
201 /**
202 * The number of fingers taking part in this gesture.
203 * If no gesture is in progress @c 0 is returned.
204 **/
205 quint32 fingerCount() const;
206
207 /**
208 * The Surface on which this gesture is performed.
209 * If no gesture is in progress the returned pointer is null.
210 **/
211 QPointer<Surface> surface() const;
212
213 operator zwp_pointer_gesture_swipe_v1 *();
214 operator zwp_pointer_gesture_swipe_v1 *() const;
215
216Q_SIGNALS:
217 /**
218 * A gesture got started.
219 * @param serial Unique serial for this start gesture event.
220 * @param time Timestamp in milliseconds granularity
221 * @see updated
222 * @see ended
223 * @see cancelled
224 **/
225 void started(quint32 serial, quint32 time);
226
227 /**
228 * A gesture got updated.
229 * @param delta relative coordinates of the logical center of the gesture compared to the previous event
230 * @param time Timestamp in milliseconds granularity
231 * @see started
232 * @see ended
233 * @see cancelled
234 **/
235 void updated(const QSizeF &delta, quint32 time);
236
237 /**
238 * A gesture ended.
239 *
240 * @param serial Unique serial for this end gesture event.
241 * @param time Timestamp in milliseconds granularity
242 * @see started
243 * @see updated
244 * @see cancelled
245 **/
246 void ended(quint32 serial, quint32 time);
247
248 /**
249 * A gesture got cancelled by the Wayland compositor.
250 *
251 * @param serial Unique serial for this cancel gesture event.
252 * @param time Timestamp in milliseconds granularity
253 * @see started
254 * @see updated
255 * @see ended
256 **/
257 void cancelled(quint32 serial, quint32 time);
258
259private:
260 friend class PointerGestures;
261 explicit PointerSwipeGesture(QObject *parent = nullptr);
262 class Private;
263 QScopedPointer<Private> d;
264};
265
266/**
267 * This class is a wrapper for the zwp_pointer_gesture_pinch_v1 protocol.
268 *
269 * A PointerPinchGesture object notifies a client about a multi-finger pinch
270 * gesture detected on an indirect input device such as a touchpad.
271 * The gesture is usually initiated by multiple fingers moving towards
272 * each other or away from each other, or by two or more fingers rotating
273 * around a logical center of gravity. The precise conditions of when
274 * such a gesture is detected are implementation-dependent.
275 *
276 * A gesture consists of three stages: begin, update (optional) and end.
277 * There cannot be multiple simultaneous pinch or swipe gestures on the
278 * same pointer/seat, how compositors prevent these situations is
279 * implementation-dependent.
280 *
281 * A gesture may be cancelled by the compositor or the hardware.
282 * Clients should not consider performing permanent or irreversible
283 * actions until the end of a gesture has been received.
284 *
285 * @see PointerGestures
286 * @see PointerSwipeGesture
287 * @since 5.29
288 **/
289class KWAYLANDCLIENT_EXPORT PointerPinchGesture : public QObject
290{
291 Q_OBJECT
292public:
293 ~PointerPinchGesture() override;
294
295 /**
296 * Setup this PointerPinchGesture to manage the @p pointerpinchgesture.
297 * When using PointerGestures::createPointerPinchGesture there is no need to call this
298 * method.
299 **/
300 void setup(zwp_pointer_gesture_pinch_v1 *pointerpinchgesture);
301 /**
302 * @returns @c true if managing a zwp_pointer_gesture_pinch_v1.
303 **/
304 bool isValid() const;
305 /**
306 * Releases the zwp_pointer_gesture_pinch_v1 interface.
307 * After the interface has been released the PointerPinchGesture instance is no
308 * longer valid and can be setup with another zwp_pointer_gesture_pinch_v1 interface.
309 **/
310 void release();
311 /**
312 * Destroys the data held by this PointerPinchGesture.
313 * This method is supposed to be used when the connection to the Wayland
314 * server goes away. If the connection is not valid anymore, it's not
315 * possible to call release anymore as that calls into the Wayland
316 * connection and the call would fail. This method cleans up the data, so
317 * that the instance can be deleted or set up to a new zwp_pointer_gesture_pinch_v1 interface
318 * once there is a new connection available.
319 *
320 * It is suggested to connect this method to ConnectionThread::connectionDied:
321 * @code
322 * connect(connection, &ConnectionThread::connectionDied, pointerpinchgesture, &PointerPinchGesture::destroy);
323 * @endcode
324 *
325 * @see release
326 **/
327 void destroy();
328
329 /**
330 * The number of fingers taking part in this gesture.
331 * If no gesture is in progress @c 0 is returned.
332 **/
333 quint32 fingerCount() const;
334
335 /**
336 * The Surface on which this gesture is performed.
337 * If no gesture is in progress the returned pointer is null.
338 **/
339 QPointer<Surface> surface() const;
340
341 operator zwp_pointer_gesture_pinch_v1 *();
342 operator zwp_pointer_gesture_pinch_v1 *() const;
343
344Q_SIGNALS:
345 /**
346 * A gesture got started.
347 * @param serial Unique serial for this start gesture event.
348 * @param time Timestamp in milliseconds granularity
349 * @see updated
350 * @see ended
351 * @see cancelled
352 **/
353 void started(quint32 serial, quint32 time);
354
355 /**
356 * A gesture got updated.
357 * @param delta relative coordinates of the logical center of the gesture compared to the previous event
358 * @param scale an absolute scale compared to the start
359 * @param rotation relative angle in degrees clockwise compared to the previous start or update event.
360 * @param time Timestamp in milliseconds granularity
361 * @see started
362 * @see ended
363 * @see cancelled
364 **/
365 void updated(const QSizeF &delta, qreal scale, qreal rotation, quint32 time);
366
367 /**
368 * A gesture ended.
369 *
370 * @param serial Unique serial for this end gesture event.
371 * @param time Timestamp in milliseconds granularity
372 * @see started
373 * @see updated
374 * @see cancelled
375 **/
376 void ended(quint32 serial, quint32 time);
377
378 /**
379 * A gesture got cancelled by the Wayland compositor.
380 *
381 * @param serial Unique serial for this cancel gesture event.
382 * @param time Timestamp in milliseconds granularity
383 * @see started
384 * @see updated
385 * @see ended
386 **/
387 void cancelled(quint32 serial, quint32 time);
388
389private:
390 friend class PointerGestures;
391 explicit PointerPinchGesture(QObject *parent = nullptr);
392 class Private;
393 QScopedPointer<Private> d;
394};
395
396}
397}
398
399#endif
400

source code of kwayland/src/client/pointergestures.h