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 KSHORTCUTSDIALOG_H
14#define KSHORTCUTSDIALOG_H
15
16#include <kxmlgui_export.h>
17
18#include <QDialog>
19#include <memory>
20
21#include "kshortcutseditor.h"
22
23/**
24 * @class KShortcutsDialog kshortcutsdialog.h KShortcutsDialog
25 *
26 * @short Dialog for configuration of KActionCollection and KGlobalAccel.
27 *
28 * This dialog can be used to configure keyboard shortcuts associated with actions
29 * in KActionCollection and KGlobalAccel. It integrates the KShortcutsEditor widget and
30 * offers various functionalities related to keyboard shortcuts (e.g. reset all shortcuts
31 * to defaults, manage shortcuts schemes ...etc).
32 *
33 * Several static methods are supplied, which provide a convenient interface to the dialog.
34 * The most common, and most encouraged, use is with a KActionCollection.
35 *
36 * @code
37 * KShortcutsDialog::configure(actionCollection(), KShortcutsEditor::LetterShortcutsAllowed, parent);
38 *
39 * // Alternatively, since 5.84, you can use:
40 * KShortcutsDialog::showDialog(actionCollection(), KShortcutsEditor::LetterShortcutsAllowed, parent);
41 * @endcode
42 *
43 * By default this dialog is modal (since 4.3). If you don't want that, call @c setModal(false)
44 * and then the non-static configure() method to show the dialog.
45 *
46 * If you need to run some extra code when the dialog is closed, connect to the signals
47 * emitted by @c QDialog (accepted(), rejected(), finished() ...etc.). However, note
48 * that if that extra code depends on the changed settings having already been saved,
49 * connect to the @c saved() signal instead to be on the safe side (if you connect to
50 * e.g. @c QDialog::accepted() your function might be called before the changes have
51 * actually been saved).
52 *
53 * @note Starting from 5.95, if there are no Global shortcuts in any of the action
54 * collections shown in the dialog, the relevant columns ("Global" and "Global Alternate")
55 * will be hidden.
56 *
57 * Example:
58 * @code
59 * // Create the dialog; alternatively you can use the other constructor if e.g.
60 * // you need to only show certain action types, or disallow single letter shortcuts
61 * KShortcutsDialog *dlg = new KShortcutsDialog(parent);
62 *
63 * // Set the Qt::WA_DeleteOnClose attribute, so that the dialog is automatically
64 * // deleted after it's closed
65 * dlg->setAttribute(Qt::WA_DeleteOnClose);
66 *
67 * // Add an action collection (otherwise the dialog would be empty)
68 * dlg->addCollection(actionCollection());
69 *
70 * // Run some extra code after the settings are saved
71 * connect(dlg, &KShortcutsDialog::saved, this, &ClassFoo::doExtraStuff);
72 *
73 * // Called with "true" so that the changes are saved if the dialog is accepted,
74 * // see the configure(bool) method for more details
75 * dlg->configure(true);
76 * @endcode
77 *
78 * @image html kshortcutsdialog.png "KShortcutsDialog"
79 *
80 * @author Nicolas Hadacek <hadacek@via.ecp.fr>
81 * @author Hamish Rodda <rodda@kde.org> (KDE 4 porting)
82 * @author Michael Jansen <kde@michael-jansen.biz>
83 */
84class KXMLGUI_EXPORT KShortcutsDialog : public QDialog
85{
86 Q_OBJECT
87
88public:
89 /**
90 * Constructs a KShortcutsDialog as a child of @p parent.
91 *
92 * @param actionTypes sets the action types to be shown in the dialog,
93 * this is an OR'ed combination of @c KShortcutsEditor::ActionTypes;
94 * the default is @c KShortcutsEditor::AllActions
95 * @param allowLetterShortcuts set to false if unmodified alphanumeric
96 * keys ('A', '1', etc.) are not permissible shortcuts; @see @c KShortcutsEditor::LetterShortcuts
97 * @param parent parent widget of the dialog, if not @c nullptr will be
98 * used by the window manager to place the dialog relative to it
99 */
100 explicit KShortcutsDialog(KShortcutsEditor::ActionTypes actionTypes = KShortcutsEditor::AllActions,
101 KShortcutsEditor::LetterShortcuts allowLetterShortcuts = KShortcutsEditor::LetterShortcutsAllowed,
102 QWidget *parent = nullptr);
103 /**
104 * Constructs a KShortcutsDialog as a child of @p parent, with the default settings
105 * (@ref KShortcutsEditor::AllActions and @ref KShortcutsEditor::LetterShortcutsAllowed).
106 *
107 * Typically a @ref KActionCollection is added by using @ref addCollection().
108 *
109 * @param parent the parent widget of the dialog, if not @c nullptr will be
110 * used by the window manager to place the dialog relative to it
111 *
112 * @since 5.85
113 */
114 explicit KShortcutsDialog(QWidget *parent);
115
116 /**
117 * Destructor. Deletes all resources used by a KShortcutsDialog object.
118 */
119 ~KShortcutsDialog() override;
120
121 /**
122 * Add all actions of the collection to the ones displayed and configured
123 * by the dialog.
124 *
125 * @param title the title associated with the collection (if null, the
126 * KAboutData::progName() of the collection's componentData is used)
127 */
128 void addCollection(KActionCollection *collection, const QString &title = {});
129
130 /**
131 * @return the list of action collections that are available for configuration in the dialog.
132 */
133 QList<KActionCollection *> actionCollections() const;
134
135 /**
136 * Run the dialog and call writeSettings() on the action collections
137 * that were added if @p saveSettings is true.
138 *
139 * If the dialog is modal this method will use @c QDialog::exec() to open the dialog,
140 * otherwise it will use @c QDialog::show().
141 */
142 // TODO KF6 remove this method, see configure() static method for more details
143 bool configure(bool saveSettings = true);
144
145 /** @see QWidget::sizeHint() */
146 QSize sizeHint() const override;
147
148 /**
149 * This static method shows a modal dialog that can be used to configure
150 * the shortcuts associated with each action in @p collection. The new
151 * shortcut settings will be saved and applied if the dialog is accepted.
152 *
153 * The dialog is opened by using @c QDialog::show(), and it will be deleted
154 * automatically when it's closed.
155 *
156 * Example:
157 * @code
158 * // Typical usage is with a KActionCollection:
159 * KShortcutsDialog::showDialog(actionCollection(), KShortcutsEditor::LetterShortcutsAllowed, parent);
160 * @endcode
161 *
162 * @param collection the KActionCollection to configure
163 * @param allowLetterShortcuts set to @c KShortcutsEditor::LetterShortcutsDisallowed
164 * if unmodified alphanumeric keys ('A', '1', etc.) are not permissible shortcuts
165 * @param parent the parent widget of the dialog, if not @c nullptr it will be used
166 * by the window manager to place the dialog relative to it
167 *
168 * @since 5.84
169 */
170 static void showDialog(KActionCollection *collection,
171 KShortcutsEditor::LetterShortcuts allowLetterShortcuts = KShortcutsEditor::LetterShortcutsAllowed,
172 QWidget *parent = nullptr);
173
174 /**
175 * Imports a shortcuts set up from @p path
176 *
177 * @since 5.15
178 */
179 void importConfiguration(const QString &path);
180
181 /**
182 * Exports a shortcuts set up from @p path
183 *
184 * @since 5.15
185 */
186 void exportConfiguration(const QString &path) const;
187
188 /**
189 * Reloads the list of schemes in the "Manage Schemes" section
190 *
191 * This is useful if the available scheme files changed for some reason
192 * eg. because KNewStuff was used
193 *
194 * @since 5.97
195 */
196 void refreshSchemes();
197
198 /**
199 * This adds a @c QAction to the "More Actions" menu
200 *
201 * This is useful to add for example an action to download more
202 * keyboard schemes via KNewStuff
203 *
204 * @since 5.97
205 */
206 void addActionToSchemesMoreButton(QAction *action);
207
208public Q_SLOTS:
209 /**
210 * @reimp
211 */
212 void accept() override;
213
214Q_SIGNALS:
215 /**
216 * Emitted after the dialog is accepted (by clicking the OK button) and settings are saved.
217 * Connect to this signal if you need to run some extra code after the settings are saved.
218 */
219 void saved();
220
221private:
222 friend class KShortcutsDialogPrivate;
223 std::unique_ptr<class KShortcutsDialogPrivate> const d;
224
225 Q_DISABLE_COPY(KShortcutsDialog)
226};
227
228#endif // KSHORTCUTSDIALOG_H
229

source code of kxmlgui/src/kshortcutsdialog.h