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 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()") popupMenu()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 175