File indexing completed on 2024-03-24 15:28:29

0001 /*
0002     SPDX-FileCopyrightText: 2008 Michael Jansen <kde@michael-jansen.biz>
0003 
0004     SPDX-License-Identifier: LGPL-2.0-or-later
0005 */
0006 
0007 #ifndef COMPONENT_H
0008 #define COMPONENT_H
0009 
0010 #include "globalshortcut.h"
0011 #include "kglobalshortcutinfo.h"
0012 
0013 #include "kconfiggroup.h"
0014 
0015 #include <KGlobalAccel>
0016 #include <QHash>
0017 #include <QObject>
0018 
0019 class GlobalShortcut;
0020 class GlobalShortcutContext;
0021 class GlobalShortcutsRegistry;
0022 
0023 /**
0024  * @author Michael Jansen <kde@michael-jansen.biz>
0025  */
0026 class Component : public QObject
0027 {
0028     Q_OBJECT
0029 
0030     Q_CLASSINFO("D-Bus Interface", "org.kde.kglobalaccel.Component")
0031 
0032     /* clang-format off */
0033     Q_SCRIPTABLE Q_PROPERTY(QString friendlyName READ friendlyName)
0034     Q_SCRIPTABLE Q_PROPERTY(QString uniqueName READ uniqueName)
0035 
0036 
0037 public:
0038 
0039 
0040     ~Component() override;
0041     /* clang-format on */
0042 
0043     bool activateGlobalShortcutContext(const QString &uniqueName);
0044 
0045     void activateShortcuts();
0046 
0047     //! Returns all shortcuts in context @context
0048     QList<GlobalShortcut *> allShortcuts(const QString &context = QStringLiteral("default")) const;
0049 
0050     //! Creates the new global shortcut context @p context
0051     bool createGlobalShortcutContext(const QString &context, const QString &friendlyName = QString());
0052 
0053     //! Return the current context
0054     GlobalShortcutContext *currentContext();
0055 
0056     //! Return uniqueName converted to a valid dbus path
0057     QDBusObjectPath dbusPath() const;
0058 
0059     //! Deactivate all currently active shortcuts
0060     void deactivateShortcuts(bool temporarily = false);
0061 
0062     //! Returns the friendly name
0063     QString friendlyName() const;
0064 
0065     //! Returns the currently active shortcut for key
0066     GlobalShortcut *getShortcutByKey(const QKeySequence &key, KGlobalAccel::MatchType type) const;
0067 
0068     //! Returns the shortcut context @p name or nullptr
0069     GlobalShortcutContext *shortcutContext(const QString &name);
0070     GlobalShortcutContext const *shortcutContext(const QString &name) const;
0071 
0072     /**
0073      * Returns the list of shortcuts (different context) registered with @p
0074      * key.
0075      */
0076     QList<GlobalShortcut *> getShortcutsByKey(const QKeySequence &key, KGlobalAccel::MatchType type) const;
0077 
0078     //! Returns the shortcut by unique name. Only the active context is
0079     //! searched.
0080     GlobalShortcut *getShortcutByName(const QString &uniqueName, const QString &context = QStringLiteral("default")) const;
0081 
0082     /**
0083      * Check if @a key is available for component @p component
0084      */
0085     bool isShortcutAvailable(const QKeySequence &key, const QString &component, const QString &context) const;
0086 
0087     //! Load the settings from config group @p config
0088     void loadSettings(KConfigGroup &config);
0089 
0090     //! Sets the human readable name for this component.
0091     void setFriendlyName(const QString &);
0092 
0093     QString uniqueName() const;
0094 
0095     //! Unregister @a shortcut. This will remove its siblings from all contexts
0096     void unregisterShortcut(const QString &uniqueName);
0097 
0098     void writeSettings(KConfigGroup &config) const;
0099 
0100 protected:
0101     friend class ::GlobalShortcutsRegistry;
0102 
0103     //! Constructs a component. This is a private constructor, to create a component
0104     //! use GlobalShortcutsRegistry::self()->createComponent().
0105     Component(const QString &uniqueName, const QString &friendlyName);
0106 
0107     /**
0108      * Create a new globalShortcut by its name
0109      * @param uniqueName internal unique name to identify the shortcut
0110      * @param friendlyName name for the shortcut to be presented to the user
0111      * @param shortcutString string representation of the shortcut, such as "CTRL+S"
0112      * @param defaultShortcutString string representation of the default shortcut,
0113      *                   such as "CTRL+S", when the user choses to reset to default
0114      *                   the keyboard shortcut will return to this one.
0115      */
0116     GlobalShortcut *
0117     registerShortcut(const QString &uniqueName, const QString &friendlyName, const QString &shortcutString, const QString &defaultShortcutString);
0118 
0119 public Q_SLOTS:
0120 
0121     // For dbus Q_SCRIPTABLE has to be on slots. Scriptable methods are not
0122     // exported.
0123 
0124     /**
0125      * Remove all currently not used global shortcuts registrations for this
0126      * component and if nothing is left the component too.
0127      *
0128      * If the method returns true consider all information previously acquired
0129      * from this component as void.
0130      *
0131      * The method will cleanup in all contexts.
0132      *
0133      * @return @c true if a change was made, @c false if not.
0134      */
0135     Q_SCRIPTABLE virtual bool cleanUp();
0136 
0137     /**
0138      * Check if the component is currently active.
0139      *
0140      * A component is active if at least one of it's global shortcuts is
0141      * currently present.
0142      */
0143     Q_SCRIPTABLE bool isActive() const;
0144 
0145     //! Get all shortcutnames living in @a context
0146     Q_SCRIPTABLE QStringList shortcutNames(const QString &context = QStringLiteral("default")) const;
0147 
0148     //! Returns all shortcut in @a context
0149     Q_SCRIPTABLE QList<KGlobalShortcutInfo> allShortcutInfos(const QString &context = QStringLiteral("default")) const;
0150 
0151     //! Returns the shortcut contexts available for the component.
0152     Q_SCRIPTABLE QStringList getShortcutContexts() const;
0153 
0154     virtual void emitGlobalShortcutPressed(const GlobalShortcut &shortcut);
0155     virtual void emitGlobalShortcutReleased(const GlobalShortcut &shortcut);
0156 
0157     Q_SCRIPTABLE void invokeShortcut(const QString &shortcutName, const QString &context = QStringLiteral("default"));
0158 
0159 Q_SIGNALS:
0160 
0161     //! Signals that a action for this component was triggered
0162     Q_SCRIPTABLE void globalShortcutPressed(const QString &componentUnique, const QString &shortcutUnique, qlonglong timestamp);
0163 
0164     //! Signals that a action for this component is not triggered anymore
0165     Q_SCRIPTABLE void globalShortcutReleased(const QString &componentUnique, const QString &shortcutUnique, qlonglong timestamp);
0166 
0167 private:
0168     QString _uniqueName;
0169     // the name as it would be found in a magazine article about the application,
0170     // possibly localized if a localized name exists.
0171     QString _friendlyName;
0172 
0173     GlobalShortcutsRegistry *_registry;
0174 
0175     GlobalShortcutContext *_current;
0176     QHash<QString, GlobalShortcutContext *> _contexts;
0177 };
0178 
0179 #endif /* #ifndef COMPONENT_H */