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

The per-monitor workspace ownership model: screenId → ordered slice of KWin desktop ids, with the inverse owner index. More...

#include <PhosphorWorkspaces/WorkspaceMap.h>

Public Member Functions

QStringList screenOrder () const
void setScreenOrder (const QStringList &order)
 Replace the screen order (left-to-right geometry, ties by id — computed by the caller, which owns screen geometry knowledge).
bool hasScreen (const QString &screenId) const
 Whether this screen HOLDS A SLICE.
bool knowsScreen (const QString &screenId) const
 Whether this screen is part of the world at all: it holds a slice, or it appears in the screen order.
QList< WorkspaceEntry > slice (const QString &screenId) const
int sliceSize (const QString &screenId) const
QString ownerOf (const QString &desktopId) const
 Owner screen of a desktop id, or empty when unowned.
int sliceIndexOf (const QString &desktopId) const
 Slice position (0-based) of a desktop within its owner, or -1.
QStringList allDesktopIds () const
 All owned desktop ids, slice-concatenated in screen order.
WorkspaceEntry entryFor (const QString &desktopId) const
 The entry for a desktop id (owner looked up via the index); nullptr-like default entry when unowned.
void insert (const QString &screenId, int sliceIndex, const WorkspaceEntry &entry)
 Insert an entry into a screen's slice at sliceIndex (clamped).
bool remove (const QString &desktopId)
 Remove a desktop from whatever slice owns it.
bool reorderWithinSlice (const QString &desktopId, int newSliceIndex)
 Move a desktop within its owner's slice to newSliceIndex (clamped).
bool reorderSlice (const QString &screenId, const QStringList &orderedIds)
 Put a screen's slice in exactly the order orderedIds lists.
bool transfer (const QString &desktopId, const QString &toScreenId, int sliceIndex)
 Re-own a desktop to another screen at sliceIndex (clamped); keeps the entry's metadata.
void setName (const QString &desktopId, const QString &name)
void setNamedId (const QString &desktopId, const QString &namedId)
void setHomeScreen (const QString &desktopId, const QString &homeScreenId)
bool renameScreen (const QString &fromScreenId, const QString &toScreenId)
 Re-key a screen in place: its slice, its slot in the screen order and its owner rows move to toScreenId, and every home stamp naming fromScreenId is rewritten.
QList< WorkspaceEntry > takeSlice (const QString &screenId)
 Drop a screen's slice entirely, returning its entries in order (used by hotplug migration, which re-inserts them elsewhere).
void clear ()
uint globalPositionForInsert (const QString &screenId, int sliceIndex) const
 Global 0-based insert position computed from the MAP alone: the sum of slice sizes of screens preceding screenId in screen order, plus sliceIndex (clamped to the slice size).
bool consistentWith (const QStringList &kwinIds) const
 True when every invariant holds against kwinIds (each KWin id owned exactly once, no entry for a vanished id).
QStringList repairAgainst (const QStringList &kwinIds)
 Repair against the authoritative KWin id list: drop entries whose id vanished, report ids KWin has that no slice owns (for adoption by the caller).
QString toJson (quint64 generation, const QHash< QString, int > &currentByScreen, const std::function< int(const QString &)> &indexOf, bool includeState) const
 Map JSON per plan §3.2/§3.3.
bool fromJson (const QString &json)
 Parse a state-file or public-form payload into this map.
bool operator== (const WorkspaceMap &other) const

Static Public Attributes

static constexpr int MaxDesktopIdLength = 256
 The longest desktop id fromJson accepts.

Detailed Description

The per-monitor workspace ownership model: screenId → ordered slice of KWin desktop ids, with the inverse owner index.

Pure data — no D-Bus, no signals; the reconciler mutates it and the controller persists it. Every KWin desktop id appears in exactly one slice. Concatenating the slices in screen order is the order the reconciler AIMS for in KWin's global list, but nothing repairs KWin's list towards it: a reorder verb moves the map alone, so the two can disagree, and the reconciler derives KWin insert positions from KWin's own neighbours rather than from this concatenation.

Member Function Documentation

◆ allDesktopIds()

QStringList PhosphorWorkspaces::WorkspaceMap::allDesktopIds ( ) const

All owned desktop ids, slice-concatenated in screen order.

◆ clear()

void PhosphorWorkspaces::WorkspaceMap::clear ( )

◆ consistentWith()

bool PhosphorWorkspaces::WorkspaceMap::consistentWith ( const QStringList & kwinIds) const

True when every invariant holds against kwinIds (each KWin id owned exactly once, no entry for a vanished id).

Does not check contiguity (deliberately weakened, plan §4.3). A diagnostic: the production path repairs unconditionally through repairAgainst() rather than asking first, so this exists for tests and for debugging a suspect map.

◆ entryFor()

WorkspaceEntry PhosphorWorkspaces::WorkspaceMap::entryFor ( const QString & desktopId) const

The entry for a desktop id (owner looked up via the index); nullptr-like default entry when unowned.

◆ fromJson()

bool PhosphorWorkspaces::WorkspaceMap::fromJson ( const QString & json)

Parse a state-file or public-form payload into this map.

Parsed into a scratch map first: on version mismatch or malformed JSON it returns false and leaves this map exactly as it was.

◆ globalPositionForInsert()

uint PhosphorWorkspaces::WorkspaceMap::globalPositionForInsert ( const QString & screenId,
int sliceIndex ) const

Global 0-based insert position computed from the MAP alone: the sum of slice sizes of screens preceding screenId in screen order, plus sliceIndex (clamped to the slice size).

KWin's D-Bus position base is 0 per its desktops property. Only right while KWin's list matches the slice concatenation, so the reconciler uses it as the fallback when no slice neighbour of the insert slot has a known KWin position.

◆ hasScreen()

bool PhosphorWorkspaces::WorkspaceMap::hasScreen ( const QString & screenId) const

Whether this screen HOLDS A SLICE.

A screen that is part of the world but owns no desktop yet (just added, or emptied by a transfer) answers false — use knowsScreen() to ask about membership.

◆ insert()

void PhosphorWorkspaces::WorkspaceMap::insert ( const QString & screenId,
int sliceIndex,
const WorkspaceEntry & entry )

Insert an entry into a screen's slice at sliceIndex (clamped).

The id must not be owned elsewhere; a duplicate insert is repaired by removal from the previous owner first, and the map logs that repair itself.

◆ knowsScreen()

bool PhosphorWorkspaces::WorkspaceMap::knowsScreen ( const QString & screenId) const

Whether this screen is part of the world at all: it holds a slice, or it appears in the screen order.

This is the question to ask before routing a desktop to a screen; hasScreen() would refuse a live screen simply for being empty.

◆ operator==()

bool PhosphorWorkspaces::WorkspaceMap::operator== ( const WorkspaceMap & other) const
inline

◆ ownerOf()

QString PhosphorWorkspaces::WorkspaceMap::ownerOf ( const QString & desktopId) const

Owner screen of a desktop id, or empty when unowned.

◆ remove()

bool PhosphorWorkspaces::WorkspaceMap::remove ( const QString & desktopId)

Remove a desktop from whatever slice owns it.

Returns true only when a slice entry was actually taken out, which is the answer callers use to decide whether anything OBSERVABLE changed.

Returns false if the desktop was unowned, and also if the owner index named a slice that does not actually hold the id — that stale row is dropped (with a warning) rather than kept, since a row naming a slice without the entry can only mislead later lookups. That drop is deliberately SILENT: the serialized map (toJson) is built from the screen order and the slices alone, so repairing the inverse index changes nothing any consumer of the published generation can see, and announcing it would bump the generation for a payload that is byte-identical. Per-desktop bookkeeping a caller keeps beside the map must therefore not be gated on this return value.

◆ renameScreen()

bool PhosphorWorkspaces::WorkspaceMap::renameScreen ( const QString & fromScreenId,
const QString & toScreenId )

Re-key a screen in place: its slice, its slot in the screen order and its owner rows move to toScreenId, and every home stamp naming fromScreenId is rewritten.

Refused (false) when fromScreenId is not part of the world or toScreenId already holds a slice.

◆ reorderSlice()

bool PhosphorWorkspaces::WorkspaceMap::reorderSlice ( const QString & screenId,
const QStringList & orderedIds )

Put a screen's slice in exactly the order orderedIds lists.

Refused (false, nothing changed) unless orderedIds is a permutation of the slice. Returns true only when the order actually changed.

◆ reorderWithinSlice()

bool PhosphorWorkspaces::WorkspaceMap::reorderWithinSlice ( const QString & desktopId,
int newSliceIndex )

Move a desktop within its owner's slice to newSliceIndex (clamped).

◆ repairAgainst()

QStringList PhosphorWorkspaces::WorkspaceMap::repairAgainst ( const QStringList & kwinIds)

Repair against the authoritative KWin id list: drop entries whose id vanished, report ids KWin has that no slice owns (for adoption by the caller).

Returns the unowned ids in KWin order.

◆ screenOrder()

QStringList PhosphorWorkspaces::WorkspaceMap::screenOrder ( ) const

◆ setHomeScreen()

void PhosphorWorkspaces::WorkspaceMap::setHomeScreen ( const QString & desktopId,
const QString & homeScreenId )

◆ setName()

void PhosphorWorkspaces::WorkspaceMap::setName ( const QString & desktopId,
const QString & name )

◆ setNamedId()

void PhosphorWorkspaces::WorkspaceMap::setNamedId ( const QString & desktopId,
const QString & namedId )

◆ setScreenOrder()

void PhosphorWorkspaces::WorkspaceMap::setScreenOrder ( const QStringList & order)

Replace the screen order (left-to-right geometry, ties by id — computed by the caller, which owns screen geometry knowledge).

Screens absent from order but holding slices are appended in their previous relative order so no slice is ever orphaned by a reorder.

◆ slice()

QList< WorkspaceEntry > PhosphorWorkspaces::WorkspaceMap::slice ( const QString & screenId) const

◆ sliceIndexOf()

int PhosphorWorkspaces::WorkspaceMap::sliceIndexOf ( const QString & desktopId) const

Slice position (0-based) of a desktop within its owner, or -1.

◆ sliceSize()

int PhosphorWorkspaces::WorkspaceMap::sliceSize ( const QString & screenId) const

◆ takeSlice()

QList< WorkspaceEntry > PhosphorWorkspaces::WorkspaceMap::takeSlice ( const QString & screenId)

Drop a screen's slice entirely, returning its entries in order (used by hotplug migration, which re-inserts them elsewhere).

◆ toJson()

QString PhosphorWorkspaces::WorkspaceMap::toJson ( quint64 generation,
const QHash< QString, int > & currentByScreen,
const std::function< int(const QString &)> & indexOf,
bool includeState ) const

Map JSON per plan §3.2/§3.3.

currentByScreen (screenId → 1-based global int) and indexOf (desktop id → 1-based global int) are supplied by the caller so the model stays free of VirtualDesktopManager. includeState adds homeScreen fields: the daemon's state file passes true. False gives the public form, which carries no hotplug bookkeeping; no D-Bus stream publishes it any more. A named entry's namedId rides both.

◆ transfer()

bool PhosphorWorkspaces::WorkspaceMap::transfer ( const QString & desktopId,
const QString & toScreenId,
int sliceIndex )

Re-own a desktop to another screen at sliceIndex (clamped); keeps the entry's metadata.

Returns false if unowned.

Member Data Documentation

◆ MaxDesktopIdLength

int PhosphorWorkspaces::WorkspaceMap::MaxDesktopIdLength = 256
staticconstexpr

The longest desktop id fromJson accepts.

The state file is a boundary and an id is opaque, so length is the only shape it can check.


The documentation for this class was generated from the following file: