1/*
2 This file is part of the KDE Libraries
3 SPDX-FileCopyrightText: 1999-2000 Espen Sand <espen@kde.org>
4
5 SPDX-License-Identifier: LGPL-2.0-or-later
6*/
7
8#ifndef KHELPMENU_H
9#define KHELPMENU_H
10
11#include <kxmlgui_export.h>
12
13#include <QObject>
14#include <QString>
15
16class QMenu;
17class QWidget;
18class QAction;
19
20class KAboutData;
21class KHelpMenuPrivate;
22
23/*!
24 * \class KHelpMenu
25 * \inmodule KXmlGui
26 *
27 * \brief Standard KDE help menu with dialog boxes.
28 *
29 * This class provides the standard KDE help menu with the default "About"
30 * dialog boxes and help entry.
31 *
32 * This class is used in KMainWindow so
33 * normally you don't need to use this class yourself. However, if you
34 * need the help menu or any of its dialog boxes in your code that is
35 * not subclassed from KMainWindow you should use this class.
36 *
37 * The usage is simple:
38 *
39 * \code
40 * mHelpMenu = new KHelpMenu( this );
41 * kmenubar->addMenu(mHelpMenu->menu() );
42 * \endcode
43 *
44 * or if you just want to open a dialog box:
45 *
46 * \code
47 * mHelpMenu = new KHelpMenu( this );
48 * connect(this, &ClassFoo::someSignal, mHelpMenu, &KHelpMenu::aboutKDE);
49 * \endcode
50 *
51 * \warning The first time you use KHelpMenu::menu(), a QMenu object is
52 * allocated. Only one object is created by the class so if you call
53 * KHelpMenu::menu() twice or more, the same pointer is returned. The class
54 * will destroy the popupmenu in the destructor so do not delete this
55 * pointer yourself.
56 *
57 * The KHelpMenu object will be deleted when its parent is destroyed but you
58 * can delete it yourself if you want. The code below will always work.
59 *
60 * \code
61 * MyClass::~MyClass()
62 * {
63 * delete mHelpMenu;
64 * }
65 * \endcode
66 *
67 *
68 * Using your own "About Application" dialog box:
69 *
70 * The standard "About Application" dialog box is quite simple. If you
71 * need a dialog box with more functionality you must design that one
72 * yourself. When you want to display the dialog, you simply need to
73 * connect the help menu signal showAboutApplication() to your slot.
74 *
75 * \code
76 * void MyClass::myFunc()
77 * {
78 * // ...
79 * KHelpMenu *helpMenu = new KHelpMenu( this );
80 * connect(helpMenu, &KHelpMenu::showAboutApplication, this, &ClassFoo:myDialogSlot);
81 * // ...
82 * }
83 *
84 * void MyClass::myDialogSlot()
85 * {
86 * <activate your custom dialog>
87 * }
88 * \endcode
89 *
90 * \image khelpmenu.png "KHelpMenu"
91 *
92 * KHelpMenu respects Kiosk settings (see the KAuthorized namespace in the
93 * KConfig framework). In particular, system administrators can disable items
94 * on this menu using some subset of the following configuration:
95 *
96 * \badcode
97 * [KDE Action Restrictions][$i]
98 * actions/help_contents=false
99 * actions/help_whats_this=false
100 * actions/help_report_bug=false
101 * actions/switch_application_language=false
102 * actions/help_about_app=false
103 * actions/help_about_kde=false
104 * \endcode
105 */
106
107class KXMLGUI_EXPORT KHelpMenu : public QObject
108{
109 Q_OBJECT
110
111public:
112#if KXMLGUI_ENABLE_DEPRECATED_SINCE(6, 9)
113 /*!
114 * \brief Construct a new help menu dialog.
115 *
116 * \a parent The parent of the dialog boxes. The boxes are modeless
117 * and will be centered with respect to the parent.
118 *
119 * \a aboutAppText User definable string that is used in the
120 * default application dialog box.
121 *
122 * \a showWhatsThis Decides whether a "What's this" entry will be
123 * added to the dialog.
124 *
125 * \deprecated[6.9]
126 * Use one of the other constructors
127 */
128 KXMLGUI_DEPRECATED_VERSION(6, 9, "Use one of the other constructors")
129 explicit KHelpMenu(QWidget *parent, const QString &unused, bool showWhatsThis = true);
130#endif
131
132 /*!
133 * Creates a KHelpMenu with the default app data (KAboutData::applicationData()).
134 *
135 * \a parent The parent of the dialog boxes. The boxes are modeless
136 * and will be centered with respect to the parent.
137 *
138 * \since 6.9
139 */
140 explicit KHelpMenu(QWidget *parent = nullptr);
141
142#if KXMLGUI_ENABLE_DEPRECATED_SINCE(6, 9)
143 /*!
144 * \brief Constructor.
145 *
146 * \overload KHelpMenu(QWidget *parent, const QString &aboutAppText, bool showWhatsThis)
147 *
148 * This overload is mainly useful if you want to
149 * override the standard actions aboutApplication(), aboutKDE(),
150 * and reportBug().
151 *
152 * \a parent The parent of the dialog boxes. The boxes are modeless
153 * and will be centered with respect to the parent.
154 *
155 * \a aboutData User and app data used in the About app dialog.
156 *
157 * \a showWhatsThis Decides whether a "What's this" entry will be
158 * added to the dialog.
159 *
160 * \deprecated[since 6.9]
161 *
162 * Use one of the other constructors
163 */
164 KXMLGUI_DEPRECATED_VERSION(6, 9, "Use one of the other constructors")
165 KHelpMenu(QWidget *parent, const KAboutData &aboutData, bool showWhatsThis);
166#endif
167
168 /*!
169 * Creates a KHelpMenu with app data \a aboutData.
170 *
171 * This constructor is useful if you want to use the help menu with custom
172 * application data.
173 *
174 * \a parent The parent of the dialog boxes. The boxes are modeless
175 * and will be centered with respect to the parent.
176 *
177 * \a aboutData User and app data used in the About app dialog and for
178 * the actions in the help menu.
179 *
180 * \since 6.9
181 */
182 KHelpMenu(QWidget *parent, const KAboutData &aboutData);
183
184 /*!
185 * \brief Destroys the help menu dialogs and the menu pointer
186 * returned by the menu.
187 */
188 ~KHelpMenu() override;
189
190 /*!
191 * Set whether to show the What's This menu entry in the help menu.
192 * The default is to show the menu entry (if Kiosk settings allow it).
193 * \since 6.9
194 */
195 void setShowWhatsThis(bool showWhatsThis);
196
197 /*!
198 * \brief Returns a popup menu you can use in the menu bar or where you
199 * need it.
200 *
201 * The returned menu is configured with an icon, a title and
202 * menu entries. Therefore adding the returned pointer to your menu
203 * is enough to have access to the help menu.
204 *
205 * Note: This method will only create one instance of the menu. If
206 * you call this method twice or more the same pointer is returned.
207 */
208 QMenu *menu();
209
210 /*!
211 * \enum KHelpMenu::MenuId
212 *
213 * \value menuHelpContents
214 * Whether to show the Help contents. This usually consists
215 * of the handbook for the application.
216 *
217 * \value menuWhatsThis
218 * Whether to show the "What's This?" menu.
219 * When triggered, clicking anything with the mouse cursor
220 * should show information about the clicked component.
221 *
222 * \value menuAboutApp
223 * Whether to show the "About <application>" menu.
224 * This menu usually contains information about the application
225 * version, copyright, license, library components,
226 * authors and acknowledgements.
227 *
228 * \value menuAboutKDE
229 * Whether to show the "About KDE" menu.
230 * The contents of this menu is standardized, mentioning
231 * what KDE is, how to get support, contribute, and donate.
232 *
233 * \value menuReportBug
234 * Whether to show the "Report Bug..." menu.
235 * This provides a dialog to initiate the bug report wizard
236 * provided by KCrash.
237 *
238 * \value menuSwitchLanguage
239 * Whether to show the switch language menu.
240 *
241 * \value menuDonate
242 * Since 5.24, triggering this menu opens the donation page
243 * on a browser.
244 */
245 enum MenuId {
246 menuHelpContents = 0,
247 menuWhatsThis = 1,
248 menuAboutApp = 2,
249 menuAboutKDE = 3,
250 menuReportBug = 4,
251 menuSwitchLanguage = 5,
252 menuDonate = 6,
253 };
254
255 /*!
256 * \brief Returns the QAction * associated with the given parameter \a id.
257 *
258 * Will return a nullptr if menu() has not been called.
259 */
260 QAction *action(MenuId id) const;
261
262public Q_SLOTS:
263 /*!
264 * \brief Opens the help page for the application.
265 *
266 * The application name is used as a key to determine what to display
267 * and the system will attempt to open <appName>/index.html.
268 */
269 void appHelpActivated();
270
271 /*!
272 * \brief Activates "What's This" help for the application.
273 */
274 void contextHelpActivated();
275
276 /*!
277 * \brief Opens an application specific dialog box.
278 *
279 * The method will try to open the about box using the following steps:
280 * - If the showAboutApplication() signal is connected, then it will be emitted.
281 * This means there is an application defined aboutBox.
282 * - If the aboutData was set in the constructor a KAboutApplicationDialog will be created
283 * with this aboutData.
284 * - Else a KAboutApplicationDialog will be created using KAboutData::applicationData().
285 */
286 void aboutApplication();
287
288 /*!
289 * \brief Opens the standard "About KDE" dialog box.
290 */
291 void aboutKDE();
292
293 /*!
294 * \brief Opens the standard "Report Bugs" dialog box.
295 */
296 void reportBug();
297
298 /*!
299 * \brief Opens the changing default application language dialog box.
300 */
301 void switchApplicationLanguage();
302
303 /*!
304 * \brief Opens the donate url on a browser.
305 * \since 5.24
306 */
307 void donate();
308
309private Q_SLOTS:
310 /*!
311 * \brief Connected to the menu pointer (if created) to detect a delete
312 * operation on the pointer.
313 *
314 * You should not delete the pointer in your code yourself.
315 * Let the KHelpMenu destructor do the job.
316 */
317 KXMLGUI_NO_EXPORT void menuDestroyed();
318
319 /*!
320 * \brief Connected to the dialogs (about kde and bug report) to detect
321 * when they are finished.
322 */
323 KXMLGUI_NO_EXPORT void dialogFinished();
324
325 /*!
326 * \brief This slot will delete a dialog ("About KDE" or "Report Bug...")
327 * if the dialog pointer is not zero and the dialog is not visible.
328 *
329 * This slot is activated by a one shot timer started in dialogHidden.
330 */
331 KXMLGUI_NO_EXPORT void timerExpired();
332
333Q_SIGNALS:
334 /*!
335 * \brief This signal is emitted from aboutApplication() if no
336 * "About <application>" string has been defined.
337 *
338 * The standard application specific dialog box that is
339 * normally activated in aboutApplication() will not be displayed
340 * when this signal is emitted.
341 */
342 void showAboutApplication();
343
344private:
345 KHelpMenuPrivate *const d;
346};
347
348#endif
349

source code of kxmlgui/src/khelpmenu.h