KDELibs4Support

kmenu.h
1 /* This file is part of the KDE libraries
2  Copyright (C) 2000 Daniel M. Duley <[email protected]>
3  Copyright (C) 2006 Olivier Goffart <[email protected]>
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 <[email protected]>
40  * @author Hamish Rodda <[email protected]>
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
typedef KeyboardModifiers
virtual bool focusNextPrevChild(bool next) override
A menu with keyboard searching.
Definition: kmenu.h:42
typedef MouseButtons
virtual void contextMenuEvent(QContextMenuEvent *event)
virtual void mousePressEvent(QMouseEvent *e) override
virtual void hideEvent(QHideEvent *) override
virtual void closeEvent(QCloseEvent *event)
virtual void mouseReleaseEvent(QMouseEvent *e) override
virtual void keyPressEvent(QKeyEvent *e) override
This file is part of the KDE documentation.
Documentation copyright © 1996-2021 The KDE developers.
Generated on Mon Jun 21 2021 22:58:15 by doxygen 1.8.11 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.