KXmlGui

khelpmenu.h
1 /*
2  This file is part of the KDE Libraries
3  SPDX-FileCopyrightText: 1999-2000 Espen Sand <[email protected]>
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 
16 class QMenu;
17 class QWidget;
18 class QAction;
19 
20 class KAboutData;
21 class 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 ([email protected])
106  */
107 
108 class KXMLGUI_EXPORT KHelpMenu : public QObject
109 {
110  Q_OBJECT
111 
112 public:
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 
179 public 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 
224 private 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  void menuDestroyed();
231 
232  /**
233  * Connected to the dialogs (about kde and bug report) to detect
234  * when they are finished.
235  */
236  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  void timerExpired();
244 
245 Q_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 
255 private:
256  KHelpMenuPrivate *const d;
257 };
258 
259 #endif
Standard KDE help menu with dialog boxes.
Definition: khelpmenu.h:108
This file is part of the KDE documentation.
Documentation copyright © 1996-2021 The KDE developers.
Generated on Tue Nov 30 2021 22:46:21 by doxygen 1.8.11 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.