The compositor's virtual desktops, and every rule about them. More...
#include <PhosphorWorkspaces/VirtualDesktopManager.h>
Public Types | |
| enum class | CallAnswer { Answered , Unanswered } |
| How the compositor answered one of the desktop methods (createDesktopAnswered, removeDesktopAnswered). More... | |
Signals | |
| void | currentDesktopChanged (int desktop) |
| void | desktopCountChanged (int count) |
| The committed count changed. | |
| void | desktopsChanged () |
| The desktop LIST changed — a desktop was added, removed, reordered, or renamed. | |
| void | desktopRemovedAt (int removedPosition) |
| Exactly one desktop was removed, and this is the 1-based POSITION it held before it went. | |
| void | screenDesktopChanged (const QString &screenId, int desktop) |
| A single screen's current virtual desktop changed (per-output virtual desktops). | |
| void | screenDesktopSeeded (const QString &screenId, int desktop) |
| A screen's desktop was recorded as the output (re)connected (seedScreenDesktop). | |
| void | desktopsRenumbered (const PhosphorEngine::DesktopRemap &remap) |
| The desktop positions moved: a removal, an insert, a reorder, or any mix of them, as one old-to-new map (F787). | |
| void | desktopListChanging () |
| KWin started a change that can move desktop positions (a create, a remove, a move), and the list that says what changed is on its way. | |
| void | desktopListChangeSettled () |
| The change desktopListChanging announced has committed, or was given up on after the list could not be read. | |
| void | desktopRenamed (const QString &desktopId, const QString &name) |
| A desktop present before and after a commit carries a different raw KWin name (rawDesktopNames). | |
| void | createDesktopAnswered (uint position, const QString &name, PhosphorWorkspaces::VirtualDesktopManager::CallAnswer answer) |
| KWin answered the createDesktop call made with these arguments, after any kwinDesktopCreated it caused (CallAnswer). | |
| void | removeDesktopAnswered (const QString &desktopId, PhosphorWorkspaces::VirtualDesktopManager::CallAnswer answer) |
KWin answered the removeDesktop call for desktopId, after any kwinDesktopRemoved it caused (CallAnswer). | |
| void | kwinDesktopCreated (const QString &desktopId) |
| A KWin desktopCreated arrived carrying this UUID. | |
| void | kwinDesktopRemoved (const QString &desktopId) |
| A KWin desktopRemoved arrived carrying this UUID (same timing contract). | |
| void | desktopListChanged (const QStringList &desktopIds) |
| The ordered global id list settled (create, remove, reorder). | |
Public Member Functions | |
| VirtualDesktopManager (QObject *parent=nullptr) | |
| No backend: unavailable, a single synthetic desktop. | |
| VirtualDesktopManager (std::unique_ptr< IVirtualDesktopBackend > backend, QObject *parent=nullptr) | |
Desktops from backend, owned from here on. | |
| ~VirtualDesktopManager () override | |
| bool | init () |
| void | start () |
| void | stop () |
| int | currentDesktop () const override |
| The global (active-screen) current virtual desktop, 1-based. | |
| int | currentDesktopForScreen (const QString &screenId) const override |
| The current virtual desktop for a specific screen, 1-based. | |
| bool | perScreenModeActive () const override |
| Superseded, kept for the installed API (IVirtualDesktopManager): no production code calls it, only this library's tests. | |
| void | updateScreenDesktop (const QString &screenId, int desktop) |
| Record a screen's current virtual desktop (1-based). | |
| void | removeScreenDesktop (const QString &screenId) |
| Drop a screen's recorded per-output desktop when the output is removed, so the map doesn't retain stale entries (and perScreenModeActive() doesn't keep counting a gone screen) across monitor hot-plug. | |
| bool | hasScreenDesktopReport (const QString &screenId) const |
True when a per-output report exists for screenId (or, for a virtual screen id, for its parent output). | |
| void | renameScreen (const QString &oldId, const QString &newId) |
| Carry a recorded per-output desktop across a screen-id rename. | |
| QString | liveScreenIdFor (const QString &screenId) const |
The id a per-output report naming screenId is recorded under: the new id while screenId is an aliased old spelling of a renamed output (renameScreen), else screenId. | |
| void | refresh () |
| Re-read the whole desktop list from the backend, for a consumer that knows its picture went stale (the reconciler's expired ledger entry). | |
| void | setCurrentDesktop (int desktop) |
| Ask KWin to switch to the desktop at this 1-based position. | |
| void | setCurrentDesktopById (const QString &desktopId) |
| Switch by KWin's desktop UUID rather than by position. | |
| void | createDesktop (uint position, const QString &name) |
| Ask KWin to create a desktop at the given 0-based global position (KWin's D-Bus signature; the caller computes the position, this wrapper only forwards). | |
| void | removeDesktop (const QString &desktopId) |
| Ask KWin to remove the desktop with the given UUID string. | |
| void | setDesktopName (const QString &desktopId, const QString &name) |
| Ask KWin to rename the desktop with the given UUID string. | |
| int | desktopCount () const |
| int | desktopRows () const |
| Number of rows in KWin's virtual-desktop grid (>= 1). | |
| QStringList | desktopNames () const |
| QStringList | desktopIds () const |
| KWin's desktop UUIDs, in position order and index-aligned with desktopNames(). | |
| QString | desktopIdAt (int desktop) const |
| UUID at 1-based global index, or empty when out of range. | |
| int | desktopIndexOf (const QString &desktopId) const |
| 1-based global index of the UUID, or 0 when unknown. | |
| QStringList | rawDesktopNames () const |
| KWin's names EXACTLY as KWin reports them, aligned 1:1 with desktopIds(). | |
| bool | isAvailable () const |
| True once init() reached the backend's desktops (for KWin's, once KWin's VirtualDesktopManager interface answered on the session bus). | |
| void | seedScreenDesktop (const QString &screenId, int desktop) |
| Record the desktop an output shows as it is connected or comes back. | |
| void | setBaselineDesktopIds (const QStringList &desktopIds) |
| The desktop ids a previous session saw, in position order, so a change KWin made while nothing was listening (desktops added, removed or moved while the daemon was down) still renumbers the stores keyed on the old positions. | |
| Public Member Functions inherited from PhosphorEngine::IVirtualDesktopManager | |
| virtual | ~IVirtualDesktopManager ()=default |
Protected Types | |
| using | DesktopEntry = PhosphorWorkspaces::DesktopEntry |
Protected Member Functions | |
| bool | commitDesktopList (QList< DesktopEntry > desktops, const QString ¤tId, int rows) |
| Commit one whole desktop list: the core behind both of the backend's reads and the list built from its change signals at countChanged. | |
| void | ingestDesktopCreated (const QString &desktopId, int position, const QString &name) |
| The backend's desktopCreated and desktopDataChanged. | |
| void | ingestDesktopDataChanged (const QString &desktopId, int position, const QString &name) |
The compositor's virtual desktops, and every rule about them.
The desktops come from an IVirtualDesktopBackend (KWin's, over the session bus, is PhosphorWorkspaces::Plasma's). Without one, or when the backend reaches no desktops, the manager is unavailable and every getter answers for a single synthetic desktop.
|
protected |
|
strong |
How the compositor answered one of the desktop methods (createDesktopAnswered, removeDesktopAnswered).
|
explicit |
No backend: unavailable, a single synthetic desktop.
|
explicit |
Desktops from backend, owned from here on.
Null is the same as the constructor above.
|
override |
|
protected |
Commit one whole desktop list: the core behind both of the backend's reads and the list built from its change signals at countChanged.
Returns false, committing nothing, for a list no compositor can send (empty, an empty id, a duplicate id). Protected so a driver with no compositor (the tests) can feed lists directly.
| void PhosphorWorkspaces::VirtualDesktopManager::createDesktop | ( | uint | position, |
| const QString & | name ) |
Ask KWin to create a desktop at the given 0-based global position (KWin's D-Bus signature; the caller computes the position, this wrapper only forwards).
The desktop arrives as kwinDesktopCreated and then the committed list (desktopListChanged), and KWin's answer to the call as createDesktopAnswered after both. Dropped without an answer when KWin's interface is unavailable.
|
signal |
KWin answered the createDesktop call made with these arguments, after any kwinDesktopCreated it caused (CallAnswer).
One per call made while KWin's interface was available.
|
overridevirtual |
The global (active-screen) current virtual desktop, 1-based.
Implements PhosphorEngine::IVirtualDesktopManager.
|
signal |
|
overridevirtual |
The current virtual desktop for a specific screen, 1-based.
Under Plasma 6.7 "switch desktops independently for each screen" (per-output virtual desktops) each screen can be on its own desktop. The default returns the global currentDesktop(), which is correct for single-desktop / pre-6.7 setups and for screens with no per-output desktop on record.
Reimplemented from PhosphorEngine::IVirtualDesktopManager.
| int PhosphorWorkspaces::VirtualDesktopManager::desktopCount | ( | ) | const |
|
signal |
The committed count changed.
For a create or a remove it goes out with the list, last of that commit's signals. Only when KWin's signals for the change did not add up to a list (a desktop signal missed) is a GROWING count committed as KWin reports it, ahead of the list (F1022), and then desktopIds() and desktopNames() still hold the old list here; desktopsChanged follows once the list commits, and is the signal a consumer of the names listens to (F1101).
| QString PhosphorWorkspaces::VirtualDesktopManager::desktopIdAt | ( | int | desktop | ) | const |
UUID at 1-based global index, or empty when out of range.
| QStringList PhosphorWorkspaces::VirtualDesktopManager::desktopIds | ( | ) | const |
KWin's desktop UUIDs, in position order and index-aligned with desktopNames().
The stable identity of a desktop: names are user-editable and positions renumber, ids do neither.
| int PhosphorWorkspaces::VirtualDesktopManager::desktopIndexOf | ( | const QString & | desktopId | ) | const |
1-based global index of the UUID, or 0 when unknown.
|
signal |
The ordered global id list settled (create, remove, reorder).
Emitted only when the ordered id list actually changed, and BEFORE any screenDesktopChanged or desktopCountChanged the same commit drives, so a consumer resolving those numbers against the id list it last settled reads them against the new list. The per-screen desktops (currentDesktopForScreen) are already in the new numbering here.
A create or a remove commits when KWin's countChanged closes it, built from the desktop signals KWin sent for it, so this goes out before any report KWin sent after the change. A report KWin sent DURING it (the active output's move off a removed desktop) still arrives first. A move or a rename commits with the next list read.
|
signal |
The change desktopListChanging announced has committed, or was given up on after the list could not be read.
Sent after every other signal of that commit, desktopsRenumbered included when there was one, so a store that marked its entries on desktopListChanging drops the marks here whether or not anything was renumbered.
|
signal |
KWin started a change that can move desktop positions (a create, a remove, a move), and the list that says what changed is on its way.
Sent once per change, on the first of the several signals KWin sends for it (F1023), and paired with desktopListChangeSettled. A rename moves no position and sends neither. Not sent before the first snapshot, whose map compares against a previous session. A change that moves no number is never followed by desktopsRenumbered. A store whose entries the compositor re-reports in the new numbering on its own (the window registry) marks here which entries predate the change.
| QStringList PhosphorWorkspaces::VirtualDesktopManager::desktopNames | ( | ) | const |
|
signal |
Exactly one desktop was removed, and this is the 1-based POSITION it held before it went.
Emitted ahead of desktopCountChanged, because a consumer keyed on positions has to act in that order: drop the removed position's state first, then shift everything above it down one.
desktopCountChanged cannot carry this. It reports the new count, and after a mid-list removal every surviving position is still within it — so a consumer seeing only the count cannot tell 2-of-4 was deleted from 4-of-4, and pruning "everything past the new count" drops the TOPMOST desktop's state instead of the removed one's.
Only for the unambiguous case: exactly one id gone and none added. A reorder, a simultaneous add and remove, or a multi-desktop change leaves this silent.
Superseded by desktopsRenumbered, which goes out just before it and covers every shape of change. Nothing in this tree connects it; it is kept for installed-API compatibility. Connect one of the two, never both, or a store is shifted twice.
|
signal |
A desktop present before and after a commit carries a different raw KWin name (rawDesktopNames).
Sent for every such rename, those this process asked for with setDesktopName included, after desktopsChanged.
| int PhosphorWorkspaces::VirtualDesktopManager::desktopRows | ( | ) | const |
Number of rows in KWin's virtual-desktop grid (>= 1).
With the count, this gives the grid shape that cross-desktop directional navigation walks. Defaults to 1 until the first KWin refresh.
|
signal |
The desktop LIST changed — a desktop was added, removed, reordered, or renamed.
Distinct from desktopCountChanged, which a rename does not move: KWin delivers renames through desktopDataChanged, and without this signal a pager would keep showing the old label until something unrelated forced a refresh. Emitted only when the ids or names actually differ from the previous snapshot.
|
signal |
The desktop positions moved: a removal, an insert, a reorder, or any mix of them, as one old-to-new map (F787).
Every store keyed on a desktop NUMBER applies remap once. By the time it goes out the manager's own state is renumbered: the ids, the count, the current desktop, and each screen's desktop (moved through DesktopRemap::successor, silently, for the reason desktopRemovedAt's shift is silent). Ahead of desktopCountChanged, like desktopRemovedAt. Only in the fallback desktopCountChanged describes (a growing count committed before its list) does the count go first. Never sent for a change that moves no number (a rename, a desktop appended after the last one).
| bool PhosphorWorkspaces::VirtualDesktopManager::hasScreenDesktopReport | ( | const QString & | screenId | ) | const |
True when a per-output report exists for screenId (or, for a virtual screen id, for its parent output).
currentDesktopForScreen falls back to the global current when this is false, so callers that must not act on the fallback (first-run adoption) gate on this instead.
|
protected |
The backend's desktopCreated and desktopDataChanged.
The tests drive them directly.
|
protected |
| bool PhosphorWorkspaces::VirtualDesktopManager::init | ( | ) |
| bool PhosphorWorkspaces::VirtualDesktopManager::isAvailable | ( | ) | const |
True once init() reached the backend's desktops (for KWin's, once KWin's VirtualDesktopManager interface answered on the session bus).
False without a backend, on a compositor it reaches nothing on, or before init(), where every getter degrades to a single synthetic desktop — a UI should hide itself rather than show a pager with one permanent pill. init() returns true unconditionally and so cannot be used for this.
|
signal |
A KWin desktopCreated arrived carrying this UUID.
Emitted BEFORE the list commits: id-only, desktopIds() still the old list. The dynamic-workspaces reconciler matches its ledger on this, then acts on desktopListChanged.
|
signal |
A KWin desktopRemoved arrived carrying this UUID (same timing contract).
| QString PhosphorWorkspaces::VirtualDesktopManager::liveScreenIdFor | ( | const QString & | screenId | ) | const |
The id a per-output report naming screenId is recorded under: the new id while screenId is an aliased old spelling of a renamed output (renameScreen), else screenId.
|
overridevirtual |
Superseded, kept for the installed API (IVirtualDesktopManager): no production code calls it, only this library's tests.
It only tells whether two recorded screens differ right now, which is not whether KWin runs per-output desktops (two screens on the same desktop answer false in that mode too).
Reimplemented from PhosphorEngine::IVirtualDesktopManager.
| QStringList PhosphorWorkspaces::VirtualDesktopManager::rawDesktopNames | ( | ) | const |
KWin's names EXACTLY as KWin reports them, aligned 1:1 with desktopIds().
KWin gives every desktop it creates without a name a positional default label of its own ("Desktop N", in KWin's language), so an entry is empty only when a client explicitly set an empty name; it is never a reliable "unnamed" marker. desktopNames() differs only there, filling the empty entries with this library's placeholder. Empty without KWin.
| void PhosphorWorkspaces::VirtualDesktopManager::refresh | ( | ) |
Re-read the whole desktop list from the backend, for a consumer that knows its picture went stale (the reconciler's expired ledger entry).
Asynchronous while running, and one read at a time like every other read; nothing without a reachable backend.
| void PhosphorWorkspaces::VirtualDesktopManager::removeDesktop | ( | const QString & | desktopId | ) |
Ask KWin to remove the desktop with the given UUID string.
Result arrives as kwinDesktopRemoved + desktopListChanged, then removeDesktopAnswered.
|
signal |
KWin answered the removeDesktop call for desktopId, after any kwinDesktopRemoved it caused (CallAnswer).
| void PhosphorWorkspaces::VirtualDesktopManager::removeScreenDesktop | ( | const QString & | screenId | ) |
Drop a screen's recorded per-output desktop when the output is removed, so the map doesn't retain stale entries (and perScreenModeActive() doesn't keep counting a gone screen) across monitor hot-plug.
Driven by the daemon's screenRemoved handler.
| void PhosphorWorkspaces::VirtualDesktopManager::renameScreen | ( | const QString & | oldId, |
| const QString & | newId ) |
Carry a recorded per-output desktop across a screen-id rename.
KWin can flip an output's id between its bare and "/CONNECTOR"-qualified spellings and ScreenManager reports that as screenIdentifierChanged, with no screenRemoved/screenAdded; without this the row stays under the dead id and every hasScreenDesktopReport / currentDesktopForScreen ask under the live id falls back to the GLOBAL desktop.
The carried row goes out as screenDesktopSeeded, never as screenDesktopChanged: the output did not switch desktops, it was renamed, and every consumer keyed on the screen id must learn its desktop under the new id without running a desktop-switch pass.
A row already present under newId wins and oldId is merely dropped: that row is a report the effect already made under the live id, so it is newer than the one carried over. Nothing is emitted in that case, nor when oldId is unknown or either id is empty or the two are equal.
The old spelling also stays an alias of the new id until a report under the new id arrives after the rename, or the output goes. The daemon learns the rename from its own QScreen set and the effect re-spells on KWin's screenAdded/screenRemoved, two channels with no order between them, so the effect can still answer under the old spelling after this call. updateScreenDesktop and seedScreenDesktop record such a report under the new id (liveScreenIdFor). The effect's reports arrive in the order it sent them, so none under the old spelling follows one under the new id, and that report drops the alias. When the effect re-spelled before this call, the alias waits for the next such report and translates nothing meanwhile. A rename back to the old spelling and removeScreenDesktop of the new id drop it as well.
|
signal |
A single screen's current virtual desktop changed (per-output virtual desktops).
The primary trigger the daemon's per-screen desktop handler subscribes to; in single-desktop mode it is driven the same for every screen so downstream has one code path.
|
signal |
A screen's desktop was recorded as the output (re)connected (seedScreenDesktop).
Not a switch.
| void PhosphorWorkspaces::VirtualDesktopManager::seedScreenDesktop | ( | const QString & | screenId, |
| int | desktop ) |
Record the desktop an output shows as it is connected or comes back.
KWin picks it without a desktop change, so it is a seed, not a switch: it emits screenDesktopSeeded, never screenDesktopChanged, and always, because the engines dropped the output's desktop when it went away.
| void PhosphorWorkspaces::VirtualDesktopManager::setBaselineDesktopIds | ( | const QStringList & | desktopIds | ) |
The desktop ids a previous session saw, in position order, so a change KWin made while nothing was listening (desktops added, removed or moved while the daemon was down) still renumbers the stores keyed on the old positions.
Compared against the first committed snapshot, or against the current one at once when it has already landed; a difference goes out as desktopsRenumbered and nothing else (the per-screen desktops and desktopRemovedAt are about live changes only). An empty list is ignored.
| void PhosphorWorkspaces::VirtualDesktopManager::setCurrentDesktop | ( | int | desktop | ) |
Ask KWin to switch to the desktop at this 1-based position.
Asynchronous (a Properties.Set the caller does not wait for): the switch arrives as currentDesktopChanged.
| void PhosphorWorkspaces::VirtualDesktopManager::setCurrentDesktopById | ( | const QString & | desktopId | ) |
Switch by KWin's desktop UUID rather than by position.
Positions renumber whenever a desktop is created or removed, so anything that holds a desktop across such an event (a pager's pills, a rule) must key on the id. Unknown ids are ignored. Asynchronous, like setCurrentDesktop.
| void PhosphorWorkspaces::VirtualDesktopManager::setDesktopName | ( | const QString & | desktopId, |
| const QString & | name ) |
Ask KWin to rename the desktop with the given UUID string.
The new name arrives as desktopRenamed. KWin's reply is not reported: an unknown id is ignored by KWin, and nothing here keeps a ledger of renames.
| void PhosphorWorkspaces::VirtualDesktopManager::start | ( | ) |
| void PhosphorWorkspaces::VirtualDesktopManager::stop | ( | ) |
| void PhosphorWorkspaces::VirtualDesktopManager::updateScreenDesktop | ( | const QString & | screenId, |
| int | desktop ) |
Record a screen's current virtual desktop (1-based).
This is fed by the KWin effect's per-output desktopChanged report (Plasma 6.7 per-output virtual desktops) — KWin's own D-Bus VirtualDesktopManager interface only exposes the GLOBAL current desktop, so per-screen data arrives this way. Emits screenDesktopChanged only when the value actually changes.