File indexing completed on 2024-03-03 04:08:07

0001 /*
0002     This file is part of the KDE libraries
0003     SPDX-FileCopyrightText: 1997 Nicolas Hadacek <hadacek@kde.org>
0004     SPDX-FileCopyrightText: 2001, 2001 Ellis Whitehead <ellis@kde.org>
0005     SPDX-FileCopyrightText: 2006 Hamish Rodda <rodda@kde.org>
0006     SPDX-FileCopyrightText: 2007 Roberto Raggi <roberto@kdevelop.org>
0007     SPDX-FileCopyrightText: 2007 Andreas Hartmetz <ahartmetz@gmail.com>
0008     SPDX-FileCopyrightText: 2008 Michael Jansen <kde@michael-jansen.biz>
0009 
0010     SPDX-License-Identifier: LGPL-2.0-or-later
0011 */
0012 
0013 #ifndef KSHORTCUTSEDITOR_H
0014 #define KSHORTCUTSEDITOR_H
0015 
0016 #include <kxmlgui_export.h>
0017 
0018 #include <QWidget>
0019 
0020 class KActionCollection;
0021 class KConfig;
0022 class KConfigBase;
0023 class KConfigGroup;
0024 class KGlobalAccel;
0025 class KShortcutsEditorPrivate;
0026 
0027 // KShortcutsEditor expects that the list of existing shortcuts is already
0028 // free of conflicts. If it is not, nothing will crash, but your users
0029 // won't like the resulting behavior.
0030 
0031 /**
0032  * @class KShortcutsEditor kshortcutseditor.h KShortcutsEditor
0033  *
0034  * @short Widget for configuration of KAccel and KGlobalAccel.
0035  *
0036  * Configure dictionaries of key/action associations for QActions,
0037  * including global shortcuts.
0038  *
0039  * The class takes care of all aspects of configuration, including
0040  * handling key conflicts internally. Connect to the allDefault()
0041  * slot if you want to set all configurable shortcuts to their
0042  * default values.
0043  *
0044  * @see KShortcutsDialog
0045  * @author Nicolas Hadacek <hadacek@via.ecp.fr>
0046  * @author Hamish Rodda <rodda@kde.org> (KDE 4 porting)
0047  * @author Michael Jansen <kde@michael-jansen.biz>
0048  */
0049 class KXMLGUI_EXPORT KShortcutsEditor : public QWidget
0050 {
0051     Q_OBJECT
0052     Q_PROPERTY(ActionTypes actionTypes READ actionTypes WRITE setActionTypes)
0053 
0054 public:
0055     /**
0056      * @see ActionTypes
0057      */
0058     enum ActionType {
0059         /// Actions which are triggered by any keypress in a widget which has the action added to it
0060         WidgetAction = Qt::WidgetShortcut /*0*/,
0061         /// Actions which are triggered by any keypress in a window which has the action added to it or its child widget(s)
0062         WindowAction = Qt::WindowShortcut /*1*/,
0063         /// Actions which are triggered by any keypress in the application
0064         ApplicationAction = Qt::ApplicationShortcut /*2*/,
0065         /// Actions which are triggered by any keypress in the windowing system
0066         /// @note Starting from 5.95, this flag is ignored if there are no actual Global shortcuts in any of the action collections that are added
0067         GlobalAction = 4,
0068         /// All actions
0069         AllActions = 0xffffffff,
0070     };
0071     /**
0072      * Stores a combination of #ActionType values.
0073      */
0074     Q_DECLARE_FLAGS(ActionTypes, ActionType)
0075 
0076     enum LetterShortcuts {
0077         /// Shortcuts without a modifier are not allowed,
0078         /// so 'A' would not be valid, whereas 'Ctrl+A' would be.
0079         /// This only applies to printable characters, however.
0080         /// 'F1', 'Insert' etc. could still be used.
0081         LetterShortcutsDisallowed = 0,
0082         /// Letter shortcuts are allowed
0083         LetterShortcutsAllowed,
0084     };
0085 
0086     /**
0087      * Constructor.
0088      *
0089      * @param collection the KActionCollection to configure
0090      * @param parent parent widget
0091      * @param actionTypes types of actions to display in this widget.
0092      * @param allowLetterShortcuts set to LetterShortcutsDisallowed if unmodified alphanumeric
0093      *  keys ('A', '1', etc.) are not permissible shortcuts.
0094      */
0095     KShortcutsEditor(KActionCollection *collection,
0096                      QWidget *parent,
0097                      ActionTypes actionTypes = AllActions,
0098                      LetterShortcuts allowLetterShortcuts = LetterShortcutsAllowed);
0099 
0100     /**
0101      * \overload
0102      *
0103      * Creates a key chooser without a starting action collection.
0104      *
0105      * @param parent parent widget
0106      * @param actionTypes types of actions to display in this widget.
0107      * @param allowLetterShortcuts set to LetterShortcutsDisallowed if unmodified alphanumeric
0108      *  keys ('A', '1', etc.) are not permissible shortcuts.
0109      */
0110     explicit KShortcutsEditor(QWidget *parent, ActionTypes actionTypes = AllActions, LetterShortcuts allowLetterShortcuts = LetterShortcutsAllowed);
0111 
0112     /// Destructor
0113     ~KShortcutsEditor() override;
0114 
0115     /**
0116      * Are the unsaved changes?
0117      */
0118     bool isModified() const;
0119 
0120     /**
0121      * Removes all action collections from the editor
0122      */
0123     void clearCollections();
0124 
0125     /**
0126      * Insert an action collection, i.e. add all its actions to the ones
0127      * already associated with the KShortcutsEditor object.
0128      * @param title subtree title of this collection of shortcut.
0129      */
0130     void addCollection(KActionCollection *, const QString &title = QString());
0131 
0132     /**
0133      * Undo all change made since the last save().
0134      *
0135      * @since 5.75
0136      */
0137     void undo();
0138 
0139     /**
0140      * Save the changes.
0141      *
0142      * This saves the actions to disk.
0143      * Any KActionCollection objects with the xmlFile() value set will be
0144      * written to an XML file.  All other will be written to the application's
0145      * rc file.
0146      */
0147     void save();
0148 
0149     /**
0150      * Sets the types of actions to display in this widget.
0151      *
0152      * @param actionTypes New types of actions
0153      * @since 5.0
0154      */
0155     void setActionTypes(ActionTypes actionTypes);
0156     /**
0157      *
0158      * @return The types of actions currently displayed in this widget.
0159      * @since 5.0
0160      */
0161     ActionTypes actionTypes() const;
0162 
0163 Q_SIGNALS:
0164     /**
0165      * Emitted when an action's shortcut has been changed.
0166      **/
0167     void keyChange();
0168 
0169 public Q_SLOTS:
0170     /**
0171      * Set all shortcuts to their default values (bindings).
0172      **/
0173     void allDefault();
0174 
0175 private Q_SLOTS:
0176     /*
0177      * Resize columns to width required
0178      */
0179     KXMLGUI_NO_EXPORT void resizeColumns();
0180 
0181     /*
0182      * Opens a printing dialog to print all the shortcuts
0183      */
0184     KXMLGUI_NO_EXPORT void printShortcuts() const;
0185 
0186 private:
0187     /*
0188      * Write the current settings to the \p config object.
0189      *
0190      * This does not initialize the \p config object. It adds the
0191      * configuration.
0192      *
0193      * @note This will not save the global configuration! globalaccel holds
0194      * that part of the configuration.
0195      * @see writeGlobalConfig()
0196      *
0197      * @param config Config object to save to or, or null to use the
0198      *               applications config object
0199      *
0200      */
0201     KXMLGUI_NO_EXPORT void writeConfiguration(KConfigGroup *config = nullptr) const;
0202 
0203     /*
0204      * Export the current setting to configuration @p config.
0205      *
0206      * This initializes the configuration object. This will export the global
0207      * configuration too.
0208      *
0209      * @param config Config object
0210      */
0211     KXMLGUI_NO_EXPORT void exportConfiguration(KConfigBase *config) const;
0212 
0213     /*
0214      * Import the settings from configuration @p config.
0215      *
0216      * This will remove all current setting before importing. All shortcuts
0217      * are set to QList<QKeySequence>() prior to importing from @p config!
0218      *
0219      * @param config Config object
0220      */
0221     KXMLGUI_NO_EXPORT void importConfiguration(KConfigBase *config);
0222 
0223     friend class KShortcutsDialog;
0224     friend class KShortcutsEditorPrivate;
0225     std::unique_ptr<KShortcutsEditorPrivate> const d;
0226     Q_DISABLE_COPY(KShortcutsEditor)
0227 };
0228 
0229 Q_DECLARE_OPERATORS_FOR_FLAGS(KShortcutsEditor::ActionTypes)
0230 
0231 #endif // KSHORTCUTSEDITOR_H