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 SPDX-FileCopyrightText: 2023 Kai Uwe Broulik <kde@broulik.de>
13
14 SPDX-License-Identifier: LGPL-2.0-only
15*/
16
17#ifndef KTOOLBARPOPUPACTION_H
18#define KTOOLBARPOPUPACTION_H
19
20#include <QToolButton>
21#include <QWidgetAction>
22#include <memory>
23
24#include <kwidgetsaddons_export.h>
25
26class QMenu;
27
28/*!
29 * \class KToolBarPopupAction
30 * \inmodule KWidgetsAddons
31 *
32 * \brief This action is a normal action everywhere, except in a toolbar
33 * where it also has a popupmenu (optionally delayed).
34 *
35 * This action is designed
36 * for history actions (back/forward, undo/redo) and for any other action
37 * that has more detail in a toolbar than in a menu (e.g. tool chooser
38 * with "Other" leading to a dialog...).
39 *
40 * In contrast to KActionMenu, this action is a \e simple menuitem when plugged
41 * into a menu, and has a popup only in a toolbar.
42 *
43 * Use cases include Back/Forward, and Undo/Redo. Simple click is what's most commonly
44 * used, and enough for menus, but in toolbars there is \e also an optional popup
45 * to go back N steps or undo N steps.
46 *
47 * \note Add actions to the popupMenu(), don't use setMenu().
48 */
49class KWIDGETSADDONS_EXPORT KToolBarPopupAction : public QWidgetAction
50{
51 Q_OBJECT
52
53 /*!
54 * \property KToolBarPopupAction::popupMode
55 */
56 Q_PROPERTY(PopupMode popupMode READ popupMode WRITE setPopupMode)
57
58public:
59 /*!
60 * The menu popup mode.
61 *
62 * Default is MenuButtonPopup.
63 *
64 * \sa QToolButton::ToolButtonPopupMode
65 *
66 * \value NoPopup Behave as if the button had no menu.
67 * \value DelayedPopup Clicking anywhere on the toolbar button triggers the default action. Clicking and holding the toolbar button opens the popup menu
68 * instead.
69 * \value MenuButtonPopup The toolbar button is split in a main button (triggers default action) and an arrow button (opens the popup menu).
70 * \value InstantPopup Clicking anywhere on the toolbar button opens the popup menu.
71 *
72 * \since 6.0
73 */
74 enum PopupMode {
75 NoPopup = -1,
76 DelayedPopup = QToolButton::DelayedPopup,
77
78 MenuButtonPopup = QToolButton::MenuButtonPopup,
79
80 InstantPopup = QToolButton::InstantPopup,
81 };
82 Q_ENUM(PopupMode)
83
84 // Not all constructors - because we need an icon, since this action only makes
85 // sense when being plugged at least in a toolbar.
86 /*!
87 * Create a KToolBarPopupAction, with a text, an icon, a
88 * parent and a name.
89 *
90 * \a icon The icon to display.
91 *
92 * \a text The text that will be displayed.
93 *
94 * \a parent This action's parent.
95 */
96 KToolBarPopupAction(const QIcon &icon, const QString &text, QObject *parent);
97
98 ~KToolBarPopupAction() override;
99
100 /*!
101 * The popup menu that is shown when clicking (some time) on the toolbar
102 * button. You may want to plug items into it on creation, or connect to
103 * aboutToShow for a more dynamic menu.
104 *
105 * \note menu() is null on this action by default and using setMenu()
106 * will effectively turn this action into a regular action with a submenu.
107 *
108 * \since 6.0
109 */
110 QMenu *popupMenu() const;
111
112 /*!
113 * The popup mode of the toolbar button.
114 *
115 * \sa setPopupMode()
116 *
117 * \since 6.0
118 */
119 PopupMode popupMode() const;
120
121 /*!
122 * Determines the popup mode of the toolbar button.
123 * \sa PopupMode
124 *
125 * \since 6.0
126 */
127 void setPopupMode(PopupMode popupMode);
128
129 QWidget *createWidget(QWidget *parent) override;
130
131private:
132 std::unique_ptr<class KToolBarPopupActionPrivate> const d;
133};
134
135#endif
136

source code of kwidgetsaddons/src/ktoolbarpopupaction.h