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