File indexing completed on 2025-02-16 13:11:41
0001 /* 0002 This file is part of the KDE libraries 0003 SPDX-FileCopyrightText: 2010 Aurélien Gâteau <agateau@kde.org> 0004 0005 SPDX-License-Identifier: LGPL-2.1-or-later 0006 */ 0007 #ifndef KDUALACTION_H 0008 #define KDUALACTION_H 0009 0010 #include <QAction> 0011 0012 #include <kwidgetsaddons_export.h> 0013 0014 #include <memory> 0015 0016 class KGuiItem; 0017 0018 /** 0019 * @class KDualAction kdualaction.h KDualAction 0020 * 0021 * @short An action which can alternate between two texts/icons when triggered. 0022 * 0023 * KDualAction should be used when you want to create an action which alternate 0024 * between two states when triggered but which should not be rendered as a 0025 * checkable widget because it is more appropriate to change the text and icon 0026 * of the action instead. 0027 * 0028 * You should use KDualAction to implement this kind of actions instead of 0029 * KToggleAction because KToggleAction is rendered as a checkable widget: this 0030 * means one of your state will have a checkbox in a menu and will be 0031 * represented as a sunken button in a toolbar. 0032 * 0033 * Porting from KToggleAction to KDualAction: 0034 * 0035 * 1. If you used the KToggleAction constructor which accepts the action text, 0036 * adjust the constructor: KDualAction constructor accepts both inactive and 0037 * active text. 0038 * 0039 * 2. Replace connections to the checked(bool) signal with a connection to the 0040 * activeChanged(bool) (or activeChangedByUser(bool)) 0041 * 0042 * 3. Replace calls to setChecked()/isChecked() with setActive()/isActive() 0043 * 0044 * 4. Replace calls to setCheckedState(guiItem) with 0045 * setActiveGuiItem(guiItem) 0046 * 0047 * @author Aurélien Gâteau <agateau@kde.org> 0048 * @since 4.6 0049 */ 0050 class KWIDGETSADDONS_EXPORT KDualAction : public QAction 0051 { 0052 Q_OBJECT 0053 public: 0054 /** 0055 * Constructs a KDualAction with the specified parent. Texts must be set 0056 * with setTextForState() or setGuiItemForState(). 0057 */ 0058 explicit KDualAction(QObject *parent); 0059 0060 /** 0061 * Constructs a KDualAction with the specified parent and texts. 0062 */ 0063 KDualAction(const QString &inactiveText, const QString &activeText, QObject *parent); 0064 0065 ~KDualAction() override; 0066 0067 /** 0068 * Sets the KGuiItem for the active state 0069 */ 0070 void setActiveGuiItem(const KGuiItem &); 0071 0072 /** 0073 * Gets the KGuiItem for the active state 0074 */ 0075 KGuiItem activeGuiItem() const; 0076 0077 /** 0078 * Sets the KGuiItem for the inactive state 0079 */ 0080 void setInactiveGuiItem(const KGuiItem &); 0081 0082 /** 0083 * Gets the KGuiItem for the inactive state 0084 */ 0085 KGuiItem inactiveGuiItem() const; 0086 0087 /** 0088 * Sets the icon for the active state 0089 */ 0090 void setActiveIcon(const QIcon &); 0091 0092 /** 0093 * Gets the icon for the active state 0094 */ 0095 QIcon activeIcon() const; 0096 0097 /** 0098 * Sets the icon for the inactive state 0099 */ 0100 void setInactiveIcon(const QIcon &); 0101 0102 /** 0103 * Gets the icon for the inactive state 0104 */ 0105 QIcon inactiveIcon() const; 0106 0107 /** 0108 * Sets the text for the active state 0109 */ 0110 void setActiveText(const QString &); 0111 0112 /** 0113 * Gets the text for the active state 0114 */ 0115 QString activeText() const; 0116 0117 /** 0118 * Sets the text for the inactive state 0119 */ 0120 void setInactiveText(const QString &); 0121 0122 /** 0123 * Gets the text for the inactive state 0124 */ 0125 QString inactiveText() const; 0126 0127 /** 0128 * Sets the tooltip for the active state 0129 */ 0130 void setActiveToolTip(const QString &); 0131 0132 /** 0133 * Gets the tooltip for the active state 0134 */ 0135 QString activeToolTip() const; 0136 0137 /** 0138 * Sets the tooltip for the inactive state 0139 */ 0140 void setInactiveToolTip(const QString &); 0141 0142 /** 0143 * Gets the tooltip for the inactive state 0144 */ 0145 QString inactiveToolTip() const; 0146 0147 /** 0148 * Convenience method to set the icon for both active and inactive states. 0149 */ 0150 void setIconForStates(const QIcon &icon); 0151 0152 /** 0153 * Returns the action state. 0154 * The action is inactive by default. 0155 */ 0156 bool isActive() const; 0157 0158 /** 0159 * Defines whether the current action should automatically be changed when 0160 * the user triggers this action. 0161 */ 0162 void setAutoToggle(bool); 0163 0164 /** 0165 * Returns whether the current action will automatically be changed when 0166 * the user triggers this action. The default value is true. 0167 */ 0168 bool autoToggle() const; 0169 0170 public Q_SLOTS: 0171 /** 0172 * Sets the action state. 0173 * activeChanged() will be emitted but not activeChangedByUser(). 0174 */ 0175 void setActive(bool state); 0176 0177 Q_SIGNALS: 0178 /** 0179 * Emitted when the state changes. This signal is emitted when the user 0180 * trigger the action and when setActive() is called. 0181 */ 0182 void activeChanged(bool); 0183 0184 /** 0185 * Only emitted when the state changes because the user triggered the 0186 * action. 0187 */ 0188 void activeChangedByUser(bool); 0189 0190 private: 0191 friend class KDualActionPrivate; 0192 std::unique_ptr<class KDualActionPrivate> const d; 0193 }; 0194 0195 #endif /* KDUALACTION_H */