KWidgetsAddons

ktoolbarpopupaction.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 
13  SPDX-License-Identifier: LGPL-2.0-only
14 */
15 
16 #ifndef KTOOLBARPOPUPACTION_H
17 #define KTOOLBARPOPUPACTION_H
18 
19 #include <QToolButton>
20 #include <QWidgetAction>
21 #include <memory>
22 
23 #include <kwidgetsaddons_export.h>
24 
25 class QMenu;
26 
27 /**
28  * @class KToolBarPopupAction ktoolbarpopupaction.h KToolBarPopupAction
29  *
30  * This action is a normal action everywhere, except in a toolbar
31  * where it also has a popupmenu (optionally delayed). This action is designed
32  * for history actions (back/forward, undo/redo) and for any other action
33  * that has more detail in a toolbar than in a menu (e.g. tool chooser
34  * with "Other" leading to a dialog...).
35  *
36  * In contrast to KActionMenu, this action is a \e simple menuitem when plugged
37  * into a menu, and has a popup only in a toolbar.
38  *
39  * Use cases include Back/Forward, and Undo/Redo. Simple click is what's most commonly
40  * used, and enough for menus, but in toolbars there is \e also an optional popup
41  * to go back N steps or undo N steps.
42  */
43 class KWIDGETSADDONS_EXPORT KToolBarPopupAction : public QWidgetAction
44 {
45  Q_OBJECT
46 #if KWIDGETSADDONS_ENABLE_DEPRECATED_SINCE(5, 78)
47  Q_PROPERTY(bool delayed READ delayed WRITE setDelayed)
48  Q_PROPERTY(bool stickyMenu READ stickyMenu WRITE setStickyMenu)
49 #endif
50  Q_PROPERTY(QToolButton::ToolButtonPopupMode popupMode READ popupMode WRITE setPopupMode)
51 
52 public:
53  // Not all constructors - because we need an icon, since this action only makes
54  // sense when being plugged at least in a toolbar.
55  /**
56  * Create a KToolBarPopupAction, with a text, an icon, a
57  * parent and a name.
58  *
59  * @param icon The icon to display.
60  * @param text The text that will be displayed.
61  * @param parent This action's parent.
62  */
63  KToolBarPopupAction(const QIcon &icon, const QString &text, QObject *parent);
64 
65  /**
66  * Destroys the toolbar popup action.
67  */
68  ~KToolBarPopupAction() override;
69 
70 #if KWIDGETSADDONS_ENABLE_DEPRECATED_SINCE(5, 0)
71  /**
72  * The popup menu that is shown when clicking (some time) on the toolbar
73  * button. You may want to plug items into it on creation, or connect to
74  * aboutToShow for a more dynamic menu.
75  *
76  * \deprecated Since 5.0, use menu() instead
77  */
78  KWIDGETSADDONS_DEPRECATED_VERSION(5, 0, "Use KToolBarPopupAction::menu()")
79  QMenu *popupMenu() const;
80 #endif
81 
82 #if KWIDGETSADDONS_ENABLE_DEPRECATED_SINCE(5, 78)
83  /**
84  * Returns true if this action creates a delayed popup menu
85  * when plugged in a KToolBar.
86  *
87  * @deprecated Since 5.78, use popupMode() instead.
88  */
89  bool delayed() const;
90 #endif
91 
92 #if KWIDGETSADDONS_ENABLE_DEPRECATED_SINCE(5, 78)
93  /**
94  * If set to true, this action will create a delayed popup menu
95  * when plugged in a KToolBar. Otherwise it creates a normal popup.
96  * Default: delayed.
97  *
98  * @deprecated Since 5.78, use setPopupMode() instead.
99  */
100  void setDelayed(bool delayed);
101 #endif
102 
103 #if KWIDGETSADDONS_ENABLE_DEPRECATED_SINCE(5, 78)
104  /**
105  * Returns true if this action creates a sticky popup menu.
106  * @see setStickyMenu().
107  * @deprecated Since 5.78, use popupMode() instead.
108  */
109  bool stickyMenu() const;
110 #endif
111 
112 #if KWIDGETSADDONS_ENABLE_DEPRECATED_SINCE(5, 78)
113  /**
114  * If set to true, this action will create a sticky popup menu
115  * when plugged in a KToolBar.
116  * "Sticky", means it's visible until a selection is made or the mouse is
117  * clicked elsewhere. This feature allows you to make a selection without
118  * having to press and hold down the mouse while making a selection.
119  * Only available if delayed() is true.
120  * Default: sticky.
121  *
122  * @deprecated Since 5.78, use setPopupMode() instead.
123  */
124  void setStickyMenu(bool sticky);
125 #endif
126 
127  /**
128  * The popup mode of the toolbar button.
129  *
130  * @see setPopupMode()
131  *
132  * @since 5.78
133  */
134  QToolButton::ToolButtonPopupMode popupMode() const;
135 
136  /**
137  * Determines the popup mode of the toolbar button.
138  *
139  * Options are:
140  * - QToolButton::InstantPopup
141  * Clicking anywhere on the toolbar button opens the popup menu.
142  * - QToolButton::DelayedPopup
143  * Clicking anywhere on the toolbar button triggers the default action.
144  * Clicking and holding the toolbar button opens the popup menu instead.
145  * - QToolButton::MenuButtonPopup (Default)
146  * The toolbar button is split in a main button (triggers default action)
147  * and an arrow button (opens the popup menu).
148  *
149  * @see QToolButton
150  *
151  * @since 5.78
152  */
153  void setPopupMode(QToolButton::ToolButtonPopupMode popupMode);
154 
155  /**
156  * Reimplemented from QWidgetAction.
157  */
158  QWidget *createWidget(QWidget *parent) override;
159 
160 private:
161  std::unique_ptr<class KToolBarPopupActionPrivate> const d;
162 };
163 
164 #endif
Q_PROPERTY(...)
virtual QWidget * createWidget(QWidget *parent)
This file is part of the KDE documentation.
Documentation copyright © 1996-2023 The KDE developers.
Generated on Thu Mar 23 2023 04:11:11 by doxygen 1.8.17 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.