1/*
2 * This file is part of the KDE Libraries
3 * Copyright (C) 1999-2000 Espen Sand (espen@kde.org)
4 *
5 * This library is free software; you can redistribute it and/or
6 * modify it under the terms of the GNU Library General Public
7 * License as published by the Free Software Foundation; either
8 * version 2 of the License, or (at your option) any later version.
9 *
10 * This library is distributed in the hope that it will be useful,
11 * but WITHOUT ANY WARRANTY; without even the implied warranty of
12 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
13 * Library General Public License for more details.
14 *
15 * You should have received a copy of the GNU Library General Public License
16 * along with this library; see the file COPYING.LIB. If not, write to
17 * the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
18 * Boston, MA 02110-1301, USA.
19 *
20 */
21
22#ifndef KHELPMENU_H
23#define KHELPMENU_H
24
25#include <kdeui_export.h>
26
27#include <QtCore/QObject>
28#include <QtCore/QString>
29
30class KActionCollection;
31class KMenu;
32class QWidget;
33class QAction;
34
35class KAboutData;
36class KHelpMenuPrivate;
37
38
39/**
40 * @short Standard %KDE help menu with dialog boxes.
41 *
42 * This class provides the standard %KDE help menu with the default "about"
43 * dialog boxes and help entry.
44 *
45 * This class is used in KMainWindow so
46 * normally you don't need to use this class yourself. However, if you
47 * need the help menu or any of its dialog boxes in your code that is
48 * not subclassed from KMainWindow you should use this class.
49 *
50 * The usage is simple:
51 *
52 * \code
53 * mHelpMenu = new KHelpMenu( this, <someText> );
54 * kmenubar->addMenu(mHelpMenu->menu() );
55 * \endcode
56 *
57 * or if you just want to open a dialog box:
58 *
59 * \code
60 * mHelpMenu = new KHelpMenu( this, <someText> );
61 * connect( this, SIGNAL(someSignal()), mHelpMenu,SLOT(aboutKDE()));
62 * \endcode
63 *
64 * IMPORTANT:
65 * The first time you use KHelpMenu::menu(), a KMenu object is
66 * allocated. Only one object is created by the class so if you call
67 * KHelpMenu::menu() twice or more, the same pointer is returned. The class
68 * will destroy the popupmenu in the destructor so do not delete this
69 * pointer yourself.
70 *
71 * The KHelpMenu object will be deleted when its parent is destroyed but you
72 * can delete it yourself if you want. The code below will always work.
73 *
74 * \code
75 * MyClass::~MyClass()
76 * {
77 * delete mHelpMenu;
78 * }
79 * \endcode
80 *
81 *
82 * Using your own "about application" dialog box:
83 *
84 * The standard "about application" dialog box is quite simple. If you
85 * need a dialog box with more functionality you must design that one
86 * yourself. When you want to display the dialog, you simply need to
87 * connect the help menu signal showAboutApplication() to your slot.
88 *
89 * \code
90 * void MyClass::myFunc()
91 * {
92 * ..
93 * KHelpMenu *helpMenu = new KHelpMenu( this );
94 * connect( helpMenu, SIGNAL(showAboutApplication()),
95 * this, SLOT(myDialogSlot()));
96 * ..
97 * }
98 *
99 * void MyClass::myDialogSlot()
100 * {
101 * <activate your custom dialog>
102 * }
103 * \endcode
104 *
105 * \image html khelpmenu.png "KDE Help Menu"
106 *
107 * @author Espen Sand (espen@kde.org)
108 */
109
110class KDEUI_EXPORT KHelpMenu : public QObject
111{
112 Q_OBJECT
113
114 public:
115 /**
116 * Constructor.
117 *
118 * @param parent The parent of the dialog boxes. The boxes are modeless
119 * and will be centered with respect to the parent.
120 * @param aboutAppText User definable string that is used in the
121 * default application dialog box.
122 * @param showWhatsThis Decides whether a "Whats this" entry will be
123 * added to the dialog.
124 *
125 */
126 explicit KHelpMenu( QWidget *parent=0, const QString &aboutAppText=QString(),
127 bool showWhatsThis=true );
128
129 /**
130 * Constructor.
131 *
132 * This alternative constructor is mainly useful if you want to
133 * overide the standard actions (aboutApplication(), aboutKDE(),
134 * helpContents(), reportBug, and optionally whatsThis).
135 *
136 * @param parent The parent of the dialog boxes. The boxes are modeless
137 * and will be centered with respect to the parent.
138 * @param aboutData User and app data used in the About app dialog
139 * @param showWhatsThis Decides whether a "Whats this" entry will be
140 * added to the dialog.
141 * @param actions KActionCollection that is used instead of the
142 * standard actions.
143 *
144 */
145 KHelpMenu( QWidget *parent, const KAboutData *aboutData,
146 bool showWhatsThis=true, KActionCollection *actions = 0 );
147
148 /**
149 * Destructor
150 *
151 * Destroys dialogs and the menu pointer retuned by menu
152 */
153 ~KHelpMenu();
154
155 /**
156 * Returns a popup menu you can use in the menu bar or where you
157 * need it.
158 *
159 * The returned menu is configured with an icon, a title and
160 * menu entries. Therefore adding the returned pointer to your menu
161 * is enougth to have access to the help menu.
162 *
163 * Note: This method will only create one instance of the menu. If
164 * you call this method twice or more the same pointer is returned.
165 */
166 KMenu *menu();
167
168 enum MenuId
169 {
170 menuHelpContents = 0,
171 menuWhatsThis = 1,
172 menuAboutApp = 2,
173 menuAboutKDE = 3,
174 menuReportBug = 4,
175 menuSwitchLanguage = 5
176 };
177
178 /**
179 * Returns the QAction * associated with the given parameter
180 * Will return NULL pointers if menu() has not been called
181 *
182 * @param id The id of the action of which you want to get QAction *
183 */
184 QAction *action( MenuId id ) const;
185
186 public Q_SLOTS:
187 /**
188 * Opens the help page for the application. The application name is
189 * used as a key to determine what to display and the system will attempt
190 * to open \<appName\>/index.html.
191 */
192 void appHelpActivated();
193
194 /**
195 * Activates What's This help for the application.
196 */
197 void contextHelpActivated();
198
199 /**
200 * Opens an application specific dialog box.
201 *
202 * The method will try to open the about box using the following steps:
203 * - If the showAboutApplication() signal is connected, then it will be called.
204 * This means there is an application defined aboutBox.
205 * - If the aboutData was set in the constructor a KAboutApplicationDialog will be created.
206 * - Else a default about box using the aboutAppText from the constructor will be created.
207 */
208 void aboutApplication();
209
210 /**
211 * Opens the standard "About KDE" dialog box.
212 */
213 void aboutKDE();
214
215 /**
216 * Opens the standard "Report Bugs" dialog box.
217 */
218 void reportBug();
219
220 /**
221 * Opens the changing default application language dialog box.
222 */
223 void switchApplicationLanguage();
224
225 private Q_SLOTS:
226 /**
227 * Connected to the menu pointer (if created) to detect a delete
228 * operation on the pointer. You should not delete the pointer in your
229 * code yourself. Let the KHelpMenu destructor do the job.
230 */
231 void menuDestroyed();
232
233 /**
234 * Connected to the dialogs (about kde and bug report) to detect
235 * when they are finished.
236 */
237 void dialogFinished();
238
239 /**
240 * This slot will delete a dialog (about kde or bug report) if the
241 * dialog pointer is not zero and the dialog is not visible. This
242 * slot is activated by a one shot timer started in dialogHidden
243 */
244 void timerExpired();
245
246 Q_SIGNALS:
247 /**
248 * This signal is emitted from aboutApplication() if no
249 * "about application" string has been defined. The standard
250 * application specific dialog box that is normally activated in
251 * aboutApplication() will not be displayed when this signal
252 * is emitted.
253 */
254 void showAboutApplication();
255
256 private:
257 KHelpMenuPrivate *const d;
258};
259
260
261#endif
262