KWayland

pointerconstraints_interface.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_SERVER_POINTERCONSTRAINTS_INTERFACE_H
7 #define KWAYLAND_SERVER_POINTERCONSTRAINTS_INTERFACE_H
8 
9 #include "global.h"
10 #include "resource.h"
11 
12 #include <KWayland/Server/kwaylandserver_export.h>
13 
14 #include <QRegion>
15 
16 namespace KWayland
17 {
18 namespace Server
19 {
20 
21 class Display;
22 class SurfaceInterface;
23 
24 /**
25  * Enum describing the interface versions the PointerConstraintsInterface can support.
26  *
27  * @since 5.29
28  **/
30  /**
31  * zwp_pointer_constraints_v1
32  **/
34 };
35 
36 /**
37  * Manager object to create pointer constraints.
38  *
39  * To create this manager use {@link Display::createPointerConstraints}
40  *
41  * @see ConfinedPointerInterface
42  * @see LockedPointerInterface
43  * @see Display::createPointerConstraints
44  * @since 5.29
45  **/
46 class KWAYLANDSERVER_EXPORT PointerConstraintsInterface : public Global
47 {
48  Q_OBJECT
49 public:
50  virtual ~PointerConstraintsInterface();
51 
52  /**
53  * @returns The interface version used by this PointerConstraintsInterface
54  **/
55  PointerConstraintsInterfaceVersion interfaceVersion() const;
56 
57 protected:
58  class Private;
59  explicit PointerConstraintsInterface(Private *d, QObject *parent = nullptr);
60 
61 private:
62  Private *d_func() const;
63 };
64 
65 /**
66  * The LockedPointerInterface lets the client request to disable movements of
67  * the virtual pointer (i.e. the cursor), effectively locking the pointer
68  * to a position.
69  *
70  * It is up to the compositor whether the lock gets activated.
71  * To activate it needs to use {@link LockedPointerInterface::setLocked}.
72  * The compositor needs to ensure that the SurfaceInterface has pointer focus
73  * and that the pointer is inside the {@link LockedPointerInterface::region} when
74  * it activates the lock.
75  *
76  * While the lock is active the PointerInterface does no longer emit pointer motion
77  * events, but still emits relative pointer motion events.
78  *
79  * @since 5.29
80  **/
81 class KWAYLANDSERVER_EXPORT LockedPointerInterface : public Resource
82 {
83  Q_OBJECT
84 public:
85 
86  virtual ~LockedPointerInterface();
87 
88  /**
89  * @returns The interface version used by this LockedPointerInterface
90  **/
91  PointerConstraintsInterfaceVersion interfaceVersion() const;
92 
93  enum class LifeTime {
94  OneShot,
95  Persistent
96  };
97 
98  LifeTime lifeTime() const;
99 
100  /**
101  * The intersection of this region and the input region of the SurfaceInterface is used
102  * to determine where the pointer must be in order for the lock to activate.
103  * It is up to the compositor whether to warp the pointer or require some kind of
104  * user interaction for the lock to activate.
105  *
106  * If the region is empty the SurfaceInterface input region is used.
107  *
108  * @see regionChanged
109  * @see SurfaceInterface::input
110  **/
111  QRegion region() const;
112 
113  /**
114  * Indicates where the mouse cursor should be positioned after it has been unlocked again.
115  * The compositor can warp the cursor at this moment to the position. For that it
116  * will not emit any relative motion events. The hint is relative to the top-left
117  * corner of the surface the lock was applied to. Only non-negative x and y values
118  * are allowed. Otherwise the hint is invalid and should be ignored by the compositor.
119  *
120  * In case the client never set the hint, an invalid one will be returned.
121  *
122  * This function should be called when the compositor decides to break the lock or the
123  * client unbinds the resource. To set the position in this case the compositor should
124  * call this function when the aboutToBeUnbound signal has been emitted.
125  *
126  * @see cursorPositionHintChanged
127  * @since 5.49
128  **/
129  QPointF cursorPositionHint() const;
130 
131  /**
132  * Whether the Compositor set this pointer lock to be active.
133  * @see setLocked
134  * @see lockedChanged
135  **/
136  bool isLocked() const;
137 
138  /**
139  * Activates or deactivates the lock.
140  *
141  * A pointer lock can only be activated if the SurfaceInterface
142  * this LockedPointerInterface was created for has pointer focus
143  * and the pointer is inside the {@link region}.
144  *
145  * Unlocking resets the cursor position hint.
146  *
147  * @param locked Whether the lock should be active
148  * @see isLocked
149  * @see lockedChanged
150  **/
151  void setLocked(bool locked);
152 
153 Q_SIGNALS:
154  /**
155  * Emitted whenever the region changes.
156  * This happens when the parent SurfaceInterface gets committed
157  * @see region
158  **/
159  void regionChanged();
160 
161  /**
162  * Emitted whenever the cursor position hint changes.
163  * This happens when the parent SurfaceInterface gets committed
164  * @see cursorPositionHint
165  * @since 5.49
166  **/
167  void cursorPositionHintChanged();
168 
169  /**
170  * Emitted whenever the {@link isLocked} state changes.
171  * @see isLocked
172  * @see setLocked
173  **/
174  void lockedChanged();
175 
176 protected:
177  class Private;
178  explicit LockedPointerInterface(Private *p, QObject *parent = nullptr);
179 
180 private:
181  Private *d_func() const;
182  friend class SurfaceInterface;
183 };
184 
185 /**
186  *
187  * The ConfinedPointerInterface gets installed on a SurfaceInterface.
188  * The confinement indicates that the SurfaceInterface wants to confine the
189  * pointer to a region of the SurfaceInterface.
190  *
191  * It is up to the compositor whether the confinement gets activated.
192  * To activate it needs to use {@link ConfinedPointerInterface::setConfined}.
193  * The compositor needs to ensure that the SurfaceInterface has pointer focus
194  * and that the pointer is inside the {@link ConfinedPointerInterface::region} when
195  * it activates the confinement.
196  *
197  * From client side the confinement gets deactivated by destroying the ConfinedPointerInterface.
198  * From compositor side the confinement can be deactivated by setting
199  * {@link ConfinedPointerInterface::setConfined} to @c false.
200  *
201  * @since 5.29
202  **/
203 class KWAYLANDSERVER_EXPORT ConfinedPointerInterface : public Resource
204 {
205  Q_OBJECT
206 public:
207 
208  virtual ~ConfinedPointerInterface();
209 
210  /**
211  * @returns The interface version used by this ConfinedPointerInterface
212  **/
213  PointerConstraintsInterfaceVersion interfaceVersion() const;
214 
215  enum class LifeTime {
216  OneShot,
217  Persistent
218  };
219 
220  LifeTime lifeTime() const;
221 
222  /**
223  * The intersection of this region and the input region of the SurfaceInterface is used
224  * to determine where the pointer must be in order for the confinement to activate.
225  * It is up to the compositor whether to warp the pointer or require some kind of
226  * user interaction for the confinement to activate.
227  *
228  * If the region is empty the SurfaceInterface input region is used.
229  *
230  * @see regionChanged
231  * @see SurfaceInterface::input
232  **/
233  QRegion region() const;
234 
235  /**
236  * Whether the Compositor set this pointer confinement to be active.
237  * @see setConfined
238  * @see confinedChanged
239  **/
240  bool isConfined() const;
241 
242  /**
243  * Activates or deactivates the confinement.
244  *
245  * A pointer confinement can only be activated if the SurfaceInterface
246  * this ConfinedPointerInterface was created for has pointer focus
247  * and the pointer is inside the {@link region}.
248  *
249  * @param confined Whether the confinement should be active
250  * @see isConfined
251  * @see confinedChanged
252  **/
253  void setConfined(bool confined);
254 
255 Q_SIGNALS:
256  /**
257  * Emitted whenever the region changes.
258  * This happens when the parent SurfaceInterface gets committed
259  * @see region
260  **/
261  void regionChanged();
262 
263  /**
264  * Emitted whenever the {@link isConfined} state changes.
265  * @see isConfined
266  * @see setConfined
267  **/
268  void confinedChanged();
269 
270 protected:
271  class Private;
272  explicit ConfinedPointerInterface(Private *p, QObject *parent = nullptr);
273 
274 private:
275  Private *d_func() const;
276  friend class SurfaceInterface;
277 };
278 
279 }
280 }
281 
282 #endif
PointerConstraintsInterfaceVersion
Enum describing the interface versions the PointerConstraintsInterface can support.
The LockedPointerInterface lets the client request to disable movements of the virtual pointer (i...
Resource representing a wl_surface.
Base class for all Globals.
Definition: global.h:46
Represents a bound Resource.
Definition: resource.h:32
The ConfinedPointerInterface gets installed on a SurfaceInterface.
Manager object to create pointer constraints.
This file is part of the KDE documentation.
Documentation copyright © 1996-2021 The KDE developers.
Generated on Tue Apr 13 2021 22:50:02 by doxygen 1.8.11 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.