summaryrefslogtreecommitdiffabout
path: root/microkde/kdeui/kmainwindow.h
Unidiff
Diffstat (limited to 'microkde/kdeui/kmainwindow.h') (more/less context) (ignore whitespace changes)
-rw-r--r--microkde/kdeui/kmainwindow.h19
1 files changed, 12 insertions, 7 deletions
diff --git a/microkde/kdeui/kmainwindow.h b/microkde/kdeui/kmainwindow.h
index 2dc8033..a3ac82f 100644
--- a/microkde/kdeui/kmainwindow.h
+++ b/microkde/kdeui/kmainwindow.h
@@ -1,520 +1,525 @@
1//Added by qt3to4:
2#include <QResizeEvent>
3#include <QChildEvent>
4#include <QCloseEvent>
5#include <QPaintEvent>
1/* 6/*
2 This file is part of the KDE libraries 7 This file is part of the KDE libraries
3 8
4 This library is free software; you can redistribute it and/or 9 This library is free software; you can redistribute it and/or
5 modify it under the terms of the GNU Library General Public 10 modify it under the terms of the GNU Library General Public
6 License version 2 as published by the Free Software Foundation. 11 License version 2 as published by the Free Software Foundation.
7 12
8 This library is distributed in the hope that it will be useful, 13 This library is distributed in the hope that it will be useful,
9 but WITHOUT ANY WARRANTY; without even the implied warranty of 14 but WITHOUT ANY WARRANTY; without even the implied warranty of
10 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 15 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
11 Library General Public License for more details. 16 Library General Public License for more details.
12 17
13 You should have received a copy of the GNU Library General Public License 18 You should have received a copy of the GNU Library General Public License
14 along with this library; see the file COPYING.LIB. If not, write to 19 along with this library; see the file COPYING.LIB. If not, write to
15 the Free Software Foundation, Inc., 59 Temple Place - Suite 330, 20 the Free Software Foundation, Inc., 59 Temple Place - Suite 330,
16 Boston, MA 02111-1307, USA. 21 Boston, MA 02111-1307, USA.
17 22
18 $Id$ 23 $Id$
19 24
20*/ 25*/
21 26
22 27
23 28
24#ifndef KMAINWINDOW_H 29#ifndef KMAINWINDOW_H
25#define KMAINWINDOW_H 30#define KMAINWINDOW_H
26 31
27/*US 32/*US
28#include "kxmlguifactory.h" 33#include "kxmlguifactory.h"
29#include "kxmlguiclient.h" 34#include "kxmlguiclient.h"
30#include "kxmlguibuilder.h" 35#include "kxmlguibuilder.h"
31#include <qmetaobject.h> 36#include <qmetaobject.h>
32 37
33class KPopupMenu; 38class KPopupMenu;
34class KXMLGUIFactory; 39class KXMLGUIFactory;
35class KConfig; 40class KConfig;
36class KHelpMenu; 41class KHelpMenu;
37class KStatusBar; 42class KStatusBar;
38class QStatusBar; 43class QStatusBar;
39class KMenuBar; 44class KMenuBar;
40class KMWSessionManaged; 45class KMWSessionManaged;
41class KAccel; 46class KAccel;
42class KToolBarMenuAction; 47class KToolBarMenuAction;
43*/ 48*/
44 49
45class QMenuBar; 50class QMenuBar;
46class QStatusBar; 51class QStatusBar;
47class KMainWindowPrivate; 52class KMainWindowPrivate;
48class KAction; 53class KAction;
49 54
50#include <ktoolbar.h> 55#include <ktoolbar.h>
51#include <ktoolbarhandler.h> 56#include <ktoolbarhandler.h>
52#include <kxmlguiclient.h> 57#include <kxmlguiclient.h>
53#include <qmainwindow.h> 58#include <q3mainwindow.h>
54#include <qptrlist.h> 59#include <q3ptrlist.h>
55 60
56class KActionCollection; 61class KActionCollection;
57 62
58class KMainWindow : public QMainWindow, virtual public KXMLGUIClient 63class KMainWindow : public Q3MainWindow, virtual public KXMLGUIClient
59{ 64{
60 Q_OBJECT 65 Q_OBJECT
61 66
62private: 67private:
63//US create private defaultconstructor 68//US create private defaultconstructor
64 KMainWindow() {;}; 69 KMainWindow() {;};
65 70
66 71
67public: 72public:
68 /** 73 /**
69 * Construct a main window. 74 * Construct a main window.
70 * 75 *
71 * @param parent The widget parent. This is usually 0 but it may also be the window 76 * @param parent The widget parent. This is usually 0 but it may also be the window
72 * group leader. In that case, the KMainWindow becomes sort of a 77 * group leader. In that case, the KMainWindow becomes sort of a
73 * secondary window. 78 * secondary window.
74 * 79 *
75 * @param name The object name. For session management and window management to work 80 * @param name The object name. For session management and window management to work
76 * properly, all main windows in the application should have a 81 * properly, all main windows in the application should have a
77 * different name. When passing 0 (the default), KMainWindow will create 82 * different name. When passing 0 (the default), KMainWindow will create
78 * a unique name, but it's recommended to explicitly pass a window name that will 83 * a unique name, but it's recommended to explicitly pass a window name that will
79 * also describe the type of the window. If there can be several windows of the same 84 * also describe the type of the window. If there can be several windows of the same
80 * type, append '#' (hash) to the name, and KMainWindow will append numbers to make 85 * type, append '#' (hash) to the name, and KMainWindow will append numbers to make
81 * the names unique. For example, for a mail client which has one main window showing 86 * the names unique. For example, for a mail client which has one main window showing
82 * the mails and folders, and which can also have one or more windows for composing 87 * the mails and folders, and which can also have one or more windows for composing
83 * mails, the name for the folders window should be e.g. "mainwindow" and 88 * mails, the name for the folders window should be e.g. "mainwindow" and
84 * for the composer windows "composer#". 89 * for the composer windows "composer#".
85 * 90 *
86 * @param f Specify the widget flags. The default is 91 * @param f Specify the widget flags. The default is
87 * WType_TopLevel and WDestructiveClose. TopLevel indicates that a 92 * WType_TopLevel and WDestructiveClose. TopLevel indicates that a
88 * main window is a toplevel window, regardless of whether it has a 93 * main window is a toplevel window, regardless of whether it has a
89 * parent or not. DestructiveClose indicates that a main window is 94 * parent or not. DestructiveClose indicates that a main window is
90 * automatically destroyed when its window is closed. Pass 0 if 95 * automatically destroyed when its window is closed. Pass 0 if
91 * you do not want this behavior. 96 * you do not want this behavior.
92 * 97 *
93 * KMainWindows must be created on the heap with 'new', like: 98 * KMainWindows must be created on the heap with 'new', like:
94 * <pre> KMainWindow *kmw = new KMainWindow (...</pre> 99 * <pre> KMainWindow *kmw = new KMainWindow (...</pre>
95 **/ 100 **/
96 //LR remove WDestructiveClose 101 //LR remove WDestructiveClose
97 KMainWindow( QWidget* parent = 0, const char *name = 0 ); //, WFlags f = WType_TopLevel /*| WDestructiveClose*/ ; 102 KMainWindow( QWidget* parent = 0, const char *name = 0 ); //, WFlags f = WType_TopLevel /*| WDestructiveClose*/ ;
98 103
99 104
100 /** 105 /**
101 * Destructor. 106 * Destructor.
102 * 107 *
103 * Will also destroy the toolbars, and menubar if 108 * Will also destroy the toolbars, and menubar if
104 * needed. 109 * needed.
105 */ 110 */
106 virtual ~KMainWindow(); 111 virtual ~KMainWindow();
107 112
108 /** 113 /**
109 * Retrieve the standard help menu. 114 * Retrieve the standard help menu.
110 * 115 *
111 * It contains entires for the 116 * It contains entires for the
112 * help system (activated by F1), an optional "What's This?" entry 117 * help system (activated by F1), an optional "What's This?" entry
113 * (activated by Shift F1), an application specific dialog box, 118 * (activated by Shift F1), an application specific dialog box,
114 * and an "About KDE" dialog box. 119 * and an "About KDE" dialog box.
115 * 120 *
116 * Example (adding a standard help menu to your application): 121 * Example (adding a standard help menu to your application):
117 * <pre> 122 * <pre>
118 * KPopupMenu *help = helpMenu( <myTextString> ); 123 * KPopupMenu *help = helpMenu( <myTextString> );
119 * menuBar()->insertItem( i18n("&Help"), help ); 124 * menuBar()->insertItem( i18n("&Help"), help );
120 * </pre> 125 * </pre>
121 * 126 *
122 * @param aboutAppText The string that is used in the application 127 * @param aboutAppText The string that is used in the application
123 * specific dialog box. If you leave this string empty the 128 * specific dialog box. If you leave this string empty the
124 * information in the global @ref KAboutData of the 129 * information in the global @ref KAboutData of the
125 * application will be used to make a standard dialog box. 130 * application will be used to make a standard dialog box.
126 * 131 *
127 * @param showWhatsThis Set this to false if you do not want to include 132 * @param showWhatsThis Set this to false if you do not want to include
128 * the "What's This" menu entry. 133 * the "What's This" menu entry.
129 * 134 *
130 * @return A standard help menu. 135 * @return A standard help menu.
131 */ 136 */
132//US KPopupMenu* helpMenu( const QString &aboutAppText = QString::null, 137//US KPopupMenu* helpMenu( const QString &aboutAppText = QString::null,
133//US bool showWhatsThis = TRUE ); 138//US bool showWhatsThis = TRUE );
134 139
135 /** 140 /**
136 * Returns the help menu. Creates a standard help menu if none exists yet. 141 * Returns the help menu. Creates a standard help menu if none exists yet.
137 * 142 *
138 * It contains entries for the 143 * It contains entries for the
139 * help system (activated by F1), an optional "What's This?" entry 144 * help system (activated by F1), an optional "What's This?" entry
140 * (activated by Shift F1), an application specific dialog box, 145 * (activated by Shift F1), an application specific dialog box,
141 * and an "About KDE" dialog box. You must create the application 146 * and an "About KDE" dialog box. You must create the application
142 * specific dialog box yourself. When the "About application" 147 * specific dialog box yourself. When the "About application"
143 * menu entry is activated, a signal will trigger the 148 * menu entry is activated, a signal will trigger the
144 * @ref showAboutApplication slot. See @ref showAboutApplication for more 149 * @ref showAboutApplication slot. See @ref showAboutApplication for more
145 * information. 150 * information.
146 * 151 *
147 * Example (adding a help menu to your application): 152 * Example (adding a help menu to your application):
148 * <pre> 153 * <pre>
149 * menuBar()->insertItem( i18n("&Help"), customHelpMenu() ); 154 * menuBar()->insertItem( i18n("&Help"), customHelpMenu() );
150 * </pre> 155 * </pre>
151 * 156 *
152 * @param showWhatsThis Set this to @p false if you do not want to include 157 * @param showWhatsThis Set this to @p false if you do not want to include
153 * the "What's This" menu entry. 158 * the "What's This" menu entry.
154 * 159 *
155 * @return A standard help menu. 160 * @return A standard help menu.
156 */ 161 */
157//US KPopupMenu* customHelpMenu( bool showWhatsThis = TRUE ); 162//US KPopupMenu* customHelpMenu( bool showWhatsThis = TRUE );
158 163
159 /** 164 /**
160 * @sect Session Management 165 * @sect Session Management
161 * 166 *
162 * Try to restore the toplevel widget as defined by the number (1..X). 167 * Try to restore the toplevel widget as defined by the number (1..X).
163 * 168 *
164 * If the session did not contain so high a number, the configuration 169 * If the session did not contain so high a number, the configuration
165 * is not changed and @p false returned. 170 * is not changed and @p false returned.
166 * 171 *
167 * That means clients could simply do the following: 172 * That means clients could simply do the following:
168 * <pre> 173 * <pre>
169 * if (kapp->isRestored()){ 174 * if (kapp->isRestored()){
170 * int n = 1; 175 * int n = 1;
171 * while (KMainWindow::canBeRestored(n)){ 176 * while (KMainWindow::canBeRestored(n)){
172 * (new childMW)->restore(n); 177 * (new childMW)->restore(n);
173 * n++; 178 * n++;
174 * } 179 * }
175 * } else { 180 * } else {
176 * // create default application as usual 181 * // create default application as usual
177 * } 182 * }
178 * </pre> 183 * </pre>
179 * Note that @ref QWidget::show() is called implicitly in restore. 184 * Note that @ref QWidget::show() is called implicitly in restore.
180 * 185 *
181 * With this you can easily restore all toplevel windows of your 186 * With this you can easily restore all toplevel windows of your
182 * application. 187 * application.
183 * 188 *
184 * If your application uses different kinds of toplevel 189 * If your application uses different kinds of toplevel
185 * windows, then you can use @ref KMainWindow::classNameOfToplevel(n) 190 * windows, then you can use @ref KMainWindow::classNameOfToplevel(n)
186 * to determine the exact type before calling the childMW 191 * to determine the exact type before calling the childMW
187 * constructor in the example from above. 192 * constructor in the example from above.
188 * 193 *
189 * If your client has only one kind of toplevel widgets (which 194 * If your client has only one kind of toplevel widgets (which
190 * should be pretty usual) then you should use the RESTORE-macro 195 * should be pretty usual) then you should use the RESTORE-macro
191 * for backwards compatibility with 3.1 and 3.0 branches: 196 * for backwards compatibility with 3.1 and 3.0 branches:
192 * 197 *
193 * <pre> 198 * <pre>
194 * if (kapp->isRestored()) 199 * if (kapp->isRestored())
195 * RESTORE(childMW) 200 * RESTORE(childMW)
196 * else { 201 * else {
197 * // create default application as usual 202 * // create default application as usual
198 * } 203 * }
199 * </pre> 204 * </pre>
200 * 205 *
201 * The macro expands to the term above but is easier to use and 206 * The macro expands to the term above but is easier to use and
202 * less code to write. 207 * less code to write.
203 * 208 *
204 * For new code or if you have more than one kind of toplevel 209 * For new code or if you have more than one kind of toplevel
205 * widget (each derived from @ref KMainWindow, of course), you can 210 * widget (each derived from @ref KMainWindow, of course), you can
206 * use the templated @ref kRestoreMainWindows global functions: 211 * use the templated @ref kRestoreMainWindows global functions:
207 * 212 *
208 * <pre> 213 * <pre>
209 * if (kapp->isRestored()) 214 * if (kapp->isRestored())
210 * kRestoreMainWindows< childMW1, childMW2, childMW3 >(); 215 * kRestoreMainWindows< childMW1, childMW2, childMW3 >();
211 * else { 216 * else {
212 * // create default application as usual 217 * // create default application as usual
213 * } 218 * }
214 * </pre> 219 * </pre>
215 * 220 *
216 * Currently, these functions are provided for up to three 221 * Currently, these functions are provided for up to three
217 * template arguments. If you need more, tell us. To help you in 222 * template arguments. If you need more, tell us. To help you in
218 * deciding whether or not you can use @ref kRestoreMainWindows, a 223 * deciding whether or not you can use @ref kRestoreMainWindows, a
219 * define KDE_RESTORE_MAIN_WINDOWS_NUM_TEMPLATE_ARGS is provided. 224 * define KDE_RESTORE_MAIN_WINDOWS_NUM_TEMPLATE_ARGS is provided.
220 * 225 *
221 * @see restore() 226 * @see restore()
222 * @see classNameOfToplevel() 227 * @see classNameOfToplevel()
223 * 228 *
224 **/ 229 **/
225 static bool canBeRestored( int number ); 230 static bool canBeRestored( int number );
226 231
227 /** 232 /**
228 * Returns the @ref className() of the @p number of the toplevel window which 233 * Returns the @ref className() of the @p number of the toplevel window which
229 * should be restored. 234 * should be restored.
230 * 235 *
231 * This is only useful if your application uses 236 * This is only useful if your application uses
232 * different kinds of toplevel windows. 237 * different kinds of toplevel windows.
233 */ 238 */
234 static const QString classNameOfToplevel( int number ); 239 static const QString classNameOfToplevel( int number );
235 240
236 /** 241 /**
237 * Restore the session specified by @p number. 242 * Restore the session specified by @p number.
238 * 243 *
239 * Returns @p false if this 244 * Returns @p false if this
240 * fails, otherwise returns @p true and shows the window. 245 * fails, otherwise returns @p true and shows the window.
241 * You should call @ref canBeRestored() first. 246 * You should call @ref canBeRestored() first.
242 * If @p show is true (default), this widget will be shown automatically. 247 * If @p show is true (default), this widget will be shown automatically.
243 */ 248 */
244 bool restore( int number, bool show = TRUE ); 249 bool restore( int number, bool show = TRUE );
245 250
246//US virtual KXMLGUIFactory *guiFactory(); 251//US virtual KXMLGUIFactory *guiFactory();
247 252
248 /** 253 /**
249 * Create a GUI given a local XML file. 254 * Create a GUI given a local XML file.
250 * 255 *
251 * If @p xmlfile is NULL, 256 * If @p xmlfile is NULL,
252 * then it will try to construct a local XML filename like 257 * then it will try to construct a local XML filename like
253 * appnameui.rc where 'appname' is your app's name. If that file 258 * appnameui.rc where 'appname' is your app's name. If that file
254 * does not exist, then the XML UI code will only use the global 259 * does not exist, then the XML UI code will only use the global
255 * (standard) XML file for the layout purposes. 260 * (standard) XML file for the layout purposes.
256 * 261 *
257 * Note that when passing true for the conserveMemory argument subsequent 262 * Note that when passing true for the conserveMemory argument subsequent
258 * calls to guiFactory()->addClient/removeClient may not work as expected. 263 * calls to guiFactory()->addClient/removeClient may not work as expected.
259 * Also retrieving references to containers like popup menus or toolbars using 264 * Also retrieving references to containers like popup menus or toolbars using
260 * the container method will not work. 265 * the container method will not work.
261 * 266 *
262 * @param xmlfile The local xmlfile (relative or absolute) 267 * @param xmlfile The local xmlfile (relative or absolute)
263 * @param _conserveMemory Specify whether createGUI() should call 268 * @param _conserveMemory Specify whether createGUI() should call
264 * @ref KXMLGuiClient::conserveMemory() to free all memory 269 * @ref KXMLGuiClient::conserveMemory() to free all memory
265 * allocated by the @ref QDomDocument and by the KXMLGUIFactory. 270 * allocated by the @ref QDomDocument and by the KXMLGUIFactory.
266 */ 271 */
267 void createGUI( const QString &xmlfile = QString::null, bool _conserveMemory = TRUE ); 272 void createGUI( const QString &xmlfile = QString::null, bool _conserveMemory = TRUE );
268 273
269 /** 274 /**
270 * Enables the build of a standard help menu when calling createGUI(). 275 * Enables the build of a standard help menu when calling createGUI().
271 * 276 *
272 * The default behavior is to build one, you must call this function 277 * The default behavior is to build one, you must call this function
273 * to disable it 278 * to disable it
274 */ 279 */
275 void setHelpMenuEnabled(bool showHelpMenu = true); 280 void setHelpMenuEnabled(bool showHelpMenu = true);
276 281
277 /** 282 /**
278 * Return @p true when the help menu is enabled 283 * Return @p true when the help menu is enabled
279 */ 284 */
280 bool isHelpMenuEnabled(); 285 bool isHelpMenuEnabled();
281 286
282 287
283 /** 288 /**
284 * Returns true, if there is a menubar 289 * Returns true, if there is a menubar
285 * @since 3.1 290 * @since 3.1
286 */ 291 */
287 bool hasMenuBar(); 292 bool hasMenuBar();
288 293
289 /** 294 /**
290 * Returns a pointer to the menu bar. 295 * Returns a pointer to the menu bar.
291 * 296 *
292 * If there is no menu bar yet one will be created. 297 * If there is no menu bar yet one will be created.
293 **/ 298 **/
294//US KMenuBar *menuBar(); 299//US KMenuBar *menuBar();
295 QMenuBar *menuBar(); 300 QMenuBar *menuBar();
296 301
297 /** 302 /**
298 * Returns a pointer to the status bar. 303 * Returns a pointer to the status bar.
299 * 304 *
300 * If there is no 305 * If there is no
301 * status bar yet one will be created. 306 * status bar yet one will be created.
302 */ 307 */
303//US KStatusBar *statusBar(); 308//US KStatusBar *statusBar();
304 QStatusBar *statusBar(); 309 QStatusBar *statusBar();
305 310
306 /** 311 /**
307 * List of members of KMainWindow class. 312 * List of members of KMainWindow class.
308 */ 313 */
309//US static QPtrList<KMainWindow>* memberList; 314//US static QPtrList<KMainWindow>* memberList;
310 315
311 /** 316 /**
312 * Returns a pointer to the toolbar with the specified name. 317 * Returns a pointer to the toolbar with the specified name.
313 * This refers to toolbars created dynamically from the XML UI 318 * This refers to toolbars created dynamically from the XML UI
314 * framework. If the toolbar does not exist one will be created. 319 * framework. If the toolbar does not exist one will be created.
315 * 320 *
316 * @param name The internal name of the toolbar. If no name is 321 * @param name The internal name of the toolbar. If no name is
317 * specified "mainToolBar" is assumed. 322 * specified "mainToolBar" is assumed.
318 * 323 *
319 * @return A pointer to the toolbar 324 * @return A pointer to the toolbar
320 **/ 325 **/
321 KToolBar *toolBar( const char *name=0 ); 326 KToolBar *toolBar( const char *name=0 );
322 // method for getting rid of KDE-Crap 327 // method for getting rid of KDE-Crap
323 QToolBar *tBar( ); 328 Q3ToolBar *tBar( );
324 329
325 /** 330 /**
326 * @return An iterator over the list of all toolbars for this window. 331 * @return An iterator over the list of all toolbars for this window.
327 */ 332 */
328 QPtrListIterator<KToolBar> toolBarIterator(); 333 Q3PtrListIterator<KToolBar> toolBarIterator();
329 334
330 /** 335 /**
331 * @return A KAccel instance bound to this mainwindow. Used automatically 336 * @return A KAccel instance bound to this mainwindow. Used automatically
332 * by KAction to make keybindings work in all cases. 337 * by KAction to make keybindings work in all cases.
333 */ 338 */
334 KAccel *accel(); 339 KAccel *accel();
335 340
336 void setFrameBorderWidth( int ) {} 341 void setFrameBorderWidth( int ) {}
337 342
338 /** 343 /**
339 * Call this to enable "auto-save" of toolbar/menubar/statusbar settings 344 * Call this to enable "auto-save" of toolbar/menubar/statusbar settings
340 * (and optionally window size). 345 * (and optionally window size).
341 * If the *bars were moved around/shown/hidden when the window is closed, 346 * If the *bars were moved around/shown/hidden when the window is closed,
342 * saveMainWindowSettings( KGlobal::config(), groupName ) will be called. 347 * saveMainWindowSettings( KGlobal::config(), groupName ) will be called.
343 * 348 *
344 * @param groupName a name that identifies this "type of window". 349 * @param groupName a name that identifies this "type of window".
345 * You can have several types of window in the same application. 350 * You can have several types of window in the same application.
346 * 351 *
347 * @param saveWindowSize set it to true to include the window size 352 * @param saveWindowSize set it to true to include the window size
348 * when saving. 353 * when saving.
349 * 354 *
350 * Typically, you will call setAutoSaveSettings() in your 355 * Typically, you will call setAutoSaveSettings() in your
351 * KMainWindow-inherited class constructor, and it will take care 356 * KMainWindow-inherited class constructor, and it will take care
352 * of restoring and saving automatically. Make sure you call this 357 * of restoring and saving automatically. Make sure you call this
353 * _after all_ your *bars have been created. 358 * _after all_ your *bars have been created.
354 */ 359 */
355 void setAutoSaveSettings( const QString & groupName = QString::fromLatin1("MainWindow"), 360 void setAutoSaveSettings( const QString & groupName = QString::fromLatin1("MainWindow"),
356 bool saveWindowSize = true ); 361 bool saveWindowSize = true );
357 362
358 /** 363 /**
359 * Disable the auto-save-settings feature. 364 * Disable the auto-save-settings feature.
360 * You don't normally need to call this, ever. 365 * You don't normally need to call this, ever.
361 */ 366 */
362 void resetAutoSaveSettings(); 367 void resetAutoSaveSettings();
363 368
364 /** 369 /**
365 * @return the current autosave setting, i.e. true if setAutoSaveSettings() was called, 370 * @return the current autosave setting, i.e. true if setAutoSaveSettings() was called,
366 * false by default or if resetAutoSaveSettings() was called. 371 * false by default or if resetAutoSaveSettings() was called.
367 * @since 3.1 372 * @since 3.1
368 */ 373 */
369 bool autoSaveSettings() const; 374 bool autoSaveSettings() const;
370 375
371 /** 376 /**
372 * @return the group used for setting-autosaving. 377 * @return the group used for setting-autosaving.
373 * Only meaningful if setAutoSaveSettings() was called. 378 * Only meaningful if setAutoSaveSettings() was called.
374 * This can be useful for forcing a save or an apply, e.g. before and after 379 * This can be useful for forcing a save or an apply, e.g. before and after
375 * using KEditToolbar. 380 * using KEditToolbar.
376 * @since 3.1 381 * @since 3.1
377 */ 382 */
378 QString autoSaveGroup() const; 383 QString autoSaveGroup() const;
379 384
380 /** 385 /**
381 * Read settings for statusbar, menubar and toolbar from their respective 386 * Read settings for statusbar, menubar and toolbar from their respective
382 * groups in the config file and apply them. 387 * groups in the config file and apply them.
383 * 388 *
384 * @param config Config file to read the settings from. 389 * @param config Config file to read the settings from.
385 * @param groupName Group name to use. If not specified, the last used 390 * @param groupName Group name to use. If not specified, the last used
386 * group name is used. 391 * group name is used.
387 */ 392 */
388 void applyMainWindowSettings(KConfig *config, const QString &groupName = QString::null); 393 void applyMainWindowSettings(KConfig *config, const QString &groupName = QString::null);
389 394
390 /** 395 /**
391 * Save settings for statusbar, menubar and toolbar to their respective 396 * Save settings for statusbar, menubar and toolbar to their respective
392 * groups in the config file @p config. 397 * groups in the config file @p config.
393 * 398 *
394 * @param config Config file to save the settings to. 399 * @param config Config file to save the settings to.
395 * @param groupName Group name to use. If not specified, the last used 400 * @param groupName Group name to use. If not specified, the last used
396 * group name is used 401 * group name is used
397 */ 402 */
398 void saveMainWindowSettings(KConfig *config, const QString &groupName = QString::null); 403 void saveMainWindowSettings(KConfig *config, const QString &groupName = QString::null);
399 404
400 /** 405 /**
401 * Sets whether KMainWindow should provide a menu that allows showing/hiding 406 * Sets whether KMainWindow should provide a menu that allows showing/hiding
402 * the available toolbars ( using @ref KToggleToolBarAction ) . In case there 407 * the available toolbars ( using @ref KToggleToolBarAction ) . In case there
403 * is only one toolbar configured a simple 'Show <toolbar name here>' menu item 408 * is only one toolbar configured a simple 'Show <toolbar name here>' menu item
404 * is shown. 409 * is shown.
405 * 410 *
406 * The menu / menu item is implemented using xmlgui. It will be inserted in your 411 * The menu / menu item is implemented using xmlgui. It will be inserted in your
407 * menu structure in the 'Settings' menu. 412 * menu structure in the 'Settings' menu.
408 * 413 *
409 * If your application uses a non-standard xmlgui resource file then you can 414 * If your application uses a non-standard xmlgui resource file then you can
410 * specify the exact position of the menu / menu item by adding a 415 * specify the exact position of the menu / menu item by adding a
411 * &lt;Merge name="StandardToolBarMenuHandler" /&gt; 416 * &lt;Merge name="StandardToolBarMenuHandler" /&gt;
412 * line to the settings menu section of your resource file ( usually appname.rc ). 417 * line to the settings menu section of your resource file ( usually appname.rc ).
413 * 418 *
414 * Note that you should enable this feature before calling createGUI() ( or similar ) . 419 * Note that you should enable this feature before calling createGUI() ( or similar ) .
415 * You enable/disable it anytime if you pass false to the conserveMemory argument of createGUI. 420 * You enable/disable it anytime if you pass false to the conserveMemory argument of createGUI.
416 * @since 3.1 421 * @since 3.1
417 */ 422 */
418 void setStandardToolBarMenuEnabled( bool enable ); 423 void setStandardToolBarMenuEnabled( bool enable );
419 /// @since 3.1 424 /// @since 3.1
420 bool isStandardToolBarMenuEnabled() const; 425 bool isStandardToolBarMenuEnabled() const;
421 426
422 427
423 /** 428 /**
424 * Sets whether KMainWindow should provide a menu that allows showing/hiding 429 * Sets whether KMainWindow should provide a menu that allows showing/hiding
425 * of the statusbar ( using @ref KToggleStatusBarAction ). 430 * of the statusbar ( using @ref KToggleStatusBarAction ).
426 * 431 *
427 * The menu / menu item is implemented using xmlgui. It will be inserted 432 * The menu / menu item is implemented using xmlgui. It will be inserted
428 * in your menu structure in the 'Settings' menu. 433 * in your menu structure in the 'Settings' menu.
429 * 434 *
430 * Note that you should enable this feature before calling createGUI() 435 * Note that you should enable this feature before calling createGUI()
431 * ( or similar ). 436 * ( or similar ).
432 * 437 *
433 * If an application maintains the action on its own (i.e. never calls 438 * If an application maintains the action on its own (i.e. never calls
434 * this function) a connection needs to be made to let KMainWindow 439 * this function) a connection needs to be made to let KMainWindow
435 * know when that status (hidden/shown) of the statusbar has changed. 440 * know when that status (hidden/shown) of the statusbar has changed.
436 * For example: 441 * For example:
437 * connect(action, SIGNAL(activated()), 442 * connect(action, SIGNAL(activated()),
438 * kmainwindow, SLOT(setSettingsDirty())); 443 * kmainwindow, SLOT(setSettingsDirty()));
439 * Otherwise the status (hidden/show) of the statusbar might not be saved 444 * Otherwise the status (hidden/show) of the statusbar might not be saved
440 * by KMainWindow. 445 * by KMainWindow.
441 * @since 3.2 446 * @since 3.2
442 */ 447 */
443 void createStandardStatusBarAction(); 448 void createStandardStatusBarAction();
444 449
445 450
446 /** 451 /**
447 * Returns a pointer to the mainwindows action responsible for the toolbars menu 452 * Returns a pointer to the mainwindows action responsible for the toolbars menu
448 * @since 3.1 453 * @since 3.1
449 */ 454 */
450 KAction *toolBarMenuAction(); 455 KAction *toolBarMenuAction();
451 456
452 // why do we support old gcc versions? using KXMLGUIBuilder::finalizeGUI; 457 // why do we support old gcc versions? using KXMLGUIBuilder::finalizeGUI;
453 /// @since 3.1 458 /// @since 3.1
454 virtual void finalizeGUI( KXMLGUIClient *client ); 459 virtual void finalizeGUI( KXMLGUIClient *client );
455 460
456 /** 461 /**
457 * @internal 462 * @internal
458 */ 463 */
459 void finalizeGUI( bool force ); 464 void finalizeGUI( bool force );
460 465
461 /** 466 /**
462 * @return true if a -geometry argument was given on the command line, 467 * @return true if a -geometry argument was given on the command line,
463 * and this is the first window created (the one on which this option applies) 468 * and this is the first window created (the one on which this option applies)
464 */ 469 */
465 bool initialGeometrySet() const; 470 bool initialGeometrySet() const;
466 471
467 /** 472 /**
468 * @internal 473 * @internal
469 * Used from Konqueror when reusing the main window. 474 * Used from Konqueror when reusing the main window.
470 */ 475 */
471 void ignoreInitialGeometry(); 476 void ignoreInitialGeometry();
472 477
473 /** 478 /**
474 * @return the size the mainwindow should have so that the central 479 * @return the size the mainwindow should have so that the central
475 * widget will be of @p size. 480 * widget will be of @p size.
476 */ 481 */
477 QSize sizeForCentralWidgetSize(QSize size); 482 QSize sizeForCentralWidgetSize(QSize size);
478 483
479public slots: 484public slots:
480 /** 485 /**
481 * Makes a KDE compliant caption. 486 * Makes a KDE compliant caption.
482 * 487 *
483 * @param caption Your caption. @em Do @em not include the application name 488 * @param caption Your caption. @em Do @em not include the application name
484 * in this string. It will be added automatically according to the KDE 489 * in this string. It will be added automatically according to the KDE
485 * standard. 490 * standard.
486 */ 491 */
487 virtual void setCaption( const QString &caption ); 492 virtual void setCaption( const QString &caption );
488 /** 493 /**
489 * Makes a KDE compliant caption. 494 * Makes a KDE compliant caption.
490 * 495 *
491 * @param caption Your caption. @em Do @em not include the application name 496 * @param caption Your caption. @em Do @em not include the application name
492 * in this string. It will be added automatically according to the KDE 497 * in this string. It will be added automatically according to the KDE
493 * standard. 498 * standard.
494 * @param modified Specify whether the document is modified. This displays 499 * @param modified Specify whether the document is modified. This displays
495 * an additional sign in the title bar, usually "**". 500 * an additional sign in the title bar, usually "**".
496 */ 501 */
497 virtual void setCaption( const QString &caption, bool modified ); 502 virtual void setCaption( const QString &caption, bool modified );
498 503
499 /** 504 /**
500 * Make a plain caption without any modifications. 505 * Make a plain caption without any modifications.
501 * 506 *
502 * @param caption Your caption. This is the string that will be 507 * @param caption Your caption. This is the string that will be
503 * displayed in the window title. 508 * displayed in the window title.
504 */ 509 */
505 virtual void setPlainCaption( const QString &caption ); 510 virtual void setPlainCaption( const QString &caption );
506 511
507 /** 512 /**
508 * Open the help page for the application. 513 * Open the help page for the application.
509 * 514 *
510 * The application name is 515 * The application name is
511 * used as a key to determine what to display and the system will attempt 516 * used as a key to determine what to display and the system will attempt
512 * to open <appName>/index.html. 517 * to open <appName>/index.html.
513 * 518 *
514 * This method is intended for use by a help button in the toolbar or 519 * This method is intended for use by a help button in the toolbar or
515 * components outside the regular help menu. Use @ref helpMenu() when you 520 * components outside the regular help menu. Use @ref helpMenu() when you
516 * want to provide access to the help system from the help menu. 521 * want to provide access to the help system from the help menu.
517 * 522 *
518 * Example (adding a help button to the first toolbar): 523 * Example (adding a help button to the first toolbar):
519 * 524 *
520 * <pre> 525 * <pre>
@@ -569,209 +574,209 @@ public slots:
569protected: 574protected:
570 void paintEvent( QPaintEvent* e ); 575 void paintEvent( QPaintEvent* e );
571 void childEvent( QChildEvent* e); 576 void childEvent( QChildEvent* e);
572 void resizeEvent( QResizeEvent* e); 577 void resizeEvent( QResizeEvent* e);
573 /** 578 /**
574 * Reimplemented to call the queryClose() and queryExit() handlers. 579 * Reimplemented to call the queryClose() and queryExit() handlers.
575 * 580 *
576 * We recommend that you reimplement the handlers rather than @ref closeEvent(). 581 * We recommend that you reimplement the handlers rather than @ref closeEvent().
577 * If you do it anyway, ensure to call the base implementation to keep 582 * If you do it anyway, ensure to call the base implementation to keep
578 * @ref queryExit() running. 583 * @ref queryExit() running.
579 */ 584 */
580 virtual void closeEvent ( QCloseEvent *); 585 virtual void closeEvent ( QCloseEvent *);
581 586
582 // KDE4 This seems to be flawed to me. Either the app has only one 587 // KDE4 This seems to be flawed to me. Either the app has only one
583 // mainwindow, so queryClose() is enough, or if it can have more of them, 588 // mainwindow, so queryClose() is enough, or if it can have more of them,
584 // then the windows should take care of themselves, and queryExit() 589 // then the windows should take care of themselves, and queryExit()
585 // would be useful only for the annoying 'really quit' dialog, which 590 // would be useful only for the annoying 'really quit' dialog, which
586 // also doesn't make sense in apps with multiple mainwindows. 591 // also doesn't make sense in apps with multiple mainwindows.
587 // And saving configuration in something called queryExit()? IMHO 592 // And saving configuration in something called queryExit()? IMHO
588 // one can e.g. use KApplication::shutDown(), which if nothing else 593 // one can e.g. use KApplication::shutDown(), which if nothing else
589 // has at least better fitting name. 594 // has at least better fitting name.
590 // See also KApplication::sessionSaving(). 595 // See also KApplication::sessionSaving().
591 // This stuff should get changed somehow, so that it at least doesn't 596 // This stuff should get changed somehow, so that it at least doesn't
592 // mess with session management. 597 // mess with session management.
593 /** 598 /**
594 Called before the very last window is closed, either by the 599 Called before the very last window is closed, either by the
595 user or indirectly by the session manager. 600 user or indirectly by the session manager.
596 601
597 It is not recommended to do any user interaction in this 602 It is not recommended to do any user interaction in this
598 function other than indicating severe errors. Better ask the 603 function other than indicating severe errors. Better ask the
599 user on @ref queryClose() (see below). 604 user on @ref queryClose() (see below).
600 605
601 A typical usage of @ref queryExit() is to write configuration data back. 606 A typical usage of @ref queryExit() is to write configuration data back.
602 Note that the application may continue to run after @ref queryExit() 607 Note that the application may continue to run after @ref queryExit()
603 (the user may have cancelled a shutdown), so you should not do any cleanups 608 (the user may have cancelled a shutdown), so you should not do any cleanups
604 here. The purpose of @ref queryExit() is purely to prepare the application 609 here. The purpose of @ref queryExit() is purely to prepare the application
605 (with possible user interaction) so it can safely be closed later (without 610 (with possible user interaction) so it can safely be closed later (without
606 user interaction). 611 user interaction).
607 612
608 If you need to do serious things on exit (like shutting a 613 If you need to do serious things on exit (like shutting a
609 dial-up connection down), connect to the signal 614 dial-up connection down), connect to the signal
610 @ref KApplication::shutDown(). 615 @ref KApplication::shutDown().
611 616
612 Default implementation returns @p true. Returning @p false will 617 Default implementation returns @p true. Returning @p false will
613 cancel the exiting. In the latter case, the last window will 618 cancel the exiting. In the latter case, the last window will
614 remain visible. If KApplication::sessionSaving() is true, refusing 619 remain visible. If KApplication::sessionSaving() is true, refusing
615 the exit will also cancel KDE logout. 620 the exit will also cancel KDE logout.
616 621
617 @see queryClose() 622 @see queryClose()
618 @see KApplication::sessionSaving() 623 @see KApplication::sessionSaving()
619 */ 624 */
620 virtual bool queryExit(); 625 virtual bool queryExit();
621 626
622 /** 627 /**
623 Called before the window is closed, either by the user or indirectly by 628 Called before the window is closed, either by the user or indirectly by
624 the session manager. 629 the session manager.
625 630
626 The purpose of this function is to prepare the window in a way that it is 631 The purpose of this function is to prepare the window in a way that it is
627 safe to close it, i.e. without the user losing some data. 632 safe to close it, i.e. without the user losing some data.
628 633
629 Default implementation returns true. Returning @p false will cancel 634 Default implementation returns true. Returning @p false will cancel
630 the closing, and, if KApplication::sessionSaving() is true, it will also 635 the closing, and, if KApplication::sessionSaving() is true, it will also
631 cancel KDE logout. 636 cancel KDE logout.
632 637
633 Reimplement this function to prevent the user from losing data. 638 Reimplement this function to prevent the user from losing data.
634 Example: 639 Example:
635 <pre> 640 <pre>
636 641
637 switch ( KMessageBox::warningYesNoCancel( this, 642 switch ( KMessageBox::warningYesNoCancel( this,
638 i18n("Save changes to document foo?")) ) { 643 i18n("Save changes to document foo?")) ) {
639 case KMessageBox::Yes : 644 case KMessageBox::Yes :
640 // save document here. If saving fails, return FALSE; 645 // save document here. If saving fails, return FALSE;
641 return TRUE; 646 return TRUE;
642 case KMessageBox::No : 647 case KMessageBox::No :
643 return TRUE; 648 return TRUE;
644 default: // cancel 649 default: // cancel
645 return FALSE; 650 return FALSE;
646 651
647 </pre> 652 </pre>
648 653
649 @see queryExit() 654 @see queryExit()
650 @see KApplication::sessionSaving() 655 @see KApplication::sessionSaving()
651 656
652 */ 657 */
653 virtual bool queryClose(); 658 virtual bool queryClose();
654 /** 659 /**
655 * Save your instance-specific properties. The function is 660 * Save your instance-specific properties. The function is
656 * invoked when the session manager requests your application 661 * invoked when the session manager requests your application
657 * to save its state. 662 * to save its state.
658 * 663 *
659 * You @em must @em not change the group of the @p kconfig object, since 664 * You @em must @em not change the group of the @p kconfig object, since
660 * KMainWindow uses one group for each window. Please 665 * KMainWindow uses one group for each window. Please
661 * reimplement these function in childclasses. 666 * reimplement these function in childclasses.
662 * 667 *
663 * Note: No user interaction is allowed 668 * Note: No user interaction is allowed
664 * in this function! 669 * in this function!
665 * 670 *
666 */ 671 */
667 virtual void saveProperties( KConfig* ) {} 672 virtual void saveProperties( KConfig* ) {}
668 673
669 /** 674 /**
670 * Read your instance-specific properties. 675 * Read your instance-specific properties.
671 */ 676 */
672 virtual void readProperties( KConfig* ) {} 677 virtual void readProperties( KConfig* ) {}
673 678
674 /** 679 /**
675 * Save your application-wide properties. The function is 680 * Save your application-wide properties. The function is
676 * invoked when the session manager requests your application 681 * invoked when the session manager requests your application
677 * to save its state. 682 * to save its state.
678 * 683 *
679 * This function is similar to @ref saveProperties() but is only called for 684 * This function is similar to @ref saveProperties() but is only called for
680 * the very first main window, regardless how many main window are open. 685 * the very first main window, regardless how many main window are open.
681 686
682 * Override it if you need to save other data about your documents on 687 * Override it if you need to save other data about your documents on
683 * session end. sessionConfig is a config to which that data should be 688 * session end. sessionConfig is a config to which that data should be
684 * saved. Normally, you don't need this function. But if you want to save 689 * saved. Normally, you don't need this function. But if you want to save
685 * data about your documents that are not in opened windows you might need 690 * data about your documents that are not in opened windows you might need
686 * it. 691 * it.
687 * 692 *
688 * Default implementation does nothing. 693 * Default implementation does nothing.
689 */ 694 */
690 virtual void saveGlobalProperties( KConfig* sessionConfig ); 695 virtual void saveGlobalProperties( KConfig* sessionConfig );
691 696
692 /** 697 /**
693 * The counterpart of @ref saveGlobalProperties(). 698 * The counterpart of @ref saveGlobalProperties().
694 * 699 *
695 * Read the application-specific properties in again. 700 * Read the application-specific properties in again.
696 */ 701 */
697 virtual void readGlobalProperties( KConfig* sessionConfig ); 702 virtual void readGlobalProperties( KConfig* sessionConfig );
698 void savePropertiesInternal( KConfig*, int ); 703 void savePropertiesInternal( KConfig*, int );
699 bool readPropertiesInternal( KConfig*, int ); 704 bool readPropertiesInternal( KConfig*, int );
700 705
701 /** 706 /**
702 * For inherited classes 707 * For inherited classes
703 */ 708 */
704 bool settingsDirty() const; 709 bool settingsDirty() const;
705 /** 710 /**
706 * For inherited classes 711 * For inherited classes
707 */ 712 */
708 QString settingsGroup() const; 713 QString settingsGroup() const;
709 /** 714 /**
710 * For inherited classes 715 * For inherited classes
711 * Note that the group must be set before calling 716 * Note that the group must be set before calling
712 */ 717 */
713 void saveWindowSize( KConfig * config ) const; 718 void saveWindowSize( KConfig * config ) const;
714 /** 719 /**
715 * For inherited classes 720 * For inherited classes
716 * Note that the group must be set before calling, and that 721 * Note that the group must be set before calling, and that
717 * a -geometry on the command line has priority. 722 * a -geometry on the command line has priority.
718 */ 723 */
719 void restoreWindowSize( KConfig * config ); 724 void restoreWindowSize( KConfig * config );
720 725
721 /// parse the geometry from the geometry command line argument 726 /// parse the geometry from the geometry command line argument
722 void parseGeometry(bool parsewidth); 727 void parseGeometry(bool parsewidth);
723 728
724protected slots: 729protected slots:
725 730
726 /** 731 /**
727 * This slot does nothing. 732 * This slot does nothing.
728 * 733 *
729 * It must be reimplemented if you want 734 * It must be reimplemented if you want
730 * to use a custom About Application dialog box. This slot is 735 * to use a custom About Application dialog box. This slot is
731 * connected to the About Application entry in the menu returned 736 * connected to the About Application entry in the menu returned
732 * by @ref customHelpMenu. 737 * by @ref customHelpMenu.
733 * 738 *
734 * Example: 739 * Example:
735 * <pre> 740 * <pre>
736 * 741 *
737 * void MyMainLevel::setupInterface() 742 * void MyMainLevel::setupInterface()
738 * { 743 * {
739 * .. 744 * ..
740 * menuBar()->insertItem( i18n("&Help"), customHelpMenu() ); 745 * menuBar()->insertItem( i18n("&Help"), customHelpMenu() );
741 * .. 746 * ..
742 * } 747 * }
743 * 748 *
744 * void MyMainLevel::showAboutApplication() 749 * void MyMainLevel::showAboutApplication()
745 * { 750 * {
746 * <activate your custom dialog> 751 * <activate your custom dialog>
747 * } 752 * }
748 * </pre> 753 * </pre>
749 */ 754 */
750//US virtual void showAboutApplication(); 755//US virtual void showAboutApplication();
751 756
752private slots: 757private slots:
753 /** 758 /**
754 * Called when the app is shutting down. 759 * Called when the app is shutting down.
755 */ 760 */
756 void shuttingDown(); 761 void shuttingDown();
757 762
758 void saveAutoSaveSettings(); 763 void saveAutoSaveSettings();
759 764
760private: 765private:
761 QToolBar * mQToolBar; 766 Q3ToolBar * mQToolBar;
762//US KMenuBar *internalMenuBar(); 767//US KMenuBar *internalMenuBar();
763 QMenuBar *internalMenuBar(); 768 QMenuBar *internalMenuBar();
764//US KStatusBar *internalStatusBar(); 769//US KStatusBar *internalStatusBar();
765 QStatusBar *internalStatusBar(); 770 QStatusBar *internalStatusBar();
766 771
767 KMainWindowPrivate *d; 772 KMainWindowPrivate *d;
768 void initKMainWindow(const char *name); 773 void initKMainWindow(const char *name);
769 774
770 QPtrList<KToolBar> toolbarList; 775 Q3PtrList<KToolBar> toolbarList;
771 776
772protected: 777protected:
773 virtual void virtual_hook( int id, void* data ); 778 virtual void virtual_hook( int id, void* data );
774 779
775}; 780};
776 781
777#endif 782#endif