1/* This file is part of the KDE libraries
2 Copyright (C) 2000 Daniel M. Duley <mosfet@kde.org>
3 Copyright (C) 2006 Olivier Goffart <ogoffart@kde.org>
4
5 This library is free software; you can redistribute it and/or
6 modify it under the terms of the GNU Library General Public
7 License version 2 as published by the Free Software Foundation.
8
9 This library is distributed in the hope that it will be useful,
10 but WITHOUT ANY WARRANTY; without even the implied warranty of
11 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
12 Library General Public License for more details.
13
14 You should have received a copy of the GNU Library General Public License
15 along with this library; see the file COPYING.LIB. If not, write to
16 the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
17 Boston, MA 02110-1301, USA.
18*/
19
20#ifndef KMENU_H
21#define KMENU_H
22
23#include <kdeui_export.h>
24
25#include <QtGui/QMenu>
26
27/**
28 * @short A menu with keyboard searching
29 *
30 * KMenu is a class for menus with keyboard
31 * accessibility for popups with many options and/or varying options. It acts
32 * identically to QMenu, with the addition of setKeyboardShortcutsEnabled() and
33 * setKeyboardShortcutsExecute() methods.
34 *
35 *
36 * The keyboard search algorithm is incremental with additional underlining
37 * for user feedback.
38 *
39 * @author Daniel M. Duley <mosfet@kde.org>
40 * @author Hamish Rodda <rodda@kde.org>
41 */
42class KDEUI_EXPORT KMenu : public QMenu {
43 Q_OBJECT
44public:
45 /**
46 * Constructs a KMenu.
47 */
48 explicit KMenu(QWidget *parent = 0L);
49
50 /**
51 * Constructs a KMenu.
52 * \param title The text displayed in a parent menu when it is inserted
53 * into another menu as a submenu.
54 * \param parent the parent QWidget object
55 */
56 explicit KMenu(const QString& title, QWidget *parent = 0L);
57
58 /**
59 * Destructs the object
60 */
61 ~KMenu();
62
63 /**
64 * Inserts a title item with no icon.
65 */
66 QAction* addTitle(const QString &text, QAction* before = 0L);
67
68 /**
69 * Inserts a title item with the given icon and title.
70 */
71 QAction* addTitle(const QIcon &icon, const QString &text, QAction* before = 0L);
72
73 /**
74 * Enables keyboard navigation by searching for the entered key sequence.
75 * Also underlines the currently selected item, providing feedback on the search.
76 *
77 * Defaults to off.
78 *
79 * \warning calls to text() of currently keyboard-selected items will
80 * contain additional ampersand characters.
81 *
82 * \warning though pre-existing keyboard shortcuts will not interfere with the
83 * operation of this feature, they may be confusing to the user as the existing
84 * shortcuts will not work. In addition, where text already contains ampersands,
85 * the underline produced is likely to confuse the user (as this feature uses
86 * underlining of text to indicate the current key selection sequence).
87 */
88 void setKeyboardShortcutsEnabled(bool enable);
89
90 /**
91 * Enables execution of the menu item once it is uniquely specified.
92 * Defaults to off.
93 */
94 void setKeyboardShortcutsExecute(bool enable);
95
96 /**
97 * Returns the context menu associated with this menu
98 * The data property of all actions inserted into the context menu is modified
99 * all the time to point to the action and menu it has been shown for
100 */
101 QMenu* contextMenu();
102
103 /**
104 * Returns the context menu associated with this menu
105 */
106 const QMenu* contextMenu() const;
107
108 /**
109 * Hides the context menu if shown
110 */
111 void hideContextMenu();
112
113 /**
114 * Returns the KMenu associated with the current context menu
115 */
116 static KMenu* contextMenuFocus();
117
118 /**
119 * returns the QAction associated with the current context menu
120 */
121 static QAction* contextMenuFocusAction();
122
123 /**
124 * Return the state of the mouse buttons when the last menuitem was activated.
125 */
126 Qt::MouseButtons mouseButtons() const;
127
128 /**
129 * Return the state of the keyboard modifiers when the last menuitem was activated.
130 */
131 Qt::KeyboardModifiers keyboardModifiers() const;
132
133Q_SIGNALS:
134 /**
135 * connect to this signal to be notified when a context menu is about to be shown
136 * @param menu The menu that the context menu is about to be shown for
137 * @param menuAction The action that the context menu is currently on
138 * @param ctxMenu The context menu itself
139 */
140 void aboutToShowContextMenu(KMenu* menu, QAction* menuAction, QMenu* ctxMenu);
141
142protected:
143 virtual void closeEvent(QCloseEvent *);
144 virtual void keyPressEvent(QKeyEvent* e);
145 virtual void mouseReleaseEvent(QMouseEvent* e);
146 virtual void mousePressEvent(QMouseEvent* e);
147 virtual bool focusNextPrevChild( bool next );
148 virtual void contextMenuEvent(QContextMenuEvent *e);
149 virtual void hideEvent(QHideEvent*);
150
151private:
152 QString underlineText(const QString& text, uint length);
153 class KMenuPrivate;
154 KMenuPrivate * const d;
155
156 Q_PRIVATE_SLOT(d, void resetKeyboardVars(bool b = false))
157 Q_PRIVATE_SLOT(d, void actionHovered(QAction*))
158 Q_PRIVATE_SLOT(d, void showCtxMenu(const QPoint &))
159
160};
161
162
163
164#endif
165