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 khelpmenu.h KHelpMenu
25 *
26 * @short Standard %KDE help menu with dialog boxes.
27 *
28 * This class provides the standard %KDE help menu with the default "about"
29 * dialog boxes and help entry.
30 *
31 * This class is used in KMainWindow so
32 * normally you don't need to use this class yourself. However, if you
33 * need the help menu or any of its dialog boxes in your code that is
34 * not subclassed from KMainWindow you should use this class.
35 *
36 * The usage is simple:
37 *
38 * \code
39 * mHelpMenu = new KHelpMenu( this, <someText> );
40 * kmenubar->addMenu(mHelpMenu->menu() );
41 * \endcode
42 *
43 * or if you just want to open a dialog box:
44 *
45 * \code
46 * mHelpMenu = new KHelpMenu( this, <someText> );
47 * connect(this, &ClassFoo::someSignal, mHelpMenu, &KHelpMenu::aboutKDE);
48 * \endcode
49 *
50 * IMPORTANT:
51 * 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 html 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 * @verbatim
96 [KDE Action Restrictions][$i]
97 actions/help_contents=false
98 actions/help_whats_this=false
99 actions/help_report_bug=false
100 actions/switch_application_language=false
101 actions/help_about_app=false
102 actions/help_about_kde=false
103 @endverbatim
104 *
105 * @author Espen Sand (espen@kde.org)
106 */
107
108class KXMLGUI_EXPORT KHelpMenu : public QObject
109{
110 Q_OBJECT
111
112public:
113 /**
114 * Constructor.
115 *
116 * @param parent The parent of the dialog boxes. The boxes are modeless
117 * and will be centered with respect to the parent.
118 * @param aboutAppText User definable string that is used in the
119 * default application dialog box.
120 * @param showWhatsThis Decides whether a "What's this" entry will be
121 * added to the dialog.
122 *
123 */
124 explicit KHelpMenu(QWidget *parent = nullptr, const QString &aboutAppText = QString(), bool showWhatsThis = true);
125
126 /**
127 * Constructor.
128 *
129 * This alternative constructor is mainly useful if you want to
130 * override the standard actions (aboutApplication(), aboutKDE(),
131 * helpContents(), reportBug, and optionally whatsThis).
132 *
133 * @param parent The parent of the dialog boxes. The boxes are modeless
134 * and will be centered with respect to the parent.
135 * @param aboutData User and app data used in the About app dialog
136 * @param showWhatsThis Decides whether a "What's this" entry will be
137 * added to the dialog.
138 */
139 KHelpMenu(QWidget *parent, const KAboutData &aboutData, bool showWhatsThis = true);
140
141 /**
142 * Destructor
143 *
144 * Destroys dialogs and the menu pointer returned by menu
145 */
146 ~KHelpMenu() override;
147
148 /**
149 * Returns a popup menu you can use in the menu bar or where you
150 * need it.
151 *
152 * The returned menu is configured with an icon, a title and
153 * menu entries. Therefore adding the returned pointer to your menu
154 * is enough to have access to the help menu.
155 *
156 * Note: This method will only create one instance of the menu. If
157 * you call this method twice or more the same pointer is returned.
158 */
159 QMenu *menu();
160
161 enum MenuId {
162 menuHelpContents = 0,
163 menuWhatsThis = 1,
164 menuAboutApp = 2,
165 menuAboutKDE = 3,
166 menuReportBug = 4,
167 menuSwitchLanguage = 5,
168 menuDonate = 6, ///< @since 5.24
169 };
170
171 /**
172 * Returns the QAction * associated with the given parameter
173 * Will return a nullptr if menu() has not been called
174 *
175 * @param id The id of the action of which you want to get QAction *
176 */
177 QAction *action(MenuId id) const;
178
179public Q_SLOTS:
180 /**
181 * Opens the help page for the application. The application name is
182 * used as a key to determine what to display and the system will attempt
183 * to open \<appName\>/index.html.
184 */
185 void appHelpActivated();
186
187 /**
188 * Activates What's This help for the application.
189 */
190 void contextHelpActivated();
191
192 /**
193 * Opens an application specific dialog box.
194 *
195 * The method will try to open the about box using the following steps:
196 * - If the showAboutApplication() signal is connected, then it will be called.
197 * This means there is an application defined aboutBox.
198 * - If the aboutData was set in the constructor a KAboutApplicationDialog will be created.
199 * - Else a default about box using the aboutAppText from the constructor will be created.
200 */
201 void aboutApplication();
202
203 /**
204 * Opens the standard "About KDE" dialog box.
205 */
206 void aboutKDE();
207
208 /**
209 * Opens the standard "Report Bugs" dialog box.
210 */
211 void reportBug();
212
213 /**
214 * Opens the changing default application language dialog box.
215 */
216 void switchApplicationLanguage();
217
218 /**
219 * Opens the donate url.
220 * @since 5.24
221 */
222 void donate();
223
224private Q_SLOTS:
225 /**
226 * Connected to the menu pointer (if created) to detect a delete
227 * operation on the pointer. You should not delete the pointer in your
228 * code yourself. Let the KHelpMenu destructor do the job.
229 */
230 KXMLGUI_NO_EXPORT void menuDestroyed();
231
232 /**
233 * Connected to the dialogs (about kde and bug report) to detect
234 * when they are finished.
235 */
236 KXMLGUI_NO_EXPORT void dialogFinished();
237
238 /**
239 * This slot will delete a dialog (about kde or bug report) if the
240 * dialog pointer is not zero and the dialog is not visible. This
241 * slot is activated by a one shot timer started in dialogHidden
242 */
243 KXMLGUI_NO_EXPORT void timerExpired();
244
245Q_SIGNALS:
246 /**
247 * This signal is emitted from aboutApplication() if no
248 * "about application" string has been defined. The standard
249 * application specific dialog box that is normally activated in
250 * aboutApplication() will not be displayed when this signal
251 * is emitted.
252 */
253 void showAboutApplication();
254
255private:
256 KHelpMenuPrivate *const d;
257};
258
259#endif
260

source code of kxmlgui/src/khelpmenu.h