1/* This file is part of the KDE libraries
2 Copyright (C) 2000 Daniel M. Duley <mosfet@kde.org>
3
4 This library is free software; you can redistribute it and/or
5 modify it under the terms of the GNU Library General Public
6 License version 2 as published by the Free Software Foundation.
7
8 This library is distributed in the hope that it will be useful,
9 but WITHOUT ANY WARRANTY; without even the implied warranty of
10 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
11 Library General Public License for more details.
12
13 You should have received a copy of the GNU Library General Public License
14 along with this library; see the file COPYING.LIB. If not, write to
15 the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
16 Boston, MA 02110-1301, USA.
17*/
18
19#ifndef _K3POPUPMENU_H
20#define _K3POPUPMENU_H
21
22#ifndef QT3_SUPPORT
23#define QT3_SUPPORT
24#endif
25
26#include <kde3support_export.h>
27
28#include <Qt3Support/Q3PopupMenu>
29#include <QtGui/QMenuItem>
30
31/**
32 * @short A menu with keyboard searching and convenience methods for title items.
33 *
34 * K3PopupMenu is a compatibility class for KPopupMenu from KDE 3.
35 * It provides menus with standard title items and keyboard
36 * accessibility for popups with many options and/or varying options. It acts
37 * identically to QMenu, with the addition of insertTitle(),
38 * changeTitle(), setKeyboardShortcutsEnabled() and
39 * setKeyboardShortcutsExecute() methods.
40 *
41 * The titles support a text string and an icon.
42 *
43 * The keyboard search algorithm is incremental with additional underlining
44 * for user feedback.
45 *
46 * @author Daniel M. Duley <mosfet@kde.org>
47 * @author Hamish Rodda <rodda@kde.org>
48 */
49class KDE3SUPPORT_EXPORT K3PopupMenu : public Q3PopupMenu {
50 Q_OBJECT
51public:
52 /**
53 * Constructs a K3PopupMenu.
54 */
55 K3PopupMenu(QWidget *parent=0);
56
57 /**
58 * Destructs the object
59 */
60 ~K3PopupMenu();
61
62 /**
63 * Inserts a title item with no icon.
64 */
65 QAction* addTitle(const QString &text, QAction* before = 0L);
66 /**
67 * Inserts a title item with the given icon and title.
68 */
69 QAction* addTitle(const QIcon &icon, const QString &text, QAction* before = 0L);
70
71 /**
72 * Enables keyboard navigation by searching for the entered key sequence.
73 * Also underlines the currently selected item, providing feedback on the search.
74 *
75 * Defaults to off.
76 *
77 * WARNING: calls to text() of currently keyboard-selected items will
78 * contain additional ampersand characters.
79 *
80 * WARNING: though pre-existing keyboard shortcuts will not interfere with the
81 * operation of this feature, they may be confusing to the user as the existing
82 * shortcuts will not work.
83 */
84 void setKeyboardShortcutsEnabled(bool enable);
85
86 /**
87 * Enables execution of the menu item once it is uniquely specified.
88 * Defaults to off.
89 */
90 void setKeyboardShortcutsExecute(bool enable);
91
92 /**
93 * Returns the context menu associated with this menu
94 */
95 Q3PopupMenu* contextMenu();
96
97 /**
98 * Returns the context menu associated with this menu
99 */
100 const Q3PopupMenu* contextMenu() const;
101
102 /**
103 * Hides the context menu if shown
104 */
105 void hideContextMenu();
106
107 /**
108 * Returns the K3PopupMenu associated with the current context menu
109 */
110 static K3PopupMenu* contextMenuFocus();
111
112 /**
113 * returns the QAction associated with the current context menu
114 */
115 static QAction* contextMenuFocusAction();
116
117#ifdef QT3_SUPPORT
118 /**
119 * Return the state of the mouse button and keyboard modifiers
120 * when the last menuitem was activated.
121 */
122 Qt::ButtonState state() const;
123#endif
124
125 /**
126 * Return the state of the mouse buttons when the last menuitem was activated.
127 */
128 Qt::MouseButtons mouseButtons() const;
129
130 /**
131 * Return the state of the keyboard modifiers when the last menuitem was activated.
132 */
133 Qt::KeyboardModifiers keyboardModifiers() const;
134
135#ifdef QT3_SUPPORT
136 /**
137 * Inserts a title item with no icon.
138 */
139 int insertTitle(const QString &text, int id=-1, int index=-1);
140 /**
141 * Inserts a title item with the given icon and title.
142 */
143 int insertTitle(const QPixmap &icon, const QString &text, int id=-1,
144 int index=-1);
145 /**
146 * Changes the title of the item at the specified id. If a icon was
147 * previously set it is cleared.
148 */
149 void changeTitle(int id, const QString &text);
150 /**
151 * Changes the title and icon of the title item at the specified id.
152 */
153 void changeTitle(int id, const QPixmap &icon, const QString &text);
154 /**
155 * Returns the title of the title item at the specified id. The default
156 * id of -1 is for backwards compatibility only, you should always specify
157 * the id.
158 */
159 QString title(int id=-1) const;
160 /**
161 * Returns the icon of the title item at the specified id.
162 */
163 QPixmap titlePixmap(int id) const;
164
165 /**
166 * @deprecated
167 * Obsolete method provided for backwards compatibility only. Use the
168 * normal constructor and insertTitle instead.
169 */
170 K3PopupMenu(const QString &title, QWidget *parent=0);
171
172 /**
173 * @deprecated
174 * Obsolete method provided for backwards compatibility only. Use
175 * insertTitle and changeTitle instead.
176 */
177 void setTitle(const QString &title);
178
179 /**
180 * returns the ID of the menuitem associated with the current context menu
181 */
182 static int contextMenuFocusItem();
183
184 /**
185 * Reimplemented for internal purposes
186 */
187 virtual void activateItemAt(int index);
188 // END compat methods
189
190 /**
191 * Helper for porting things. Returns ID of action, or -1 if passed null.
192 * ### KDE4: should be able to remove on Monday
193 */
194 static int actionId(QAction* action)
195 {
196 if (!action)
197 return -1;
198 return static_cast<QMenuItem*>(action)->id();
199 }
200#endif
201Q_SIGNALS:
202 /**
203 * connect to this signal to be notified when a context menu is about to be shown
204 * @param menu The menu that the context menu is about to be shown for
205 * @param menuAction The action that the context menu is currently on
206 * @param ctxMenu The context menu itself
207 */
208 void aboutToShowContextMenu(K3PopupMenu* menu, QAction* menuAction, QMenu* ctxMenu);
209 /// compat
210 void aboutToShowContextMenu(K3PopupMenu* menu, int menuItem, Q3PopupMenu* ctxMenu);
211
212protected:
213 virtual void closeEvent(QCloseEvent *);
214 virtual void keyPressEvent(QKeyEvent* e);
215 virtual void mouseReleaseEvent(QMouseEvent* e);
216 virtual void mousePressEvent(QMouseEvent* e);
217 virtual bool focusNextPrevChild( bool next );
218 virtual void contextMenuEvent(QContextMenuEvent *e);
219 virtual void hideEvent(QHideEvent*);
220
221 virtual void virtual_hook( int id, void* data );
222
223protected Q_SLOTS:
224 QString underlineText(const QString& text, uint length);
225 void resetKeyboardVars(bool noMatches = false);
226 void actionHovered(QAction* action);
227 void showCtxMenu(const QPoint &pos);
228 void ctxMenuHiding();
229 void ctxMenuHideShowingMenu();
230
231private:
232 class K3PopupMenuPrivate;
233 K3PopupMenuPrivate *d;
234 Q_DISABLE_COPY( K3PopupMenu )
235};
236
237#endif
238