Phosphor
Qt6 / Wayland library suite for window-management tools
Loading...
Searching...
No Matches
Registry.h
Go to the documentation of this file.
1// SPDX-FileCopyrightText: 2026 fuddlesworth
2// SPDX-License-Identifier: LGPL-2.1-or-later
3
4#pragma once
5
6#include <QHash>
7#include <QKeySequence>
8#include <QObject>
9#include <QPointer>
10#include <QString>
11#include <QStringList>
12#include <QVector>
13
14#include <functional>
15#include <optional>
16
17#include "phosphorshortcuts_export.h"
18
19namespace PhosphorShortcuts {
20
21class IBackend;
22
34class PHOSPHORSHORTCUTS_EXPORT Registry : public QObject
35{
36 Q_OBJECT
37public:
38 struct Binding
39 {
40 QString id;
41 QKeySequence defaultSeq;
42 QKeySequence currentSeq;
43 QString description;
44 };
45
46 explicit Registry(IBackend* backend, QObject* parent = nullptr);
47 ~Registry() override;
48
78 void bind(const QString& id, const QKeySequence& defaultSeq, const QString& description = {},
79 std::function<void()> callback = {}, bool persistent = true);
80
88 void rebind(const QString& id, const QKeySequence& seq);
89
99 bool setForeignShortcuts(const QString& componentName, const QString& actionName,
100 const QList<QKeySequence>& sequences);
101 std::optional<QList<QKeySequence>> foreignShortcuts(const QString& componentName, const QString& actionName) const;
102
110 void unbind(const QString& id);
111
120 void purge(const QString& id);
121
125 std::optional<QStringList> storedShortcutIds() const;
126
157 void setActive(const QString& id, bool active);
158
160 bool isActive(const QString& id) const;
161
175 void flush();
176
177 QKeySequence shortcut(const QString& id) const;
178
199 QStringList effectiveTriggers(const QString& id) const;
200
210 QVector<Binding> bindings(bool persistentOnly = false) const;
211
212Q_SIGNALS:
220 void triggered(QString id);
221
225 void ready();
226
237 void triggersChanged(QString id);
238
239private Q_SLOTS:
240 void onBackendActivated(QString id);
241 void onBackendReady();
242
243private:
244 struct Entry
245 {
246 Binding binding;
247 std::function<void()> callback;
248 // Last values successfully pushed to the backend. Used to decide
249 // whether flush() should re-register (default changed) or update-only
250 // (current changed), and to short-circuit no-op flushes.
251 QKeySequence lastSentDefault;
252 QKeySequence lastSentCurrent;
253 bool registered = false; // has registerShortcut been sent yet?
254 // Persistent flag last forwarded to the backend. flush() re-registers
255 // when this drifts from `persistent` so a re-bind() that flips the flag
256 // without changing the key still reaches the backend — the backend's
257 // crash-purge decision (KGlobalAccelBackend) depends on the latest
258 // value. Only meaningful once `registered` is true.
259 bool lastSentPersistent = true;
260 bool persistent = true; // surfaces in bindings(persistentOnly=true)
261 // Feature gate, see setActive(). An inactive entry keeps its sequence
262 // and its callback but holds no grab; flush() parks it through
263 // IBackend::suspendShortcut instead of unregistering it, so the
264 // platform's record of the user's own chord survives the gate.
265 bool active = true;
266 // Has flush() visited this entry at least once? Sequences applied
267 // before that are the consumer's stored config, not a user change,
268 // so they never arm storePending (see setActive()).
269 bool settled = false;
270 // currentSeq moved while the backend held no registration for the
271 // id. The platform's record still carries the old chord, so flush()
272 // writes the new one through IBackend::storeShortcut before the id is
273 // registered again (or while it stays parked).
274 bool storePending = false;
275 };
276
277 QPointer<IBackend> m_backend;
278 QHash<QString, Entry> m_entries;
279};
280
281} // namespace PhosphorShortcuts
Pluggable global shortcut backend.
Definition IBackend.h:32
void ready()
Forwarded from IBackend::ready().
std::optional< QStringList > storedShortcutIds() const
Every id the platform keeps a record for under this process's component (IBackend::storedShortcutIds)...
QVector< Binding > bindings(bool persistentOnly=false) const
Enumerate registered bindings, sorted by id for deterministic output.
void rebind(const QString &id, const QKeySequence &seq)
Change the active binding for an already-registered id.
void setActive(const QString &id, bool active)
Park or revive a binding without forgetting it and without destroying what the platform persists abou...
void flush()
Forward queued bind/rebind ops to the backend.
bool setForeignShortcuts(const QString &componentName, const QString &actionName, const QList< QKeySequence > &sequences)
Rebind / read another component's global shortcut (IBackend foreign pass-throughs; only the KGlobalAc...
void purge(const QString &id)
Like unbind() for an id this registry holds.
QKeySequence shortcut(const QString &id) const
void unbind(const QString &id)
Drop a binding entirely.
void bind(const QString &id, const QKeySequence &defaultSeq, const QString &description={}, std::function< void()> callback={}, bool persistent=true)
Register a shortcut.
void triggered(QString id)
Emitted on every activation, regardless of whether the binding has a callback.
Registry(IBackend *backend, QObject *parent=nullptr)
bool isActive(const QString &id) const
Whether the id is currently active. Unknown ids report false.
void triggersChanged(QString id)
Forwarded from IBackend::triggersChanged for ids this registry owns — the effective binding changed o...
QStringList effectiveTriggers(const QString &id) const
Display strings for the key(s) the user EFFECTIVELY has to press for an id right now.
std::optional< QList< QKeySequence > > foreignShortcuts(const QString &componentName, const QString &actionName) const
Definition Factory.h:12
Definition Registry.h:39
QString description
Definition Registry.h:43
QKeySequence defaultSeq
Definition Registry.h:41
QKeySequence currentSeq
Definition Registry.h:42
QString id
Definition Registry.h:40