KWidgetsAddons

kdualaction.h
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
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 */
189
190private:
191 friend class KDualActionPrivate;
192 std::unique_ptr<class KDualActionPrivate> const d;
193};
194
195#endif /* KDUALACTION_H */
An action which can alternate between two texts/icons when triggered.
Definition kdualaction.h:51
void activeChanged(bool)
Emitted when the state changes.
void activeChangedByUser(bool)
Only emitted when the state changes because the user triggered the action.
An abstract class for setting the text, icon, tooltip and WhatsThis data on a GUI item (e....
Definition kguiitem.h:34
Q_SIGNALSQ_SIGNALS
Q_SLOTSQ_SLOTS
This file is part of the KDE documentation.
Documentation copyright © 1996-2024 The KDE developers.
Generated on Tue Mar 26 2024 11:14:43 by doxygen 1.10.0 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.