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

source code of kwidgetsaddons/src/ktoolbarpopupaction.h