KWidgetsAddons

kactionmenu.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]kde.org>
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 KACTIONMENU_H
17 #define KACTIONMENU_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 KActionMenu kactionmenu.h KActionMenu
29  *
30  * A KActionMenu is an action that provides a sub-menu of other actions.
31  *
32  * Plugged in a popupmenu, it will create a submenu.
33  * Plugged in a toolbar, it will create a button with a popup menu.
34  *
35  * This is the action used by the XMLGUI since it holds other actions.
36  * If you want a submenu for selecting one tool among many (without icons), see KSelectAction.
37  */
38 class KWIDGETSADDONS_EXPORT KActionMenu : public QWidgetAction
39 {
40  Q_OBJECT
41 #if KWIDGETSADDONS_ENABLE_DEPRECATED_SINCE(5, 77)
42  Q_PROPERTY(bool delayed READ delayed WRITE setDelayed)
43  Q_PROPERTY(bool stickyMenu READ stickyMenu WRITE setStickyMenu)
44 #endif
45  Q_PROPERTY(QToolButton::ToolButtonPopupMode popupMode READ popupMode WRITE setPopupMode)
46 
47 public:
48  explicit KActionMenu(QObject *parent);
49  KActionMenu(const QString &text, QObject *parent);
50  KActionMenu(const QIcon &icon, const QString &text, QObject *parent);
51  ~KActionMenu() override;
52 
53 #if KWIDGETSADDONS_ENABLE_DEPRECATED_SINCE(5, 0)
54  /**
55  * @deprecated Since 5.0.
56  */
57  KWIDGETSADDONS_DEPRECATED_VERSION(5, 0, "Use KActionMenu::removeAction(QAction*)")
58  void remove(QAction *);
59 #endif
60 
61  /**
62  * Adds @p action to this KActionMenu.
63  * The KActionMenu does not take ownership of @p action.
64  */
65  void addAction(QAction *action);
66  QAction *addSeparator();
67  void insertAction(QAction *before, QAction *action);
68  QAction *insertSeparator(QAction *before);
69  void removeAction(QAction *action);
70 
71 #if KWIDGETSADDONS_ENABLE_DEPRECATED_SINCE(5, 0)
72  /**
73  * Returns this action's menu as a KMenu, if it is one.
74  * If none exists, one will be created.
75  * @deprecated Since 5.0, use menu() instead.
76  */
77  KWIDGETSADDONS_DEPRECATED_VERSION(5, 0, "Use KActionMenu::menu()")
78  inline QMenu *popupMenu()
79  {
80  return menu();
81  }
82 #endif
83 
84 #if KWIDGETSADDONS_ENABLE_DEPRECATED_SINCE(5, 77)
85  /**
86  * Returns true if this action creates a delayed popup menu
87  * when plugged in a KToolBar.
88  *
89  * @deprecated Since 5.77, use popupMode() instead.
90  */
91  KWIDGETSADDONS_DEPRECATED_VERSION(5, 77, "Use KActionMenu::popupMode()")
92  bool delayed() const;
93 #endif
94 
95 #if KWIDGETSADDONS_ENABLE_DEPRECATED_SINCE(5, 77)
96  /**
97  * If set to true, this action will create a delayed popup menu
98  * when plugged in a KToolBar. Otherwise it creates a normal popup.
99  * Default: true
100  *
101  * Remember that if the "main" action (the toolbar button itself)
102  * cannot be clicked, then you should call setDelayed(false).
103  *
104  * In the other case, if the main action can be clicked, it can only happen
105  * in a toolbar: in a menu, the parent of a submenu can't be activated.
106  * To get a "normal" menu item when plugged a menu (and no submenu)
107  * use KToolBarPopupAction.
108  *
109  * @deprecated Since 5.77, use setPopupMode() instead.
110  */
111  KWIDGETSADDONS_DEPRECATED_VERSION(5, 77, "Use KActionMenu::setPopupMode()")
112  void setDelayed(bool delayed);
113 #endif
114 
115 #if KWIDGETSADDONS_ENABLE_DEPRECATED_SINCE(5, 77)
116  /**
117  * Returns true if this action creates a sticky popup menu.
118  * @see setStickyMenu().
119  * @deprecated Since 5.77, use popupMode() instead.
120  */
121  KWIDGETSADDONS_DEPRECATED_VERSION(5, 77, "Use KActionMenu::popupMode()")
122  bool stickyMenu() const;
123 #endif
124 
125 #if KWIDGETSADDONS_ENABLE_DEPRECATED_SINCE(5, 77)
126  /**
127  * If set to true, this action will create a sticky popup menu
128  * when plugged in a KToolBar.
129  * "Sticky", means it's visible until a selection is made or the mouse is
130  * clicked elsewhere. This feature allows you to make a selection without
131  * having to press and hold down the mouse while making a selection.
132  * Default: sticky.
133  *
134  * @deprecated Since 5.77, use setPopupMode() instead.
135  */
136  KWIDGETSADDONS_DEPRECATED_VERSION(5, 77, "Use KActionMenu::setPopupMode()")
137  void setStickyMenu(bool sticky);
138 #endif
139 
140  /**
141  * The currently used popup mode when plugged in a KToolBar.
142  *
143  * @see setPopupMode()
144  *
145  * @since 5.77
146  */
147  QToolButton::ToolButtonPopupMode popupMode() const;
148 
149  /**
150  * Determines the popup mode when plugged in a KToolBar.
151  *
152  * Options are:
153  * - QToolButton::InstantPopup
154  * Clicking anywhere on the toolbar button opens the popup menu.
155  * - QToolButton::DelayedPopup (Default)
156  * Clicking anywhere on the toolbar button triggers the default action.
157  * Clicking and holding the toolbar button opens the popup menu instead.
158  * - QToolButton::MenuButtonPopup
159  * The toolbar button is split in a main button (triggers default action)
160  * and an arrow button (opens the popup menu).
161  *
162  * @see QToolButton
163  *
164  * @since 5.77
165  */
166  void setPopupMode(QToolButton::ToolButtonPopupMode popupMode);
167 
168  QWidget *createWidget(QWidget *parent) override;
169 
170 private:
171  std::unique_ptr<class KActionMenuPrivate> const d;
172 };
173 
174 #endif
Q_PROPERTY(...)
QMenu * menu() const const
virtual QWidget * createWidget(QWidget *parent)
This file is part of the KDE documentation.
Documentation copyright © 1996-2023 The KDE developers.
Generated on Sun Feb 5 2023 04:07:48 by doxygen 1.8.17 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.