KGlobalAccel

kglobalaccel.h
1 /*
2  This file is part of the KDE libraries
3  SPDX-FileCopyrightText: 2001, 2002 Ellis Whitehead <[email protected]>
4  SPDX-FileCopyrightText: 2006 Hamish Rodda <[email protected]>
5  SPDX-FileCopyrightText: 2007 Andreas Hartmetz <[email protected]>
6 
7  SPDX-License-Identifier: LGPL-2.0-or-later
8 */
9 
10 #ifndef _KGLOBALACCEL_H_
11 #define _KGLOBALACCEL_H_
12 
13 #include "kglobalshortcutinfo.h"
14 #include <kglobalaccel_export.h>
15 
16 #include <QKeySequence>
17 #include <QList>
18 #include <QObject>
19 
20 class QAction;
21 class OrgKdeKglobalaccelComponentInterface;
22 
23 /**
24  * @short Configurable global shortcut support
25  *
26  * KGlobalAccel allows you to have global accelerators that are independent of
27  * the focused window. Unlike regular shortcuts, the application's window does not need focus
28  * for them to be activated.
29  *
30  * @see KKeyChooser
31  * @see KKeyDialog
32  */
33 class KGLOBALACCEL_EXPORT KGlobalAccel : public QObject
34 {
35  Q_OBJECT
36 
37 public:
38  /**
39  * An enum about global shortcut setter semantics
40  */
42  /// Look up the action in global settings (using its main component's name and text())
43  /// and set the shortcut as saved there.
44  /// @see setGlobalShortcut()
45  Autoloading = 0x0,
46  /// Prevent autoloading of saved global shortcut for action
47  NoAutoloading = 0x4,
48  };
49 
50  /**
51  * Index for actionId QStringLists
52  */
54  ComponentUnique = 0, //!< Components Unique Name (ID)
55  ActionUnique = 1, //!< Actions Unique Name(ID)
56  ComponentFriendly = 2, //!< Components Friendly Translated Name
57  ActionFriendly = 3, //!< Actions Friendly Translated Name
58  };
59 
60  /**
61  * Returns (and creates if necessary) the singleton instance
62  */
63  static KGlobalAccel *self();
64 
65  /**
66  * Take away the given shortcut from the named action it belongs to.
67  * This applies to all actions with global shortcuts in any KDE application.
68  *
69  * @see promptStealShortcutSystemwide()
70  */
71  static void stealShortcutSystemwide(const QKeySequence &seq);
72 
73  /**
74  * Set global shortcut context.
75  *
76  * A global shortcut context allows an application to have different sets
77  * of global shortcuts and to switch between them. This is used by
78  * plasma to switch the active global shortcuts when switching between
79  * activities.
80  *
81  * @param context the name of the context.
82  *
83  * @since 4.2
84  */
85  static void activateGlobalShortcutContext(const QString &contextUnique, const QString &contextFriendly, const QString &programName);
86 
87  /**
88  * Clean the shortcuts for component @a componentUnique.
89  *
90  * If the component is not active all global shortcut registrations are
91  * purged and the component is removed completely.
92  *
93  * If the component is active all global shortcut registrations not in use
94  * will be purged. If there is no shortcut registration left the component
95  * is purged too.
96  *
97  * If a purged component or shortcut is activated the next time it will
98  * reregister itself. All you probably will lose on wrong usage are the
99  * user's set shortcuts.
100  *
101  * If you make sure your component is running and all global shortcuts it
102  * has are active this function can be used to clean up the registry.
103  *
104  * Handle with care!
105  *
106  * If the method return @c true at least one shortcut was purged so handle
107  * all previously acquired information with care.
108  */
109  static bool cleanComponent(const QString &componentUnique);
110 
111  /**
112  * Check if @a component is active.
113  *
114  * @param componentUnique the components unique identifier
115  * @return @c true if active, @false if not
116  */
117  static bool isComponentActive(const QString &componentName);
118 
119  /**
120  * Returns a list of global shortcuts registered for the shortcut @seq.
121  *
122  * If the list contains more that one entry it means the component
123  * that registered the shortcuts uses global shortcut contexts. All
124  * returned shortcuts belong to the same component.
125  *
126  * @since 4.2
127  */
128  static QList<KGlobalShortcutInfo> getGlobalShortcutsByKey(const QKeySequence &seq);
129 
130  /**
131  * Check if the shortcut @seq is available for the @p component. The
132  * component is only of interest if the current application uses global shortcut
133  * contexts. In that case a global shortcut by @p component in an inactive
134  * global shortcut contexts does not block the @p seq for us.
135  *
136  * @since 4.2
137  */
138  static bool isGlobalShortcutAvailable(const QKeySequence &seq, const QString &component = QString());
139 
140  /**
141  * Show a messagebox to inform the user that a global shortcut is already occupied,
142  * and ask to take it away from its current action(s). This is GUI only, so nothing will
143  * be actually changed.
144  *
145  * @see stealShortcutSystemwide()
146  *
147  * @since 4.2
148  */
149  static bool promptStealShortcutSystemwide(QWidget *parent, const QList<KGlobalShortcutInfo> &shortcuts, const QKeySequence &seq);
150 
151  /**
152  * Assign a default global shortcut for a given QAction.
153  * For more information about global shortcuts @see setShortcut
154  * Upon shortcut change the globalShortcutChanged will be triggered so other applications get notified
155  *
156  * @sa globalShortcutChanged
157  *
158  * @since 5.0
159  */
160  bool setDefaultShortcut(QAction *action, const QList<QKeySequence> &shortcut, GlobalShortcutLoading loadFlag = Autoloading);
161 
162  /**
163  * Assign a global shortcut for the given action. Global shortcuts
164  * allow an action to respond to key shortcuts independently of the focused window,
165  * i.e. the action will trigger if the keys were pressed no matter where in the X session.
166  *
167  * The action must have a per main component unique
168  * action->objectName() to enable cross-application bookkeeping. If the action->objectName() is empty this method will
169  * do nothing and will return false.
170  *
171  * It is mandatory that the action->objectName() doesn't change once the shortcut has been successfully registered.
172  *
173  * \note KActionCollection::insert(name, action) will set action's objectName to name so you often
174  * don't have to set an objectName explicitly.
175  *
176  * When an action, identified by main component name and objectName(), is assigned
177  * a global shortcut for the first time on a KDE installation the assignment will
178  * be saved. The shortcut will then be restored every time setGlobalShortcut() is
179  * called with @p loading == Autoloading.
180  *
181  * If you actually want to change the global shortcut you have to set
182  * @p loading to NoAutoloading. The new shortcut will be automatically saved again.
183  *
184  * @param action the action for which the shortcut will be assigned
185  * @param shortcut global shortcut(s) to assign. Will be ignored unless @p loading is set to NoAutoloading or this is the first time ever you call this
186  * method (see above).
187  * @param loadFlag if Autoloading, assign the global shortcut this action has previously had if any.
188  * That way user preferences and changes made to avoid clashes will be conserved.
189  * if NoAutoloading the given shortcut will be assigned without looking up old values.
190  * You should only do this if the user wants to change the shortcut or if you have
191  * another very good reason. Key combinations that clash with other shortcuts will be
192  * dropped.
193  *
194  * \note the default shortcut will never be influenced by autoloading - it will be set as given.
195  * @sa shortcut()
196  * @sa globalShortcutChanged
197  * @since 5.0
198  */
199  bool setShortcut(QAction *action, const QList<QKeySequence> &shortcut, GlobalShortcutLoading loadFlag = Autoloading);
200 
201  /**
202  * Convenient method to set both active and default shortcut.
203  *
204  * If more control for loading the shortcuts is needed use the variants offering more control.
205  *
206  * @sa setShortcut
207  * @sa setDefaultShortcut
208  * @since 5.0
209  **/
210  static bool setGlobalShortcut(QAction *action, const QList<QKeySequence> &shortcut);
211 
212  /**
213  * Convenient method to set both active and default shortcut.
214  *
215  * This method is suited for the case that only one shortcut is to be configured.
216  *
217  * If more control for loading the shortcuts is needed use the variants offering more control.
218  *
219  * @sa setShortcut
220  * @sa setDefaultShortcut
221  * @since 5.0
222  **/
223  static bool setGlobalShortcut(QAction *action, const QKeySequence &shortcut);
224 
225  /**
226  * Get the global default shortcut for this action, if one exists. Global shortcuts
227  * allow your actions to respond to accellerators independently of the focused window.
228  * Unlike regular shortcuts, the application's window does not need focus
229  * for them to be activated.
230  *
231  * @sa setDefaultShortcut()
232  * @since 5.0
233  */
234  QList<QKeySequence> defaultShortcut(const QAction *action) const;
235 
236  /**
237  * Get the global shortcut for this action, if one exists. Global shortcuts
238  * allow your actions to respond to accellerators independently of the focused window.
239  * Unlike regular shortcuts, the application's window does not need focus
240  * for them to be activated.
241  *
242  * @note that this method only works together with setShortcut() because the action pointer
243  * is used to retrieve the result. If you would like to retrieve the shortcut as stored
244  * in the global settings, use the globalShortcut(componentName, actionId) instead.
245  *
246  * @sa setShortcut()
247  * @since 5.0
248  */
249  QList<QKeySequence> shortcut(const QAction *action) const;
250 
251  /**
252  * Retrieves the shortcut as defined in global settings by
253  * componentName (e.g. "kwin") and actionId (e.g. "Kill Window").
254  *
255  * @since 5.10
256  */
257  QList<QKeySequence> globalShortcut(const QString &componentName, const QString &actionId) const;
258 
259  /**
260  * Unregister and remove all defined global shortcuts for the given action.
261  *
262  * @since 5.0
263  */
264  void removeAllShortcuts(QAction *action);
265 
266  /**
267  * Returns true if a shortcut or a default shortcut has been registered for the given action
268  *
269  * @since 5.0
270  */
271  bool hasShortcut(const QAction *action) const;
272 
273 #if KGLOBALACCEL_ENABLE_DEPRECATED_SINCE(4, 4)
274  /**
275  * No effect.
276  *
277  * @deprecated Since 4.4.
278  */
279  KGLOBALACCEL_DEPRECATED_VERSION(4, 4, "Property no longer used")
280  bool isEnabled() const;
281 #endif
282 
283 #if KGLOBALACCEL_ENABLE_DEPRECATED_SINCE(4, 4)
284  /**
285  * No effect.
286  *
287  * @deprecated Since 4.4.
288  */
289  KGLOBALACCEL_DEPRECATED_VERSION(4, 4, "Property no longer used")
290  void setEnabled(bool enabled);
291 #endif
292 
293 #if KGLOBALACCEL_ENABLE_DEPRECATED_SINCE(4, 2)
294  /**
295  * Return the unique and common names of all main components that have global shortcuts.
296  * The action strings of the returned actionId stringlists will be empty.
297  *
298  * @deprecated Since 4.2. Do not use.
299  */
300  KGLOBALACCEL_DEPRECATED_VERSION(4, 2, "Do not use")
301  QList<QStringList> allMainComponents();
302 #endif
303 
304 #if KGLOBALACCEL_ENABLE_DEPRECATED_SINCE(4, 2)
305  /**
306  * @deprecated Since 4.2. Do not use
307  */
308  KGLOBALACCEL_DEPRECATED_VERSION(4, 2, "Do not use")
309  QList<QStringList> allActionsForComponent(const QStringList &actionId);
310 #endif
311 
312 #if KGLOBALACCEL_ENABLE_DEPRECATED_SINCE(4, 2)
313  /**
314  * @deprecated Since 4.2, use KGlobalAccel::getGlobalShortcutsByKey(const QKeySequence &)
315  */
316  KGLOBALACCEL_DEPRECATED_VERSION(4, 2, "Use KGlobalAccel::getGlobalShortcutsByKey(const QKeySequence &)")
317  static QStringList findActionNameSystemwide(const QKeySequence &seq);
318 #endif
319 
320 #if KGLOBALACCEL_ENABLE_DEPRECATED_SINCE(4, 2)
321  /**
322  * @deprecated Since 4.2, use KGlobalAccel::promptStealShortcutSystemwide(QWidget *, const QList<KGlobalShortcutInfo> &, const QKeySequence &)
323  */
324  KGLOBALACCEL_DEPRECATED_VERSION(4,
325  2,
326  "Use KGlobalAccel::promptStealShortcutSystemwide(QWidget *, const QList<KGlobalShortcutInfo> &, const QKeySequence &)")
327  static bool promptStealShortcutSystemwide(QWidget *parent, const QStringList &actionIdentifier, const QKeySequence &seq);
328 #endif
329 
330 #if KGLOBALACCEL_BUILD_DEPRECATED_SINCE(5, 9)
331  /**
332  * @internal
333  * Override no longer needed, left for BIC
334  */
335  bool eventFilter(QObject *watched, QEvent *event) override;
336 #endif
337 
338 Q_SIGNALS:
339  /**
340  * Emitted when the global shortcut is changed. A global shortcut is
341  * subject to be changed by the global shortcuts kcm.
342  *
343  * @param action pointer to the action for which the changed shortcut was registered
344  * @param seq the key sequence that corresponds to the changed shortcut
345  *
346  * @see setGlobalShortcut
347  * @see setDefaultShortcut
348  * @since 5.0
349  *
350  * @todo KF6: add const to the QAction parameter
351  */
352  void globalShortcutChanged(/*const would be better*/ QAction *action, const QKeySequence &seq);
353 
354 private:
355  /// Creates a new KGlobalAccel object
356  KGlobalAccel();
357 
358  /// Destructor
359  ~KGlobalAccel();
360 
361  //! get component @p componentUnique
362  OrgKdeKglobalaccelComponentInterface *getComponent(const QString &componentUnique);
363 
364  class KGlobalAccelPrivate *const d;
365 
366  Q_PRIVATE_SLOT(d, void _k_invokeAction(const QString &, const QString &, qlonglong))
367  Q_PRIVATE_SLOT(d, void _k_shortcutGotChanged(const QStringList &, const QList<int> &))
368  Q_PRIVATE_SLOT(d, void _k_serviceOwnerChanged(const QString &, const QString &, const QString &))
369 
370  friend class KGlobalAccelSingleton;
371 };
372 
373 #endif // _KGLOBALACCEL_H_
actionIdFields
Index for actionId QStringLists.
Definition: kglobalaccel.h:53
virtual bool eventFilter(QObject *watched, QEvent *event)
GlobalShortcutLoading
An enum about global shortcut setter semantics.
Definition: kglobalaccel.h:41
Configurable global shortcut support.
Definition: kglobalaccel.h:33
This file is part of the KDE documentation.
Documentation copyright © 1996-2021 The KDE developers.
Generated on Mon May 17 2021 22:53:55 by doxygen 1.8.11 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.