1/*
2 This file is part of the KDE libraries
3 SPDX-FileCopyrightText: 1997 Nicolas Hadacek <hadacek@kde.org>
4 SPDX-FileCopyrightText: 2001, 2001 Ellis Whitehead <ellis@kde.org>
5 SPDX-FileCopyrightText: 2006 Hamish Rodda <rodda@kde.org>
6 SPDX-FileCopyrightText: 2007 Roberto Raggi <roberto@kdevelop.org>
7 SPDX-FileCopyrightText: 2007 Andreas Hartmetz <ahartmetz@gmail.com>
8 SPDX-FileCopyrightText: 2008 Michael Jansen <kde@michael-jansen.biz>
9
10 SPDX-License-Identifier: LGPL-2.0-or-later
11*/
12
13#ifndef KSHORTCUTSEDITOR_H
14#define KSHORTCUTSEDITOR_H
15
16#include <kxmlgui_export.h>
17
18#include <QWidget>
19
20class KActionCollection;
21class KConfig;
22class KConfigBase;
23class KConfigGroup;
24class KGlobalAccel;
25class KShortcutsEditorPrivate;
26
27// KShortcutsEditor expects that the list of existing shortcuts is already
28// free of conflicts. If it is not, nothing will crash, but your users
29// won't like the resulting behavior.
30
31/**
32 * @class KShortcutsEditor kshortcutseditor.h KShortcutsEditor
33 *
34 * @short Widget for configuration of KAccel and KGlobalAccel.
35 *
36 * Configure dictionaries of key/action associations for QActions,
37 * including global shortcuts.
38 *
39 * The class takes care of all aspects of configuration, including
40 * handling key conflicts internally. Connect to the allDefault()
41 * slot if you want to set all configurable shortcuts to their
42 * default values.
43 *
44 * @see KShortcutsDialog
45 * @author Nicolas Hadacek <hadacek@via.ecp.fr>
46 * @author Hamish Rodda <rodda@kde.org> (KDE 4 porting)
47 * @author Michael Jansen <kde@michael-jansen.biz>
48 */
49class KXMLGUI_EXPORT KShortcutsEditor : public QWidget
50{
51 Q_OBJECT
52 Q_PROPERTY(ActionTypes actionTypes READ actionTypes WRITE setActionTypes)
53
54public:
55 /**
56 * @see ActionTypes
57 */
58 enum ActionType {
59 /// Actions which are triggered by any keypress in a widget which has the action added to it
60 WidgetAction = Qt::WidgetShortcut /*0*/,
61 /// Actions which are triggered by any keypress in a window which has the action added to it or its child widget(s)
62 WindowAction = Qt::WindowShortcut /*1*/,
63 /// Actions which are triggered by any keypress in the application
64 ApplicationAction = Qt::ApplicationShortcut /*2*/,
65 /// Actions which are triggered by any keypress in the windowing system
66 /// @note Starting from 5.95, this flag is ignored if there are no actual Global shortcuts in any of the action collections that are added
67 GlobalAction = 4,
68 /// All actions
69 AllActions = 0xffffffff,
70 };
71 /**
72 * Stores a combination of #ActionType values.
73 */
74 Q_DECLARE_FLAGS(ActionTypes, ActionType)
75
76 enum LetterShortcuts {
77 /// Shortcuts without a modifier are not allowed,
78 /// so 'A' would not be valid, whereas 'Ctrl+A' would be.
79 /// This only applies to printable characters, however.
80 /// 'F1', 'Insert' etc. could still be used.
81 LetterShortcutsDisallowed = 0,
82 /// Letter shortcuts are allowed
83 LetterShortcutsAllowed,
84 };
85
86 /**
87 * Constructor.
88 *
89 * @param collection the KActionCollection to configure
90 * @param parent parent widget
91 * @param actionTypes types of actions to display in this widget.
92 * @param allowLetterShortcuts set to LetterShortcutsDisallowed if unmodified alphanumeric
93 * keys ('A', '1', etc.) are not permissible shortcuts.
94 */
95 KShortcutsEditor(KActionCollection *collection,
96 QWidget *parent,
97 ActionTypes actionTypes = AllActions,
98 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 ~KShortcutsEditor() override;
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 * Undo all change made since the last save().
134 *
135 * @since 5.75
136 */
137 void undo();
138
139 /**
140 * Save the changes.
141 *
142 * This saves the actions to disk.
143 * Any KActionCollection objects with the xmlFile() value set will be
144 * written to an XML file. All other will be written to the application's
145 * rc file.
146 */
147 void save();
148
149 /**
150 * Sets the types of actions to display in this widget.
151 *
152 * @param actionTypes New types of actions
153 * @since 5.0
154 */
155 void setActionTypes(ActionTypes actionTypes);
156 /**
157 *
158 * @return The types of actions currently displayed in this widget.
159 * @since 5.0
160 */
161 ActionTypes actionTypes() const;
162
163Q_SIGNALS:
164 /**
165 * Emitted when an action's shortcut has been changed.
166 **/
167 void keyChange();
168
169public Q_SLOTS:
170 /**
171 * Set all shortcuts to their default values (bindings).
172 **/
173 void allDefault();
174
175private Q_SLOTS:
176 /*
177 * Resize columns to width required
178 */
179 KXMLGUI_NO_EXPORT void resizeColumns();
180
181 /*
182 * Opens a printing dialog to print all the shortcuts
183 */
184 KXMLGUI_NO_EXPORT void printShortcuts() const;
185
186private:
187 /*
188 * Write the current settings to the \p config object.
189 *
190 * This does not initialize the \p config object. It adds the
191 * configuration.
192 *
193 * @note This will not save the global configuration! globalaccel holds
194 * that part of the configuration.
195 * @see writeGlobalConfig()
196 *
197 * @param config Config object to save to or, or null to use the
198 * applications config object
199 *
200 */
201 KXMLGUI_NO_EXPORT void writeConfiguration(KConfigGroup *config = nullptr) const;
202
203 /*
204 * Export the current setting to configuration @p config.
205 *
206 * This initializes the configuration object. This will export the global
207 * configuration too.
208 *
209 * @param config Config object
210 */
211 KXMLGUI_NO_EXPORT void exportConfiguration(KConfigBase *config) const;
212
213 /*
214 * Import the settings from configuration @p config.
215 *
216 * This will remove all current setting before importing. All shortcuts
217 * are set to QList<QKeySequence>() prior to importing from @p config!
218 *
219 * @param config Config object
220 */
221 KXMLGUI_NO_EXPORT void importConfiguration(KConfigBase *config);
222
223 friend class KShortcutsDialog;
224 friend class KShortcutsEditorPrivate;
225 std::unique_ptr<KShortcutsEditorPrivate> const d;
226 Q_DISABLE_COPY(KShortcutsEditor)
227};
228
229Q_DECLARE_OPERATORS_FOR_FLAGS(KShortcutsEditor::ActionTypes)
230
231#endif // KSHORTCUTSEDITOR_H
232

source code of kxmlgui/src/kshortcutseditor.h