1/*
2 This file is part of the KDE libraries
3 SPDX-FileCopyrightText: 1999 Reginald Stadlbauer <reggie@kde.org>
4 SPDX-FileCopyrightText: 1999 Simon Hausmann <hausmann@kde.org>
5 SPDX-FileCopyrightText: 2000 Nicolas Hadacek <haadcek@kde.org>
6 SPDX-FileCopyrightText: 2000 Kurt Granroth <granroth@kde.org>
7 SPDX-FileCopyrightText: 2000 Michael Koch <koch@kde.org>
8 SPDX-FileCopyrightText: 2001 Holger Freyther <freyther@kde.org>
9 SPDX-FileCopyrightText: 2002 Ellis Whitehead <ellis@kde.org>
10 SPDX-FileCopyrightText: 2003 Andras Mantia <amantia@kde.org>
11 SPDX-FileCopyrightText: 2005-2006 Hamish Rodda <rodda@kde.org>
12 SPDX-FileCopyrightText: 2006 Albert Astals Cid <aacid@kde.org>
13 SPDX-FileCopyrightText: 2006 Clarence Dang <dang@kde.org>
14 SPDX-FileCopyrightText: 2006 Michel Hermier <michel.hermier@gmail.com>
15 SPDX-FileCopyrightText: 2007 Nick Shaforostoff <shafff@ukr.net>
16
17 SPDX-License-Identifier: LGPL-2.0-only
18*/
19
20#ifndef KSELECTACTION_H
21#define KSELECTACTION_H
22
23#include <QToolButton>
24#include <QWidgetAction>
25#include <memory>
26
27#include <kwidgetsaddons_export.h>
28
29class KSelectActionPrivate;
30
31/**
32 * @class KSelectAction kselectaction.h KSelectAction
33 *
34 * @short Action for selecting one of several items
35 *
36 * Action for selecting one of several items.
37 *
38 * This action shows up a submenu with a list of items.
39 * One of them can be checked. If the user clicks on an item
40 * this item will automatically be checked,
41 * the formerly checked item becomes unchecked.
42 * There can be only one item checked at a time.
43 *
44 * Porting from KF5 to KF6:
45 *
46 * <!-- Using '%' before the old symbol to prevent auto linking here and below -->
47 * The overloaded signal %KSelectAction::triggered(QAction *action) was renamed
48 * to KSelectAction::actionTriggered(QAction *action).
49 *
50 * The protected virtual method %KSelectAction::actionTriggered(QAction *action) was renamed
51 * to KSelectAction::slotActionTriggered(QAction *action).
52 */
53class KWIDGETSADDONS_EXPORT KSelectAction : public QWidgetAction
54{
55 Q_OBJECT
56 Q_PROPERTY(QAction *currentAction READ currentAction WRITE setCurrentAction)
57 Q_PROPERTY(bool editable READ isEditable WRITE setEditable)
58 Q_PROPERTY(int comboWidth READ comboWidth WRITE setComboWidth)
59 Q_PROPERTY(QString currentText READ currentText)
60 Q_PROPERTY(ToolBarMode toolBarMode READ toolBarMode WRITE setToolBarMode)
61 Q_PROPERTY(QToolButton::ToolButtonPopupMode toolButtonPopupMode READ toolButtonPopupMode WRITE setToolButtonPopupMode)
62 Q_PROPERTY(int currentItem READ currentItem WRITE setCurrentItem)
63 Q_PROPERTY(QStringList items READ items WRITE setItems)
64
65public:
66 /**
67 * Constructs a selection action with the specified parent.
68 *
69 * @param parent The action's parent object.
70 */
71 explicit KSelectAction(QObject *parent);
72
73 /**
74 * Constructs a selection action with text; a shortcut may be specified by
75 * the ampersand character (e.g.\ "&Option" creates a shortcut with key \e O )
76 *
77 * This is the most common KSelectAction used when you do not have a
78 * corresponding icon (note that it won't appear in the current version
79 * of the "Edit ToolBar" dialog, because an action needs an icon to be
80 * plugged in a toolbar...).
81 *
82 * @param text The text that will be displayed.
83 * @param parent The action's parent object.
84 */
85 KSelectAction(const QString &text, QObject *parent);
86
87 /**
88 * Constructs a selection action with text and an icon; a shortcut may be specified by
89 * the ampersand character (e.g.\ "&Option" creates a shortcut with key \e O )
90 *
91 * This is the other common KSelectAction used. Use it when you
92 * \e do have a corresponding icon.
93 *
94 * @param icon The icon to display.
95 * @param text The text that will be displayed.
96 * @param parent The action's parent object.
97 */
98 KSelectAction(const QIcon &icon, const QString &text, QObject *parent);
99
100 /**
101 * Destructor
102 */
103 ~KSelectAction() override;
104
105 enum ToolBarMode {
106 /// Creates a button which pops up a menu when interacted with, as defined by toolButtonPopupMode().
107 MenuMode,
108 /// Creates a combo box which contains the actions.
109 /// This is the default.
110 ComboBoxMode,
111 };
112 Q_ENUM(ToolBarMode)
113
114 /**
115 * Returns which type of widget (combo box or button with drop-down menu) will be inserted
116 * in a toolbar.
117 */
118 ToolBarMode toolBarMode() const;
119
120 /**
121 * Set the type of widget to be inserted in a toolbar to \a mode.
122 */
123 void setToolBarMode(ToolBarMode mode);
124
125 /**
126 * Returns the style for the list of actions, when this action is plugged
127 * into a KToolBar. The default value is QToolButton::InstantPopup
128 *
129 * \sa QToolButton::setPopupMode()
130 */
131 QToolButton::ToolButtonPopupMode toolButtonPopupMode() const;
132
133 /**
134 * Set how this list of actions should behave when in popup mode and plugged into a toolbar.
135 */
136 void setToolButtonPopupMode(QToolButton::ToolButtonPopupMode mode);
137
138 /**
139 * The action group used to create exclusivity between the actions associated with this action.
140 */
141 QActionGroup *selectableActionGroup() const;
142
143 /**
144 * Returns the current QAction.
145 * @see setCurrentAction
146 */
147 QAction *currentAction() const;
148
149 /**
150 * Returns the index of the current item.
151 *
152 * @sa currentText(), currentAction()
153 */
154 int currentItem() const;
155
156 /**
157 * Returns the text of the currently selected item.
158 *
159 * @sa currentItem(), currentAction()
160 */
161 QString currentText() const;
162
163 /**
164 * Returns the list of selectable actions
165 */
166 QList<QAction *> actions() const;
167
168 /**
169 * Returns the action at \a index, if one exists.
170 */
171 QAction *action(int index) const;
172
173 /**
174 * Searches for an action with the specified \a text, using a search whose
175 * case sensitivity is defined by \a cs.
176 */
177 QAction *action(const QString &text, Qt::CaseSensitivity cs = Qt::CaseSensitive) const;
178
179 /**
180 * Sets the currently checked item.
181 *
182 * @param action the QAction to become the currently checked item.
183 *
184 * \return \e true if a corresponding action was found and successfully checked.
185 */
186 bool setCurrentAction(QAction *action);
187
188 /**
189 * Convenience function to set the currently checked action to be the action
190 * at index \p index.
191 *
192 * If there is no action at that index, the currently checked action (if any) will
193 * be deselected.
194 *
195 * \return \e true if a corresponding action was found and thus set to the current action, otherwise \e false
196 */
197 bool setCurrentItem(int index);
198
199 /**
200 * Overloaded member function, provided for convenience, to set the currently
201 * checked action to be the action which has \p text as its text().
202 *
203 * If there is no action at that index, the currently checked action (if any) will
204 * be deselected.
205 *
206 * \return \e true if a corresponding action was found, otherwise \e false
207 */
208 bool setCurrentAction(const QString &text, Qt::CaseSensitivity cs = Qt::CaseSensitive);
209
210 /**
211 * Add \a action to the list of selectable actions.
212 */
213 void addAction(QAction *action);
214
215 /**
216 * Overloaded member function, provided for convenience, which creates an action
217 * from \p text and inserts it into the list of selectable actions.
218 *
219 * The newly created action is checkable and not user configurable.
220 */
221 QAction *addAction(const QString &text);
222
223 /**
224 * Overloaded member function, provided for convenience, which creates an action
225 * from \p text and \p icon and inserts it into the list of selectable actions.
226 *
227 * The newly created action is checkable and not user configurable.
228 */
229 QAction *addAction(const QIcon &icon, const QString &text);
230
231 /**
232 * Remove the specified \a action from this action selector.
233 *
234 * You take ownership here, so save or delete it in order to not leak the action.
235 */
236 virtual QAction *removeAction(QAction *action);
237
238 /**
239 * Inserts the action action to this widget's list of actions, before the action before.
240 * It appends the action if before is a null pointer or before is not a valid action for this widget.
241 *
242 * @since 5.0
243 */
244 virtual void insertAction(QAction *before, QAction *action);
245
246 /**
247 * Convenience function to create the list of selectable items.
248 * Any previously existing items will be cleared.
249 */
250 void setItems(const QStringList &lst);
251
252 /**
253 * Convenience function which returns the items that can be selected with this action.
254 * It is the same as iterating selectableActionGroup()->actions() and looking at each
255 * action's text().
256 */
257 QStringList items() const;
258
259 /**
260 * When this action is plugged into a toolbar, it creates a combobox.
261 * @return true if the combo editable.
262 */
263 bool isEditable() const;
264
265 /**
266 * When this action is plugged into a toolbar, it creates a combobox.
267 * This makes the combo editable or read-only.
268 */
269 void setEditable(bool);
270
271 /**
272 * When this action is plugged into a toolbar, it creates a combobox.
273 * This returns the maximum width set by setComboWidth
274 */
275 int comboWidth() const;
276
277 /**
278 * When this action is plugged into a toolbar, it creates a combobox.
279 * This gives a _maximum_ size to the combobox.
280 * The minimum size is automatically given by the contents (the items).
281 */
282 void setComboWidth(int width);
283
284 /**
285 * Sets the maximum items that are visible at once if the action
286 * is a combobox, that is the number of items in the combobox's viewport
287 */
288 void setMaxComboViewCount(int n);
289
290 /**
291 * Remove and delete all the items in this action.
292 *
293 * @see removeAllActions()
294 */
295 void clear();
296
297 /**
298 * Remove all the items in this action.
299 *
300 * Unlike clear(), this will not delete the actions.
301 *
302 * @see clear()
303 */
304 void removeAllActions();
305
306 /**
307 * Sets whether any occurrence of the ampersand character ( & ) in items
308 * should be interpreted as keyboard accelerator for items displayed in a
309 * menu or not. Only applies to (overloaded) methods dealing with QStrings,
310 * not those dealing with QActions.
311 *
312 * Defaults to true.
313 *
314 * \param b true if ampersands indicate a keyboard accelerator, otherwise false.
315 */
316 void setMenuAccelsEnabled(bool b);
317
318 /**
319 * Returns whether ampersands passed to methods using QStrings are interpreted
320 * as keyboard accelerator indicators or as literal ampersands.
321 */
322 bool menuAccelsEnabled() const;
323
324 /**
325 * You should delete KSelectAction::menu() before calling setMenu(). KSelectAction
326 * will take the @param menu ownership and it will be deleted when KSelectAction is
327 * destroyed.
328 */
329 using QWidgetAction::setMenu;
330
331 /**
332 * Changes the text of item @param index to @param text .
333 */
334 void changeItem(int index, const QString &text);
335
336Q_SIGNALS:
337 /**
338 * This signal is emitted when an item is selected.
339 * @param action indicates the item selected
340 *
341 * @since 6.0
342 */
343 void actionTriggered(QAction *action);
344
345 /**
346 * This signal is emitted when an item is selected.
347 * @param index indicates the item selected
348 *
349 * @since 5.78
350 */
351 void indexTriggered(int index);
352
353 /**
354 * This signal is emitted when an item is selected.
355 * @param text indicates the item selected
356 *
357 * @since 5.78
358 */
359 void textTriggered(const QString &text);
360
361protected Q_SLOTS:
362 /**
363 * This function is called whenever an action from the selections is triggered.
364 * The default implementation calls trigger() if isCheckable() is @c true, then emits
365 * the signals actionTriggered(QAction *), indexTriggered(int) and textTriggered(const QString &).
366 *
367 * @since 6.0
368 */
369 virtual void slotActionTriggered(QAction *action);
370
371 /**
372 * For structured menu building. Deselects all items if the action was unchecked by the top menu
373 */
374 void slotToggled(bool);
375
376protected:
377 /**
378 * Reimplemented from QWidgetAction.
379 */
380 QWidget *createWidget(QWidget *parent) override;
381
382 /**
383 * Reimplemented from QWidgetAction.
384 */
385 void deleteWidget(QWidget *widget) override;
386
387 bool event(QEvent *event) override;
388
389 bool eventFilter(QObject *watched, QEvent *event) override;
390
391 /**
392 * @internal
393 * Creates a new KSelectAction object.
394 *
395 * @param dd the private d member
396 * @param parent The action's parent object.
397 */
398 KWIDGETSADDONS_NO_EXPORT KSelectAction(KSelectActionPrivate &dd, QObject *parent);
399
400 std::unique_ptr<class KSelectActionPrivate> const d_ptr;
401
402private:
403 Q_DECLARE_PRIVATE(KSelectAction)
404};
405
406#endif
407

source code of kwidgetsaddons/src/kselectaction.h