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, 281 insertions, 0 deletions

diff --git a/kdeui/khelpmenu.h b/kdeui/khelpmenu.h
new file mode 100644
index 000000000..052f7e394
--- /dev/null
+++ b/kdeui/khelpmenu.h
@@ -0,0 +1,281 @@
+/*
+ * This file is part of the KDE Libraries
+ * Copyright (C) 1999-2000 Espen Sand (espen@kde.org)
+ *
+ * This library is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU Library General Public
+ * License as published by the Free Software Foundation; either
+ * version 2 of the License, or (at your option) any later version.
+ *
+ * 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 _KHELPMENU_H_
+#define _KHELPMENU_H_
+
+#include <qobject.h>
+#include <qstring.h>
+
+#include <kdelibs_export.h>
+
+class KActionCollection;
+class KPopupMenu;
+class QWidget;
+
+class KAboutData;
+class KAboutKDE;
+class KBugReport;
+class KDialogBase;
+class KHelpMenuPrivate;
+
+
+/**
+ * @short Standard %KDE help menu with dialog boxes.
+ *
+ * This class provides the standard %KDE help menu with the default "about"
+ * dialog boxes and help entry.
+ *
+ * This class is used in KMainWindow so
+ * normally you don't need to use this class yourself. However, if you
+ * need the help menu or any of its dialog boxes in your code that is
+ * not subclassed from KMainWindow you should use this class.
+ *
+ * The usage is simple:
+ *
+ * \code
+ * mHelpMenu = new KHelpMenu( this, <someText> );
+ * kmenubar->insertItem(i18n("&Help"), mHelpMenu->menu() );
+ * \endcode
+ *
+ * or if you just want to open a dialog box:
+ *
+ * \code
+ * mHelpMenu = new KHelpMenu( this, <someText> );
+ * connect( this, SIGNAL(someSignal()), mHelpMenu,SLOT(mHelpMenu->aboutKDE()));
+ * \endcode
+ *
+ * IMPORTANT:
+ * The first time you use KHelpMenu::menu(), a KPopupMenu object is
+ * allocated. Only one object is created by the class so if you call
+ * KHelpMenu::menu() twice or more, the same pointer is returned. The class
+ * will destroy the popupmenu in the destructor so do not delete this
+ * pointer yourself.
+ *
+ * The KHelpMenu object will be deleted when its parent is destroyed but you
+ * can delete it yourself if you want. The code below will always work.
+ *
+ * \code
+ * MyClass::~MyClass()
+ * {
+ *   delete mHelpMenu;
+ * }
+ * \endcode
+ *
+ *
+ * Using your own "about application" dialog box:
+ *
+ * The standard "about application" dialog box is quite simple. If you
+ * need a dialog box with more functionality you must design that one
+ * yourself. When you want to display the dialog you can choose one of
+ * two methods. Common for both is that you must make a help menu object
+ * with no text argument If the text is missing the default dialog box
+ * will not be displayed:
+ *
+ * Example 1 Using showAboutApplication signal (preferred)
+ * \code
+ *
+ * void MyClass::myFunc()
+ * {
+ *   ..
+ *   KHelpMenu *helpMenu = new KHelpMenu( this );
+ *   connect( helpMenu, SIGNAL(showAboutApplication()),
+ *          this, SLOT(myDialogSlot()));
+ *   ..
+ * }
+ *
+ * void MyClass::myDialogSlot()
+ * {
+ *   <activate your custom dialog>
+ * }
+ * \endcode
+ *
+ *
+ * Example 2 Old style - connecting directly to the menu entry.
+ * \code
+ *
+ * void MyClass::myFunc()
+ * {
+ *   KHelpMenu *helpMenu = new KHelpMenu( this );
+ *   KPopupMenu *help = mHelpMenu->menu();
+ *   help->connectItem( KHelpMenu::menuAboutApp, this, SLOT(myDialogSlot()) );
+ * }
+ *
+ * void MyClass::myDialogSlot()
+ * {
+ *   <activate your custom dialog>
+ * }
+ * \endcode
+ *
+ * @author Espen Sand (espen@kde.org)
+ */
+
+class KDEUI_EXPORT KHelpMenu : public QObject
+{
+  Q_OBJECT
+
+  public:
+    enum MenuId
+    {
+      menuHelpContents = 0,
+      menuWhatsThis = 1,
+      menuAboutApp = 2,
+      menuAboutKDE = 3,
+      menuReportBug = 4,
+      menuSwitchLanguage = 5
+    };
+
+    /**
+     * Constructor.
+     *
+     * @param parent The parent of the dialog boxes. The boxes are modeless
+     *        and will be centered with respect to the parent.
+     * @param aboutAppText User definable string that is used in the
+     *        application specific dialog box. Note: The help menu will
+     *        not open this dialog box if you don't define a string. See
+     *        showAboutApplication() for more information.
+     * @param showWhatsThis Decides whether a "Whats this" entry will be
+     *        added to the dialog.
+     *
+     */
+    KHelpMenu( QWidget *parent=0, const QString &aboutAppText=QString::null,
+	       bool showWhatsThis=true );
+
+    /**
+     * Constructor.
+     *
+     * This alternative constructor is mainly useful if you want to
+     * overide the standard actions (aboutApplication(), aboutKDE(),
+     * helpContents(), reportBug, and optionally whatsThis).
+     *
+     * @param parent The parent of the dialog boxes. The boxes are modeless
+     *        and will be centered with respect to the parent.
+     * @param aboutData User and app data used in the About app dialog
+     * @param showWhatsThis Decides whether a "Whats this" entry will be
+     *        added to the dialog.
+     * @param actions KActionCollection that is used instead of the
+     *        standard actions.
+     *
+     */
+    KHelpMenu( QWidget *parent, const KAboutData *aboutData,
+	       bool showWhatsThis=true, KActionCollection *actions = 0 );
+
+    /**
+     * Destructor
+     *
+     * Destroys dialogs and the menu pointer retuned by menu
+     */
+    ~KHelpMenu();
+
+    /**
+     * Returns a popup menu you can use in the menu bar or where you
+     * need it.
+     *
+     * Note: This method will only create one instance of the menu. If
+     * you call this method twice or more the same pointer is returned
+     */
+    KPopupMenu *menu();
+
+  public slots:
+    /**
+     * Opens 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.
+     */
+    void appHelpActivated();
+
+    /**
+     * Activates What's This help for the application.
+     */
+    void contextHelpActivated();
+
+    /**
+     * Opens an application specific dialog box. The dialog box will display
+     * the string that was defined in the constructor. If that string was
+     * empty the showAboutApplication() is emitted instead.
+     */
+    void aboutApplication();
+
+    /**
+     * Opens the standard "About KDE" dialog box.
+     */
+    void aboutKDE();
+
+    /**
+     * Opens the standard "Report Bugs" dialog box.
+     */
+    void reportBug();
+    
+    /**
+     * Opens changing default application language dialog box.
+     */
+    void switchApplicationLanguage();
+
+  private slots:
+    /**
+     * Connected to the menu pointer (if created) to detect a delete
+     * operation on the pointer. You should not delete the pointer in your
+     * code yourself. Let the KHelpMenu destructor do the job.
+     */
+    void menuDestroyed();
+
+    /**
+     * Connected to the dialogs (about kde and bug report) to detect
+     * when they are finished.
+     */
+    void dialogFinished();
+
+    /**
+     * This slot will delete a dialog (about kde or bug report) if the
+     * dialog pointer is not zero and the the dialog is not visible. This
+     * slot is activated by a one shot timer started in dialogHidden
+     */
+    void timerExpired();
+
+  signals:
+    /**
+     * This signal is emitted from aboutApplication() if no
+     * "about application" string has been defined. The standard
+     * application specific dialog box that is normally activated in
+     * aboutApplication() will not be displayed when this signal
+     * is emitted.
+     */
+    void showAboutApplication();
+
+  private:
+    KPopupMenu   *mMenu;
+    KDialogBase  *mAboutApp;
+    KAboutKDE    *mAboutKDE;
+    KBugReport   *mBugReport;
+
+    QString      mAboutAppText;
+    QWidget      *mParent;
+
+    bool         mShowWhatsThis;
+
+  protected:
+    virtual void virtual_hook( int id, void* data );
+  private:
+    KHelpMenuPrivate *d;
+};
+
+
+#endif