1 /*************************************************************************** 2 qgsshortcutsmanager.h 3 --------------------- 4 begin : May 2009 5 copyright : (C) 2009 by Martin Dobias 6 email : wonder dot sk at gmail dot com 7 *************************************************************************** 8 * * 9 * This program is free software; you can redistribute it and/or modify * 10 * it under the terms of the GNU General Public License as published by * 11 * the Free Software Foundation; either version 2 of the License, or * 12 * (at your option) any later version. * 13 * * 14 ***************************************************************************/ 15 16 #ifndef QGSSHORTCUTSMANAGER_H 17 #define QGSSHORTCUTSMANAGER_H 18 19 #include <QHash> 20 #include <QList> 21 #include <QAction> 22 #include "qgis_gui.h" 23 #include "qgis_sip.h" 24 25 class QShortcut; 26 27 /** 28 * \ingroup gui 29 * \class QgsShortcutsManager 30 * \brief Shortcuts manager is a class that contains a list of QActions and QShortcuts 31 * that have been registered and their shortcuts can be changed. 32 * 33 * QgsShortcutsManager is not usually directly created, but rather accessed through 34 * QgsGui::shortcutsManager(). 35 * \since QGIS 2.16 36 */ 37 class GUI_EXPORT QgsShortcutsManager : public QObject 38 { 39 Q_OBJECT 40 41 public: 42 43 /** 44 * Constructor for QgsShortcutsManager. 45 * \param parent parent object 46 * \param settingsRoot root QgsSettings path for storing settings, e.g., "/myplugin/shortcuts". Leave 47 * as the default value to store settings alongside built in QGIS shortcuts, but care must be 48 * taken to not register actions which conflict with the built in QGIS actions. 49 */ 50 QgsShortcutsManager( QObject *parent SIP_TRANSFERTHIS = nullptr, const QString &settingsRoot = "/shortcuts/" ); 51 52 /** 53 * Automatically registers all QActions and QShortcuts which are children of the 54 * passed object. 55 * \param object parent object containing actions and shortcuts to register 56 * \param recursive set to TRUE to recursively add child actions and shortcuts 57 * \see registerAllChildActions() 58 * \see registerAllChildShortcuts() 59 */ 60 void registerAllChildren( QObject *object, bool recursive = false ); 61 62 /** 63 * Automatically registers all QActions which are children of the passed object. 64 * \param object parent object containing actions to register 65 * \param recursive set to TRUE to recursively add child actions 66 * \see registerAction() 67 * \see registerAllChildren() 68 * \see registerAllChildShortcuts() 69 */ 70 void registerAllChildActions( QObject *object, bool recursive = false ); 71 72 /** 73 * Automatically registers all QShortcuts which are children of the passed object. 74 * \param object parent object containing shortcuts to register 75 * \param recursive set to TRUE to recursively add child shortcuts 76 * \see registerShortcut() 77 * \see registerAllChildren() 78 * \see registerAllChildActions() 79 */ 80 void registerAllChildShortcuts( QObject *object, bool recursive = false ); 81 82 /** 83 * Registers an action with the manager so the shortcut can be configured in GUI. 84 * \param action action to register. The action must have a unique text string for 85 * identification. 86 * \param defaultShortcut default key sequence for action 87 * \returns TRUE if action was successfully registered 88 * \see registerShortcut() 89 * \see unregisterAction() 90 * \see registerAllChildActions() 91 */ 92 bool registerAction( QAction *action, const QString &defaultShortcut = QString() ); 93 94 /** 95 * Registers a QShortcut with the manager so the shortcut can be configured in GUI. 96 * \param shortcut QShortcut to register. The shortcut must have a unique QObject::objectName() for 97 * identification. 98 * \param defaultSequence default key sequence for shortcut 99 * \returns TRUE if shortcut was successfully registered 100 * \see registerAction() 101 * \see registerAllChildShortcuts() 102 */ 103 bool registerShortcut( QShortcut *shortcut, const QString &defaultSequence = QString() ); 104 105 /** 106 * Removes an action from the manager. 107 * \param action action to remove 108 * \returns TRUE if action was previously registered in manager and has been removed, or 109 * FALSE if action was not previously registered in manager 110 * \see registerAction() 111 * \see unregisterShortcut() 112 */ 113 bool unregisterAction( QAction *action ); 114 115 /** 116 * Removes a shortcut from the manager. 117 * \param shortcut shortcut to remove 118 * \returns TRUE if shortcut was previously registered in manager and has been removed, or 119 * FALSE if shortcut was not previously registered in manager 120 * \see registerShortcut() 121 * \see unregisterAction() 122 */ 123 bool unregisterShortcut( QShortcut *shortcut ); 124 125 /** 126 * Returns a list of all actions in the manager. 127 * \see listShortcuts() 128 * \see listAll() 129 */ 130 QList<QAction *> listActions() const; 131 132 /** 133 * Returns a list of shortcuts in the manager. 134 * \see listActions() 135 * \see listAll() 136 */ 137 QList<QShortcut *> listShortcuts() const; 138 139 /** 140 * Returns a list of both actions and shortcuts in the manager. 141 * \see listActions() 142 * \see listShortcuts() 143 */ 144 QList<QObject *> listAll() const; 145 146 /** 147 * Returns the default sequence for an object (either a QAction or QShortcut). 148 * An empty return string indicates no shortcut. 149 * \param object QAction or QShortcut to return default key sequence for 150 * \see defaultKeySequence() 151 */ 152 QString objectDefaultKeySequence( QObject *object ) const; 153 154 /** 155 * Returns the default sequence for an action. An empty return string indicates 156 * no default sequence. 157 * \param action action to return default key sequence for 158 * \see objectDefaultKeySequence() 159 */ 160 QString defaultKeySequence( QAction *action ) const; 161 162 /** 163 * Returns the default sequence for a shortcut. An empty return string indicates 164 * no default sequence. 165 * \param shortcut shortcut to return default key sequence for 166 * \see objectDefaultKeySequence() 167 */ 168 QString defaultKeySequence( QShortcut *shortcut ) const; 169 170 /** 171 * Modifies an action or shortcut's key sequence. 172 * \param name name of action or shortcut to modify. Must match the action's QAction::text() or the 173 * shortcut's QObject::objectName() 174 * \param sequence new shortcut key sequence 175 * \see setObjectKeySequence() 176 */ 177 bool setKeySequence( const QString &name, const QString &sequence ); 178 179 /** 180 * Modifies an object's (either a QAction or a QShortcut) key sequence. 181 * \param object QAction or QShortcut to modify 182 * \param sequence new shortcut key sequence 183 * \see setKeySequence() 184 */ 185 bool setObjectKeySequence( QObject *object, const QString &sequence ); 186 187 /** 188 * Modifies an action's key sequence. 189 * \param action action to modify 190 * \param sequence new shortcut key sequence 191 * \see setObjectKeySequence() 192 */ 193 bool setKeySequence( QAction *action, const QString &sequence ); 194 195 /** 196 * Modifies a shortcuts's key sequence. 197 * \param shortcut QShortcut to modify 198 * \param sequence new shortcut key sequence 199 * \see setObjectKeySequence() 200 */ 201 bool setKeySequence( QShortcut *shortcut, const QString &sequence ); 202 203 /** 204 * Returns the object (QAction or QShortcut) matching the specified key sequence, 205 * \param sequence key sequence to find 206 * \returns object with matching sequence, or NULLPTR if not found 207 * \see actionForSequence() 208 * \see shortcutForSequence() 209 */ 210 QObject *objectForSequence( const QKeySequence &sequence ) const; 211 212 /** 213 * Returns the action which is associated for a shortcut sequence, or NULLPTR if no action is associated. 214 * \param sequence shortcut key sequence 215 * \see objectForSequence() 216 * \see shortcutForSequence() 217 */ 218 QAction *actionForSequence( const QKeySequence &sequence ) const; 219 220 /** 221 * Returns the shortcut which is associated for a key sequence, or NULLPTR if no shortcut is associated. 222 * \param sequence shortcut key sequence 223 * \see objectForSequence() 224 * \see actionForSequence() 225 */ 226 QShortcut *shortcutForSequence( const QKeySequence &sequence ) const; 227 228 /** 229 * Returns an action by its name, or NULLPTR if nothing found. 230 * \param name action name. Must match QAction's text. 231 * \see shortcutByName() 232 */ 233 QAction *actionByName( const QString &name ) const; 234 235 /** 236 * Returns a shortcut by its name, or NULLPTR if nothing found 237 * \param name shortcut name. Must match QShortcut's QObject::objectName() property. 238 * \see actionByName() 239 */ 240 QShortcut *shortcutByName( const QString &name ) const; 241 242 //! Returns the root settings path used to store shortcut customization. settingsPath()243 QString settingsPath() const { return mSettingsPath; } 244 245 private slots: 246 247 void actionDestroyed(); 248 void shortcutDestroyed(); 249 250 private: 251 252 typedef QHash< QAction *, QString > ActionsHash; 253 typedef QHash< QShortcut *, QString > ShortcutsHash; 254 255 ActionsHash mActions; 256 ShortcutsHash mShortcuts; 257 QString mSettingsPath; 258 259 /** 260 * Updates the action to include the shortcut keys. Shortcut keys are 261 * included between () at the end of the action tooltop. 262 * \param action The action to append the shortcut. 263 * \param sequence The shortcut sequence. 264 */ 265 void updateActionToolTip( QAction *action, const QString &sequence ); 266 }; 267 268 // clazy:excludeall=qstring-allocations 269 270 #endif // QGSSHORTCUTSMANAGER_H 271