1/*
2 SPDX-FileCopyrightText: 2017 David Edmundson <kde@davidedmundson.co.uk>
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
13struct org_kde_kwin_appmenu_manager;
14struct org_kde_kwin_appmenu;
15
16namespace KWayland
17{
18namespace Client
19{
20class EventQueue;
21class Surface;
22class 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 **/
48class KWAYLANDCLIENT_EXPORT AppMenuManager : public QObject
49{
50 Q_OBJECT
51public:
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 ~AppMenuManager() override;
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
109Q_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
118private:
119 class Private;
120 QScopedPointer<Private> d;
121};
122
123/**
124 *
125 * @since 5.42
126 **/
127class KWAYLANDCLIENT_EXPORT AppMenu : public QObject
128{
129 Q_OBJECT
130public:
131 ~AppMenu() override;
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
176private:
177 friend class AppMenuManager;
178 explicit AppMenu(QObject *parent = nullptr);
179 class Private;
180 QScopedPointer<Private> d;
181};
182
183}
184}
185
186#endif
187

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