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

source code of kxmlgui/src/kshortcutseditor.h