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 | |
26 | class 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 | */ |
58 | class KDEUI_EXPORT KDualAction : public KAction |
59 | { |
60 | Q_OBJECT |
61 | public: |
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 | |
178 | public Q_SLOTS: |
179 | /** |
180 | * Sets the action state. |
181 | * activeChanged() will be emitted but not activeChangedByUser(). |
182 | */ |
183 | void setActive(bool state); |
184 | |
185 | Q_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 | |
198 | private: |
199 | Q_PRIVATE_SLOT(d, void slotTriggered()) |
200 | KDualActionPrivate *const d; |
201 | friend class KDualActionPrivate; |
202 | }; |
203 | |
204 | #endif /* KDUALACTION_H */ |
205 | |