KWayland

plasmavirtualdesktop.h
1 /*
2  SPDX-FileCopyrightText: 2018 Marco Martin <[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_PLASMAVIRTUALDESKTOP_H
7 #define KWAYLAND_CLIENT_PLASMAVIRTUALDESKTOP_H
8 
9 #include <QObject>
10 
11 #include <KWayland/Client/kwaylandclient_export.h>
12 
13 struct org_kde_plasma_virtual_desktop_management;
14 struct org_kde_plasma_virtual_desktop;
15 
16 namespace KWayland
17 {
18 namespace Client
19 {
20 class EventQueue;
21 class PlasmaVirtualDesktop;
22 
23 /**
24  * @short Wrapper for the org_kde_plasma_virtual_desktop_management interface.
25  *
26  * This class provides a convenient wrapper for the org_kde_plasma_virtual_desktop_management interface.
27  *
28  * To use this class one needs to interact with the Registry. There are two
29  * possible ways to create the PlasmaVirtualDesktopManagement interface:
30  * @code
31  * PlasmaVirtualDesktopManagement *c = registry->createPlasmaVirtualDesktopManagement(name, version);
32  * @endcode
33  *
34  * This creates the PlasmaVirtualDesktopManagement and sets it up directly. As an alternative this
35  * can also be done in a more low level way:
36  * @code
37  * PlasmaVirtualDesktopManagement *c = new PlasmaVirtualDesktopManagement;
38  * c->setup(registry->bindPlasmaVirtualDesktopManagement(name, version));
39  * @endcode
40  *
41  * The PlasmaVirtualDesktopManagement can be used as a drop-in replacement for any org_kde_plasma_virtual_desktop_management
42  * pointer as it provides matching cast operators.
43  * @since 5.52
44  *
45  * @see Registry
46  **/
47 class KWAYLANDCLIENT_EXPORT PlasmaVirtualDesktopManagement : public QObject
48 {
49  Q_OBJECT
50 public:
51  /**
52  * Creates a new PlasmaVirtualDesktopManagement.
53  * Note: after constructing the PlasmaVirtualDesktopManagement it is not yet valid and one needs
54  * to call setup. In order to get a ready to use PlasmaVirtualDesktopManagement prefer using
55  * Registry::createPlasmaVirtualDesktopManagement.
56  **/
57  explicit PlasmaVirtualDesktopManagement(QObject *parent = nullptr);
59 
60  /**
61  * Setup this PlasmaVirtualDesktopManagement to manage the @p plasmavirtualdesktopmanagement.
62  * When using Registry::createPlasmaVirtualDesktopManagement there is no need to call this
63  * method.
64  **/
65  void setup(org_kde_plasma_virtual_desktop_management *plasmavirtualdesktopmanagement);
66  /**
67  * @returns @c true if managing a org_kde_plasma_virtual_desktop_management.
68  **/
69  bool isValid() const;
70  /**
71  * Releases the org_kde_plasma_virtual_desktop_management interface.
72  * After the interface has been released the PlasmaVirtualDesktopManagement instance is no
73  * longer valid and can be setup with another org_kde_plasma_virtual_desktop_management interface.
74  **/
75  void release();
76  /**
77  * Destroys the data held by this PlasmaVirtualDesktopManagement.
78  * This method is supposed to be used when the connection to the Wayland
79  * server goes away. If the connection is not valid anymore, it's not
80  * possible to call release anymore as that calls into the Wayland
81  * connection and the call would fail. This method cleans up the data, so
82  * that the instance can be deleted or set up to a new org_kde_plasma_virtual_desktop_management interface
83  * once there is a new connection available.
84  *
85  * It is suggested to connect this method to ConnectionThread::connectionDied:
86  * @code
87  * connect(connection, &ConnectionThread::connectionDied, plasmavirtualdesktopmanagement, &PlasmaVirtualDesktopManagement::destroy);
88  * @endcode
89  *
90  * @see release
91  **/
92  void destroy();
93 
94  /**
95  * Sets the @p queue to use for creating objects with this PlasmaVirtualDesktopManagement.
96  **/
97  void setEventQueue(EventQueue *queue);
98 
99  /**
100  * @returns The event queue to use for creating objects with this PlasmaVirtualDesktopManagement.
101  * The object is owned by the manager and the caller should not delete it.
102  **/
103  EventQueue *eventQueue();
104 
105  /**
106  * @returns the PlasmaVirtualDesktop representing the desktop id.
107  * The PlasmaVirtualDesktop instance is guaranteed to be unique for each id.
108  */
109  PlasmaVirtualDesktop *getVirtualDesktop(const QString &id);
110 
111  /**
112  * Requests for the desktop identified by id to be removed.
113  * The server may or may not acconsent to the request.
114  */
115  void requestRemoveVirtualDesktop(const QString &id);
116 
117  /**
118  * Ask the server to create a new virtual desktop, and position it at a specified position.
119  * If the position is zero or less, it will be positioned at the beginning,
120  * if the cosition is the count or more, it will be positioned at the end.
121  * @param name The name we want for the desktop
122  * @param position The position for the desktop to be created
123  */
124  void requestCreateVirtualDesktop(const QString &name, quint32 position = std::numeric_limits<uint32_t>::max());
125 
126  /**
127  * @returns All the existent virtual desktops
128  */
129  QList<PlasmaVirtualDesktop *> desktops() const;
130 
131  /**
132  * @returns How many rows the virtual desktops should be laid out into
133  * @since 5.55
134  */
135  quint32 rows() const;
136 
137  operator org_kde_plasma_virtual_desktop_management *();
138  operator org_kde_plasma_virtual_desktop_management *() const;
139 
140 Q_SIGNALS:
141  void removed();
142 
143  /**
144  * Emitted when a new desktop has been added
145  */
146  void desktopCreated(const QString &id, quint32 position);
147 
148  /**
149  * Emitted when a desktop has been removed
150  */
151  void desktopRemoved(const QString &id);
152 
153  /**
154  * Emitted when the number of rows of virtual desktops has been changed by the server
155  * @since 5.55
156  */
157  void rowsChanged(quint32 rows);
158 
159  /**
160  * This event is sent after all other properties has been
161  * sent after binding to the desktop manager object and after any
162  * other property changes done after that. This allows
163  * changes to the org_kde_plasma_virtual_desktop_management properties
164  * to be seen as atomic, even if they happen via multiple events.
165  */
166  void done();
167 
168 private:
169  class Private;
171 };
172 
173 class KWAYLANDCLIENT_EXPORT PlasmaVirtualDesktop : public QObject
174 {
175  Q_OBJECT
176 public:
177  virtual ~PlasmaVirtualDesktop();
178 
179  /**
180  * Setup this PlasmaVirtualDesktop to manage the @p plasmavirtualdesktop.
181  * When using PlasmaVirtualDesktopManagement::createPlasmaVirtualDesktop there is no need to call this
182  * method.
183  **/
184  void setup(org_kde_plasma_virtual_desktop *plasmavirtualdesktop);
185 
186  /**
187  * @returns @c true if managing a org_kde_plasma_virtual_desktop.
188  **/
189  bool isValid() const;
190 
191  /**
192  * Releases the org_kde_plasma_virtual_desktop interface.
193  * After the interface has been released the PlasmaVirtualDesktop instance is no
194  * longer valid and can be setup with another org_kde_plasma_virtual_desktop interface.
195  **/
196  void release();
197 
198  /**
199  * Destroys the data held by this PlasmaVirtualDesktop.
200  * This method is supposed to be used when the connection to the Wayland
201  * server goes away. If the connection is not valid anymore, it's not
202  * possible to call release anymore as that calls into the Wayland
203  * connection and the call would fail. This method cleans up the data, so
204  * that the instance can be deleted or set up to a new org_kde_plasma_virtual_desktop interface
205  * once there is a new connection available.
206  *
207  * It is suggested to connect this method to ConnectionThread::connectionDied:
208  * @code
209  * connect(connection, &ConnectionThread::connectionDied, plasmavirtualdesktop, &PlasmaVirtualDesktop::destroy);
210  * @endcode
211  *
212  * @see release
213  **/
214  void destroy();
215 
216  /**
217  * Requests this desktop to be activated.
218  * The server may or may not decide to consent to the request.
219  */
220  void requestActivate();
221 
222  /**
223  * @returns The unique id of this desktop. The format of the id is decided by the compositor
224  */
225  QString id() const;
226 
227  /**
228  * @returns User readable name for the desktop.
229  */
230  QString name() const;
231 
232  /**
233  * @returns True if the desktop is the active one.
234  * when this property changes, activated or deactivated will be emitted.
235  * @see activated
236  * @see deactivated
237  */
238  bool isActive() const;
239 
240  operator org_kde_plasma_virtual_desktop *();
241  operator org_kde_plasma_virtual_desktop *() const;
242 
243 Q_SIGNALS:
244  /**
245  * TODO: activeChanged(bool)?
246  * Emitted when this desktop has been activated by the server
247  */
248  void activated();
249 
250  /**
251  * Emitted when this desktop has been activated by the server
252  */
253  void deactivated();
254 
255  /**
256  * This event is sent after all other properties has been
257  * sent after binding to the desktop manager object and after any
258  * other property changes done after that. This allows
259  * changes to the org_kde_plasma_virtual_desktop properties
260  * to be seen as atomic, even if they happen via multiple events.
261  */
262  void done();
263 
264  /**
265  * This virtual desktop has just been removed by the server:
266  * This object itself is about to be deleted. All windows will
267  * lose the association to this desktop.
268  */
269  void removed();
270 
271 private:
272  friend class PlasmaVirtualDesktopManagement;
273  explicit PlasmaVirtualDesktop(QObject *parent = nullptr);
274  class Private;
276 };
277 
278 }
279 }
280 
281 #endif
Wrapper class for wl_event_queue interface.
Definition: event_queue.h:54
Wrapper for the org_kde_plasma_virtual_desktop_management interface.
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.