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 | |
30 | class KActionCollection; |
31 | class ; |
32 | class QWidget; |
33 | class QAction; |
34 | |
35 | class KAboutData; |
36 | class ; |
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 | |
110 | class KDEUI_EXPORT : 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 ( 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 | ( 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 | (); |
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 *(); |
167 | |
168 | enum |
169 | { |
170 | = 0, |
171 | = 1, |
172 | = 2, |
173 | = 3, |
174 | = 4, |
175 | = 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 *( 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 (); |
193 | |
194 | /** |
195 | * Activates What's This help for the application. |
196 | */ |
197 | void (); |
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 (); |
209 | |
210 | /** |
211 | * Opens the standard "About KDE" dialog box. |
212 | */ |
213 | void (); |
214 | |
215 | /** |
216 | * Opens the standard "Report Bugs" dialog box. |
217 | */ |
218 | void (); |
219 | |
220 | /** |
221 | * Opens the changing default application language dialog box. |
222 | */ |
223 | void (); |
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 (); |
232 | |
233 | /** |
234 | * Connected to the dialogs (about kde and bug report) to detect |
235 | * when they are finished. |
236 | */ |
237 | void (); |
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 (); |
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 (); |
255 | |
256 | private: |
257 | KHelpMenuPrivate *const ; |
258 | }; |
259 | |
260 | |
261 | #endif |
262 | |