KWayland

appmenu.h
1 /*
2  SPDX-FileCopyrightText: 2017 David Edmundson <[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_APPMENU_H
7 #define KWAYLAND_CLIENT_APPMENU_H
8 
9 #include <QObject>
10 
11 #include <KWayland/Client/kwaylandclient_export.h>
12 
13 struct org_kde_kwin_appmenu_manager;
14 struct org_kde_kwin_appmenu;
15 
16 namespace KWayland
17 {
18 namespace Client
19 {
20 
21 class EventQueue;
22 class Surface;
23 class AppMenu;
24 
25 /**
26  * @short Wrapper for the org_kde_kwin_appmenu_manager interface.
27  *
28  * This class provides a convenient wrapper for the org_kde_kwin_appmenu_manager interface.
29  *
30  * To use this class one needs to interact with the Registry. There are two
31  * possible ways to create the AppMenuManager interface:
32  * @code
33  * AppMenuManager *c = registry->createAppMenuManager(name, version);
34  * @endcode
35  *
36  * This creates the AppMenuManager and sets it up directly. As an alternative this
37  * can also be done in a more low level way:
38  * @code
39  * AppMenuManager *c = new AppMenuManager;
40  * c->setup(registry->bindAppMenuManager(name, version));
41  * @endcode
42  *
43  * The AppMenuManager can be used as a drop-in replacement for any org_kde_kwin_appmenu_manager
44  * pointer as it provides matching cast operators.
45  *
46  * @see Registry
47  * @since 5.42
48  **/
49 class KWAYLANDCLIENT_EXPORT AppMenuManager : public QObject
50 {
51  Q_OBJECT
52 public:
53  /**
54  * Creates a new AppMenuManager.
55  * Note: after constructing the AppMenuManager it is not yet valid and one needs
56  * to call setup. In order to get a ready to use AppMenuManager prefer using
57  * Registry::createAppMenuManager.
58  **/
59  explicit AppMenuManager(QObject *parent = nullptr);
60  virtual ~AppMenuManager();
61 
62  /**
63  * Setup this AppMenuManager to manage the @p appmenumanager.
64  * When using Registry::createAppMenuManager there is no need to call this
65  * method.
66  **/
67  void setup(org_kde_kwin_appmenu_manager *appmenumanager);
68  /**
69  * @returns @c true if managing a org_kde_kwin_appmenu_manager.
70  **/
71  bool isValid() const;
72  /**
73  * Releases the org_kde_kwin_appmenu_manager interface.
74  * After the interface has been released the AppMenuManager instance is no
75  * longer valid and can be setup with another org_kde_kwin_appmenu_manager interface.
76  **/
77  void release();
78  /**
79  * Destroys the data held by this AppMenuManager.
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_appmenu_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, appmenumanager, &AppMenuManager::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 AppMenuManager.
98  **/
99  void setEventQueue(EventQueue *queue);
100  /**
101  * @returns The event queue to use for creating objects with this AppMenuManager.
102  **/
103  EventQueue *eventQueue();
104 
105  AppMenu *create(Surface *surface, QObject *parent = nullptr);
106 
107  operator org_kde_kwin_appmenu_manager*();
108  operator org_kde_kwin_appmenu_manager*() const;
109 
110 Q_SIGNALS:
111  /**
112  * The corresponding global for this interface on the Registry got removed.
113  *
114  * This signal gets only emitted if the AppMenuManager got created by
115  * Registry::createAppMenuManager
116  **/
117  void removed();
118 
119 private:
120  class Private;
122 };
123 
124 /**
125  *
126  * @since 5.42
127  **/
128 class KWAYLANDCLIENT_EXPORT AppMenu : public QObject
129 {
130  Q_OBJECT
131 public:
132  virtual ~AppMenu();
133 
134  /**
135  * Setup this Appmenu to manage the @p appmenu.
136  * When using AppMenuManager::createAppmenu there is no need to call this
137  * method.
138  **/
139  void setup(org_kde_kwin_appmenu *appmenu);
140  /**
141  * @returns @c true if managing a org_kde_kwin_appmenu.
142  **/
143  bool isValid() const;
144  /**
145  * Releases the org_kde_kwin_appmenu interface.
146  * After the interface has been released the Appmenu instance is no
147  * longer valid and can be setup with another org_kde_kwin_appmenu interface.
148  **/
149  void release();
150  /**
151  * Destroys the data held by this Appmenu.
152  * This method is supposed to be used when the connection to the Wayland
153  * server goes away. If the connection is not valid anymore, it's not
154  * possible to call release anymore as that calls into the Wayland
155  * connection and the call would fail. This method cleans up the data, so
156  * that the instance can be deleted or set up to a new org_kde_kwin_appmenu interface
157  * once there is a new connection available.
158  *
159  * It is suggested to connect this method to ConnectionThread::connectionDied:
160  * @code
161  * connect(connection, &ConnectionThread::connectionDied, appmenu, &Appmenu::destroy);
162  * @endcode
163  *
164  * @see release
165  **/
166  void destroy();
167 
168  /**
169  * Sets the appmenu address. The DBus object should be registered before making this call
170  * Strings should be valid DBus formatted names, in latin1.
171  */
172  void setAddress(const QString & serviceName, const QString & objectPath);
173 
174  operator org_kde_kwin_appmenu*();
175  operator org_kde_kwin_appmenu*() const;
176 
177 private:
178  friend class AppMenuManager;
179  explicit AppMenu(QObject *parent = nullptr);
180  class Private;
182 };
183 
184 
185 }
186 }
187 
188 #endif
Wrapper class for wl_event_queue interface.
Definition: event_queue.h:55
Wrapper for the wl_surface interface.
Definition: surface.h:44
Wrapper for the org_kde_kwin_appmenu_manager interface.
Definition: appmenu.h:49
This file is part of the KDE documentation.
Documentation copyright © 1996-2021 The KDE developers.
Generated on Sat Apr 10 2021 22:50:19 by doxygen 1.8.11 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.