/* This file is part of the KDE libraries SPDX-FileCopyrightText: 1997 Nicolas Hadacek SPDX-FileCopyrightText: 2001, 2001 Ellis Whitehead SPDX-FileCopyrightText: 2006 Hamish Rodda SPDX-FileCopyrightText: 2007 Roberto Raggi SPDX-FileCopyrightText: 2007 Andreas Hartmetz SPDX-FileCopyrightText: 2008 Michael Jansen SPDX-License-Identifier: LGPL-2.0-or-later */ #ifndef KSHORTCUTSDIALOG_H #define KSHORTCUTSDIALOG_H #include #include #include #include "kshortcutseditor.h" /** * @class KShortcutsDialog kshortcutsdialog.h KShortcutsDialog * * @short Dialog for configuration of KActionCollection and KGlobalAccel. * * This dialog can be used to configure keyboard shortcuts associated with actions * in KActionCollection and KGlobalAccel. It integrates the KShortcutsEditor widget and * offers various functionalities related to keyboard shortcuts (e.g. reset all shortcuts * to defaults, manage shortcuts schemes ...etc). * * Several static methods are supplied, which provide a convenient interface to the dialog. * The most common, and most encouraged, use is with a KActionCollection. * * @code * KShortcutsDialog::configure(actionCollection(), KShortcutsEditor::LetterShortcutsAllowed, parent); * * // Alternatively, since 5.84, you can use: * KShortcutsDialog::showDialog(actionCollection(), KShortcutsEditor::LetterShortcutsAllowed, parent); * @endcode * * By default this dialog is modal (since 4.3). If you don't want that, call @c setModal(false) * and then the non-static configure() method to show the dialog. * * If you need to run some extra code when the dialog is closed, connect to the signals * emitted by @c QDialog (accepted(), rejected(), finished() ...etc.). However, note * that if that extra code depends on the changed settings having already been saved, * connect to the @c saved() signal instead to be on the safe side (if you connect to * e.g. @c QDialog::accepted() your function might be called before the changes have * actually been saved). * * @note Starting from 5.95, if there are no Global shortcuts in any of the action * collections shown in the dialog, the relevant columns ("Global" and "Global Alternate") * will be hidden. * * Example: * @code * // Create the dialog; alternatively you can use the other constructor if e.g. * // you need to only show certain action types, or disallow single letter shortcuts * KShortcutsDialog *dlg = new KShortcutsDialog(parent); * * // Set the Qt::WA_DeleteOnClose attribute, so that the dialog is automatically * // deleted after it's closed * dlg->setAttribute(Qt::WA_DeleteOnClose); * * // Add an action collection (otherwise the dialog would be empty) * dlg->addCollection(actionCollection()); * * // Run some extra code after the settings are saved * connect(dlg, &KShortcutsDialog::saved, this, &ClassFoo::doExtraStuff); * * // Called with "true" so that the changes are saved if the dialog is accepted, * // see the configure(bool) method for more details * dlg->configure(true); * @endcode * * @image html kshortcutsdialog.png "KShortcutsDialog" * * @author Nicolas Hadacek * @author Hamish Rodda (KDE 4 porting) * @author Michael Jansen */ class KXMLGUI_EXPORT KShortcutsDialog : public QDialog { Q_OBJECT public: /** * Constructs a KShortcutsDialog as a child of @p parent. * * @param actionTypes sets the action types to be shown in the dialog, * this is an OR'ed combination of @c KShortcutsEditor::ActionTypes; * the default is @c KShortcutsEditor::AllActions * @param allowLetterShortcuts set to false if unmodified alphanumeric * keys ('A', '1', etc.) are not permissible shortcuts; @see @c KShortcutsEditor::LetterShortcuts * @param parent parent widget of the dialog, if not @c nullptr will be * used by the window manager to place the dialog relative to it */ explicit KShortcutsDialog(KShortcutsEditor::ActionTypes actionTypes = KShortcutsEditor::AllActions, KShortcutsEditor::LetterShortcuts allowLetterShortcuts = KShortcutsEditor::LetterShortcutsAllowed, QWidget *parent = nullptr); /** * Constructs a KShortcutsDialog as a child of @p parent, with the default settings * (@ref KShortcutsEditor::AllActions and @ref KShortcutsEditor::LetterShortcutsAllowed). * * Typically a @ref KActionCollection is added by using @ref addCollection(). * * @param parent the parent widget of the dialog, if not @c nullptr will be * used by the window manager to place the dialog relative to it * * @since 5.85 */ explicit KShortcutsDialog(QWidget *parent); /** * Destructor. Deletes all resources used by a KShortcutsDialog object. */ ~KShortcutsDialog() override; /** * Add all actions of the collection to the ones displayed and configured * by the dialog. * * @param title the title associated with the collection (if null, the * KAboutData::progName() of the collection's componentData is used) */ void addCollection(KActionCollection *collection, const QString &title = {}); /** * @return the list of action collections that are available for configuration in the dialog. */ QList actionCollections() const; /** * Run the dialog and call writeSettings() on the action collections * that were added if @p saveSettings is true. * * If the dialog is modal this method will use @c QDialog::exec() to open the dialog, * otherwise it will use @c QDialog::show(). */ // TODO KF6 remove this method, see configure() static method for more details bool configure(bool saveSettings = true); /** @see QWidget::sizeHint() */ QSize sizeHint() const override; /** * This static method shows a modal dialog that can be used to configure * the shortcuts associated with each action in @p collection. The new * shortcut settings will be saved and applied if the dialog is accepted. * * The dialog is opened by using @c QDialog::show(), and it will be deleted * automatically when it's closed. * * Example: * @code * // Typical usage is with a KActionCollection: * KShortcutsDialog::showDialog(actionCollection(), KShortcutsEditor::LetterShortcutsAllowed, parent); * @endcode * * @param collection the KActionCollection to configure * @param allowLetterShortcuts set to @c KShortcutsEditor::LetterShortcutsDisallowed * if unmodified alphanumeric keys ('A', '1', etc.) are not permissible shortcuts * @param parent the parent widget of the dialog, if not @c nullptr it will be used * by the window manager to place the dialog relative to it * * @since 5.84 */ static void showDialog(KActionCollection *collection, KShortcutsEditor::LetterShortcuts allowLetterShortcuts = KShortcutsEditor::LetterShortcutsAllowed, QWidget *parent = nullptr); /** * Imports a shortcuts set up from @p path * * @since 5.15 */ void importConfiguration(const QString &path); /** * Exports a shortcuts set up from @p path * * @since 5.15 */ void exportConfiguration(const QString &path) const; /** * Reloads the list of schemes in the "Manage Schemes" section * * This is useful if the available scheme files changed for some reason * eg. because KNewStuff was used * * @since 5.97 */ void refreshSchemes(); /** * This adds a @c QAction to the "More Actions" menu * * This is useful to add for example an action to download more * keyboard schemes via KNewStuff * * @since 5.97 */ void addActionToSchemesMoreButton(QAction *action); public Q_SLOTS: /** * @reimp */ void accept() override; Q_SIGNALS: /** * Emitted after the dialog is accepted (by clicking the OK button) and settings are saved. * Connect to this signal if you need to run some extra code after the settings are saved. */ void saved(); private: friend class KShortcutsDialogPrivate; std::unique_ptr const d; Q_DISABLE_COPY(KShortcutsDialog) }; #endif // KSHORTCUTSDIALOG_H