Copy the KDE 3.5 branch to branches/trinity for new KDE 3.5 features.

BUG:215923


git-svn-id: svn://anonsvn.kde.org/home/kde/branches/trinity/kdelibs@1054174 283d02a7-25f6-0310-bc7c-ecb5cbfe19da

1 files changed, 1067 insertions, 0 deletions

diff --git a/kdeui/kmainwindow.h b/kdeui/kmainwindow.h
new file mode 100644
index 000000000..00d3aaee6
--- /dev/null
+++ b/kdeui/kmainwindow.h
@@ -0,0 +1,1067 @@
+/*
+    This file is part of the KDE libraries
+
+    This library is free software; you can redistribute it and/or
+    modify it under the terms of the GNU Library General Public
+    License version 2 as published by the Free Software Foundation.
+
+    This library is distributed in the hope that it will be useful,
+    but WITHOUT ANY WARRANTY; without even the implied warranty of
+    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+    Library General Public License for more details.
+
+    You should have received a copy of the GNU Library General Public License
+    along with this library; see the file COPYING.LIB.  If not, write to
+    the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
+    Boston, MA 02110-1301, USA.
+
+
+*/
+
+#ifndef KMAINWINDOW_H
+#define KMAINWINDOW_H
+
+#include "kxmlguifactory.h"
+#include "kxmlguiclient.h"
+#include "kxmlguibuilder.h"
+#include <qmainwindow.h>
+#include <qmetaobject.h>
+#include <ktoolbar.h>
+
+class KPopupMenu;
+class KXMLGUIFactory;
+class KConfig;
+class KHelpMenu;
+class KStatusBar;
+class QStatusBar;
+class KMenuBar;
+class KMWSessionManaged;
+class KMainWindowPrivate;
+class KAccel;
+class KToolBarMenuAction;
+class DCOPObject;
+
+#define KDE_DEFAULT_WINDOWFLAGS WType_TopLevel | WDestructiveClose
+
+
+/**
+ * @short %KDE top level main window
+ *
+ * Top level widget that provides toolbars, a status line and a frame.
+ *
+ * It should be used as a top level (parent-less) widget.
+ * It manages the geometry for all its children, including your
+ * main widget.
+ *
+ * Normally, you will inherit from KMainWindow,
+ * then construct (or use some existing) widget as
+ * your main view. You can set only one main view.
+ *
+ * You can add as many toolbars as you like. There can be only one menubar
+ * and only one statusbar.
+ *
+ * The toolbars, menubar, and statusbar can be created by the
+ * KMainWindow and - unlike the old KMainWindow - may, but do not
+ * have to, be deleted by you. KMainWindow will handle that internally.
+ *
+ * Height and width can be operated independently from each other. Simply
+ * define the minimum/maximum height/width of your main widget and
+ * KMainWindow will take this into account. For fixed size windows set
+ * your main widget to a fixed size.
+ *
+ * Fixed aspect ratios (heightForWidth()) and fixed width widgets are
+ * not supported.
+*
+ * KMainWindow will set icon, mini icon and caption, which it gets
+ * from KApplication. It provides full session management, and
+ * will save its position, geometry and positions of toolbars and
+ * menubar on logout. If you want to save additional data, reimplement
+ * saveProperties() and (to read them again on next login)
+ * readProperties(). To save special data about your data, reimplement
+ * saveGlobalProperties(). To warn user that application or
+ * windows have unsaved data on close or logout, reimplement
+ * queryClose() and/or queryExit().
+ *
+ * There are also kRestoreMainWindows convenience functions which
+ * can restore all your windows on next login.
+ *
+ *  Note that a KMainWindow per-default is created with the
+ *  WDestructiveClose flag, i.e. it is automatically destroyed when the
+ *  window is closed. If you do not want this behavior, specify 0 as
+ *  widget flag in the constructor.
+ *
+ * @see KApplication
+ * @author Reginald Stadlbauer ([email protected]) Stephan Kulow ([email protected]), Matthias Ettrich ([email protected]), Chris Schlaeger ([email protected]), Sven Radej ([email protected]). Maintained by Sven Radej ([email protected])
+
+ */
+
+class KDEUI_EXPORT KMainWindow : public QMainWindow, public KXMLGUIBuilder, virtual public KXMLGUIClient
+{
+    friend class KMWSessionManaged;
+    Q_OBJECT
+
+public:
+    /**
+     * Construct a main window.
+     *
+     * @param parent The widget parent. This is usually 0 but it may also be the window
+     * group leader. In that case, the KMainWindow becomes sort of a
+     * secondary window.
+     *
+     * @param name The object name. For session management and window management to work
+     * properly, all main windows in the application should have a
+     * different name. When passing 0 (the default), KMainWindow will create
+     * a unique name, but it's recommended to explicitly pass a window name that will
+     * also describe the type of the window. If there can be several windows of the same
+     * type, append '#' (hash) to the name, and KMainWindow will append numbers to make
+     * the names unique. For example, for a mail client which has one main window showing
+     * the mails and folders, and which can also have one or more windows for composing
+     * mails, the name for the folders window should be e.g. "mainwindow" and
+     * for the composer windows "composer#".
+     *
+     * @param f Specify the widget flags. The default is
+     * WType_TopLevel and WDestructiveClose.  TopLevel indicates that a
+     * main window is a toplevel window, regardless of whether it has a
+     * parent or not. DestructiveClose indicates that a main window is
+     * automatically destroyed when its window is closed. Pass 0 if
+     * you do not want this behavior.
+     *
+     * @see http://doc.trolltech.com/3.2/qt.html#WidgetFlags-enum
+     *
+     * KMainWindows must be created on the heap with 'new', like:
+     * \code
+     * KMainWindow *kmw = new KMainWindow (...);
+     * \endcode
+     **/
+    KMainWindow( QWidget* parent = 0, const char *name = 0, WFlags f = WType_TopLevel | WDestructiveClose );
+
+    /**
+     * Flags that can be passed in an argument to the constructor to
+     * change the behavior.
+     *
+     * NoDCOPObject tells KMainWindow not to create a KMainWindowInterface.
+     * This can be useful in particular for inherited classes, which
+     * might want to create more specific dcop interfaces. It's a good
+     * idea to use KMainWindowInterface as the base class for such interfaces
+     * though (to provide the standard mainwindow functionality via DCOP).
+     */
+    enum CreationFlags
+    {
+        NoDCOPObject = 1
+    };
+
+    /**
+     * Overloaded constructor which allows passing some KMainWindow::CreationFlags.
+     *
+     * @since 3.2
+     */
+    KMainWindow( int cflags, QWidget* parent = 0, const char *name = 0, WFlags f = WType_TopLevel | WDestructiveClose );
+
+    /**
+     * \brief Destructor.
+     *
+     * Will also destroy the toolbars, and menubar if
+     * needed.
+     */
+    virtual ~KMainWindow();
+
+    /**
+     * Retrieve the standard help menu.
+     *
+     * It contains entires for the
+     * help system (activated by F1), an optional "What's This?" entry
+     * (activated by Shift F1), an application specific dialog box,
+     * and an "About KDE" dialog box.
+     *
+     * Example (adding a standard help menu to your application):
+     * \code
+     * KPopupMenu *help = helpMenu( <myTextString> );
+     * menuBar()->insertItem( i18n("&Help"), help );
+     * \endcode
+     *
+     * @param aboutAppText The string that is used in the application
+     *        specific dialog box. If you leave this string empty the
+     *        information in the global KAboutData of the
+     *        application will be used to make a standard dialog box.
+     *
+     * @param showWhatsThis Set this to false if you do not want to include
+     *        the "What's This" menu entry.
+     *
+     * @return A standard help menu.
+     */
+    KPopupMenu* helpMenu( const QString &aboutAppText = QString::null,
+			  bool showWhatsThis = true );
+
+    /**
+     * Returns the help menu. Creates a standard help menu if none exists yet.
+     *
+     * It contains entries for the
+     * help system (activated by F1), an optional "What's This?" entry
+     * (activated by Shift F1), an application specific dialog box,
+     * and an "About KDE" dialog box. You must create the application
+     * specific dialog box yourself. When the "About application"
+     * menu entry is activated, a signal will trigger the
+     * showAboutApplication slot. See showAboutApplication for more
+     * information.
+     *
+     * Example (adding a help menu to your application):
+     * \code
+     * menuBar()->insertItem( i18n("&Help"), customHelpMenu() );
+     * \endcode
+     *
+     * @param showWhatsThis Set this to @p false if you do not want to include
+     *        the "What's This" menu entry.
+     *
+     * @return A standard help menu.
+     */
+    KPopupMenu* customHelpMenu( bool showWhatsThis = true );
+
+    /**
+     * <b>Session Management</b>
+     *
+     * Try to restore the toplevel widget as defined by the number (1..X).
+     *
+     * If the session did not contain so high a number, the configuration
+     * is not changed and @p false returned.
+     *
+     * That means clients could simply do the following:
+     * \code
+     * if (kapp->isRestored()){
+     *   int n = 1;
+     *   while (KMainWindow::canBeRestored(n)){
+     *     (new childMW)->restore(n);
+     *     n++;
+     *   }
+     * } else {
+     *   // create default application as usual
+     * }
+     * \endcode
+     * Note that QWidget::show() is called implicitly in restore.
+     *
+     * With this you can easily restore all toplevel windows of your
+     * application.
+     *
+     * If your application uses different kinds of toplevel
+     * windows, then you can use KMainWindow::classNameOfToplevel(n)
+     * to determine the exact type before calling the childMW
+     * constructor in the example from above.
+     *
+     * If your client has only one kind of toplevel widgets (which
+     * should be pretty usual) then you should use the RESTORE-macro
+     * for backwards compatibility with 3.1 and 3.0 branches:
+     *
+     * \code
+     * if (kapp->isRestored())
+     *   RESTORE(childMW)
+     * else {
+     *   // create default application as usual
+     * }
+     * \endcode
+     *
+     * The macro expands to the term above but is easier to use and
+     * less code to write.
+     *
+     * For new code or if you have more than one kind of toplevel
+     * widget (each derived from KMainWindow, of course), you can
+     * use the templated kRestoreMainWindows global functions:
+     *
+     * \code
+     * if (kapp->isRestored())
+     *   kRestoreMainWindows< childMW1, childMW2, childMW3 >();
+     * else {
+     *   // create default application as usual
+     * }
+     * \endcode
+     *
+     * Currently, these functions are provided for up to three
+     * template arguments. If you need more, tell us. To help you in
+     * deciding whether or not you can use kRestoreMainWindows, a
+     * define KDE_RESTORE_MAIN_WINDOWS_NUM_TEMPLATE_ARGS is provided.
+     *
+     * @see restore()
+     * @see classNameOfToplevel()
+     *
+     **/
+    static bool canBeRestored( int number );
+
+    /**
+     * Returns the className() of the @p number of the toplevel window which
+     * should be restored.
+     *
+     * This is only useful if your application uses
+     * different kinds of toplevel windows.
+     */
+    // KDE 4 return QCString - QObject::className() returns const char*
+    static const QString classNameOfToplevel( int number );
+
+    /**
+     * Reimplementation of QMainWindow::show()
+     */
+    // KDE4 remove this method if this has been fixed in Qt
+    virtual void show();
+
+    /**
+     * Reimplementation of QMainWindow::hide()
+     */
+    // KDE4 remove this method if this has been fixed in Qt
+    virtual void hide();
+
+    /**
+     * Restore the session specified by @p number.
+     *
+     * Returns @p false if this
+     * fails, otherwise returns @p true and shows the window.
+     * You should call canBeRestored() first.
+     * If @p show is true (default), this widget will be shown automatically.
+     */
+    bool restore( int number, bool show = true );
+
+    virtual KXMLGUIFactory *guiFactory();
+
+    /**
+     * Create a GUI given a local XML file.
+     *
+     * If @p xmlfile is NULL,
+     * then it will try to construct a local XML filename like
+     * appnameui.rc where 'appname' is your app's name.  If that file
+     * does not exist, then the XML UI code will only use the global
+     * (standard) XML file for the layout purposes.
+     *
+     * Note that when passing true for the conserveMemory argument subsequent
+     * calls to guiFactory()->addClient/removeClient may not work as expected.
+     * Also retrieving references to containers like popup menus or toolbars using
+     * the container method will not work.
+     *
+     * @param xmlfile The local xmlfile (relative or absolute)
+     * @param _conserveMemory Specify whether createGUI() should call
+     * KXMLGUIClient::conserveMemory() to free all memory
+     *     allocated by the QDomDocument and by the KXMLGUIFactory.
+     */
+    void createGUI( const QString &xmlfile = QString::null, bool _conserveMemory = true );
+
+    /**
+     * Enables the build of a standard help menu when calling createGUI().
+     *
+     * The default behavior is to build one, you must call this function
+     * to disable it
+     */
+    void setHelpMenuEnabled(bool showHelpMenu = true);
+
+    /**
+     * Return @p true when the help menu is enabled
+     */
+    bool isHelpMenuEnabled();
+
+
+    /**
+     * Returns true, if there is a menubar
+     * @since 3.1
+     */
+     bool hasMenuBar();
+
+    /**
+     * Returns a pointer to the menu bar.
+     *
+     * If there is no menu bar yet one will be created.
+     **/
+    KMenuBar *menuBar();
+
+    /**
+     * Returns a pointer to the status bar.
+     *
+     * If there is no status bar yet, one will be created.
+     *
+     * Note that tooltips for kactions in actionCollection() are not
+     * automatically connected to this statusBar.
+     * See the KActionCollection documentation for more details.
+     *
+     * @see KActionCollection
+     */
+    KStatusBar *statusBar();
+
+    /**
+     * List of members of KMainWindow class.
+     */
+    static QPtrList<KMainWindow>* memberList;
+
+    //KDE4: replace with memberList() and make memberList member private
+    /**
+     * List of members of KMainWindow class.
+     * @since 3.4
+     */
+    static QPtrList<KMainWindow>* getMemberList();
+
+    /**
+     * Returns a pointer to the toolbar with the specified name.
+     * This refers to toolbars created dynamically from the XML UI
+     * framework.  If the toolbar does not exist one will be created.
+     *
+     * @param name The internal name of the toolbar. If no name is
+     *             specified "mainToolBar" is assumed.
+     *
+     * @return A pointer to the toolbar
+     **/
+    KToolBar *toolBar( const char *name=0 );
+
+    /**
+     * @return An iterator over the list of all toolbars for this window.
+     */
+    QPtrListIterator<KToolBar> toolBarIterator();
+
+    /**
+     * @return A KAccel instance bound to this mainwindow. Used automatically
+     * by KAction to make keybindings work in all cases.
+     */
+    KAccel *accel();
+
+    void setFrameBorderWidth( int ) {}
+
+    /**
+     * Call this to enable "auto-save" of toolbar/menubar/statusbar settings
+     * (and optionally window size).
+     * If the *bars were moved around/shown/hidden when the window is closed,
+     * saveMainWindowSettings( KGlobal::config(), groupName ) will be called.
+     *
+     * @param groupName a name that identifies this "type of window".
+     * You can have several types of window in the same application.
+     *
+     * @param saveWindowSize set it to true to include the window size
+     * when saving.
+     *
+     * Typically, you will call setAutoSaveSettings() in your
+     * KMainWindow-inherited class constructor, and it will take care
+     * of restoring and saving automatically. Make sure you call this
+     * _after all_ your *bars have been created.
+     *
+     * To make sure that KMainWindow propertly obtains the default
+     * size of the window you should do the following:
+     * - Remove hard coded resize() calls in the constructor or main, they
+     *   should be removed in favor of letting the automatic resizing
+     *   determine the default window size.  Hard coded window sizes will
+     *   be wrong for users that have big fonts, use different styles,
+     *   long/small translations, large toolbars, and other factors.
+     * - Put the setAutoSaveSettings ( or setupGUI() ) call after all widgets
+     *   have been created and placed inside the main window (i.e. for 99% of
+     *   apps setCentralWidget())
+     * - Widgets that inherit from QWidget (like game boards) should overload
+     *   "virtual QSize sizeHint() const;" to specify a default size rather
+     *   than letting QWidget::adjust use the default size of 0x0.
+     */
+    void setAutoSaveSettings( const QString & groupName = QString::fromLatin1("MainWindow"),
+                              bool saveWindowSize = true );
+
+    /**
+     * Disable the auto-save-settings feature.
+     * You don't normally need to call this, ever.
+     */
+    void resetAutoSaveSettings();
+
+    /**
+     * @return the current autosave setting, i.e. true if setAutoSaveSettings() was called,
+     * false by default or if resetAutoSaveSettings() was called.
+     * @since 3.1
+     */
+    bool autoSaveSettings() const;
+
+    /**
+     * @return the group used for setting-autosaving.
+     * Only meaningful if setAutoSaveSettings() was called.
+     * This can be useful for forcing a save or an apply, e.g. before and after
+     * using KEditToolbar.
+     * @since 3.1
+     */
+    QString autoSaveGroup() const;
+
+    /**
+     * Read settings for statusbar, menubar and toolbar from their respective
+     * groups in the config file and apply them.
+     *
+     * @param config Config file to read the settings from.
+     * @param groupName Group name to use. If not specified, the last used
+     * group name is used.
+     * @param force if set, even default settings are re-applied
+     */
+    void applyMainWindowSettings(KConfig *config, const QString &groupName, bool force);
+    // KDE4 merge with force=false
+    void applyMainWindowSettings(KConfig *config, const QString &groupName = QString::null);
+
+    /**
+     * Save settings for statusbar, menubar and toolbar to their respective
+     * groups in the config file @p config.
+     *
+     * @param config Config file to save the settings to.
+     * @param groupName Group name to use. If not specified, the last used
+     * group name is used
+     */
+    void saveMainWindowSettings(KConfig *config, const QString &groupName = QString::null);
+
+    /**
+     * Sets whether KMainWindow should provide a menu that allows showing/hiding
+     * the available toolbars ( using KToggleToolBarAction ) . In case there
+     * is only one toolbar configured a simple 'Show \<toolbar name here\>' menu item
+     * is shown.
+     *
+     * The menu / menu item is implemented using xmlgui. It will be inserted in your
+     * menu structure in the 'Settings' menu.
+     *
+     * If your application uses a non-standard xmlgui resource file then you can
+     * specify the exact position of the menu / menu item by adding a
+     * &lt;Merge name="StandardToolBarMenuHandler" /&gt;
+     * line to the settings menu section of your resource file ( usually appname.rc ).
+     *
+     * Note that you should enable this feature before calling createGUI() ( or similar ) .
+     * You enable/disable it anytime if you pass false to the conserveMemory argument of createGUI.
+     * @since 3.1
+     */
+    void setStandardToolBarMenuEnabled( bool enable );
+    /// @since 3.1
+    bool isStandardToolBarMenuEnabled() const;
+
+
+    /**
+     * Sets whether KMainWindow should provide a menu that allows showing/hiding
+     * of the statusbar ( using KToggleStatusBarAction ).
+     *
+     * The menu / menu item is implemented using xmlgui. It will be inserted
+     * in your menu structure in the 'Settings' menu.
+     *
+     * Note that you should enable this feature before calling createGUI()
+     * ( or similar ).
+     *
+     * If an application maintains the action on its own (i.e. never calls
+     * this function) a connection needs to be made to let KMainWindow
+     * know when that status (hidden/shown) of the statusbar has changed.
+     * For example:
+     * connect(action, SIGNAL(activated()),
+     *         kmainwindow, SLOT(setSettingsDirty()));
+     * Otherwise the status (hidden/show) of the statusbar might not be saved
+     * by KMainWindow.
+     * @since 3.2
+     */
+    void createStandardStatusBarAction();
+
+    /**
+     * @see setupGUI()
+     */
+    enum StandardWindowOptions
+    {
+        /**
+         * adds action to show/hide the toolbar(s) and adds
+         * action to configure the toolbar(s).
+         * @see setStandardToolBarMenuEnabled
+         */
+        ToolBar = 1,
+
+        /**
+         * adds action to show the key configure action.
+         */
+        Keys = 2,
+
+        /**
+         * adds action to show/hide the statusbar if the
+         * statusbar exists.  See createStandardStatusBarAction
+         */
+        StatusBar = 4,
+
+        /**
+         * auto-saves (and loads) the toolbar/menubar/statusbar settings and
+         * window size using the default name.  See setAutoSaveSettings
+         *
+         * Typically you want to let the default window size be determined by
+         * the widgets size hints. Make sure that setupGUI() is called after
+         * all the widgets are created ( including setCentralWidget ) so the
+         * default size's will be correct. See setAutoSaveSettings for
+         * more information on this topic.
+         */
+        Save = 8,
+
+        /**
+         * calls createGUI() once ToolBar, Keys and Statusbar have been
+         * taken care of.  See createGUI
+         */
+        Create = 16
+    };
+
+    /**
+     * Configures the current windows and its actions in the typical KDE
+     * fashion.  The options are all enabled by default but can be turned
+     * off if desired through the params or if the prereqs don't exists.
+     *
+     * Typically this function replaces createGUI().
+     *
+     * @see StandardWindowOptions
+     *
+     * @since 3.3
+     */
+    void setupGUI( int options = ToolBar | Keys | StatusBar | Save | Create, const QString& xmlfile = QString::null );
+
+    /**
+     * Configures the current windows and its actions in the typical KDE
+     * fashion.  The options are all enabled by default but can be turned
+     * off if desired through the params or if the prereqs don't exists.
+     *
+     * @p defaultSize The default size of the window
+     *
+     * Typically this function replaces createGUI().
+     *
+     * @see StandardWindowOptions
+     *
+     * @since 3.5
+     */
+    void setupGUI( QSize defaultSize, int options = ToolBar | Keys | StatusBar | Save | Create, const QString& xmlfile = QString::null );
+
+    /**
+     * Returns a pointer to the mainwindows action responsible for the toolbars menu
+     * @since 3.1
+     */
+    KAction *toolBarMenuAction();
+
+    /**
+     * @internal for KToolBar
+     * @since 3.3.1
+     */
+    void setupToolbarMenuActions();
+
+    // why do we support old gcc versions? using KXMLGUIBuilder::finalizeGUI;
+    /// @since 3.1
+    virtual void finalizeGUI( KXMLGUIClient *client );
+
+    /**
+     * @internal
+     */
+    void finalizeGUI( bool force );
+
+    /**
+     * @return true if a -geometry argument was given on the command line,
+     * and this is the first window created (the one on which this option applies)
+     */
+    bool initialGeometrySet() const;
+
+    /**
+     * @internal
+     * Used from Konqueror when reusing the main window.
+     */
+    void ignoreInitialGeometry();
+
+    /**
+     * @return the size the mainwindow should have so that the central
+     * widget will be of @p size.
+     *
+     * @deprecated You normally don't need this, the recommended way to achieve a
+     *   certain central widget size is as follows:
+     *     @li Override sizeHint() in the central widget so that it
+     *      returns the desired size.
+     *     @li Call updateGeometry() in the central widget whenever the
+     *      desired size changes. This ensures that the new sizeHint() is properly
+     *      propagated to any parent layout.
+     *     @li Now call adjustSize() in the mainwindow to resize the
+     *      mainwindow such that the central widget will become the desired size.
+     *
+     */
+    // KDE4 to be removed
+    QSize sizeForCentralWidgetSize(QSize size) KDE_DEPRECATED;
+
+    /**
+     * @internal
+     */
+    // KDE4 remove
+    virtual void setIcon( const QPixmap & );
+
+public slots:
+    /**
+     * Show a standard configure toolbar dialog.
+     *
+     * This slot can be connected dirrectly to the action to configure shortcuts.
+     * This is very simple to do that by adding a single line
+     * \code
+     * KStdAction::configureToolbars( guiFactory(), SLOT( configureToolbars() ),
+     *                                actionCollection() );
+     * \endcode
+     *
+     * @since 3.3
+     */
+   int configureToolbars(); // TODO KDE4: make virtual and reimplement in KParts::MainWindow
+
+    /**
+     * Makes a KDE compliant caption.
+     *
+     * @param caption Your caption. @em Do @em not include the application name
+     * in this string. It will be added automatically according to the KDE
+     * standard.
+     */
+    virtual void setCaption( const QString &caption );
+    /**
+     * Makes a KDE compliant caption.
+     *
+     * @param caption Your caption. @em Do @em not include the application name
+     * in this string. It will be added automatically according to the KDE
+     * standard.
+     * @param modified Specify whether the document is modified. This displays
+     * an additional sign in the title bar, usually "**".
+     */
+    virtual void setCaption( const QString &caption, bool modified );
+
+    /**
+     * Make a plain caption without any modifications.
+     *
+     * @param caption Your caption. This is the string that will be
+     * displayed in the window title.
+     */
+    virtual void setPlainCaption( const QString &caption );
+
+    /**
+     * Open the help page for the application.
+     *
+     *  The application name is
+     * used as a key to determine what to display and the system will attempt
+     * to open \<appName\>/index.html.
+     *
+     * This method is intended for use by a help button in the toolbar or
+     * components outside the regular help menu. Use helpMenu() when you
+     * want to provide access to the help system from the help menu.
+     *
+     * Example (adding a help button to the first toolbar):
+     *
+     * \code
+     * KIconLoader &loader = *KGlobal::iconLoader();
+     * QPixmap pixmap = loader.loadIcon( "help" );
+     * toolBar(0)->insertButton( pixmap, 0, SIGNAL(clicked()),
+     *   this, SLOT(appHelpActivated()), true, i18n("Help") );
+     * \endcode
+     *
+     */
+    void appHelpActivated( void );
+
+    /**
+     * Apply a state change
+     *
+     * Enable and disable actions as defined in the XML rc file
+     * @since 3.1
+     */
+    virtual void slotStateChanged(const QString &newstate);
+
+    /**
+     * Apply a state change
+     *
+     * Enable and disable actions as defined in the XML rc file,
+     * can "reverse" the state (disable the actions which should be
+     * enabled, and vice-versa) if specified.
+     * @since 3.1
+     */
+    void slotStateChanged(const QString &newstate,
+                          KXMLGUIClient::ReverseStateChange); // KDE 4.0: remove this
+
+
+    /**
+     * Apply a state change
+     *
+     * Enable and disable actions as defined in the XML rc file,
+     * can "reverse" the state (disable the actions which should be
+     * enabled, and vice-versa) if specified.
+     */
+//     void slotStateChanged(const QString &newstate,
+//                           bool reverse); // KDE 4.0: enable this
+
+    /**
+     * Tell the main window that it should save its settings when being closed.
+     * This is part of the auto-save-settings feature.
+     * For everything related to toolbars this happens automatically,
+     * but you have to call setSettingsDirty() in the slot that toggles
+     * the visibility of the statusbar.
+     */
+    void setSettingsDirty();
+
+protected:
+    void paintEvent( QPaintEvent* e );
+    void childEvent( QChildEvent* e);
+    void resizeEvent( QResizeEvent* e);
+    /**
+     * Reimplemented to call the queryClose() and queryExit() handlers.
+     *
+     * We recommend that you reimplement the handlers rather than closeEvent().
+     * If you do it anyway, ensure to call the base implementation to keep
+     * queryExit() running.
+     */
+    virtual void closeEvent ( QCloseEvent *);
+
+    // KDE4 This seems to be flawed to me. Either the app has only one
+    // mainwindow, so queryClose() is enough, or if it can have more of them,
+    // then the windows should take care of themselves, and queryExit()
+    // would be useful only for the annoying 'really quit' dialog, which
+    // also doesn't make sense in apps with multiple mainwindows.
+    // And saving configuration in something called queryExit()? IMHO
+    // one can e.g. use KApplication::shutDown(), which if nothing else
+    // has at least better fitting name.
+    // See also KApplication::sessionSaving().
+    // This stuff should get changed somehow, so that it at least doesn't
+    // mess with session management.
+    /**
+       Called before the very last window is closed, either by the
+       user or indirectly by the session manager.
+
+       It is not recommended to do any user interaction in this
+       function other than indicating severe errors. Better ask the
+       user on queryClose() (see below).
+
+       A typical usage of queryExit() is to write configuration data back.
+       Note that the application may continue to run after queryExit()
+       (the user may have canceled a shutdown), so you should not do any cleanups
+       here. The purpose of queryExit() is purely to prepare the application
+       (with possible user interaction) so it can safely be closed later (without
+       user interaction).
+
+       If you need to do serious things on exit (like shutting a
+       dial-up connection down), connect to the signal
+ KApplication::shutDown().
+
+       Default implementation returns @p true. Returning @p false will
+       cancel the exiting. In the latter case, the last window will
+       remain visible. If KApplication::sessionSaving() is true, refusing
+       the exit will also cancel KDE logout.
+
+       @see queryClose()
+       @see KApplication::sessionSaving()
+     */
+    virtual bool queryExit();
+
+    /**
+       Called before the window is closed, either by the user or indirectly by
+       the session manager.
+
+       The purpose of this function is to prepare the window in a way that it is
+       safe to close it, i.e. without the user losing some data.
+
+       Default implementation returns true. Returning @p false will cancel
+       the closing, and, if KApplication::sessionSaving() is true, it will also
+       cancel KDE logout.
+
+       Reimplement this function to prevent the user from losing data.
+       Example:
+       \code
+       switch ( KMessageBox::warningYesNoCancel( this,
+                i18n("Save changes to document foo?")) ) {
+       case KMessageBox::Yes :
+         // save document here. If saving fails, return false;
+         return true;
+       case KMessageBox::No :
+         return true;
+       default: // cancel
+         return false;
+       \endcode
+
+       Note that you should probably @em not actually close the document from
+       within this method, as it may be called by the session manager before the
+       session is saved. If the document is closed before the session save occurs,
+       its location might not be properly saved. In addition, the session shutdown
+       may be canceled, in which case the document should remain open.
+
+       @see queryExit()
+       @see KApplication::sessionSaving()
+    */
+    virtual bool queryClose();
+
+    /**
+     * Save your instance-specific properties. The function is
+     * invoked when the session manager requests your application
+     * to save its state.
+     *
+     * You @em must @em not change the group of the @p kconfig object, since
+     * KMainWindow uses one group for each window.  Please
+     * reimplement these function in childclasses.
+     *
+     * Note: No user interaction is allowed
+     * in this function!
+     *
+     */
+    virtual void saveProperties( KConfig* ) {}
+
+   /**
+    * Read your instance-specific properties.
+    */
+    virtual void readProperties( KConfig* ) {}
+
+   /**
+     * Save your application-wide properties. The function is
+     * invoked when the session manager requests your application
+     * to save its state.
+     *
+     * This function is similar to saveProperties() but is only called for
+     * the very first main window, regardless how many main window are open.
+
+     * Override it if you need to save other data about your documents on
+     * session end. sessionConfig is a config to which that data should be
+     * saved. Normally, you don't need this function. But if you want to save
+     * data about your documents that are not in opened windows you might need
+     * it.
+     *
+     * Default implementation does nothing.
+     */
+    virtual void saveGlobalProperties( KConfig* sessionConfig );
+
+    /**
+     * The counterpart of saveGlobalProperties().
+     *
+     * Read the application-specific properties in again.
+     */
+    virtual void readGlobalProperties( KConfig* sessionConfig );
+    void savePropertiesInternal( KConfig*, int );
+    bool readPropertiesInternal( KConfig*, int );
+
+    /**
+     * For inherited classes
+     */
+    bool settingsDirty() const;
+    /**
+     * For inherited classes
+     */
+    QString settingsGroup() const;
+    /**
+     * For inherited classes
+     * Note that the group must be set before calling
+     */
+    void saveWindowSize( KConfig * config ) const;
+    /**
+     * For inherited classes
+     * Note that the group must be set before calling, and that
+     * a -geometry on the command line has priority.
+     */
+    void restoreWindowSize( KConfig * config );
+
+    /// parse the geometry from the geometry command line argument
+    void parseGeometry(bool parsewidth);
+
+protected slots:
+   /**
+    * Rebuilds the GUI after KEditToolbar changed the toolbar layout.
+    * @see configureToolbars()
+    */
+   void saveNewToolbarConfig(); // TODO KDE4: make virtual and reimplement in KParts::MainWindow
+
+    /**
+    * This slot does nothing.
+    *
+    * It must be reimplemented if you want
+    * to use a custom About Application dialog box. This slot is
+    * connected to the About Application entry in the menu returned
+    * by customHelpMenu.
+    *
+    * Example:
+    * \code
+    *
+    * void MyMainLevel::setupInterface()
+    * {
+    *   ..
+    *   menuBar()->insertItem( i18n("&Help"), customHelpMenu() );
+    *   ..
+    * }
+    *
+    * void MyMainLevel::showAboutApplication()
+    * {
+    *   <activate your custom dialog>
+    * }
+    * \endcode
+    */
+    virtual void showAboutApplication();
+
+   /**
+    * This slot should only be called in case you reimplement closeEvent() and
+    * if you are using the "auto-save" feature. In all other cases,
+    * setSettingsDirty() should be called instead to benefit from the delayed
+    * saving.
+    *
+    * @see setAutoSaveSettings
+    * @see setSettingsDirty
+    *
+    * @since 3.2
+    *
+    * Example:
+    * \code
+    *
+    * void MyMainWindow::closeEvent( QCloseEvent *e )
+    * {
+    *   // Save settings if auto-save is enabled, and settings have changed
+    *   if ( settingsDirty() && autoSaveSettings() )
+    *     saveAutoSaveSettings();
+    *   ..
+    * }
+    * \endcode
+    */
+    void saveAutoSaveSettings();
+
+private slots:
+   /**
+    * Called when the app is shutting down.
+    */
+    void shuttingDown();
+
+private:
+    KMenuBar *internalMenuBar();
+    KStatusBar *internalStatusBar();
+    KHelpMenu *mHelpMenu, *helpMenu2;
+    KXMLGUIFactory *factory_;
+    QPtrList<KToolBar> toolbarList;
+protected:
+    virtual void virtual_hook( int id, void* data );
+private:
+    KMainWindowPrivate *d;
+    void initKMainWindow(const char *name, int cflags);
+};
+
+#define RESTORE(type) { int n = 1;\
+    while (KMainWindow::canBeRestored(n)){\
+      (new type)->restore(n);\
+      n++;}}
+
+#define KDE_RESTORE_MAIN_WINDOWS_NUM_TEMPLATE_ARGS 3
+
+/**
+ *  These global convenience functions (that come with a varying
+ *  number of template arguments) are a replacement for the RESTORE
+ *  macro provided in earlier versions of KDE. The old RESTORE macro
+ *  is still provided for backwards compatibility. See
+ *  KMainWindow documentation for more.
+ *
+ * \since KDE 3.2
+ *
+ **/
+template <typename T>
+inline void kRestoreMainWindows() {
+  for ( int n = 1 ; KMainWindow::canBeRestored( n ) ; ++n ) {
+    const QString className = KMainWindow::classNameOfToplevel( n );
+    if ( className == QString::fromLatin1( T::staticMetaObject()->className() ) )
+      (new T)->restore( n );
+  }
+}
+
+template <typename T0, typename T1>
+inline void kRestoreMainWindows() {
+  const char * classNames[2];
+  classNames[0] = T0::staticMetaObject()->className();
+  classNames[1] = T1::staticMetaObject()->className();
+  for ( int n = 1 ; KMainWindow::canBeRestored( n ) ; ++n ) {
+    const QString className = KMainWindow::classNameOfToplevel( n );
+    if ( className == QString::fromLatin1( classNames[0] ) )
+      (new T0)->restore( n );
+    else if ( className == QString::fromLatin1( classNames[1] ) )
+      (new T1)->restore( n );
+  }
+}
+
+template <typename T0, typename T1, typename T2>
+inline void kRestoreMainWindows() {
+  const char * classNames[3];
+  classNames[0] = T0::staticMetaObject()->className();
+  classNames[1] = T1::staticMetaObject()->className();
+  classNames[2] = T2::staticMetaObject()->className();
+  for ( int n = 1 ; KMainWindow::canBeRestored( n ) ; ++n ) {
+    const QString className = KMainWindow::classNameOfToplevel( n );
+    if ( className == QString::fromLatin1( classNames[0] ) )
+      (new T0)->restore( n );
+    else if ( className == QString::fromLatin1( classNames[1] ) )
+      (new T1)->restore( n );
+    else if ( className == QString::fromLatin1( classNames[2] ) )
+      (new T2)->restore( n );
+  }
+}
+
+#endif