KWayland

pointergestures.h
1 /*
2  SPDX-FileCopyrightText: 2016 Martin Gräßlin <[email protected]>
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 
14 struct zwp_pointer_gestures_v1;
15 struct zwp_pointer_gesture_swipe_v1;
16 struct zwp_pointer_gesture_pinch_v1;
17 
18 class QSizeF;
19 
20 namespace KWayland
21 {
22 namespace Client
23 {
24 class EventQueue;
25 class PointerPinchGesture;
26 class Pointer;
27 class Surface;
28 class 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  **/
56 class KWAYLANDCLIENT_EXPORT PointerGestures : public QObject
57 {
58  Q_OBJECT
59 public:
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  virtual ~PointerGestures();
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 
124 Q_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 
133 private:
134  class Private;
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  **/
161 class KWAYLANDCLIENT_EXPORT PointerSwipeGesture : public QObject
162 {
163  Q_OBJECT
164 public:
165  virtual ~PointerSwipeGesture();
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 
216 Q_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 
259 private:
260  friend class PointerGestures;
261  explicit PointerSwipeGesture(QObject *parent = nullptr);
262  class Private;
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  **/
289 class KWAYLANDCLIENT_EXPORT PointerPinchGesture : public QObject
290 {
291  Q_OBJECT
292 public:
293  virtual ~PointerPinchGesture();
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 
344 Q_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 
389 private:
390  friend class PointerGestures;
391  explicit PointerPinchGesture(QObject *parent = nullptr);
392  class Private;
394 };
395 
396 }
397 }
398 
399 #endif
Wrapper class for wl_event_queue interface.
Definition: event_queue.h:54
This class is a wrapper for the zwp_pointer_gesture_swipe_v1 protocol.
Wrapper for the zwp_pointer_gestures_v1 interface.
This class is a wrapper for the zwp_pointer_gesture_pinch_v1 protocol.
Wrapper for the wl_pointer interface.
Definition: pointer.h:31
This file is part of the KDE documentation.
Documentation copyright © 1996-2021 The KDE developers.
Generated on Sat Oct 16 2021 22:52:02 by doxygen 1.8.11 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.