1/*
2 SPDX-FileCopyrightText: 2018 Marco Martin <notmart@gmail.com>
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
13struct org_kde_plasma_virtual_desktop_management;
14struct org_kde_plasma_virtual_desktop;
15
16namespace KWayland
17{
18namespace Client
19{
20class EventQueue;
21class 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 **/
47class KWAYLANDCLIENT_EXPORT PlasmaVirtualDesktopManagement : public QObject
48{
49 Q_OBJECT
50public:
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);
58 ~PlasmaVirtualDesktopManagement() override;
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
140Q_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
168private:
169 class Private;
170 QScopedPointer<Private> d;
171};
172
173class KWAYLANDCLIENT_EXPORT PlasmaVirtualDesktop : public QObject
174{
175 Q_OBJECT
176public:
177 ~PlasmaVirtualDesktop() override;
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
243Q_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
271private:
272 friend class PlasmaVirtualDesktopManagement;
273 explicit PlasmaVirtualDesktop(QObject *parent = nullptr);
274 class Private;
275 QScopedPointer<Private> d;
276};
277
278}
279}
280
281#endif
282

source code of kwayland/src/client/plasmavirtualdesktop.h