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 KACTIONMENU_H
28#define KACTIONMENU_H
29
30#include <kaction.h>
31
32class KMenu;
33
34/**
35 * A KActionMenu is an action that has several properties specific to holding a
36 * sub-menu of other actions.
37 *
38 * Any QAction can be used to create a submenu.
39 *
40 * Plugged in a popupmenu, it will create a submenu.
41 * Plugged in a toolbar, it will create a button with a popup menu.
42 *
43 * This is the action used by the XMLGUI since it holds other actions.
44 * If you want a submenu for selecting one tool among many (without icons), see KSelectAction.
45 * See also setDelayed about the main action.
46 */
47class KDEUI_EXPORT KActionMenu : public KAction
48{
49 Q_OBJECT
50 Q_PROPERTY( bool delayed READ delayed WRITE setDelayed )
51 Q_PROPERTY( bool stickyMenu READ stickyMenu WRITE setStickyMenu )
52
53public:
54 explicit KActionMenu(QObject *parent);
55 KActionMenu(const QString& text, QObject *parent);
56 KActionMenu(const KIcon& icon, const QString& text, QObject *parent);
57 virtual ~KActionMenu();
58
59 /**
60 * @deprecated
61 */
62#ifndef KDE_NO_DEPRECATED
63 KDE_DEPRECATED void remove( KAction* );
64#endif
65
66 void addAction(QAction* action);
67 QAction* addSeparator();
68 void insertAction(QAction* before, QAction* action);
69 QAction* insertSeparator(QAction* before);
70 void removeAction(QAction* action);
71
72 /**
73 * Returns this action's menu as a KMenu, if it is one.
74 * If none exists, one will be created.
75 * @deprecated use menu() instead.
76 */
77#ifndef KDE_NO_DEPRECATED
78 inline KDE_DEPRECATED KMenu* popupMenu() { return menu(); }
79#endif
80
81 /**
82 * Returns this action's menu as a KMenu, if it is one.
83 * If none exists, one will be created.
84 */
85 KMenu* menu();
86
87 /*
88 * Overload of QAction::setMenu to make sure a KMenu is passed
89 **/
90 void setMenu( KMenu *menu );
91
92 /**
93 * Returns true if this action creates a delayed popup menu
94 * when plugged in a KToolBar.
95 */
96 bool delayed() const;
97
98 /**
99 * If set to true, this action will create a delayed popup menu
100 * when plugged in a KToolBar. Otherwise it creates a normal popup.
101 * Default: delayed
102 *
103 * Remember that if the "main" action (the toolbar button itself)
104 * cannot be clicked, then you should call setDelayed(false).
105 *
106 * In the other case, if the main action can be clicked, it can only happen
107 * in a toolbar: in a menu, the parent of a submenu can't be activated.
108 * To get a "normal" menu item when plugged a menu (and no submenu)
109 * use KToolBarPopupAction.
110 */
111 void setDelayed(bool delayed);
112
113 /**
114 * Returns true if this action creates a sticky popup menu.
115 * @see setStickyMenu().
116 */
117 bool stickyMenu() const;
118
119 /**
120 * If set to true, this action will create a sticky popup menu
121 * when plugged in a KToolBar.
122 * "Sticky", means it's visible until a selection is made or the mouse is
123 * clicked elsewhere. This feature allows you to make a selection without
124 * having to press and hold down the mouse while making a selection.
125 * Default: sticky.
126 */
127 void setStickyMenu(bool sticky);
128
129 virtual QWidget* createWidget(QWidget* parent);
130
131private:
132 class KActionMenuPrivate* const d;
133};
134
135#endif
136