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 | |
31 | class QWidget; |
32 | class KShortcut; |
33 | class KComponentData; |
34 | class 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 | */ |
46 | class KDEUI_EXPORT KGlobalAccel : public QObject |
47 | { |
48 | Q_OBJECT |
49 | |
50 | public: |
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 | |
239 | private: |
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 | |