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