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

source code of kxmlgui/src/kshortcutsdialog.h