kshortcutsdialog.h

/*
    This file is part of the KDE libraries
    SPDX-FileCopyrightText: 1997 Nicolas Hadacek <hadacek@kde.org>
    SPDX-FileCopyrightText: 2001, 2001 Ellis Whitehead <ellis@kde.org>
    SPDX-FileCopyrightText: 2006 Hamish Rodda <rodda@kde.org>
    SPDX-FileCopyrightText: 2007 Roberto Raggi <roberto@kdevelop.org>
    SPDX-FileCopyrightText: 2007 Andreas Hartmetz <ahartmetz@gmail.com>
    SPDX-FileCopyrightText: 2008 Michael Jansen <kde@michael-jansen.biz>
 
    SPDX-License-Identifier: LGPL-2.0-or-later
*/
 
#ifndef KSHORTCUTSDIALOG_H
#define KSHORTCUTSDIALOG_H
 
#include <kxmlgui_export.h>
 
#include <QDialog>
#include <memory>
 
#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 <hadacek@via.ecp.fr>
 * @author Hamish Rodda <rodda@kde.org> (KDE 4 porting)
 * @author Michael Jansen <kde@michael-jansen.biz>
 */
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<KActionCollection *> 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<class KShortcutsDialogPrivate> const d;
 
    Q_DISABLE_COPY(KShortcutsDialog)
};
 
#endif // KSHORTCUTSDIALOG_H