KWayland

relativepointer.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_RELATIVEPOINTER_H
7 #define KWAYLAND_CLIENT_RELATIVEPOINTER_H
8 
9 #include <QObject>
10 
11 #include <KWayland/Client/kwaylandclient_export.h>
12 
13 struct zwp_relative_pointer_manager_v1;
14 struct zwp_relative_pointer_v1;
15 
16 namespace KWayland
17 {
18 namespace Client
19 {
20 class EventQueue;
21 class Pointer;
22 class RelativePointer;
23 
24 /**
25  * @short Wrapper for the zwp_relative_pointer_manager_v1 interface.
26  *
27  * This class provides a convenient wrapper for the zwp_relative_pointer_manager_v1 interface.
28  *
29  * To use this class one needs to interact with the Registry. There are two
30  * possible ways to create the RelativePointerManager interface:
31  * @code
32  * RelativePointerManager *c = registry->createRelativePointerManagerUnstableV1(name, version);
33  * @endcode
34  *
35  * This creates the RelativePointerManager and sets it up directly. As an alternative this
36  * can also be done in a more low level way:
37  * @code
38  * RelativePointerManager *c = new RelativePointerManager;
39  * c->setup(registry->RelativePointerManager(name, version));
40  * @endcode
41  *
42  * The RelativePointerManager can be used as a drop-in replacement for any zwp_relative_pointer_manager_v1
43  * pointer as it provides matching cast operators.
44  *
45  * @see Registry
46  * @since 5.28
47  **/
48 class KWAYLANDCLIENT_EXPORT RelativePointerManager : public QObject
49 {
50  Q_OBJECT
51 public:
52  /**
53  * Creates a new RelativePointerManager.
54  * Note: after constructing the RelativePointerManager it is not yet valid and one needs
55  * to call setup. In order to get a ready to use RelativePointerManager prefer using
56  * Registry::createRelativePointerManagerUnstableV1.
57  **/
58  explicit RelativePointerManager(QObject *parent = nullptr);
59  virtual ~RelativePointerManager();
60 
61  /**
62  * Setup this RelativePointerManagerUnstableV1 to manage the @p relativepointermanagerunstablev1.
63  * When using Registry::createRelativePointerManagerUnstableV1 there is no need to call this
64  * method.
65  **/
66  void setup(zwp_relative_pointer_manager_v1 *relativepointermanagerunstablev1);
67  /**
68  * @returns @c true if managing a zwp_relative_pointer_manager_v1.
69  **/
70  bool isValid() const;
71  /**
72  * Releases the zwp_relative_pointer_manager_v1 interface.
73  * After the interface has been released the RelativePointerManagerUnstableV1 instance is no
74  * longer valid and can be setup with another zwp_relative_pointer_manager_v1 interface.
75  **/
76  void release();
77  /**
78  * Destroys the data held by this RelativePointerManagerUnstableV1.
79  * This method is supposed to be used when the connection to the Wayland
80  * server goes away. If the connection is not valid anymore, it's not
81  * possible to call release anymore as that calls into the Wayland
82  * connection and the call would fail. This method cleans up the data, so
83  * that the instance can be deleted or set up to a new zwp_relative_pointer_manager_v1 interface
84  * once there is a new connection available.
85  *
86  * It is suggested to connect this method to ConnectionThread::connectionDied:
87  * @code
88  * connect(connection, &ConnectionThread::connectionDied, relativepointermanagerunstablev1, &RelativePointerManagerUnstableV1::destroy);
89  * @endcode
90  *
91  * @see release
92  **/
93  void destroy();
94 
95  /**
96  * Sets the @p queue to use for creating objects with this RelativePointerManagerUnstableV1.
97  **/
98  void setEventQueue(EventQueue *queue);
99  /**
100  * @returns The event queue to use for creating objects with this RelativePointerManagerUnstableV1.
101  **/
102  EventQueue *eventQueue();
103 
104  /**
105  * Creates a RelativePointer for the given @p pointer.
106  **/
107  RelativePointer *createRelativePointer(Pointer *pointer, QObject *parent = nullptr);
108 
109  operator zwp_relative_pointer_manager_v1 *();
110  operator zwp_relative_pointer_manager_v1 *() const;
111 
112 Q_SIGNALS:
113  /**
114  * The corresponding global for this interface on the Registry got removed.
115  *
116  * This signal gets only emitted if the RelativePointerManagerUnstableV1 got created by
117  * Registry::createRelativePointerManagerUnstableV1
118  **/
119  void removed();
120 
121 private:
122  class Private;
124 };
125 
126 /**
127  * @short Wrapper for the zwp_relative_pointer_v1 interface.
128  *
129  * The RelativePointer is an extension to the Pointer used for emitting
130  * relative pointer events. It shares the same focus as Pointer of the same Seat
131  * and will only emit events when it has focus.
132  *
133  * @since 5.28
134  **/
135 class KWAYLANDCLIENT_EXPORT RelativePointer : public QObject
136 {
137  Q_OBJECT
138 public:
139  virtual ~RelativePointer();
140 
141  /**
142  * Setup this RelativePointerUnstableV1 to manage the @p relativepointerunstablev1.
143  * When using RelativePointerManagerUnstableV1::createRelativePointerUnstableV1 there is no need to call this
144  * method.
145  **/
146  void setup(zwp_relative_pointer_v1 *relativepointerunstablev1);
147  /**
148  * @returns @c true if managing a zwp_relative_pointer_v1.
149  **/
150  bool isValid() const;
151  /**
152  * Releases the zwp_relative_pointer_v1 interface.
153  * After the interface has been released the RelativePointerUnstableV1 instance is no
154  * longer valid and can be setup with another zwp_relative_pointer_v1 interface.
155  **/
156  void release();
157  /**
158  * Destroys the data held by this RelativePointerUnstableV1.
159  * This method is supposed to be used when the connection to the Wayland
160  * server goes away. If the connection is not valid anymore, it's not
161  * possible to call release anymore as that calls into the Wayland
162  * connection and the call would fail. This method cleans up the data, so
163  * that the instance can be deleted or set up to a new zwp_relative_pointer_v1 interface
164  * once there is a new connection available.
165  *
166  * This method is automatically invoked when the Registry which created this
167  * RelativePointer gets destroyed.
168  *
169  * @see release
170  **/
171  void destroy();
172 
173  operator zwp_relative_pointer_v1 *();
174  operator zwp_relative_pointer_v1 *() const;
175 
176 Q_SIGNALS:
177  /**
178  * A relative motion event.
179  *
180  * A relative motion is in the same dimension as regular motion events,
181  * except they do not represent an absolute position. For example,
182  * moving a pointer from (x, y) to (x', y') would have the equivalent
183  * relative motion (x' - x, y' - y). If a pointer motion caused the
184  * absolute pointer position to be clipped by for example the edge of the
185  * monitor, the relative motion is unaffected by the clipping and will
186  * represent the unclipped motion.
187  *
188  * This signal also contains non-accelerated motion deltas (@p deltaNonAccelerated).
189  * The non-accelerated delta is, when applicable, the regular pointer motion
190  * delta as it was before having applied motion acceleration and other
191  * transformations such as normalization.
192  *
193  * Note that the non-accelerated delta does not represent 'raw' events as
194  * they were read from some device. Pointer motion acceleration is device-
195  * and configuration-specific and non-accelerated deltas and accelerated
196  * deltas may have the same value on some devices.
197  *
198  * Relative motions are not coupled to Pointer motion events,
199  * and can be sent in combination with such events, but also independently. There may
200  * also be scenarios where Pointer motion is sent, but there is no
201  * relative motion. The order of an absolute and relative motion event
202  * originating from the same physical motion is not guaranteed.
203  *
204  * @param delta Motion vector
205  * @param deltaNonAccelerated non-accelerated motion vector
206  * @param microseconds timestamp with microseconds granularity
207  **/
208  void relativeMotion(const QSizeF &delta, const QSizeF &deltaNonAccelerated, quint64 timestamp);
209 
210 private:
211  friend class RelativePointerManager;
212  explicit RelativePointer(QObject *parent = nullptr);
213  class Private;
215 };
216 
217 }
218 }
219 
220 #endif
Wrapper class for wl_event_queue interface.
Definition: event_queue.h:54
Wrapper for the zwp_relative_pointer_v1 interface.
Wrapper for the wl_pointer interface.
Definition: pointer.h:31
Wrapper for the zwp_relative_pointer_manager_v1 interface.
This file is part of the KDE documentation.
Documentation copyright © 1996-2021 The KDE developers.
Generated on Thu Sep 23 2021 22:51:09 by doxygen 1.8.11 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.