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 <kdelibs4support_export.h>
24 
25 #include <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  */
42 class KDELIBS4SUPPORT_DEPRECATED_EXPORT KMenu : public QMenu
43 {
44     Q_OBJECT
45 public:
46     /**
47      * Constructs a KMenu.
48      */
49     KDELIBS4SUPPORT_DEPRECATED explicit KMenu(QWidget *parent = nullptr);
50 
51     /**
52      * Constructs a KMenu.
53      * \param title The text displayed in a parent menu when it is inserted
54      *              into another menu as a submenu.
55      * \param parent the parent QWidget object
56      */
57     KDELIBS4SUPPORT_DEPRECATED explicit KMenu(const QString &title, QWidget *parent = nullptr);
58 
59     /**
60      * Destructs the object
61      */
62     ~KMenu() override;
63 
64     /**
65      * Inserts a title item with no icon.
66      */
67     QAction *addTitle(const QString &text, QAction *before = nullptr);
68 
69     /**
70      * Inserts a title item with the given icon and title.
71      */
72     QAction *addTitle(const QIcon &icon, const QString &text, QAction *before = nullptr);
73 
74     /**
75      * Enables keyboard navigation by searching for the entered key sequence.
76      * Also underlines the currently selected item, providing feedback on the search.
77      *
78      * Defaults to off.
79      *
80      * \warning calls to text() of currently keyboard-selected items will
81      * contain additional ampersand characters.
82      *
83      * \warning though pre-existing keyboard shortcuts will not interfere with the
84      * operation of this feature, they may be confusing to the user as the existing
85      * shortcuts will not work.  In addition, where text already contains ampersands,
86      * the underline produced is likely to confuse the user (as this feature uses
87      * underlining of text to indicate the current key selection sequence).
88      */
89     void setKeyboardShortcutsEnabled(bool enable);
90 
91     /**
92      * Enables execution of the menu item once it is uniquely specified.
93      * Defaults to off.
94      */
95     void setKeyboardShortcutsExecute(bool enable);
96 
97     /**
98      * Returns the context menu associated with this menu
99      * The data property of all actions inserted into the context menu is modified
100      * all the time to point to the action and menu it has been shown for
101      */
102     QMenu *contextMenu();
103 
104     /**
105      * Returns the context menu associated with this menu
106      */
107     const QMenu *contextMenu() const;
108 
109     /**
110      * Hides the context menu if shown
111      */
112     void hideContextMenu();
113 
114     /**
115      * Returns the KMenu associated with the current context menu
116      */
117     static KMenu *contextMenuFocus();
118 
119     /**
120      * returns the QAction associated with the current context menu
121      */
122     static QAction *contextMenuFocusAction();
123 
124     /**
125      * Return the state of the mouse buttons when the last menuitem was activated.
126      */
127     Qt::MouseButtons mouseButtons() const;
128 
129     /**
130      * Return the state of the keyboard modifiers when the last menuitem was activated.
131      */
132     Qt::KeyboardModifiers keyboardModifiers() const;
133 
134 Q_SIGNALS:
135     /**
136      * connect to this signal to be notified when a context menu is about to be shown
137      * @param menu The menu that the context menu is about to be shown for
138      * @param menuAction The action that the context menu is currently on
139      * @param ctxMenu The context menu itself
140      */
141     void aboutToShowContextMenu(KMenu *menu, QAction *menuAction, QMenu *ctxMenu);
142 
143 protected:
144     void closeEvent(QCloseEvent *) override;
145     void keyPressEvent(QKeyEvent *e) override;
146     void mouseReleaseEvent(QMouseEvent *e) override;
147     void mousePressEvent(QMouseEvent *e) override;
148     bool focusNextPrevChild(bool next) override;
149     void contextMenuEvent(QContextMenuEvent *e) override;
150     void hideEvent(QHideEvent *) override;
151 
152 private:
153     QString underlineText(const QString &text, uint length);
154     class KMenuPrivate;
155     KMenuPrivate *const d;
156 
157     Q_PRIVATE_SLOT(d, void resetKeyboardVars(bool b = false))
158     Q_PRIVATE_SLOT(d, void actionHovered(QAction *))
159     Q_PRIVATE_SLOT(d, void showCtxMenu(const QPoint &))
160 
161 };
162 
163 #endif
164