src/disabledactionnotifier.h

   1 /*
   2  * SPDX-FileCopyrightText: 2024 Jin Liu <m.liu.jin@gmail.com>
   3  *
   4  * SPDX-License-Identifier: GPL-2.0-or-later
   5  */
   6
   7 #pragma once
   8
   9 #include <QAction>
  10 #include <QHash>
  11 #include <QShortcut>
  12
  13 /**
  14  * @brief A helper class to display a notification when the user presses the shortcut of a disabled action.
  15  */
  16 class DisabledActionNotifier : public QObject
  17 {
  18     Q_OBJECT
  19
  20 public:
  21     DisabledActionNotifier(QObject *parent = nullptr);
  22
  23     /**
  24      * Set the reason why the action is disabled.
  25      *
  26      * If the action is enabled, this function does nothing.
  27      *
  28      * Otherwise, it registers a shortcut, so when the user presses the shortcut for the
  29      * disabled action, it emits the disabledActionTriggered() signal with the disabled
  30      * action and the reason.
  31      *
  32      * If a reason has already been set, it will be replaced.
  33      */
  34     void setDisabledReason(QAction *action, QStringView reason);
  35
  36     /**
  37      * Clear the reason if it's set before by setDisabledReason().
  38      *
  39      * If the action is enabled, this function does nothing.
  40      *
  41      * Otherwise, it unregisters any shortcut set by setDisabledReason() on the same action.
  42      *
  43      * When an action is disabled in two cases, but only case A needs to show the reason,
  44      * then case B should call this function. Otherwise, the reason set by case A might be
  45      * shown for case B.
  46      */
  47     void clearDisabledReason(QAction *action);
  48
  49 Q_SIGNALS:
  50     /**
  51      * Emitted when the user presses the shortcut of a disabled action.
  52      *
  53      * @param action The disabled action.
  54      * @param reason The reason set in setDisabledReason().
  55      */
  56     void disabledActionTriggered(const QAction *action, QString reason);
  57
  58 private:
  59     QHash<QAction *, QShortcut *> m_shortcuts;
  60 };