Classes | |
| class | IBackend |
| Pluggable global shortcut backend. More... | |
| class | Registry |
| Consumer-facing facade over IBackend. More... | |
Enumerations | |
| enum class | BackendHint { Auto , KGlobalAccel , Portal , DBusTrigger , Native } |
| Backend selection hint for createBackend(). More... | |
Functions | |
| PHOSPHORSHORTCUTS_EXPORT std::unique_ptr< IBackend > | createBackend (BackendHint hint=BackendHint::Auto, QObject *parent=nullptr) |
| Create a backend instance. | |
| PHOSPHORSHORTCUTS_EXPORT bool | canBlockGlobalShortcuts () |
| Session-wide suspension of global shortcuts, for a chord recorder. | |
| PHOSPHORSHORTCUTS_EXPORT bool | setGlobalShortcutsBlocked (bool blocked) |
| Take (true) or give back (false) one hold on the suspension. | |
| PHOSPHORSHORTCUTS_EXPORT bool | globalShortcutsBlocked () |
| Whether this process currently holds at least one hold taken through setGlobalShortcutsBlocked(). | |
| PHOSPHORSHORTCUTS_EXPORT bool | releaseStrandedGlobalShortcutBlock () |
| Resume the global shortcuts whatever this process believes, to clear a block a previous run left behind by crashing mid-capture. | |
|
strong |
Backend selection hint for createBackend().
Most consumers should pass Auto (the default) and let the library detect the running environment. Explicit hints exist for tests and for consumers that want deterministic behaviour in CI.
| Enumerator | |
|---|---|
| Auto | Detect via session bus service introspection. |
| KGlobalAccel | Force KGlobalAccel. Falls through to DBusTrigger if the library was built without PHOSPHORSHORTCUTS_HAVE_KGLOBALACCEL. |
| Portal | Force XDG Desktop Portal GlobalShortcuts. |
| DBusTrigger | Force D-Bus trigger fallback. |
| Native | Reserved for the future INativeGrabber-backed backend. Currently returns nullptr — callers asking explicitly for Native opted in to a backend that doesn't exist yet, so a silent fallback would mask a misconfiguration. Callers MUST null-check the createBackend() return value; passing a null backend into Registry is a programming error (asserted in debug, logged and dropped in release). |
| PHOSPHORSHORTCUTS_EXPORT bool PhosphorShortcuts::canBlockGlobalShortcuts | ( | ) |
Session-wide suspension of global shortcuts, for a chord recorder.
A recorder that captures key presses in its own window never sees a chord some component already grabs globally: the binding service consumes the press first and fires that action instead. Suspending the global shortcuts for the length of the capture lets the press reach the window.
Only kglobalaccel offers this, through its blockGlobalShortcuts call. That call is not a flag kglobalacceld keeps: it ungrabs every key of every registered component at once, and the unblock grabs them all again. So it covers every keyboard shortcut registered with kglobalaccel, KWin's own keyboard actions included (KWin registers them there). It does not cover what KWin handles outside kglobalaccel, such as its pointer-button, wheel, touchpad and touchscreen gesture shortcuts and its Alt+click and Alt+wheel window actions, which stay live. A component that registers or re-registers a shortcut while the block is in place grabs that key again. The XDG portal and the D-Bus trigger fallback have no equivalent at all, so on those a chord that is already taken cannot be recorded, and a recorder should say so rather than wait for a press that never arrives.
The block belongs to nobody. kglobalacceld keeps no record of who asked, counts nothing, and does not watch the caller, so a later unblock from any client lifts it and a caller that exits without unblocking leaves it in place. Within one process the calls here are counted (see setGlobalShortcutsBlocked), and a normal application exit releases what the process still holds. A crash mid-capture leaves the session without its keyboard shortcuts until something unblocks or KWin restarts (on Wayland kglobalacceld runs inside KWin). releaseStrandedGlobalShortcutBlock() is that something: a recorder's application calls it once at start-up.
KWin drives the same call for its "Ignore global shortcuts" window rule: it blocks when a window with that rule gains focus and unblocks when the focus leaves it, so focusing such a window and then leaving it during a capture lifts the block early. An ordinary focus change does not touch it.
GUI thread only. Whether this session runs a binding service that can suspend global shortcuts (org.kde.kglobalaccel is on the session bus).
| PHOSPHORSHORTCUTS_EXPORT std::unique_ptr< IBackend > PhosphorShortcuts::createBackend | ( | BackendHint | hint = BackendHint::Auto, |
| QObject * | parent = nullptr ) |
Create a backend instance.
Auto-detection order:
The returned backend is empty (no shortcuts registered). Hand it to a Registry, bind() some shortcuts, then flush().
| PHOSPHORSHORTCUTS_EXPORT bool PhosphorShortcuts::globalShortcutsBlocked | ( | ) |
Whether this process currently holds at least one hold taken through setGlobalShortcutsBlocked().
| PHOSPHORSHORTCUTS_EXPORT bool PhosphorShortcuts::releaseStrandedGlobalShortcutBlock | ( | ) |
Resume the global shortcuts whatever this process believes, to clear a block a previous run left behind by crashing mid-capture.
Nothing can read the block's state back, so this always sends the unblock, and it lifts a block anyone else holds at that moment as well: another client's recorder, or KWin's for a focused window with the "Ignore global shortcuts" rule (which a newly started application's window takes the focus from anyway). Call it once, at start-up, before anything in the process blocks. It does nothing and returns false while this process holds a block, and returns true without a call when no binding service is running.
| PHOSPHORSHORTCUTS_EXPORT bool PhosphorShortcuts::setGlobalShortcutsBlocked | ( | bool | blocked | ) |
Take (true) or give back (false) one hold on the suspension.
The first hold this process takes suspends the global shortcuts and giving back the last one resumes them, so two recorders that overlap in one process cannot lift each other's block. Every true that returned true must be matched by exactly one false. A false with no hold outstanding is a no-op returning true. Returns whether the binding service accepted the call, or true when the hold count changed without one. A true that returns false takes no hold. The call blocks for one local round trip when it reaches the service, so the block is in place before the caller starts listening.