File indexing completed on 2024-05-05 12:13:24
0001 /* This file is part of the KDE libraries 0002 Copyright (C) 2000 Daniel M. Duley <mosfet@kde.org> 0003 Copyright (C) 2006 Olivier Goffart <ogoffart@kde.org> 0004 0005 This library is free software; you can redistribute it and/or 0006 modify it under the terms of the GNU Library General Public 0007 License version 2 as published by the Free Software Foundation. 0008 0009 This library is distributed in the hope that it will be useful, 0010 but WITHOUT ANY WARRANTY; without even the implied warranty of 0011 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 0012 Library General Public License for more details. 0013 0014 You should have received a copy of the GNU Library General Public License 0015 along with this library; see the file COPYING.LIB. If not, write to 0016 the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, 0017 Boston, MA 02110-1301, USA. 0018 */ 0019 0020 #ifndef KMENU_H 0021 #define KMENU_H 0022 0023 #include <kdelibs4support_export.h> 0024 0025 #include <QMenu> 0026 0027 /** 0028 * @short A menu with keyboard searching 0029 * 0030 * KMenu is a class for menus with keyboard 0031 * accessibility for popups with many options and/or varying options. It acts 0032 * identically to QMenu, with the addition of setKeyboardShortcutsEnabled() and 0033 * setKeyboardShortcutsExecute() methods. 0034 * 0035 * 0036 * The keyboard search algorithm is incremental with additional underlining 0037 * for user feedback. 0038 * 0039 * @author Daniel M. Duley <mosfet@kde.org> 0040 * @author Hamish Rodda <rodda@kde.org> 0041 */ 0042 class KDELIBS4SUPPORT_DEPRECATED_EXPORT KMenu : public QMenu 0043 { 0044 Q_OBJECT 0045 public: 0046 /** 0047 * Constructs a KMenu. 0048 */ 0049 KDELIBS4SUPPORT_DEPRECATED explicit KMenu(QWidget *parent = nullptr); 0050 0051 /** 0052 * Constructs a KMenu. 0053 * \param title The text displayed in a parent menu when it is inserted 0054 * into another menu as a submenu. 0055 * \param parent the parent QWidget object 0056 */ 0057 KDELIBS4SUPPORT_DEPRECATED explicit KMenu(const QString &title, QWidget *parent = nullptr); 0058 0059 /** 0060 * Destructs the object 0061 */ 0062 ~KMenu() override; 0063 0064 /** 0065 * Inserts a title item with no icon. 0066 */ 0067 QAction *addTitle(const QString &text, QAction *before = nullptr); 0068 0069 /** 0070 * Inserts a title item with the given icon and title. 0071 */ 0072 QAction *addTitle(const QIcon &icon, const QString &text, QAction *before = nullptr); 0073 0074 /** 0075 * Enables keyboard navigation by searching for the entered key sequence. 0076 * Also underlines the currently selected item, providing feedback on the search. 0077 * 0078 * Defaults to off. 0079 * 0080 * \warning calls to text() of currently keyboard-selected items will 0081 * contain additional ampersand characters. 0082 * 0083 * \warning though pre-existing keyboard shortcuts will not interfere with the 0084 * operation of this feature, they may be confusing to the user as the existing 0085 * shortcuts will not work. In addition, where text already contains ampersands, 0086 * the underline produced is likely to confuse the user (as this feature uses 0087 * underlining of text to indicate the current key selection sequence). 0088 */ 0089 void setKeyboardShortcutsEnabled(bool enable); 0090 0091 /** 0092 * Enables execution of the menu item once it is uniquely specified. 0093 * Defaults to off. 0094 */ 0095 void setKeyboardShortcutsExecute(bool enable); 0096 0097 /** 0098 * Returns the context menu associated with this menu 0099 * The data property of all actions inserted into the context menu is modified 0100 * all the time to point to the action and menu it has been shown for 0101 */ 0102 QMenu *contextMenu(); 0103 0104 /** 0105 * Returns the context menu associated with this menu 0106 */ 0107 const QMenu *contextMenu() const; 0108 0109 /** 0110 * Hides the context menu if shown 0111 */ 0112 void hideContextMenu(); 0113 0114 /** 0115 * Returns the KMenu associated with the current context menu 0116 */ 0117 static KMenu *contextMenuFocus(); 0118 0119 /** 0120 * returns the QAction associated with the current context menu 0121 */ 0122 static QAction *contextMenuFocusAction(); 0123 0124 /** 0125 * Return the state of the mouse buttons when the last menuitem was activated. 0126 */ 0127 Qt::MouseButtons mouseButtons() const; 0128 0129 /** 0130 * Return the state of the keyboard modifiers when the last menuitem was activated. 0131 */ 0132 Qt::KeyboardModifiers keyboardModifiers() const; 0133 0134 Q_SIGNALS: 0135 /** 0136 * connect to this signal to be notified when a context menu is about to be shown 0137 * @param menu The menu that the context menu is about to be shown for 0138 * @param menuAction The action that the context menu is currently on 0139 * @param ctxMenu The context menu itself 0140 */ 0141 void aboutToShowContextMenu(KMenu *menu, QAction *menuAction, QMenu *ctxMenu); 0142 0143 protected: 0144 void closeEvent(QCloseEvent *) override; 0145 void keyPressEvent(QKeyEvent *e) override; 0146 void mouseReleaseEvent(QMouseEvent *e) override; 0147 void mousePressEvent(QMouseEvent *e) override; 0148 bool focusNextPrevChild(bool next) override; 0149 void contextMenuEvent(QContextMenuEvent *e) override; 0150 void hideEvent(QHideEvent *) override; 0151 0152 private: 0153 QString underlineText(const QString &text, uint length); 0154 class KMenuPrivate; 0155 KMenuPrivate *const d; 0156 0157 Q_PRIVATE_SLOT(d, void resetKeyboardVars(bool b = false)) 0158 Q_PRIVATE_SLOT(d, void actionHovered(QAction *)) 0159 Q_PRIVATE_SLOT(d, void showCtxMenu(const QPoint &)) 0160 0161 }; 0162 0163 #endif