KXmlGui

khelpmenu.h
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 );
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 );
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#if KXMLGUI_ENABLE_DEPRECATED_SINCE(6, 9)
114 /**
115 * Constructor.
116 *
117 * @param parent The parent of the dialog boxes. The boxes are modeless
118 * and will be centered with respect to the parent.
119 * @param unused This value is unused.
120 * @param showWhatsThis Decides whether a "What's this" entry will be
121 * added to the dialog.
122 *
123 * @deprecated Since 6.9, use one of the other constructors
124 */
125 KXMLGUI_DEPRECATED_VERSION(6, 9, "Use one of the other constructors")
126 explicit KHelpMenu(QWidget *parent, const QString &unused, bool showWhatsThis = true);
127#endif
128
129 /**
130 * Creates a KHelpMenu with the default app data (KAboutData::applicationData()).
131 *
132 * @param parent The parent of the dialog boxes. The boxes are modeless
133 * and will be centered with respect to the parent.
134 *
135 * @since 6.9
136 */
137 explicit KHelpMenu(QWidget *parent = nullptr);
138
139#if KXMLGUI_ENABLE_DEPRECATED_SINCE(6, 9)
140 /**
141 * Constructor.
142 *
143 * This alternative constructor is mainly useful if you want to
144 * override the standard actions (aboutApplication(), aboutKDE(),
145 * helpContents(), reportBug, and optionally whatsThis).
146 *
147 * @param parent The parent of the dialog boxes. The boxes are modeless
148 * and will be centered with respect to the parent.
149 * @param aboutData User and app data used in the About app dialog
150 * @param showWhatsThis Decides whether a "What's this" entry will be
151 * added to the dialog.
152 *
153 * @deprecated Since 6.9, use one of the other constructors
154 */
155 KXMLGUI_DEPRECATED_VERSION(6, 9, "Use one of the other constructors")
156 KHelpMenu(QWidget *parent, const KAboutData &aboutData, bool showWhatsThis);
157#endif
158
159 /**
160 * Creates a KHelpMenu with app data @p aboutData.
161 *
162 * This constructor is useful if you want to use the help menu with custom
163 * application data.
164 *
165 * @param parent The parent of the dialog boxes. The boxes are modeless
166 * and will be centered with respect to the parent.
167 * @param aboutData User and app data used in the About app dialog and for
168 * the actions in the help menu.
169 *
170 * @since 6.9
171 */
172 KHelpMenu(QWidget *parent, const KAboutData &aboutData);
173
174 /**
175 * Destructor
176 *
177 * Destroys dialogs and the menu pointer returned by menu
178 */
179 ~KHelpMenu() override;
180
181 /**
182 * Set whether to show the What's This menu entry in the help menu.
183 * The default is to show the menu entry (if Kiosk settings allow it).
184 * @since 6.9
185 */
186 void setShowWhatsThis(bool showWhatsThis);
187
188 /**
189 * Returns a popup menu you can use in the menu bar or where you
190 * need it.
191 *
192 * The returned menu is configured with an icon, a title and
193 * menu entries. Therefore adding the returned pointer to your menu
194 * is enough to have access to the help menu.
195 *
196 * Note: This method will only create one instance of the menu. If
197 * you call this method twice or more the same pointer is returned.
198 */
199 QMenu *menu();
200
201 enum MenuId {
202 menuHelpContents = 0,
203 menuWhatsThis = 1,
204 menuAboutApp = 2,
205 menuAboutKDE = 3,
206 menuReportBug = 4,
207 menuSwitchLanguage = 5,
208 menuDonate = 6, ///< @since 5.24
209 };
210
211 /**
212 * Returns the QAction * associated with the given parameter
213 * Will return a nullptr if menu() has not been called
214 *
215 * @param id The id of the action of which you want to get QAction *
216 */
217 QAction *action(MenuId id) const;
218
219public Q_SLOTS:
220 /**
221 * Opens the help page for the application. The application name is
222 * used as a key to determine what to display and the system will attempt
223 * to open <appName>/index.html.
224 */
225 void appHelpActivated();
226
227 /**
228 * Activates What's This help for the application.
229 */
230 void contextHelpActivated();
231
232 /**
233 * Opens an application specific dialog box.
234 *
235 * The method will try to open the about box using the following steps:
236 * - If the showAboutApplication() signal is connected, then it will be emitted.
237 * This means there is an application defined aboutBox.
238 * - If the aboutData was set in the constructor a KAboutApplicationDialog will be created
239 * with this aboutData.
240 * - Else a KAboutApplicationDialog will be created using KAboutData::applicationData().
241 */
242 void aboutApplication();
243
244 /**
245 * Opens the standard "About KDE" dialog box.
246 */
247 void aboutKDE();
248
249 /**
250 * Opens the standard "Report Bugs" dialog box.
251 */
252 void reportBug();
253
254 /**
255 * Opens the changing default application language dialog box.
256 */
257 void switchApplicationLanguage();
258
259 /**
260 * Opens the donate url.
261 * @since 5.24
262 */
263 void donate();
264
265private Q_SLOTS:
266 /**
267 * Connected to the menu pointer (if created) to detect a delete
268 * operation on the pointer. You should not delete the pointer in your
269 * code yourself. Let the KHelpMenu destructor do the job.
270 */
271 KXMLGUI_NO_EXPORT void menuDestroyed();
272
273 /**
274 * Connected to the dialogs (about kde and bug report) to detect
275 * when they are finished.
276 */
277 KXMLGUI_NO_EXPORT void dialogFinished();
278
279 /**
280 * This slot will delete a dialog (about kde or bug report) if the
281 * dialog pointer is not zero and the dialog is not visible. This
282 * slot is activated by a one shot timer started in dialogHidden
283 */
284 KXMLGUI_NO_EXPORT void timerExpired();
285
287 /**
288 * This signal is emitted from aboutApplication() if no
289 * "about application" string has been defined. The standard
290 * application specific dialog box that is normally activated in
291 * aboutApplication() will not be displayed when this signal
292 * is emitted.
293 */
295
296private:
297 KHelpMenuPrivate *const d;
298};
299
300#endif
Standard KDE help menu with dialog boxes.
Definition khelpmenu.h:109
void showAboutApplication()
This signal is emitted from aboutApplication() if no "about application" string has been defined.
Q_SIGNALSQ_SIGNALS
Q_SLOTSQ_SLOTS
This file is part of the KDE documentation.
Documentation copyright © 1996-2024 The KDE developers.
Generated on Sat Dec 21 2024 16:56:26 by doxygen 1.12.0 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.