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

KDE's Doxygen guidelines are available online.