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
20 * \inmodule KWidgetsAddons
21 *
22 * \brief An action which can alternate between two texts/icons when triggered.
23 *
24 * KDualAction should be used when you want to create an action which alternate
25 * between two states when triggered but which should not be rendered as a
26 * checkable widget because it is more appropriate to change the text and icon
27 * of the action instead.
28 *
29 * You should use KDualAction to implement this kind of actions instead of
30 * KToggleAction because KToggleAction is rendered as a checkable widget: this
31 * means one of your state will have a checkbox in a menu and will be
32 * represented as a sunken button in a toolbar.
33 *
34 * Porting from KToggleAction to KDualAction:
35 *
36 * 1. If you used the KToggleAction constructor which accepts the action text,
37 * adjust the constructor: KDualAction constructor accepts both inactive and
38 * active text.
39 *
40 * 2. Replace connections to the checked(bool) signal with a connection to the
41 * activeChanged(bool) (or activeChangedByUser(bool))
42 *
43 * 3. Replace calls to setChecked()/isChecked() with setActive()/isActive()
44 *
45 * 4. Replace calls to setCheckedState(guiItem) with
46 * setActiveGuiItem(guiItem)
47 *
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