summaryrefslogtreecommitdiffstats
path: root/kdeui/khelpmenu.h
diff options
context:
space:
mode:
Diffstat (limited to 'kdeui/khelpmenu.h')
-rw-r--r--kdeui/khelpmenu.h281
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