1/*
2 This file is part of the KDE libraries
3 SPDX-FileCopyrightText: 2010 Aurélien Gâteau <agateau@kde.org>
4
5 SPDX-License-Identifier: LGPL-2.1-or-later
6*/
7#ifndef KDUALACTION_H
8#define KDUALACTION_H
9
10#include <QAction>
11
12#include <kwidgetsaddons_export.h>
13
14#include <memory>
15
16class KGuiItem;
17
18/**
19 * @class KDualAction kdualaction.h KDualAction
20 *
21 * @short An action which can alternate between two texts/icons when triggered.
22 *
23 * KDualAction should be used when you want to create an action which alternate
24 * between two states when triggered but which should not be rendered as a
25 * checkable widget because it is more appropriate to change the text and icon
26 * of the action instead.
27 *
28 * You should use KDualAction to implement this kind of actions instead of
29 * KToggleAction because KToggleAction is rendered as a checkable widget: this
30 * means one of your state will have a checkbox in a menu and will be
31 * represented as a sunken button in a toolbar.
32 *
33 * Porting from KToggleAction to KDualAction:
34 *
35 * 1. If you used the KToggleAction constructor which accepts the action text,
36 * adjust the constructor: KDualAction constructor accepts both inactive and
37 * active text.
38 *
39 * 2. Replace connections to the checked(bool) signal with a connection to the
40 * activeChanged(bool) (or activeChangedByUser(bool))
41 *
42 * 3. Replace calls to setChecked()/isChecked() with setActive()/isActive()
43 *
44 * 4. Replace calls to setCheckedState(guiItem) with
45 * setActiveGuiItem(guiItem)
46 *
47 * @author Aurélien Gâteau <agateau@kde.org>
48 * @since 4.6
49 */
50class KWIDGETSADDONS_EXPORT KDualAction : public QAction
51{
52 Q_OBJECT
53public:
54 /**
55 * Constructs a KDualAction with the specified parent. Texts must be set
56 * with setTextForState() or setGuiItemForState().
57 */
58 explicit KDualAction(QObject *parent);
59
60 /**
61 * Constructs a KDualAction with the specified parent and texts.
62 */
63 KDualAction(const QString &inactiveText, const QString &activeText, QObject *parent);
64
65 ~KDualAction() override;
66
67 /**
68 * Sets the KGuiItem for the active state
69 */
70 void setActiveGuiItem(const KGuiItem &);
71
72 /**
73 * Gets the KGuiItem for the active state
74 */
75 KGuiItem activeGuiItem() const;
76
77 /**
78 * Sets the KGuiItem for the inactive state
79 */
80 void setInactiveGuiItem(const KGuiItem &);
81
82 /**
83 * Gets the KGuiItem for the inactive state
84 */
85 KGuiItem inactiveGuiItem() const;
86
87 /**
88 * Sets the icon for the active state
89 */
90 void setActiveIcon(const QIcon &);
91
92 /**
93 * Gets the icon for the active state
94 */
95 QIcon activeIcon() const;
96
97 /**
98 * Sets the icon for the inactive state
99 */
100 void setInactiveIcon(const QIcon &);
101
102 /**
103 * Gets the icon for the inactive state
104 */
105 QIcon inactiveIcon() const;
106
107 /**
108 * Sets the text for the active state
109 */
110 void setActiveText(const QString &);
111
112 /**
113 * Gets the text for the active state
114 */
115 QString activeText() const;
116
117 /**
118 * Sets the text for the inactive state
119 */
120 void setInactiveText(const QString &);
121
122 /**
123 * Gets the text for the inactive state
124 */
125 QString inactiveText() const;
126
127 /**
128 * Sets the tooltip for the active state
129 */
130 void setActiveToolTip(const QString &);
131
132 /**
133 * Gets the tooltip for the active state
134 */
135 QString activeToolTip() const;
136
137 /**
138 * Sets the tooltip for the inactive state
139 */
140 void setInactiveToolTip(const QString &);
141
142 /**
143 * Gets the tooltip for the inactive state
144 */
145 QString inactiveToolTip() const;
146
147 /**
148 * Convenience method to set the icon for both active and inactive states.
149 */
150 void setIconForStates(const QIcon &icon);
151
152 /**
153 * Returns the action state.
154 * The action is inactive by default.
155 */
156 bool isActive() const;
157
158 /**
159 * Defines whether the current action should automatically be changed when
160 * the user triggers this action.
161 */
162 void setAutoToggle(bool);
163
164 /**
165 * Returns whether the current action will automatically be changed when
166 * the user triggers this action. The default value is true.
167 */
168 bool autoToggle() const;
169
170public Q_SLOTS:
171 /**
172 * Sets the action state.
173 * activeChanged() will be emitted but not activeChangedByUser().
174 */
175 void setActive(bool state);
176
177Q_SIGNALS:
178 /**
179 * Emitted when the state changes. This signal is emitted when the user
180 * trigger the action and when setActive() is called.
181 */
182 void activeChanged(bool);
183
184 /**
185 * Only emitted when the state changes because the user triggered the
186 * action.
187 */
188 void activeChangedByUser(bool);
189
190private:
191 friend class KDualActionPrivate;
192 std::unique_ptr<class KDualActionPrivate> const d;
193};
194
195#endif /* KDUALACTION_H */
196

source code of kwidgetsaddons/src/kdualaction.h