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