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 | */ |
49 | class KDE3SUPPORT_EXPORT : public Q3PopupMenu { |
50 | Q_OBJECT |
51 | public: |
52 | /** |
53 | * Constructs a K3PopupMenu. |
54 | */ |
55 | (QWidget *parent=0); |
56 | |
57 | /** |
58 | * Destructs the object |
59 | */ |
60 | (); |
61 | |
62 | /** |
63 | * Inserts a title item with no icon. |
64 | */ |
65 | QAction* (const QString &text, QAction* before = 0L); |
66 | /** |
67 | * Inserts a title item with the given icon and title. |
68 | */ |
69 | QAction* (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 (bool enable); |
85 | |
86 | /** |
87 | * Enables execution of the menu item once it is uniquely specified. |
88 | * Defaults to off. |
89 | */ |
90 | void (bool enable); |
91 | |
92 | /** |
93 | * Returns the context menu associated with this menu |
94 | */ |
95 | Q3PopupMenu* (); |
96 | |
97 | /** |
98 | * Returns the context menu associated with this menu |
99 | */ |
100 | const Q3PopupMenu* () const; |
101 | |
102 | /** |
103 | * Hides the context menu if shown |
104 | */ |
105 | void (); |
106 | |
107 | /** |
108 | * Returns the K3PopupMenu associated with the current context menu |
109 | */ |
110 | static K3PopupMenu* (); |
111 | |
112 | /** |
113 | * returns the QAction associated with the current context menu |
114 | */ |
115 | static QAction* (); |
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 () const; |
123 | #endif |
124 | |
125 | /** |
126 | * Return the state of the mouse buttons when the last menuitem was activated. |
127 | */ |
128 | Qt::MouseButtons () const; |
129 | |
130 | /** |
131 | * Return the state of the keyboard modifiers when the last menuitem was activated. |
132 | */ |
133 | Qt::KeyboardModifiers () const; |
134 | |
135 | #ifdef QT3_SUPPORT |
136 | /** |
137 | * Inserts a title item with no icon. |
138 | */ |
139 | int (const QString &text, int id=-1, int index=-1); |
140 | /** |
141 | * Inserts a title item with the given icon and title. |
142 | */ |
143 | int (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 (int id, const QString &text); |
150 | /** |
151 | * Changes the title and icon of the title item at the specified id. |
152 | */ |
153 | void (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 (int id=-1) const; |
160 | /** |
161 | * Returns the icon of the title item at the specified id. |
162 | */ |
163 | QPixmap (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 | (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 (const QString &title); |
178 | |
179 | /** |
180 | * returns the ID of the menuitem associated with the current context menu |
181 | */ |
182 | static int (); |
183 | |
184 | /** |
185 | * Reimplemented for internal purposes |
186 | */ |
187 | virtual void (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 (QAction* action) |
195 | { |
196 | if (!action) |
197 | return -1; |
198 | return static_cast<QMenuItem*>(action)->id(); |
199 | } |
200 | #endif |
201 | Q_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 (K3PopupMenu* , QAction* , QMenu* ); |
209 | /// compat |
210 | void (K3PopupMenu* , int , Q3PopupMenu* ); |
211 | |
212 | protected: |
213 | virtual void (QCloseEvent *); |
214 | virtual void (QKeyEvent* e); |
215 | virtual void (QMouseEvent* e); |
216 | virtual void (QMouseEvent* e); |
217 | virtual bool ( bool next ); |
218 | virtual void (QContextMenuEvent *e); |
219 | virtual void (QHideEvent*); |
220 | |
221 | virtual void ( int id, void* data ); |
222 | |
223 | protected Q_SLOTS: |
224 | QString (const QString& text, uint length); |
225 | void (bool noMatches = false); |
226 | void (QAction* action); |
227 | void (const QPoint &pos); |
228 | void (); |
229 | void (); |
230 | |
231 | private: |
232 | class ; |
233 | K3PopupMenuPrivate *; |
234 | Q_DISABLE_COPY( ) |
235 | }; |
236 | |
237 | #endif |
238 | |