1/* This file is part of the KDE libraries
2 Copyright (C) 1999 Reginald Stadlbauer <reggie@kde.org>
3 (C) 1999 Simon Hausmann <hausmann@kde.org>
4 (C) 2000 Nicolas Hadacek <haadcek@kde.org>
5 (C) 2000 Kurt Granroth <granroth@kde.org>
6 (C) 2000 Michael Koch <koch@kde.org>
7 (C) 2001 Holger Freyther <freyther@kde.org>
8 (C) 2002 Ellis Whitehead <ellis@kde.org>
9 (C) 2003 Andras Mantia <amantia@kde.org>
10 (C) 2005-2006 Hamish Rodda <rodda@kde.org>
11
12 This library is free software; you can redistribute it and/or
13 modify it under the terms of the GNU Library General Public
14 License version 2 as published by the Free Software Foundation.
15
16 This library is distributed in the hope that it will be useful,
17 but WITHOUT ANY WARRANTY; without even the implied warranty of
18 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
19 Library General Public License for more details.
20
21 You should have received a copy of the GNU Library General Public License
22 along with this library; see the file COPYING.LIB. If not, write to
23 the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
24 Boston, MA 02110-1301, USA.
25*/
26
27#ifndef KTOOLBARPOPUPACTION_H
28#define KTOOLBARPOPUPACTION_H
29
30#include <kaction.h>
31
32class KMenu;
33
34/**
35 * This action is a normal action everywhere, except in a toolbar
36 * where it also has a popupmenu (optionally delayed). This action is designed
37 * for history actions (back/forward, undo/redo) and for any other action
38 * that has more detail in a toolbar than in a menu (e.g. tool chooser
39 * with "Other" leading to a dialog...).
40 *
41 * In contrast to KActionMenu, this action is a \e simple menuitem when plugged
42 * into a menu, and has a popup only in a toolbar.
43 *
44 * Use cases include Back/Forward, and Undo/Redo. Simple click is what's most commonly
45 * used, and enough for menus, but in toolbars there is \e also an optional popup
46 * to go back N steps or undo N steps.
47 */
48class KDEUI_EXPORT KToolBarPopupAction : public KAction
49{
50 Q_OBJECT
51 Q_PROPERTY( bool delayed READ delayed WRITE setDelayed )
52 Q_PROPERTY( bool stickyMenu READ stickyMenu WRITE setStickyMenu )
53
54 public:
55 //Not all constructors - because we need an icon, since this action only makes
56 // sense when being plugged at least in a toolbar.
57 /**
58 * Create a KToolBarPopupAction, with a text, an icon, a
59 * parent and a name.
60 *
61 * @param icon The icon to display.
62 * @param text The text that will be displayed.
63 * @param parent This action's parent.
64 */
65 KToolBarPopupAction(const KIcon& icon, const QString& text, QObject *parent);
66
67 /**
68 * Destroys the toolbar popup action.
69 */
70 virtual ~KToolBarPopupAction();
71
72 /**
73 * The popup menu that is shown when clicking (some time) on the toolbar
74 * button. You may want to plug items into it on creation, or connect to
75 * aboutToShow for a more dynamic menu.
76 *
77 * \deprecated use menu() instead
78 */
79#ifndef KDE_NO_DEPRECATED
80 KDE_DEPRECATED KMenu *popupMenu() const;
81#endif
82
83 /**
84 * Returns true if this action creates a delayed popup menu
85 * when plugged in a KToolBar.
86 */
87 bool delayed() const;
88
89 /**
90 * If set to true, this action will create a delayed popup menu
91 * when plugged in a KToolBar. Otherwise it creates a normal popup.
92 * Default: delayed.
93 */
94 void setDelayed(bool delayed);
95
96 /**
97 * Returns true if this action creates a sticky popup menu.
98 * @see setStickyMenu().
99 */
100 bool stickyMenu() const;
101
102 /**
103 * If set to true, this action will create a sticky popup menu
104 * when plugged in a KToolBar.
105 * "Sticky", means it's visible until a selection is made or the mouse is
106 * clicked elsewhere. This feature allows you to make a selection without
107 * having to press and hold down the mouse while making a selection.
108 * Only available if delayed() is true.
109 * Default: sticky.
110 */
111 void setStickyMenu(bool sticky);
112
113 /**
114 * Reimplemented from @see QActionWidgetFactory.
115 */
116 virtual QWidget* createWidget(QWidget* parent);
117
118 private:
119 class Private;
120 Private* const d;
121};
122
123#endif
124