KWidgetsAddons

kselectaction.h
1 /*
2  This file is part of the KDE libraries
3  SPDX-FileCopyrightText: 1999 Reginald Stadlbauer <[email protected]>
4  SPDX-FileCopyrightText: 1999 Simon Hausmann <[email protected]>
5  SPDX-FileCopyrightText: 2000 Nicolas Hadacek <[email protected]>
6  SPDX-FileCopyrightText: 2000 Kurt Granroth <[email protected]>
7  SPDX-FileCopyrightText: 2000 Michael Koch <[email protected]>
8  SPDX-FileCopyrightText: 2001 Holger Freyther <[email protected]>
9  SPDX-FileCopyrightText: 2002 Ellis Whitehead <[email protected]>
10  SPDX-FileCopyrightText: 2003 Andras Mantia <[email protected]>
11  SPDX-FileCopyrightText: 2005-2006 Hamish Rodda <[email protected]>
12  SPDX-FileCopyrightText: 2006 Albert Astals Cid <[email protected]>
13  SPDX-FileCopyrightText: 2006 Clarence Dang <[email protected]>
14  SPDX-FileCopyrightText: 2006 Michel Hermier <[email protected]>
15  SPDX-FileCopyrightText: 2007 Nick Shaforostoff <[email protected]>
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 
29 class 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 class KWIDGETSADDONS_EXPORT KSelectAction : public QWidgetAction
45 {
46  Q_OBJECT
47  Q_PROPERTY(QAction *currentAction READ currentAction WRITE setCurrentAction)
48  Q_PROPERTY(bool editable READ isEditable WRITE setEditable)
49  Q_PROPERTY(int comboWidth READ comboWidth WRITE setComboWidth)
50  Q_PROPERTY(QString currentText READ currentText)
51  Q_PROPERTY(ToolBarMode toolBarMode READ toolBarMode WRITE setToolBarMode)
52  Q_PROPERTY(QToolButton::ToolButtonPopupMode toolButtonPopupMode READ toolButtonPopupMode WRITE setToolButtonPopupMode)
53  Q_PROPERTY(int currentItem READ currentItem WRITE setCurrentItem)
54  Q_PROPERTY(QStringList items READ items WRITE setItems)
55 
56 public:
57  /**
58  * Constructs a selection action with the specified parent.
59  *
60  * @param parent The action's parent object.
61  */
62  explicit KSelectAction(QObject *parent);
63 
64  /**
65  * Constructs a selection action with text; a shortcut may be specified by
66  * the ampersand character (e.g.\ "&Option" creates a shortcut with key \e O )
67  *
68  * This is the most common KSelectAction used when you do not have a
69  * corresponding icon (note that it won't appear in the current version
70  * of the "Edit ToolBar" dialog, because an action needs an icon to be
71  * plugged in a toolbar...).
72  *
73  * @param text The text that will be displayed.
74  * @param parent The action's parent object.
75  */
76  KSelectAction(const QString &text, QObject *parent);
77 
78  /**
79  * Constructs a selection action with text and an icon; a shortcut may be specified by
80  * the ampersand character (e.g.\ "&Option" creates a shortcut with key \e O )
81  *
82  * This is the other common KSelectAction used. Use it when you
83  * \e do have a corresponding icon.
84  *
85  * @param icon The icon to display.
86  * @param text The text that will be displayed.
87  * @param parent The action's parent object.
88  */
89  KSelectAction(const QIcon &icon, const QString &text, QObject *parent);
90 
91  /**
92  * Destructor
93  */
94  ~KSelectAction() override;
95 
96  enum ToolBarMode {
97  /// Creates a button which pops up a menu when interacted with, as defined by toolButtonPopupMode().
99  /// Creates a combo box which contains the actions.
100  /// This is the default.
102  };
103  Q_ENUM(ToolBarMode)
104 
105  /**
106  * Returns which type of widget (combo box or button with drop-down menu) will be inserted
107  * in a toolbar.
108  */
109  ToolBarMode toolBarMode() const;
110 
111  /**
112  * Set the type of widget to be inserted in a toolbar to \a mode.
113  */
114  void setToolBarMode(ToolBarMode mode);
115 
116  /**
117  * Returns the style for the list of actions, when this action is plugged
118  * into a KToolBar. The default value is QToolButton::InstantPopup
119  *
120  * \sa QToolButton::setPopupMode()
121  */
122  QToolButton::ToolButtonPopupMode toolButtonPopupMode() const;
123 
124  /**
125  * Set how this list of actions should behave when in popup mode and plugged into a toolbar.
126  */
127  void setToolButtonPopupMode(QToolButton::ToolButtonPopupMode mode);
128 
129  /**
130  * The action group used to create exclusivity between the actions associated with this action.
131  */
132  QActionGroup *selectableActionGroup() const;
133 
134  /**
135  * Returns the current QAction.
136  * @see setCurrentAction
137  */
138  QAction *currentAction() const;
139 
140  /**
141  * Returns the index of the current item.
142  *
143  * @sa currentText(), currentAction()
144  */
145  int currentItem() const;
146 
147  /**
148  * Returns the text of the currently selected item.
149  *
150  * @sa currentItem(), currentAction()
151  */
152  QString currentText() const;
153 
154  /**
155  * Returns the list of selectable actions
156  */
157  QList<QAction *> actions() const;
158 
159  /**
160  * Returns the action at \a index, if one exists.
161  */
162  QAction *action(int index) const;
163 
164  /**
165  * Searches for an action with the specified \a text, using a search whose
166  * case sensitivity is defined by \a cs.
167  */
168  QAction *action(const QString &text, Qt::CaseSensitivity cs = Qt::CaseSensitive) const;
169 
170  /**
171  * Sets the currently checked item.
172  *
173  * @param action the QAction to become the currently checked item.
174  *
175  * \return \e true if a corresponding action was found and successfully checked.
176  */
177  bool setCurrentAction(QAction *action);
178 
179  /**
180  * Convenience function to set the currently checked action to be the action
181  * at index \p index.
182  *
183  * If there is no action at that index, the currently checked action (if any) will
184  * be deselected.
185  *
186  * \return \e true if a corresponding action was found and thus set to the current action, otherwise \e false
187  */
188  bool setCurrentItem(int index);
189 
190  /**
191  * Overloaded member function, provided for convenience, to set the currently
192  * checked action to be the action which has \p text as its text().
193  *
194  * If there is no action at that index, the currently checked action (if any) will
195  * be deselected.
196  *
197  * \return \e true if a corresponding action was found, otherwise \e false
198  */
199  bool setCurrentAction(const QString &text, Qt::CaseSensitivity cs = Qt::CaseSensitive);
200 
201  /**
202  * Add \a action to the list of selectable actions.
203  */
204  void addAction(QAction *action);
205 
206  /**
207  * Overloaded member function, provided for convenience, which creates an action
208  * from \p text and inserts it into the list of selectable actions.
209  *
210  * The newly created action is checkable and not user configurable.
211  */
212  QAction *addAction(const QString &text);
213 
214  /**
215  * Overloaded member function, provided for convenience, which creates an action
216  * from \p text and \p icon and inserts it into the list of selectable actions.
217  *
218  * The newly created action is checkable and not user configurable.
219  */
220  QAction *addAction(const QIcon &icon, const QString &text);
221 
222  /**
223  * Remove the specified \a action from this action selector.
224  *
225  * You take ownership here, so save or delete it in order to not leak the action.
226  */
227  virtual QAction *removeAction(QAction *action);
228 
229  /**
230  * Inserts the action action to this widget's list of actions, before the action before.
231  * It appends the action if before is a null pointer or before is not a valid action for this widget.
232  *
233  * @since 5.0
234  */
235  virtual void insertAction(QAction *before, QAction *action);
236 
237  /**
238  * Convenience function to create the list of selectable items.
239  * Any previously existing items will be cleared.
240  */
241  void setItems(const QStringList &lst);
242 
243  /**
244  * Convenience function which returns the items that can be selected with this action.
245  * It is the same as iterating selectableActionGroup()->actions() and looking at each
246  * action's text().
247  */
248  QStringList items() const;
249 
250  /**
251  * When this action is plugged into a toolbar, it creates a combobox.
252  * @return true if the combo editable.
253  */
254  bool isEditable() const;
255 
256  /**
257  * When this action is plugged into a toolbar, it creates a combobox.
258  * This makes the combo editable or read-only.
259  */
260  void setEditable(bool);
261 
262  /**
263  * When this action is plugged into a toolbar, it creates a combobox.
264  * This returns the maximum width set by setComboWidth
265  */
266  int comboWidth() const;
267 
268  /**
269  * When this action is plugged into a toolbar, it creates a combobox.
270  * This gives a _maximum_ size to the combobox.
271  * The minimum size is automatically given by the contents (the items).
272  */
273  void setComboWidth(int width);
274 
275  /**
276  * Sets the maximum items that are visible at once if the action
277  * is a combobox, that is the number of items in the combobox's viewport
278  */
279  void setMaxComboViewCount(int n);
280 
281  /**
282  * Remove and delete all the items in this action.
283  *
284  * @see removeAllActions()
285  */
286  void clear();
287 
288  /**
289  * Remove all the items in this action.
290  *
291  * Unlike clear(), this will not delete the actions.
292  *
293  * @see clear()
294  */
295  void removeAllActions();
296 
297  /**
298  * Sets whether any occurrence of the ampersand character ( & ) in items
299  * should be interpreted as keyboard accelerator for items displayed in a
300  * menu or not. Only applies to (overloaded) methods dealing with QStrings,
301  * not those dealing with QActions.
302  *
303  * Defaults to true.
304  *
305  * \param b true if ampersands indicate a keyboard accelerator, otherwise false.
306  */
307  void setMenuAccelsEnabled(bool b);
308 
309  /**
310  * Returns whether ampersands passed to methods using QStrings are interpreted
311  * as keyboard accelerator indicators or as literal ampersands.
312  */
313  bool menuAccelsEnabled() const;
314 
315  /**
316  * You should delete KSelectAction::menu() before calling setMenu(). KSelectAction
317  * will take the @param menu ownership and it will be deleted when KSelectAction is
318  * destroyed.
319  */
321 
322  /**
323  * Changes the text of item @param index to @param text .
324  */
325  void changeItem(int index, const QString &text);
326 
327 Q_SIGNALS:
328  /**
329  * This signal is emitted when an item is selected.
330  * @param action indicates the item selected
331  */
332  void triggered(QAction *action); // clazy:exclude=overloaded-signal
333  // TODO KF6:: rename to actionTriggered(QAction *action)
334  // We cannot do this in KF5, due to existing slot method with same signature, see below
335 
336 #if KWIDGETSADDONS_ENABLE_DEPRECATED_SINCE(5, 78)
337  /**
338  * This signal is emitted when an item is selected.
339  * @param index indicates the item selected
340  * @deprecated Since 5.78, use indexTriggered(int)
341  */
342  KWIDGETSADDONS_DEPRECATED_VERSION(5, 78, "Use KSelectAction::indexTriggered(int)")
343  void triggered(int index); // clazy:exclude=overloaded-signal
344 #endif
345  /**
346  * This signal is emitted when an item is selected.
347  * @param index indicates the item selected
348  *
349  * In your KSelectAction subclass to be backward-compatible to KF < 5.78, emit instead
350  * just the deprecated signal triggered(int). That will also
351  * automatically emit indexTriggered(int) because this signal
352  * is connected to the deprecated one in the KSelectAction constructor.
353  * Only if you compile against a variant of KWidgetsAddons built without all API
354  * deprecated up to version 5.78, then emit this signal directly.
355  * Your code would be like this:
356  * @code
357  * const int index = selectableActionGroup()->actions().indexOf(action);
358  * #if KWIDGETSADDONS_BUILD_DEPRECATED_SINCE(5, 78)
359  * // will also indirectly emit indexTriggered since 5.78
360  * Q_EMIT triggered(index);
361  * #else
362  * Q_EMIT indexTriggered(index);
363  * #endif
364  * @endcode
365  *
366  * @since 5.78
367  */
368  void indexTriggered(int index);
369 
370 #if KWIDGETSADDONS_ENABLE_DEPRECATED_SINCE(5, 78)
371  /**
372  * This signal is emitted when an item is selected.
373  * @param text indicates the item selected
374  * @deprecated Since 5.78, use textTriggered(const QString &)
375  */
376  KWIDGETSADDONS_DEPRECATED_VERSION(5, 78, "Use KSelectAction::textTriggered(const QString &)")
377  void triggered(const QString &text); // clazy:exclude=overloaded-signal
378 #endif
379 
380  /**
381  * This signal is emitted when an item is selected.
382  * @param text indicates the item selected
383  *
384  * In your KSelectAction subclass to be backward-compatible to KF < 5.78, emit instead
385  * just the deprecated signal triggered(const QString &). That will also
386  * automatically emit textTriggered(const QString &) because this signal
387  * is connected to the deprecated one in the KSelectAction constructor.
388  * Only if you compile against a variant of KWidgetsAddons built without all API
389  * deprecated up to version 5.78, then emit this signal directly.
390  * Your code would be like this:
391  * @code
392  * #if KWIDGETSADDONS_BUILD_DEPRECATED_SINCE(5, 78)
393  * // will also indirectly emit textTriggered since 5.78
394  * Q_EMIT triggered(action->text());
395  * #else
396  * Q_EMIT textTriggered(action->text());
397  * #endif
398  * @endcode
399  *
400  * @since 5.78
401  */
402  void textTriggered(const QString &text);
403 
404 protected Q_SLOTS:
405  /**
406  * This function is called whenever an action from the selections is triggered.
407  * The default implementation calls trigger() if isCheckable() is @c true, then emits
408  * the signals triggered(QAction *), triggered(int) and triggered(const QString &)
409  * as well as since 5.78 the signals indexTriggered(int) and textTriggered(const QString &).
410  */
411  virtual void actionTriggered(QAction *action);
412  // TODO KF6:: rename to handleActionTriggered, to release name to signal
413 
414  /**
415  * For structured menu building. Deselects all items if the action was unchecked by the top menu
416  */
417  void slotToggled(bool);
418 
419 protected:
420  /**
421  * Reimplemented from QWidgetAction.
422  */
423  QWidget *createWidget(QWidget *parent) override;
424 
425  /**
426  * Reimplemented from QWidgetAction.
427  */
428  void deleteWidget(QWidget *widget) override;
429 
430  bool event(QEvent *event) override;
431 
432  bool eventFilter(QObject *watched, QEvent *event) override;
433 
434  /**
435  * @internal
436  * Creates a new KSelectAction object.
437  *
438  * @param dd the private d member
439  * @param parent The action's parent object.
440  */
441  KWIDGETSADDONS_NO_EXPORT KSelectAction(KSelectActionPrivate &dd, QObject *parent);
442 
443  std::unique_ptr<class KSelectActionPrivate> const d_ptr;
444 
445 private:
446  Q_DECLARE_PRIVATE(KSelectAction)
447 };
448 
449 #endif
Q_PROPERTY(...)
Q_ENUM(...)
CaseSensitivity
Q_SLOTSQ_SLOTS
void setMenu(QMenu *menu)
@ ComboBoxMode
Creates a combo box which contains the actions.
@ MenuMode
Creates a button which pops up a menu when interacted with, as defined by toolButtonPopupMode().
Definition: kselectaction.h:98
Q_SIGNALSQ_SIGNALS
virtual QWidget * createWidget(QWidget *parent)
void triggered(bool checked)
virtual bool eventFilter(QObject *obj, QEvent *event) override
virtual bool event(QEvent *event) override
Action for selecting one of several items.
Definition: kselectaction.h:44
virtual void deleteWidget(QWidget *widget)
This file is part of the KDE documentation.
Documentation copyright © 1996-2023 The KDE developers.
Generated on Tue Dec 5 2023 04:01:59 by doxygen 1.8.17 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.