File indexing completed on 2022-04-28 15:30:30

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