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

KDE's Doxygen guidelines are available online.