File indexing completed on 2024-07-14 14:38:38

0001 /*
0002     This file is part of the KDE Libraries
0003     SPDX-FileCopyrightText: 1999-2000 Espen Sand <espen@kde.org>
0004 
0005     SPDX-License-Identifier: LGPL-2.0-or-later
0006 */
0007 
0008 #ifndef KHELPMENU_H
0009 #define KHELPMENU_H
0010 
0011 #include <kxmlgui_export.h>
0012 
0013 #include <QObject>
0014 #include <QString>
0015 
0016 class QMenu;
0017 class QWidget;
0018 class QAction;
0019 
0020 class KAboutData;
0021 class KHelpMenuPrivate;
0022 
0023 /**
0024  * @class KHelpMenu khelpmenu.h KHelpMenu
0025  *
0026  * @short Standard %KDE help menu with dialog boxes.
0027  *
0028  * This class provides the standard %KDE help menu with the default "about"
0029  * dialog boxes and help entry.
0030  *
0031  * This class is used in KMainWindow so
0032  * normally you don't need to use this class yourself. However, if you
0033  * need the help menu or any of its dialog boxes in your code that is
0034  * not subclassed from KMainWindow you should use this class.
0035  *
0036  * The usage is simple:
0037  *
0038  * \code
0039  * mHelpMenu = new KHelpMenu( this, <someText> );
0040  * kmenubar->addMenu(mHelpMenu->menu() );
0041  * \endcode
0042  *
0043  * or if you just want to open a dialog box:
0044  *
0045  * \code
0046  * mHelpMenu = new KHelpMenu( this, <someText> );
0047  * connect(this, &ClassFoo::someSignal, mHelpMenu, &KHelpMenu::aboutKDE);
0048  * \endcode
0049  *
0050  * IMPORTANT:
0051  * The first time you use KHelpMenu::menu(), a QMenu object is
0052  * allocated. Only one object is created by the class so if you call
0053  * KHelpMenu::menu() twice or more, the same pointer is returned. The class
0054  * will destroy the popupmenu in the destructor so do not delete this
0055  * pointer yourself.
0056  *
0057  * The KHelpMenu object will be deleted when its parent is destroyed but you
0058  * can delete it yourself if you want. The code below will always work.
0059  *
0060  * \code
0061  * MyClass::~MyClass()
0062  * {
0063  *   delete mHelpMenu;
0064  * }
0065  * \endcode
0066  *
0067  *
0068  * Using your own "about application" dialog box:
0069  *
0070  * The standard "about application" dialog box is quite simple. If you
0071  * need a dialog box with more functionality you must design that one
0072  * yourself. When you want to display the dialog, you simply need to
0073  * connect the help menu signal showAboutApplication() to your slot.
0074  *
0075  * \code
0076  * void MyClass::myFunc()
0077  * {
0078  *   ..
0079  *   KHelpMenu *helpMenu = new KHelpMenu( this );
0080  *   connect(helpMenu, &KHelpMenu::showAboutApplication, this, &ClassFoo:myDialogSlot);
0081  *   ..
0082  * }
0083  *
0084  * void MyClass::myDialogSlot()
0085  * {
0086  *   <activate your custom dialog>
0087  * }
0088  * \endcode
0089  *
0090  * \image html khelpmenu.png "KHelpMenu"
0091  *
0092  * KHelpMenu respects Kiosk settings (see the KAuthorized namespace in the
0093  * KConfig framework).  In particular, system administrators can disable items
0094  * on this menu using some subset of the following configuration:
0095  * @verbatim
0096    [KDE Action Restrictions][$i]
0097    actions/help_contents=false
0098    actions/help_whats_this=false
0099    actions/help_report_bug=false
0100    actions/switch_application_language=false
0101    actions/help_about_app=false
0102    actions/help_about_kde=false
0103    @endverbatim
0104  *
0105  * @author Espen Sand (espen@kde.org)
0106  */
0107 
0108 class KXMLGUI_EXPORT KHelpMenu : public QObject
0109 {
0110     Q_OBJECT
0111 
0112 public:
0113     /**
0114      * Constructor.
0115      *
0116      * @param parent The parent of the dialog boxes. The boxes are modeless
0117      *        and will be centered with respect to the parent.
0118      * @param aboutAppText User definable string that is used in the
0119      *        default application dialog box.
0120      * @param showWhatsThis Decides whether a "What's this" entry will be
0121      *        added to the dialog.
0122      *
0123      */
0124     explicit KHelpMenu(QWidget *parent = nullptr, const QString &aboutAppText = QString(), bool showWhatsThis = true);
0125 
0126     /**
0127      * Constructor.
0128      *
0129      * This alternative constructor is mainly useful if you want to
0130      * override the standard actions (aboutApplication(), aboutKDE(),
0131      * helpContents(), reportBug, and optionally whatsThis).
0132      *
0133      * @param parent The parent of the dialog boxes. The boxes are modeless
0134      *        and will be centered with respect to the parent.
0135      * @param aboutData User and app data used in the About app dialog
0136      * @param showWhatsThis Decides whether a "What's this" entry will be
0137      *        added to the dialog.
0138      */
0139     KHelpMenu(QWidget *parent, const KAboutData &aboutData, bool showWhatsThis = true);
0140 
0141     /**
0142      * Destructor
0143      *
0144      * Destroys dialogs and the menu pointer returned by menu
0145      */
0146     ~KHelpMenu() override;
0147 
0148     /**
0149      * Returns a popup menu you can use in the menu bar or where you
0150      * need it.
0151      *
0152      * The returned menu is configured with an icon, a title and
0153      * menu entries. Therefore adding the returned pointer to your menu
0154      * is enough to have access to the help menu.
0155      *
0156      * Note: This method will only create one instance of the menu. If
0157      * you call this method twice or more the same pointer is returned.
0158      */
0159     QMenu *menu();
0160 
0161     enum MenuId {
0162         menuHelpContents = 0,
0163         menuWhatsThis = 1,
0164         menuAboutApp = 2,
0165         menuAboutKDE = 3,
0166         menuReportBug = 4,
0167         menuSwitchLanguage = 5,
0168         menuDonate = 6, ///< @since 5.24
0169     };
0170 
0171     /**
0172      * Returns the QAction * associated with the given parameter
0173      * Will return a nullptr if menu() has not been called
0174      *
0175      * @param id The id of the action of which you want to get QAction *
0176      */
0177     QAction *action(MenuId id) const;
0178 
0179 public Q_SLOTS:
0180     /**
0181      * Opens the help page for the application. The application name is
0182      * used as a key to determine what to display and the system will attempt
0183      * to open \<appName\>/index.html.
0184      */
0185     void appHelpActivated();
0186 
0187     /**
0188      * Activates What's This help for the application.
0189      */
0190     void contextHelpActivated();
0191 
0192     /**
0193      * Opens an application specific dialog box.
0194      *
0195      * The method will try to open the about box using the following steps:
0196      * - If the showAboutApplication() signal is connected, then it will be called.
0197      *   This means there is an application defined aboutBox.
0198      * - If the aboutData was set in the constructor a KAboutApplicationDialog will be created.
0199      * - Else a default about box using the aboutAppText from the constructor will be created.
0200      */
0201     void aboutApplication();
0202 
0203     /**
0204      * Opens the standard "About KDE" dialog box.
0205      */
0206     void aboutKDE();
0207 
0208     /**
0209      * Opens the standard "Report Bugs" dialog box.
0210      */
0211     void reportBug();
0212 
0213     /**
0214      * Opens the changing default application language dialog box.
0215      */
0216     void switchApplicationLanguage();
0217 
0218     /**
0219      * Opens the donate url.
0220      * @since 5.24
0221      */
0222     void donate();
0223 
0224 private Q_SLOTS:
0225     /**
0226      * Connected to the menu pointer (if created) to detect a delete
0227      * operation on the pointer. You should not delete the pointer in your
0228      * code yourself. Let the KHelpMenu destructor do the job.
0229      */
0230     KXMLGUI_NO_EXPORT void menuDestroyed();
0231 
0232     /**
0233      * Connected to the dialogs (about kde and bug report) to detect
0234      * when they are finished.
0235      */
0236     KXMLGUI_NO_EXPORT void dialogFinished();
0237 
0238     /**
0239      * This slot will delete a dialog (about kde or bug report) if the
0240      * dialog pointer is not zero and the dialog is not visible. This
0241      * slot is activated by a one shot timer started in dialogHidden
0242      */
0243     KXMLGUI_NO_EXPORT void timerExpired();
0244 
0245 Q_SIGNALS:
0246     /**
0247      * This signal is emitted from aboutApplication() if no
0248      * "about application" string has been defined. The standard
0249      * application specific dialog box that is normally activated in
0250      * aboutApplication() will not be displayed when this signal
0251      * is emitted.
0252      */
0253     void showAboutApplication();
0254 
0255 private:
0256     KHelpMenuPrivate *const d;
0257 };
0258 
0259 #endif