Phosphor
Qt6 / Wayland library suite for window-management tools
Loading...
Searching...
No Matches
PhosphorShortcuts::Registry Class Reference

Consumer-facing facade over IBackend. More...

#include <PhosphorShortcuts/Registry.h>

Inheritance diagram for PhosphorShortcuts::Registry:
[legend]

Classes

struct  Binding

Signals

void triggered (QString id)
 Emitted on every activation, regardless of whether the binding has a callback.
void ready ()
 Forwarded from IBackend::ready().
void triggersChanged (QString id)
 Forwarded from IBackend::triggersChanged for ids this registry owns — the effective binding changed outside the bind/rebind flow (external rebind, compositor assignment).

Public Member Functions

 Registry (IBackend *backend, QObject *parent=nullptr)
 ~Registry () override
void bind (const QString &id, const QKeySequence &defaultSeq, const QString &description={}, std::function< void()> callback={}, bool persistent=true)
 Register a shortcut.
void rebind (const QString &id, const QKeySequence &seq)
 Change the active binding for an already-registered id.
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 KGlobalAccel backend supports them).
std::optional< QList< QKeySequence > > foreignShortcuts (const QString &componentName, const QString &actionName) const
void unbind (const QString &id)
 Drop a binding entirely.
void purge (const QString &id)
 Like unbind() for an id this registry holds.
std::optional< QStringList > storedShortcutIds () const
 Every id the platform keeps a record for under this process's component (IBackend::storedShortcutIds).
void setActive (const QString &id, bool active)
 Park or revive a binding without forgetting it and without destroying what the platform persists about it.
bool isActive (const QString &id) const
 Whether the id is currently active. Unknown ids report false.
void flush ()
 Forward queued bind/rebind ops to the backend.
QKeySequence shortcut (const QString &id) const
QStringList effectiveTriggers (const QString &id) const
 Display strings for the key(s) the user EFFECTIVELY has to press for an id right now.
QVector< Binding > bindings (bool persistentOnly=false) const
 Enumerate registered bindings, sorted by id for deterministic output.

Detailed Description

Consumer-facing facade over IBackend.

Owns a table of (id, default sequence, current sequence, description, optional callback) rows. Forwards registration + rebind calls to the backend and fans activation signals out as either per-id callbacks or the triggered() signal — consumers may use either pattern interchangeably.

The Registry does not own the backend; the caller keeps the backend alive for the Registry's lifetime. Passing a null backend is a programming error.

Constructor & Destructor Documentation

◆ Registry()

PhosphorShortcuts::Registry::Registry ( IBackend * backend,
QObject * parent = nullptr )
explicit

◆ ~Registry()

PhosphorShortcuts::Registry::~Registry ( )
override

Member Function Documentation

◆ bind()

void PhosphorShortcuts::Registry::bind ( const QString & id,
const QKeySequence & defaultSeq,
const QString & description = {},
std::function< void()> callback = {},
bool persistent = true )

Register a shortcut.

Safe to call multiple times for the same id — subsequent calls update the default sequence, description, and callback in place but PRESERVE the current sequence (any user-applied rebind is kept). Takes effect after flush().

Parameters
callbackOptional. Invoked on activation in addition to the triggered() signal. Nullptr callbacks are stored but never invoked; consumers relying purely on the signal can omit the argument.
persistentIf false, the binding is considered transient (e.g. a grab bound around a specific UI state). It is excluded from bindings(true) enumeration and forwarded to IBackend::registerShortcut, where it decides whether the requested sequence overrides the platform's stored record and whether that record is purged on teardown. A flip of the flag on a later bind() re-registers. Defaults to true.

A fresh entry starts active (see setActive()); a later bind() keeps the entry's active flag.

Note: a description reaches the backend only with a registerShortcut call, never with an update (IBackend::updateShortcut carries no description). A description changed by a later bind() therefore stays local until something makes flush() register again: a changed default, a flipped persistent flag, or the entry coming back after setActive() parked it or rebind() cleared it.

◆ bindings()

QVector< Binding > PhosphorShortcuts::Registry::bindings ( bool persistentOnly = false) const

Enumerate registered bindings, sorted by id for deterministic output.

Parameters
persistentOnlyIf true, transient bindings (those registered with persistent=false) are excluded. Intended for settings UIs that should not expose internal ad-hoc grabs to the user. Defaults to false so tests and library-internal callers see everything.

◆ effectiveTriggers()

QStringList PhosphorShortcuts::Registry::effectiveTriggers ( const QString & id) const

Display strings for the key(s) the user EFFECTIVELY has to press for an id right now.

Prefers the backend's read-back (IBackend::currentTriggers — which sees out-of-process overrides like System Settings rebinds, INCLUDING a cleared binding, which reports engaged-empty and is honored as unbound); falls back to the registry's own current sequence only when the backend cannot report at all. Empty means the id is genuinely unbound (or unknown).

The strings are DISPLAY-ONLY and not format-stable across backends (see IBackend::currentTriggers): KGlobalAccel yields PortableText while Portal relays the compositor's localized description. Don't string-compare results across backends or parse them back into QKeySequence.

A consumer that nonetheless parses these back (to normalize or token-compare them) must degrade gracefully when a string does not parse, and a change to this method's output format must keep such consumers in mind.

◆ flush()

void PhosphorShortcuts::Registry::flush ( )

Forward queued bind/rebind ops to the backend.

Does NOT include unbind() — those are applied immediately at the call site. Matches the backend's queue-then-flush model for register / update.

ready() fires after flushes settle, including no-op flushes where no entry actually changed, so consumers can gate UI on "any flush has settled" without per-entry bookkeeping. Do NOT assume a 1:1 flush→ready count: during asynchronous backend bring-up (PortalBackend before its session handle lands) multiple queued flushes coalesce into a single ready(). If you need "only fire when something actually changed", track that on the caller side.

◆ foreignShortcuts()

std::optional< QList< QKeySequence > > PhosphorShortcuts::Registry::foreignShortcuts ( const QString & componentName,
const QString & actionName ) const

◆ isActive()

bool PhosphorShortcuts::Registry::isActive ( const QString & id) const

Whether the id is currently active. Unknown ids report false.

◆ purge()

void PhosphorShortcuts::Registry::purge ( const QString & id)

Like unbind() for an id this registry holds.

For an id it does not hold, asks the backend to delete whatever persistent record the platform still keeps for it (IBackend::forgetShortcut), which is how a consumer clears a transient grab an earlier, crashed run left behind. Applied immediately. Only for transient ids: on a persistent id this destroys the user's customisation.

◆ ready

void PhosphorShortcuts::Registry::ready ( )
signal

Forwarded from IBackend::ready().

◆ rebind()

void PhosphorShortcuts::Registry::rebind ( const QString & id,
const QKeySequence & seq )

Change the active binding for an already-registered id.

Takes effect after flush(). Unknown ids are logged and ignored. Passing an empty QKeySequence releases the backend grab immediately (never leaves an empty sequence registered) but KEEPS the entry, so a later rebind() to a non-empty sequence re-registers it without a fresh bind().

◆ setActive()

void PhosphorShortcuts::Registry::setActive ( const QString & id,
bool active )

Park or revive a binding without forgetting it and without destroying what the platform persists about it.

Takes effect after flush(). Unknown ids are logged and ignored. Entries are active when bound.

This is how a consumer gates a whole family of shortcuts on a feature switch. Rebinding the family to an empty sequence looks equivalent and is not: that routes through IBackend::unregisterShortcut, which on KGlobalAccel wipes the user's saved chords for every id in the family, so turning the feature back on hands back the compiled-in defaults rather than what the user had. An inactive entry goes through IBackend::suspendShortcut instead, and reviving it re-registers with the stored binding intact.

An inactive entry reports no effectiveTriggers(): nothing the user can press reaches it. shortcut() still reports the stored sequence, which is what the consumer would grab again on revival.

A rebind() aimed at a parked entry is not lost. flush() writes it into the platform's record (IBackend::storeShortcut) so the revival grabs the new chord, including across a restart while still parked. The same holds for a rebind() that lands in the same batch as the park, and a rebind() to an empty sequence deletes the record. The write-through only follows this registry's own rebinds after the entry's first flush: the sequences applied before the first flush are the consumer's stored config, and writing those would overwrite a chord the user set in the platform's own settings while the entry was parked.

A fresh entry is active. bind() on an existing entry keeps its flag.

◆ setForeignShortcuts()

bool PhosphorShortcuts::Registry::setForeignShortcuts ( const QString & componentName,
const QString & actionName,
const QList< QKeySequence > & sequences )

Rebind / read another component's global shortcut (IBackend foreign pass-throughs; only the KGlobalAccel backend supports them).

foreignShortcuts is tri-state — see IBackend::foreignShortcuts. A disengaged optional means "could not read", and a caller about to steal the chord must treat that as a hard stop rather than as "unbound": clearing without a backup strands the user's binding.

◆ shortcut()

QKeySequence PhosphorShortcuts::Registry::shortcut ( const QString & id) const

◆ storedShortcutIds()

std::optional< QStringList > PhosphorShortcuts::Registry::storedShortcutIds ( ) const

Every id the platform keeps a record for under this process's component (IBackend::storedShortcutIds).

nullopt when the backend keeps none or the query failed.

◆ triggered

void PhosphorShortcuts::Registry::triggered ( QString id)
signal

Emitted on every activation, regardless of whether the binding has a callback.

Use this for centralised dispatch (one slot, switch on id).

Signature matches IBackend::activated (QString by value) so the two signals can be cross-connected without adapter slots.

◆ triggersChanged

void PhosphorShortcuts::Registry::triggersChanged ( QString id)
signal

Forwarded from IBackend::triggersChanged for ids this registry owns — the effective binding changed outside the bind/rebind flow (external rebind, compositor assignment).

Re-query effectiveTriggers() on it.

Always delivered from the event loop, never from inside a call into this registry: a backend may report while flush() walks the entries, and a slot that binds or unbinds in response would otherwise mutate the table under the walk.

◆ unbind()

void PhosphorShortcuts::Registry::unbind ( const QString & id)

Drop a binding entirely.

Releases any key grab and forgets the callback. Idempotent. Applied immediately — NOT batched until flush() — because the backends' unregister paths all act synchronously or with trivial state, and a late flush would be surprising for a "release this grab now" API.


The documentation for this class was generated from the following file:
  • phosphor-shortcuts/include/PhosphorShortcuts/Registry.h