1/* This file is part of the KDE libraries
2 Copyright (C) 2001,2002 Ellis Whitehead <ellis@kde.org>
3 Copyright (C) 2006 Hamish Rodda <rodda@kde.org>
4 Copyright (C) 2007 Andreas Hartmetz <ahartmetz@gmail.com>
5
6 This library is free software; you can redistribute it and/or
7 modify it under the terms of the GNU Library General Public
8 License as published by the Free Software Foundation; either
9 version 2 of the License, or (at your option) any later version.
10
11 This library is distributed in the hope that it will be useful,
12 but WITHOUT ANY WARRANTY; without even the implied warranty of
13 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
14 Library General Public License for more details.
15
16 You should have received a copy of the GNU Library General Public License
17 along with this library; see the file COPYING.LIB. If not, write to
18 the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
19 Boston, MA 02110-1301, USA.
20*/
21
22#ifndef _KGLOBALACCEL_H_
23#define _KGLOBALACCEL_H_
24
25#include "kdeui_export.h"
26#include "kaction.h"
27#include "kglobalshortcutinfo.h"
28
29#include <QtCore/QObject>
30
31class QWidget;
32class KShortcut;
33class KComponentData;
34class OrgKdeKglobalaccelComponentInterface;
35
36/**
37 * @short Configurable global shortcut support
38 *
39 * KGlobalAccel allows you to have global accelerators that are independent of
40 * the focused window. Unlike regular shortcuts, the application's window does not need focus
41 * for them to be activated.
42 *
43 * @see KKeyChooser
44 * @see KKeyDialog
45 */
46class KDEUI_EXPORT KGlobalAccel : public QObject
47{
48 Q_OBJECT
49
50public:
51
52 /**
53 * Index for actionId QStringLists
54 */
55 enum actionIdFields
56 {
57 ComponentUnique = 0, //!< Components Unique Name (ID)
58 ActionUnique = 1, //!< Actions Unique Name(ID)
59 ComponentFriendly = 2, //!< Components Friendly Translated Name
60 ActionFriendly = 3 //!< Actions Friendly Translated Name
61 };
62
63 /**
64 * Returns (and creates if necessary) the singleton instance
65 */
66 static KGlobalAccel *self();
67
68 /**
69 * Take away the given shortcut from the named action it belongs to.
70 * This applies to all actions with global shortcuts in any KDE application.
71 *
72 * @see promptStealShortcutSystemwide()
73 */
74 static void stealShortcutSystemwide(const QKeySequence &seq);
75
76 /**
77 * Set global shortcut context.
78 *
79 * A global shortcut context allows an application to have different sets
80 * of global shortcuts and to switch between them. This is used by
81 * plasma to switch the active global shortcuts when switching between
82 * activities.
83 *
84 * @param component the name of the component. KComponentData::componentName
85 * @param context the name of the context.
86 *
87 * @since 4.2
88 */
89 static void activateGlobalShortcutContext(
90 const QString &contextUnique,
91 const QString &contextFriendly,
92 const KComponentData &component = KGlobal::mainComponent());
93
94 /**
95 * Clean the shortcuts for component @a componentUnique.
96 *
97 * If the component is not active all global shortcut registrations are
98 * purged and the component is removed completely.
99 *
100 * If the component is active all global shortcut registrations not in use
101 * will be purged. If there is no shortcut registration left the component
102 * is purged too.
103 *
104 * If a purged component or shortcut is activated the next time it will
105 * reregister itself. All you probably will lose on wrong usage are the
106 * user's set shortcuts.
107 *
108 * If you make sure your component is running and all global shortcuts it
109 * has are active this function can be used to clean up the registry.
110 *
111 * Handle with care!
112 *
113 * If the method return @c true at least one shortcut was purged so handle
114 * all previously acquired information with care.
115 */
116 static bool cleanComponent(const QString &componentUnique);
117
118
119 /**
120 * Check if @a component is active.
121 *
122 * @param componentUnique the components unique identifier
123 * @return @c true if active, @false if not
124 */
125 static bool isComponentActive(const QString &componentName);
126
127 /**
128 * Returns a list of global shortcuts registered for the shortcut @seq.
129 *
130 * If the list contains more that one entry it means the component
131 * that registered the shortcuts uses global shortcut contexts. All
132 * returned shortcuts belong to the same component.
133 *
134 * @since 4.2
135 */
136 static QList<KGlobalShortcutInfo> getGlobalShortcutsByKey(const QKeySequence &seq);
137
138 /**
139 * Check if the shortcut @seq is available for the @p component. The
140 * component is only of interest if the current application uses global shortcut
141 * contexts. In that case a global shortcut by @p component in an inactive
142 * global shortcut contexts does not block the @p seq for us.
143 *
144 * @since 4.2
145 */
146 static bool isGlobalShortcutAvailable(
147 const QKeySequence &seq,
148 const QString &component = QString());
149
150 /**
151 * Show a messagebox to inform the user that a global shorcut is already occupied,
152 * and ask to take it away from its current action(s). This is GUI only, so nothing will
153 * be actually changed.
154 *
155 * @see stealShortcutSystemwide()
156 *
157 * @since 4.2
158 */
159 static bool promptStealShortcutSystemwide(
160 QWidget *parent,
161 const QList<KGlobalShortcutInfo> &shortcuts,
162 const QKeySequence &seq);
163
164 /**
165 * No effect.
166 *
167 * @deprecated
168 */
169#ifndef KDE_NO_DEPRECATED
170 KDE_DEPRECATED bool isEnabled() const;
171#endif
172
173 /**
174 * No effect.
175 *
176 * @deprecated
177 */
178#ifndef KDE_NO_DEPRECATED
179 KDE_DEPRECATED void setEnabled(bool enabled);
180#endif
181
182 /**
183 * Set the KComponentData for which to manipulate shortcuts. This is for exceptional
184 * situations, when you want to modify the shortcuts of another application
185 * as if they were yours.
186 * You cannot have your own working global shortcuts in a module/application using this
187 * special functionality. All global shortcuts of KActions will essentially be proxies.
188 * Be sure to set the default global shortcuts of the proxy KActions to the same as
189 * those on the receiving end.
190 * An example use case is the KControl Module for the window manager KWin, which has
191 * no own facility for users to change its global shortcuts.
192 *
193 * @param componentData a KComponentData about the application for which you want to
194 * manipulate shortcuts.
195 *
196 * @deprecated
197 */
198#ifndef KDE_NO_DEPRECATED
199 KDE_DEPRECATED void overrideMainComponentData(const KComponentData &componentData);
200#endif
201
202 /**
203 * Return the unique and common names of all main components that have global shortcuts.
204 * The action strings of the returned actionId stringlists will be empty.
205 *
206 * @deprecated
207 */
208#ifndef KDE_NO_DEPRECATED
209 KDE_DEPRECATED QList<QStringList> allMainComponents();
210#endif
211
212 /**
213 * @see getGlobalShortcutsByComponent
214 *
215 * @deprecated
216 */
217#ifndef KDE_NO_DEPRECATED
218 KDE_DEPRECATED QList<QStringList> allActionsForComponent(const QStringList &actionId);
219#endif
220
221 /**
222 * @see getGlobalShortcutsByKey
223 *
224 * @deprecated
225 */
226#ifndef KDE_NO_DEPRECATED
227 KDE_DEPRECATED static QStringList findActionNameSystemwide(const QKeySequence &seq);
228#endif
229
230 /**
231 * @see promptStealShortcutSystemwide below
232 *
233 * @deprecated
234 */
235#ifndef KDE_NO_DEPRECATED
236 KDE_DEPRECATED static bool promptStealShortcutSystemwide(QWidget *parent, const QStringList &actionIdentifier, const QKeySequence &seq);
237#endif
238
239private:
240
241 friend class KAction;
242
243 /// Creates a new KGlobalAccel object
244 KGlobalAccel();
245
246 /// Destructor
247 ~KGlobalAccel();
248
249 //! get component @p componentUnique
250 OrgKdeKglobalaccelComponentInterface* getComponent(const QString &componentUnique);
251
252 class KGlobalAccelPrivate *const d;
253
254 Q_PRIVATE_SLOT(d, void _k_invokeAction(const QString &, const QString &, qlonglong))
255 Q_PRIVATE_SLOT(d, void _k_shortcutGotChanged(const QStringList&, const QList<int>&))
256 Q_PRIVATE_SLOT(d, void _k_serviceOwnerChanged(const QString&, const QString&, const QString&))
257};
258
259#endif // _KGLOBALACCEL_H_
260