KWayland

server_decoration.h
1 /*
2  SPDX-FileCopyrightText: 2015 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_SERVER_DECORATION_H
7 #define KWAYLAND_CLIENT_SERVER_DECORATION_H
8 
9 #include <QObject>
10 
11 #include <KWayland/Client/kwaylandclient_export.h>
12 
13 struct org_kde_kwin_server_decoration_manager;
14 struct org_kde_kwin_server_decoration;
15 struct wl_surface;
16 
17 namespace KWayland
18 {
19 namespace Client
20 {
21 class EventQueue;
22 class Surface;
23 class ServerSideDecoration;
24 
25 /**
26  * @short Wrapper for the org_kde_kwin_server_decoration_manager interface.
27  *
28  * This class provides a convenient wrapper for the org_kde_kwin_server_decoration_manager interface.
29  *
30  * To use this class one needs to interact with the Registry. There are two
31  * possible ways to create the ServerSideDecorationManager interface:
32  * @code
33  * ServerSideDecorationManager *c = registry->createServerSideDecorationManager(name, version);
34  * @endcode
35  *
36  * This creates the ServerSideDecorationManager and sets it up directly. As an alternative this
37  * can also be done in a more low level way:
38  * @code
39  * ServerSideDecorationManager *c = new ServerSideDecorationManager;
40  * c->setup(registry->bindServerSideDecorationManager(name, version));
41  * @endcode
42  *
43  * The ServerSideDecorationManager can be used as a drop-in replacement for any org_kde_kwin_server_decoration_manager
44  * pointer as it provides matching cast operators.
45  *
46  * @see Registry
47  * @since 5.6
48  **/
49 class KWAYLANDCLIENT_EXPORT ServerSideDecorationManager : public QObject
50 {
51  Q_OBJECT
52 public:
53  /**
54  * Creates a new ServerSideDecorationManager.
55  * Note: after constructing the ServerSideDecorationManager it is not yet valid and one needs
56  * to call setup. In order to get a ready-to-use ServerSideDecorationManager prefer using
57  * Registry::createServerSideDecorationManager.
58  **/
59  explicit ServerSideDecorationManager(QObject *parent = nullptr);
60  virtual ~ServerSideDecorationManager();
61 
62  /**
63  * Setup this ServerSideDecorationManager to manage the @p serversidedecorationmanager.
64  * When using Registry::createServerSideDecorationManager there is no need to call this
65  * method.
66  **/
67  void setup(org_kde_kwin_server_decoration_manager *serversidedecorationmanager);
68  /**
69  * @returns @c true if managing a org_kde_kwin_server_decoration_manager.
70  **/
71  bool isValid() const;
72  /**
73  * Releases the org_kde_kwin_server_decoration_manager interface.
74  * After the interface has been released the ServerSideDecorationManager instance is no
75  * longer valid and can be setup with another org_kde_kwin_server_decoration_manager interface.
76  **/
77  void release();
78  /**
79  * Destroys the data held by this ServerSideDecorationManager.
80  * This method is supposed to be used when the connection to the Wayland
81  * server goes away. If the connection is not valid anymore, it's not
82  * possible to call release anymore as that calls into the Wayland
83  * connection and the call would fail. This method cleans up the data, so
84  * that the instance can be deleted or set up to a new org_kde_kwin_server_decoration_manager interface
85  * once there is a new connection available.
86  *
87  * It is suggested to connect this method to ConnectionThread::connectionDied:
88  * @code
89  * connect(connection, &ConnectionThread::connectionDied, serversidedecorationmanager, &ServerSideDecorationManager::destroy);
90  * @endcode
91  *
92  * @see release
93  **/
94  void destroy();
95 
96  /**
97  * Sets the @p queue to use for creating objects with this ServerSideDecorationManager.
98  **/
99  void setEventQueue(EventQueue *queue);
100  /**
101  * @returns The event queue to use for creating objects with this ServerSideDecorationManager.
102  **/
103  EventQueue *eventQueue();
104 
105  ServerSideDecoration *create(Surface *surface, QObject *parent = nullptr);
106  ServerSideDecoration *create(wl_surface *surface, QObject *parent = nullptr);
107 
108  operator org_kde_kwin_server_decoration_manager *();
109  operator org_kde_kwin_server_decoration_manager *() const;
110 
111 Q_SIGNALS:
112  /**
113  * The corresponding global for this interface on the Registry got removed.
114  *
115  * This signal gets only emitted if the ServerSideDecorationManager got created by
116  * Registry::createServerSideDecorationManager
117  **/
118  void removed();
119 
120 private:
121  class Private;
123 };
124 
125 /**
126  * @brief Describing how a Surface should be decorated.
127  *
128  * Use ServerSideDecorationManager::create to create a ServerSideDecoration.
129  *
130  * @see ServerSideDecorationManager
131  * @since 5.6
132  **/
133 class KWAYLANDCLIENT_EXPORT ServerSideDecoration : public QObject
134 {
135  Q_OBJECT
136 public:
137  virtual ~ServerSideDecoration();
138 
139  /**
140  * Setup this ServerSideDecoration to manage the @p serversidedecoration.
141  * When using ServerSideDecorationManager::createServerSideDecoration there is no need to call this
142  * method.
143  **/
144  void setup(org_kde_kwin_server_decoration *serversidedecoration);
145  /**
146  * @returns @c true if managing a org_kde_kwin_server_decoration.
147  **/
148  bool isValid() const;
149  /**
150  * Releases the org_kde_kwin_server_decoration interface.
151  * After the interface has been released the ServerSideDecoration instance is no
152  * longer valid and can be setup with another org_kde_kwin_server_decoration interface.
153  **/
154  void release();
155  /**
156  * Destroys the data held by this ServerSideDecoration.
157  * This method is supposed to be used when the connection to the Wayland
158  * server goes away. If the connection is not valid anymore, it's not
159  * possible to call release anymore as that calls into the Wayland
160  * connection and the call would fail. This method cleans up the data, so
161  * that the instance can be deleted or set up to a new org_kde_kwin_server_decoration interface
162  * once there is a new connection available.
163  *
164  * This method is automatically invoked when the Registry which created this
165  * ServerDecoration gets destroyed.
166  *
167  * @see release
168  **/
169  void destroy();
170 
171  /**
172  * Decoration mode used for the Surface.
173  **/
174  enum class Mode {
175  /**
176  * Undecorated: neither client, nor server provide decoration. Example: popups.
177  **/
178  None,
179  /**
180  * The decoration is part of the surface.
181  **/
182  Client,
183  /**
184  * The surface gets embedded into a decoration frame provided by the Server.
185  **/
186  Server,
187  };
188 
189  /**
190  * Request the decoration @p mode for the Surface.
191  *
192  * The server will acknowledge the change which will trigger the modeChanged signal.
193  *
194  * @see mode
195  * @see modeChanged
196  **/
197  void requestMode(Mode mode);
198 
199  /**
200  * @returns The current decoration mode for the Surface.
201  *
202  * The mode represents the mode pushed from the Server.
203  * @see requestMode
204  * @see modeChanged
205  **/
206  Mode mode() const;
207 
208  /**
209  * @returns The default decoration mode the server uses
210  *
211  * @see mode
212  **/
213  Mode defaultMode() const;
214 
215  operator org_kde_kwin_server_decoration *();
216  operator org_kde_kwin_server_decoration *() const;
217 
218 Q_SIGNALS:
219  /**
220  * Emitted whenever the Server changes the decoration mode for the Surface.
221  * @see requestMode
222  * @see mode
223  **/
224  void modeChanged();
225 
226 private:
227  friend class ServerSideDecorationManager;
228  explicit ServerSideDecoration(QObject *parent = nullptr);
229  class Private;
231 };
232 
233 }
234 }
235 
237 
238 #endif
Wrapper class for wl_event_queue interface.
Definition: event_queue.h:54
Wrapper for the wl_surface interface.
Definition: surface.h:43
Wrapper for the org_kde_kwin_server_decoration_manager interface.
Mode
Decoration mode used for the Surface.
Describing how a Surface should be decorated.
This file is part of the KDE documentation.
Documentation copyright © 1996-2021 The KDE developers.
Generated on Sat Oct 16 2021 22:52:03 by doxygen 1.8.11 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.