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 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 165