1/* This file is part of the KDE libraries
2 Copyright (C) 1997 Nicolas Hadacek <hadacek@kde.org>
3 Copyright (C) 2001,2001 Ellis Whitehead <ellis@kde.org>
4 Copyright (C) 2006 Hamish Rodda <rodda@kde.org>
5 Copyright (C) 2007 Roberto Raggi <roberto@kdevelop.org>
6 Copyright (C) 2007 Andreas Hartmetz <ahartmetz@gmail.com>
7 Copyright (C) 2008 Michael Jansen <kde@michael-jansen.biz>
8
9 This library is free software; you can redistribute it and/or
10 modify it under the terms of the GNU Library General Public
11 License as published by the Free Software Foundation; either
12 version 2 of the License, or (at your option) any later version.
13
14 This library is distributed in the hope that it will be useful,
15 but WITHOUT ANY WARRANTY; without even the implied warranty of
16 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
17 Library General Public License for more details.
18
19 You should have received a copy of the GNU Library General Public License
20 along with this library; see the file COPYING.LIB. If not, write to
21 the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
22 Boston, MA 02110-1301, USA.
23*/
24
25#ifndef KSHORTCUTSEDITOR_H
26#define KSHORTCUTSEDITOR_H
27
28#include <QtGui/QWidget>
29#include "kgesture.h"
30
31class KActionCollection;
32class KConfig;
33class KConfigBase;
34class KConfigGroup;
35class KGlobalAccel;
36class KShortcut;
37class KShortcutsEditorPrivate;
38
39// KShortcutsEditor expects that the list of existing shortcuts is already
40// free of conflicts. If it is not, nothing will crash, but your users
41// won't like the resulting behavior.
42
43
44/**
45 * @short Widget for configuration of KAccel and KGlobalAccel.
46 *
47 * Configure dictionaries of key/action associations for KActions,
48 * including global shortcuts.
49 *
50 * The class takes care of all aspects of configuration, including
51 * handling key conflicts internally. Connect to the allDefault()
52 * slot if you want to set all configurable shortcuts to their
53 * default values.
54 *
55 * @see KShortcutsDialog
56 * @author Nicolas Hadacek <hadacek@via.ecp.fr>
57 * @author Hamish Rodda <rodda@kde.org> (KDE 4 porting)
58 * @author Michael Jansen <kde@michael-jansen.biz>
59 */
60class KDEUI_EXPORT KShortcutsEditor : public QWidget
61{
62 Q_OBJECT
63
64public:
65 enum ActionType {
66 /// Actions which are triggered by any keypress in a widget which has the action added to it
67 WidgetAction = Qt::WidgetShortcut /*0*/,
68 /// Actions which are triggered by any keypress in a window which has the action added to it or its child widget(s)
69 WindowAction = Qt::WindowShortcut /*1*/,
70 /// Actions which are triggered by any keypress in the application
71 ApplicationAction = Qt::ApplicationShortcut /*2*/,
72 /// Actions which are triggered by any keypress in the windowing system
73 GlobalAction = 4,
74 /// All actions
75 AllActions = 0xffffffff
76 };
77 Q_DECLARE_FLAGS(ActionTypes, ActionType)
78
79 enum LetterShortcuts {
80 /// Shortcuts without a modifier are not allowed,
81 /// so 'A' would not be valid, whereas 'Ctrl+A' would be.
82 /// This only applies to printable characters, however.
83 /// 'F1', 'Insert' etc. could still be used.
84 LetterShortcutsDisallowed = 0,
85 /// Letter shortcuts are allowed
86 LetterShortcutsAllowed
87 };
88
89 /**
90 * Constructor.
91 *
92 * @param collection the KActionCollection to configure
93 * @param parent parent widget
94 * @param actionTypes types of actions to display in this widget.
95 * @param allowLetterShortcuts set to LetterShortcutsDisallowed if unmodified alphanumeric
96 * keys ('A', '1', etc.) are not permissible shortcuts.
97 */
98 KShortcutsEditor(KActionCollection *collection, QWidget *parent, ActionTypes actionTypes = AllActions, LetterShortcuts allowLetterShortcuts = LetterShortcutsAllowed);
99
100 /**
101 * \overload
102 *
103 * Creates a key chooser without a starting action collection.
104 *
105 * @param parent parent widget
106 * @param actionTypes types of actions to display in this widget.
107 * @param allowLetterShortcuts set to LetterShortcutsDisallowed if unmodified alphanumeric
108 * keys ('A', '1', etc.) are not permissible shortcuts.
109 */
110 explicit KShortcutsEditor( QWidget* parent, ActionTypes actionTypes = AllActions, LetterShortcuts allowLetterShortcuts = LetterShortcutsAllowed );
111
112 /// Destructor
113 virtual ~KShortcutsEditor();
114
115 /**
116 * Are the unsaved changes?
117 */
118 bool isModified() const;
119
120 /**
121 * Removes all action collections from the editor
122 */
123 void clearCollections();
124
125 /**
126 * Insert an action collection, i.e. add all its actions to the ones
127 * already associated with the KShortcutsEditor object.
128 * @param title subtree title of this collection of shortcut.
129 */
130 void addCollection(KActionCollection *, const QString &title = QString());
131
132
133 /**
134 * Undo all change made since the last commit().
135 */
136 void undoChanges();
137
138 /**
139 * Save the changes.
140 *
141 * Before saving the changes are committed. This saves the actions to disk.
142 * Any KActionCollection objects with the xmlFile() value set will be
143 * written to an XML file. All other will be written to the application's
144 * rc file.
145 */
146 void save();
147
148 /**
149 * Commit the changes without saving.
150 *
151 * This commits the changes without saving.
152 *
153 * @since 4.2
154 */
155 void commit();
156
157
158 /**
159 * Removes all configured shortcuts.
160 */
161 void clearConfiguration();
162
163 /**
164 * Write the current settings to the \p config object.
165 *
166 * This does not initialize the \p config object. It adds the
167 * configuration.
168 *
169 * @note this will not save the global configuration! globalaccel holds
170 * that part of the configuration.
171 * @see writeGlobalConfig()
172 *
173 * @param config Config object to save to or, or null to use the
174 * applications config object
175 *
176 */
177 void writeConfiguration( KConfigGroup* config = 0 ) const;
178
179 /**
180 * Export the current setting to configuration @p config.
181 *
182 * This initializes the configuration object. This will export the global
183 * configuration too.
184 *
185 * @param config Config object
186 */
187#ifndef KDE_NO_DEPRECATED
188 KDE_DEPRECATED void exportConfiguration( KConfig *config) const;
189#endif
190 void exportConfiguration( KConfigBase *config) const;
191
192 /**
193 * Import the settings from configuration @p config.
194 *
195 * This will remove all current setting before importing. All shortcuts
196 * are set to KShortcut() prior to importing from @p config!
197 *
198 * @param config Config object
199 */
200#ifndef KDE_NO_DEPRECATED
201 KDE_DEPRECATED void importConfiguration( KConfig *config);
202#endif
203 void importConfiguration( KConfigBase *config);
204
205
206Q_SIGNALS:
207 /**
208 * Emitted when an action's shortcut has been changed.
209 **/
210 void keyChange();
211
212public Q_SLOTS:
213 /**
214 * Resize columns to width required
215 */
216 void resizeColumns();
217
218 /**
219 * Set all shortcuts to their default values (bindings).
220 **/
221 void allDefault();
222
223 /**
224 * Opens a printing dialog to print all the shortcuts
225 */
226 void printShortcuts() const;
227
228private:
229 Q_PRIVATE_SLOT(d, void capturedShortcut(QVariant, const QModelIndex &))
230
231private:
232 friend class KShortcutsDialog;
233 friend class KShortcutsEditorPrivate;
234 KShortcutsEditorPrivate *const d;
235 Q_DISABLE_COPY(KShortcutsEditor)
236};
237
238Q_DECLARE_OPERATORS_FOR_FLAGS(KShortcutsEditor::ActionTypes)
239
240#endif // KSHORTCUTSEDITOR_H
241