Line data    Source code

       1              : // SPDX-FileCopyrightText: 2015 Anne Jan Brouwer
       2              : // SPDX-License-Identifier: GPL-3.0-or-later
       3              : /**
       4              :  * @file
       5              :  * @brief TrayIcon: the system tray icon and its context menu that show,
       6              :  *        hide, minimise, maximise, restore or quit the main window.
       7              :  */
       8              : #ifndef SRC_TRAYICON_H_
       9              : #define SRC_TRAYICON_H_
      10              : 
      11              : #include <QObject>
      12              : #include <QSystemTrayIcon>
      13              : 
      14              : class QAction;
      15              : class QMainWindow;
      16              : class QMenu;
      17              : 
      18              : /**
      19              :  * @class TrayIcon
      20              :  * @ingroup ui
      21              :  * @brief Handles the system tray icon and menu.
      22              :  *
      23              :  * A QObject parented to the main window: nothing here is a widget (the menu
      24              :  * and the QSystemTrayIcon are children of this object), and the parent makes
      25              :  * sure ~QSystemTrayIcon runs on quit, which is what removes the icon from the
      26              :  * notification area on Windows.
      27              :  */
      28              : class TrayIcon : public QObject {
      29           36 :   Q_OBJECT
      30              : 
      31              : public:
      32              :   /**
      33              :    * @brief Construct a TrayIcon associated with the given main window.
      34              :    * @param parent Pointer to the QMainWindow this tray icon controls.
      35              :    */
      36              :   explicit TrayIcon(QMainWindow *parent);
      37              : 
      38              :   /**
      39              :    * @brief Check whether tray resources have been allocated and initialized.
      40              :    * @return true if tray resources are allocated and initialized.
      41              :    */
      42              :   auto getIsAllocated() -> bool;
      43              : 
      44              :   /**
      45              :    * @brief Put one of the window's toggles in the tray menu, above Quit.
      46              :    * @param action The window's own action, so its checked state is the same
      47              :    *        in both places. Ignored when there is no tray.
      48              :    */
      49              :   void addToggle(QAction *action);
      50              : 
      51              : signals:
      52              : 
      53              : public slots:
      54              :   /**
      55              :    * @brief Toggle the visibility of the associated main window.
      56              :    */
      57              :   void showHideParent();
      58              : 
      59              :   /**
      60              :    * @brief Handle activation events from the system tray icon.
      61              :    * @param reason The activation reason provided by QSystemTrayIcon.
      62              :    */
      63              :   void iconActivated(QSystemTrayIcon::ActivationReason reason);
      64              : 
      65              : private:
      66              :   /**
      67              :    * @brief Create the Show/Hide/Minimize/Maximize/Restore/Quit actions and
      68              :    *        wire each one to the matching QWidget slot of the main window
      69              :    *        (Quit goes to QApplication::quit()).
      70              :    */
      71              :   void createActions();
      72              : 
      73              :   /**
      74              :    * @brief Build the context menu from the actions and create the
      75              :    *        QSystemTrayIcon that pops it up. Called only when a system tray
      76              :    *        is available.
      77              :    */
      78              :   void createTrayIcon();
      79              : 
      80              :   /** @brief Shows the main window (QWidget::show()). */
      81              :   QAction *showAction{nullptr};
      82              :   /** @brief Hides the main window (QWidget::hide()). */
      83              :   QAction *hideAction{nullptr};
      84              :   /** @brief Minimises the main window. */
      85              :   QAction *minimizeAction{nullptr};
      86              :   /** @brief Maximises the main window. */
      87              :   QAction *maximizeAction{nullptr};
      88              :   /** @brief Restores the main window to its normal size. */
      89              :   QAction *restoreAction{nullptr};
      90              :   /** @brief Quits the application. */
      91              :   QAction *quitAction{nullptr};
      92              :   /**
      93              :    * @brief Separator directly above Quit; addToggle() inserts the window's
      94              :    *        toggles (each with its own separator) in front of it.
      95              :    */
      96              :   QAction *quitSeparator{nullptr};
      97              : 
      98              :   /**
      99              :    * @brief The icon in the notification area; owned by this object so it is
     100              :    *        destroyed, and the icon removed, when the main window goes away.
     101              :    *        Null when no system tray is available.
     102              :    */
     103              :   QSystemTrayIcon *sysTrayIcon{nullptr};
     104              :   /**
     105              :    * @brief Context menu of the tray icon; a child of the main window because
     106              :    *        QMenu needs a widget parent. Null when no system tray is
     107              :    *        available.
     108              :    */
     109              :   QMenu *trayIconMenu{nullptr};
     110              :   /** @brief The main window the actions and showHideParent() operate on. */
     111              :   QMainWindow *parentwin;
     112              : 
     113              :   /**
     114              :    * @brief true once the actions, menu and icon exist; stays false when
     115              :    *        QSystemTrayIcon::isSystemTrayAvailable() was false at construction.
     116              :    */
     117              :   bool isAllocated{false};
     118              : };
     119              : 
     120              : #endif // SRC_TRAYICON_H_