File indexing completed on 2024-12-01 03:44:32

 /*
     This file is part of the KDE Libraries
     SPDX-FileCopyrightText: 1999-2000 Espen Sand <espen@kde.org>
 
     SPDX-License-Identifier: LGPL-2.0-or-later
 */
 
 #ifndef KHELPMENU_H
 #define KHELPMENU_H
 
 #include <kxmlgui_export.h>
 
 #include <QObject>
 #include <QString>
 
 class QMenu;
 class QWidget;
 class QAction;
 
 class KAboutData;
 class KHelpMenuPrivate;
 
 /**
  * @class KHelpMenu khelpmenu.h KHelpMenu
  *
  * @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->addMenu(mHelpMenu->menu() );
  * \endcode
  *
  * or if you just want to open a dialog box:
  *
  * \code
  * mHelpMenu = new KHelpMenu( this, <someText> );
  * connect(this, &ClassFoo::someSignal, mHelpMenu, &KHelpMenu::aboutKDE);
  * \endcode
  *
  * IMPORTANT:
  * The first time you use KHelpMenu::menu(), a QMenu 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 simply need to
  * connect the help menu signal showAboutApplication() to your slot.
  *
  * \code
  * void MyClass::myFunc()
  * {
  *   ..
  *   KHelpMenu *helpMenu = new KHelpMenu( this );
  *   connect(helpMenu, &KHelpMenu::showAboutApplication, this, &ClassFoo:myDialogSlot);
  *   ..
  * }
  *
  * void MyClass::myDialogSlot()
  * {
  *   <activate your custom dialog>
  * }
  * \endcode
  *
  * \image html khelpmenu.png "KHelpMenu"
  *
  * KHelpMenu respects Kiosk settings (see the KAuthorized namespace in the
  * KConfig framework).  In particular, system administrators can disable items
  * on this menu using some subset of the following configuration:
  * @verbatim
    [KDE Action Restrictions][$i]
    actions/help_contents=false
    actions/help_whats_this=false
    actions/help_report_bug=false
    actions/switch_application_language=false
    actions/help_about_app=false
    actions/help_about_kde=false
    @endverbatim
  *
  * @author Espen Sand (espen@kde.org)
  */
 
 class KXMLGUI_EXPORT KHelpMenu : public QObject
 {
     Q_OBJECT
 
 public:
     /**
      * 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
      *        default application dialog box.
      * @param showWhatsThis Decides whether a "What's this" entry will be
      *        added to the dialog.
      *
      */
     explicit KHelpMenu(QWidget *parent = nullptr, const QString &aboutAppText = QString(), bool showWhatsThis = true);
 
     /**
      * Constructor.
      *
      * This alternative constructor is mainly useful if you want to
      * override 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 "What's this" entry will be
      *        added to the dialog.
      */
     KHelpMenu(QWidget *parent, const KAboutData &aboutData, bool showWhatsThis = true);
 
     /**
      * Destructor
      *
      * Destroys dialogs and the menu pointer returned by menu
      */
     ~KHelpMenu() override;
 
     /**
      * Returns a popup menu you can use in the menu bar or where you
      * need it.
      *
      * The returned menu is configured with an icon, a title and
      * menu entries. Therefore adding the returned pointer to your menu
      * is enough to have access to the help menu.
      *
      * Note: This method will only create one instance of the menu. If
      * you call this method twice or more the same pointer is returned.
      */
     QMenu *menu();
 
     enum MenuId {
         menuHelpContents = 0,
         menuWhatsThis = 1,
         menuAboutApp = 2,
         menuAboutKDE = 3,
         menuReportBug = 4,
         menuSwitchLanguage = 5,
         menuDonate = 6, ///< @since 5.24
     };
 
     /**
      * Returns the QAction * associated with the given parameter
      * Will return a nullptr if menu() has not been called
      *
      * @param id The id of the action of which you want to get QAction *
      */
     QAction *action(MenuId id) const;
 
 public Q_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 method will try to open the about box using the following steps:
      * - If the showAboutApplication() signal is connected, then it will be called.
      *   This means there is an application defined aboutBox.
      * - If the aboutData was set in the constructor a KAboutApplicationDialog will be created.
      * - Else a default about box using the aboutAppText from the constructor will be created.
      */
     void aboutApplication();
 
     /**
      * Opens the standard "About KDE" dialog box.
      */
     void aboutKDE();
 
     /**
      * Opens the standard "Report Bugs" dialog box.
      */
     void reportBug();
 
     /**
      * Opens the changing default application language dialog box.
      */
     void switchApplicationLanguage();
 
     /**
      * Opens the donate url.
      * @since 5.24
      */
     void donate();
 
 private Q_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.
      */
     KXMLGUI_NO_EXPORT void menuDestroyed();
 
     /**
      * Connected to the dialogs (about kde and bug report) to detect
      * when they are finished.
      */
     KXMLGUI_NO_EXPORT void dialogFinished();
 
     /**
      * This slot will delete a dialog (about kde or bug report) if the
      * dialog pointer is not zero and the dialog is not visible. This
      * slot is activated by a one shot timer started in dialogHidden
      */
     KXMLGUI_NO_EXPORT void timerExpired();
 
 Q_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:
     KHelpMenuPrivate *const d;
 };
 
 #endif