Tracks tiling state for a single screen. More...

#include <phosphor-tiles/include/PhosphorTiles/TilingState.h>

Inheritance diagram for PhosphorTiles::TilingState:

Signals
void	windowCountChanged ()
	Emitted when window count changes (add/remove)

void	windowOrderChanged ()
	Emitted when window order changes (move/swap)

void	masterCountChanged ()
	Emitted when master count changes.

void	splitRatioChanged ()
	Emitted when split ratio changes.

void	floatingChanged (const QString &windowId, bool floating)
	Emitted when a window's floating state changes.

void	focusedWindowChanged ()
	Emitted when focused window changes.

void	stateChanged ()
	Emitted when any state change requires retiling.

Public Member Functions
	TilingState (const QString &screenId, QObject *parent=nullptr)
	Construct a TilingState for a specific screen.

	~TilingState () override

	TilingState (const TilingState &)=delete

TilingState &	operator= (const TilingState &)=delete

QString	screenId () const override
	Get the screen ID this state belongs to.

int	windowCount () const override
	Get total number of tracked windows (including floating)

int	tiledWindowCount () const override
	Get number of tiled windows (excluding floating)

QStringList	windowOrder () const
	Get the ordered list of window IDs.

QStringList	tiledWindows () const
	Get only tiled (non-floating) windows in order.

bool	addWindow (const QString &windowId, int position=-1)
	Add a window to the tiling.

bool	removeWindow (const QString &windowId)
	Remove a window from the tiling.

bool	moveWindow (int fromIndex, int toIndex)
	Move a window to a different position.

bool	swapWindows (int index1, int index2)
	Swap two windows' positions.

bool	swapWindowsById (const QString &windowId1, const QString &windowId2)
	Swap two windows by their IDs.

int	windowIndex (const QString &windowId) const
	Get the index of a window.

bool	containsWindow (const QString &windowId) const override
	Check if a window is tracked.

int	masterCount () const override
	Get number of windows in master area.

void	setMasterCount (int count)
	Set number of windows in master area.

bool	isMaster (const QString &windowId) const
	Check if a window is in the master area.

QStringList	masterWindows () const
	Get windows currently in master area.

QStringList	stackWindows () const
	Get windows currently in stack area.

bool	promoteToMaster (const QString &windowId)
	Promote a window to master (move to position 0)

bool	moveToFront (const QString &windowId)
	Move a window to the front (alias for promoteToMaster)

bool	insertAfterFocused (const QString &windowId)
	Insert a window after the currently focused window.

bool	moveToPosition (const QString &windowId, int position)
	Move a window to a specific position by its ID.

int	windowPosition (const QString &windowId) const
	Get the position of a window (alias for windowIndex)

int	tiledWindowIndex (const QString &windowId) const
	Get the index of a window within the tiled-only list.

bool	moveToTiledPosition (const QString &windowId, int tiledPosition)
	Move a window to a specific position in the tiled-only list.

bool	rotateWindows (bool clockwise=true)
	Rotate all windows by one position.

qreal	splitRatio () const
	Get the master/stack split ratio.

void	setSplitRatio (qreal ratio)
	Set the master/stack split ratio.

void	increaseSplitRatio (qreal delta=0.05)
	Increase split ratio by delta.

void	decreaseSplitRatio (qreal delta=0.05)
	Decrease split ratio by delta.

bool	isFloating (const QString &windowId) const override
	Check if a window is floating (excluded from tiling)

void	setFloating (const QString &windowId, bool floating)
	Set a window's floating state.

bool	toggleFloating (const QString &windowId)
	Toggle a window's floating state.

QStringList	floatingWindows () const override
	Get list of floating windows.

QStringList	managedWindows () const override
	All windows managed by this state (tiled + floating).

QString	placementIdForWindow (const QString &windowId) const override
	Opaque placement identifier for the window's current slot.

QString	focusedWindow () const
	Get the currently focused window.

void	setFocusedWindow (const QString &windowId)
	Set the focused window.

int	focusedTiledIndex () const
	Get index of focused window in tiled list.

bool	floatingHasFocus () const
	Whether the float layer holds focus right now (derived)

void	clear ()
	Clear all state (remove all windows, reset to defaults)

void	setCalculatedZones (const QVector< QRect > &zones)
	Store calculated zone geometries.

QVector< QRect >	calculatedZones () const
	Get stored calculated zone geometries.

SplitTree *	splitTree () const
	Get the persistent split tree (may be null)

void	setSplitTree (std::unique_ptr< SplitTree > tree)
	Set or replace the split tree.

void	clearSplitTree ()
	Clear the split tree (e.g., on algorithm switch)

std::unique_ptr< SplitTree >	takeSplitTree ()
	Hand the split tree to the caller, leaving this state without one.

void	rebuildSplitTree ()
	Rebuild the split tree from the current tiled window order.

QJsonObject	scriptState () const
	Get the persistent per-algorithm script-state bag.

void	setScriptState (const QJsonObject &state)
	Replace the script-state bag wholesale.


QString	lastTiledFocus () const
	Layer-side focus memory for switch-focus-between-floating-and-tiling.

QString	lastFloatingFocus () const

Public Member Functions inherited from PhosphorEngine::IPlacementState
virtual	~IPlacementState ()=default

Static Public Member Functions
static QJsonObject	sanitizeScriptState (const QJsonObject &state)
	Validate and bound a script-written state bag at the trust boundary.

Detailed Description

Tracks tiling state for a single screen.

TilingState maintains all the mutable state needed for autotiling:

Window order (insertion order determines tiling position)
Master window count (how many windows in master area)
Split ratio (master vs stack area ratio)
Per-window floating state (excluded from tiling)

This class is used by AutotileEngine to track state and by TilingAlgorithm implementations to calculate zone geometries.

Note: Window IDs are KWin's internal resource names (QString).

Constructor & Destructor Documentation

◆ TilingState() [1/2]

PhosphorTiles::TilingState::TilingState	(	const QString &	screenId,
		QObject *	parent = `nullptr`
	)

explicit

Construct a TilingState for a specific screen.

Parameters

screenId	Unique identifier for the screen
parent	Parent QObject

◆ ~TilingState()

PhosphorTiles::TilingState::~TilingState ( )

override

◆ TilingState() [2/2]

PhosphorTiles::TilingState::TilingState ( const TilingState & )

delete

Member Function Documentation

◆ addWindow()

bool PhosphorTiles::TilingState::addWindow	(	const QString &	windowId,
		int	position = `-1`
	)

Add a window to the tiling.

Parameters

windowId	Window identifier
position	Insert position (-1 = end, 0 = beginning/master)

Returns: true if window was added; false if already tracked, invalid, or the state is at the MaxRuntimeTreeDepth tiled-window cap

◆ calculatedZones()

QVector< QRect > PhosphorTiles::TilingState::calculatedZones ( ) const

Get stored calculated zone geometries.

Returns: Zone geometries from last calculation

◆ clear()

void PhosphorTiles::TilingState::clear ( )

Clear all state (remove all windows, reset to defaults)

◆ clearSplitTree()

void PhosphorTiles::TilingState::clearSplitTree ( )

Clear the split tree (e.g., on algorithm switch)

◆ containsWindow()

bool PhosphorTiles::TilingState::containsWindow ( const QString & windowId ) const

overridevirtual

Check if a window is tracked.

Implements PhosphorEngine::IPlacementState.

◆ decreaseSplitRatio()

void PhosphorTiles::TilingState::decreaseSplitRatio ( qreal delta = 0.05 )

Decrease split ratio by delta.

Parameters

delta Amount to decrease (default 0.05)

◆ floatingChanged

void PhosphorTiles::TilingState::floatingChanged	(	const QString &	windowId,
		bool	floating
	)

signal

Emitted when a window's floating state changes.

Parameters

windowId	Affected window
floating	New floating state

Note: Also emitted with floating=false when a floating window is removed via removeWindow(), to ensure listeners clean up any floating-specific state. Check containsWindow() if needed.

◆ floatingHasFocus()

bool PhosphorTiles::TilingState::floatingHasFocus ( ) const

Whether the float layer holds focus right now (derived)

Derived from m_focusedWindow's membership in the float set rather than stored: autotile funnels every focus report through setFocusedWindow and has no self-activation echo filter swallowing reports, so for focus reports naming windows in THIS state the derivation cannot go stale the way a stored flag could. A state whose screen does not hold focus keeps its last m_focusedWindow by design (nothing clears focus on the losing screen), so the answer is only meaningful on the screen the report came from.

◆ floatingWindows()

QStringList PhosphorTiles::TilingState::floatingWindows ( ) const

overridevirtual

Get list of floating windows.

Implements PhosphorEngine::IPlacementState.

◆ focusedTiledIndex()

int PhosphorTiles::TilingState::focusedTiledIndex ( ) const

Get index of focused window in tiled list.

Returns: Index, or -1 when there is no focused window or the focused window is floating

◆ focusedWindow()

QString PhosphorTiles::TilingState::focusedWindow ( ) const

Get the currently focused window.

◆ focusedWindowChanged

void PhosphorTiles::TilingState::focusedWindowChanged ( )

signal

Emitted when focused window changes.

◆ increaseSplitRatio()

void PhosphorTiles::TilingState::increaseSplitRatio ( qreal delta = 0.05 )

Increase split ratio by delta.

Parameters

delta Amount to increase (default 0.05)

◆ insertAfterFocused()

bool PhosphorTiles::TilingState::insertAfterFocused ( const QString & windowId )

Insert a window after the currently focused window.

Parameters

windowId Window to insert

Returns: true if inserted successfully

◆ isFloating()

bool PhosphorTiles::TilingState::isFloating ( const QString & windowId ) const

overridevirtual

Check if a window is floating (excluded from tiling)

Implements PhosphorEngine::IPlacementState.

◆ isMaster()

bool PhosphorTiles::TilingState::isMaster ( const QString & windowId ) const

Check if a window is in the master area.

◆ lastFloatingFocus()

QString PhosphorTiles::TilingState::lastFloatingFocus ( ) const

◆ lastTiledFocus()

QString PhosphorTiles::TilingState::lastTiledFocus ( ) const

Layer-side focus memory for switch-focus-between-floating-and-tiling.

m_focusedWindow is a single slot shared by tiles and floats, so a float taking focus erases the answer to "which tile do I return to". These remember the last focus PER LAYER: written by setFocusedWindow (classified against the float set) and by setFloating when the FOCUSED window changes layer with no focus report coming (the layer moved under the focus, mirroring the scroll engine's floatWindowInternal active-tile arm — the new side inherits, the old side drops). A NON-focused window's layer change leaves the memories alone: they are advisory, validated at every read, and retention is what lets engine-internal transient floats (drag-eviction, overflow churn) round-trip without erasing the remembered tile. Cleared when the remembered window leaves the state (removeWindow, clear). Not serialized — focus history dies with the session. Consumers validate before use (the switch verb's eligibility filter), so a stale value is a fallback-scan, never a wrong activation.

◆ managedWindows()

QStringList PhosphorTiles::TilingState::managedWindows ( ) const

overridevirtual

All windows managed by this state (tiled + floating).

Implements PhosphorEngine::IPlacementState.

◆ masterCount()

int PhosphorTiles::TilingState::masterCount ( ) const

overridevirtual

Get number of windows in master area.

Reimplemented from PhosphorEngine::IPlacementState.

◆ masterCountChanged

void PhosphorTiles::TilingState::masterCountChanged ( )

signal

Emitted when master count changes.

◆ masterWindows()

QStringList PhosphorTiles::TilingState::masterWindows ( ) const

Get windows currently in master area.

◆ moveToFront()

bool PhosphorTiles::TilingState::moveToFront ( const QString & windowId )

Move a window to the front (alias for promoteToMaster)

Parameters

windowId Window to move

Returns: true if window found and moved

◆ moveToPosition()

bool PhosphorTiles::TilingState::moveToPosition	(	const QString &	windowId,
		int	position
	)

Move a window to a specific position by its ID.

Parameters

windowId	Window to move
position	Target position

Returns: true if move was successful

◆ moveToTiledPosition()

bool PhosphorTiles::TilingState::moveToTiledPosition	(	const QString &	windowId,
		int	tiledPosition
	)

Move a window to a specific position in the tiled-only list.

Parameters

windowId	Window to move
tiledPosition	Target position in tiled list (skipping floating)

Returns: true if move was successful

◆ moveWindow()

bool PhosphorTiles::TilingState::moveWindow	(	int	fromIndex,
		int	toIndex
	)

Move a window to a different position.

Parameters

fromIndex	Current position
toIndex	Target position

Returns: true if move was successful

◆ operator=()

TilingState & PhosphorTiles::TilingState::operator= ( const TilingState & )

delete

◆ placementIdForWindow()

QString PhosphorTiles::TilingState::placementIdForWindow ( const QString & windowId ) const

overridevirtual

Opaque placement identifier for the window's current slot.

Snap mode: zone UUID. Autotile mode: tiling-order index as string. Empty if the window is floating or unassigned.

NO in-tree caller today — the three implementations are reached only from their own tests. Kept because it is the one piece of this interface that answers "where is this window" in a form comparable ACROSS modes, which is what a cross-mode restore or a support bundle would need, and each implementation is a handful of lines over state it already holds. Anyone auditing for dead code has now found this note rather than the silence; delete it if the answer is still no consumer.

Implements PhosphorEngine::IPlacementState.

◆ promoteToMaster()

bool PhosphorTiles::TilingState::promoteToMaster ( const QString & windowId )

Promote a window to master (move to position 0)

Parameters

windowId Window to promote

Returns: true if window found and promoted

◆ rebuildSplitTree()

void PhosphorTiles::TilingState::rebuildSplitTree ( )

Rebuild the split tree from the current tiled window order.

Used after operations that reorder windows (move, promote, rotate) to preserve the tree's existence while matching the new order. Split ratios are preserved positionally where possible, so DwindleMemoryAlgorithm doesn't fall back to stateless mode.

◆ removeWindow()

bool PhosphorTiles::TilingState::removeWindow ( const QString & windowId )

Remove a window from the tiling.

Parameters

windowId Window to remove

Returns: true if window was found and removed

◆ rotateWindows()

bool PhosphorTiles::TilingState::rotateWindows ( bool clockwise = true )

Rotate all windows by one position.

Clockwise: each window moves to the next position, last becomes first Counterclockwise: each window moves to the previous position, first becomes last

Parameters

clockwise Direction of rotation

Returns: true if rotation was performed (at least 2 windows)

◆ sanitizeScriptState()

static QJsonObject PhosphorTiles::TilingState::sanitizeScriptState ( const QJsonObject & state )

static

Validate and bound a script-written state bag at the trust boundary.

Enforces the AutotileDefaults::ScriptState* limits (compact-JSON byte cap, nesting depth, total key count) and strips non-finite numbers. Returns the sanitized object, or an empty object if the bag exceeds the byte cap and can't be safely stored. Applied on the scripted-algorithm write-back path, which is the only place an UNTRUSTED bag originates. The engine's stash hands back a bag that went through here on its way in.

◆ screenId()

QString PhosphorTiles::TilingState::screenId ( ) const

overridevirtual

Get the screen ID this state belongs to.

Implements PhosphorEngine::IPlacementState.

◆ scriptState()

QJsonObject PhosphorTiles::TilingState::scriptState ( ) const

Get the persistent per-algorithm script-state bag.

An opaque JSON object that scripted algorithms read (exposed as ctx.state) and write back (via the onWindowResized hook return) to remember layout adjustments — e.g. an aligned grid's column widths — across retiles. Empty by default. The engine never interprets it.

◆ setCalculatedZones()

void PhosphorTiles::TilingState::setCalculatedZones ( const QVector< QRect > & zones )

Store calculated zone geometries.

Called by AutotileEngine after algorithm computes zones. Stored for later application to windows.

Parameters

zones Calculated zone geometries (one per tiled window)

◆ setFloating()

void PhosphorTiles::TilingState::setFloating	(	const QString &	windowId,
		bool	floating
	)

Set a window's floating state.

Parameters

windowId	Window to modify
floating	true to exclude from tiling

◆ setFocusedWindow()

void PhosphorTiles::TilingState::setFocusedWindow ( const QString & windowId )

Set the focused window.

Parameters

windowId Window that received focus

◆ setMasterCount()

void PhosphorTiles::TilingState::setMasterCount ( int count )

Set number of windows in master area.

Parameters

count New master count (clamped to AutotileDefaults:: MinMasterCount..MaxMasterCount; algorithms clamp operationally against the window count)

◆ setScriptState()

void PhosphorTiles::TilingState::setScriptState ( const QJsonObject & state )

Replace the script-state bag wholesale.

Callers must pass already-sanitized JSON (see sanitizeScriptState in tilingstatedata.cpp). No NOTIFY signal: this is internal state, not a UI-observable property, and writing it must never schedule a retile (that would risk a resize→retile→resize loop).

◆ setSplitRatio()

void PhosphorTiles::TilingState::setSplitRatio ( qreal ratio )

Set the master/stack split ratio.

Parameters

ratio New ratio (clamped to 0.1..0.9)

◆ setSplitTree()

void PhosphorTiles::TilingState::setSplitTree ( std::unique_ptr< SplitTree > tree )

Set or replace the split tree.

Parameters

tree	Ownership transferred to TilingState

◆ splitRatio()

qreal PhosphorTiles::TilingState::splitRatio ( ) const

Get the master/stack split ratio.

Returns: Ratio where 0.6 = master gets 60% of width

◆ splitRatioChanged

void PhosphorTiles::TilingState::splitRatioChanged ( )

signal

Emitted when split ratio changes.

◆ splitTree()

SplitTree * PhosphorTiles::TilingState::splitTree ( ) const

Get the persistent split tree (may be null)

Used by DwindleMemoryAlgorithm to read the tree structure. Returns nullptr if no split tree has been created for this state.

◆ stackWindows()

QStringList PhosphorTiles::TilingState::stackWindows ( ) const

Get windows currently in stack area.

◆ stateChanged

void PhosphorTiles::TilingState::stateChanged ( )

signal

Emitted when any state change requires retiling.

◆ swapWindows()

bool PhosphorTiles::TilingState::swapWindows	(	int	index1,
		int	index2
	)

Swap two windows' positions.

Parameters

index1	First window position
index2	Second window position

Returns: true if swap was successful

◆ swapWindowsById()

bool PhosphorTiles::TilingState::swapWindowsById	(	const QString &	windowId1,
		const QString &	windowId2
	)

Swap two windows by their IDs.

Parameters

windowId1	First window ID
windowId2	Second window ID

Returns: true if both windows found and swapped

◆ takeSplitTree()

std::unique_ptr< SplitTree > PhosphorTiles::TilingState::takeSplitTree ( )

Hand the split tree to the caller, leaving this state without one.

For rescuing a tree out of a state that is about to be destroyed. Returns null when there is no tree. Unlike splitTree() this transfers ownership, so the tree outlives the state rather than being serialized to survive it.

◆ tiledWindowCount()

int PhosphorTiles::TilingState::tiledWindowCount ( ) const

overridevirtual

Get number of tiled windows (excluding floating)

Reimplemented from PhosphorEngine::IPlacementState.

◆ tiledWindowIndex()

int PhosphorTiles::TilingState::tiledWindowIndex ( const QString & windowId ) const

Get the index of a window within the tiled-only list.

Parameters

windowId Window to find

Returns: Index in tiled window list (skipping floating), or -1 if not found

◆ tiledWindows()

QStringList PhosphorTiles::TilingState::tiledWindows ( ) const

Get only tiled (non-floating) windows in order.

◆ toggleFloating()

bool PhosphorTiles::TilingState::toggleFloating ( const QString & windowId )

Toggle a window's floating state.

Parameters

windowId Window to toggle

Returns: Current floating state after toggle (unchanged if window not tracked)

◆ windowCount()

int PhosphorTiles::TilingState::windowCount ( ) const

overridevirtual

Get total number of tracked windows (including floating)

Implements PhosphorEngine::IPlacementState.

◆ windowCountChanged

void PhosphorTiles::TilingState::windowCountChanged ( )

signal

Emitted when window count changes (add/remove)

◆ windowIndex()

int PhosphorTiles::TilingState::windowIndex ( const QString & windowId ) const

Get the index of a window.

Parameters

windowId Window to find

Returns: Index in window order, or -1 if not found

◆ windowOrder()

QStringList PhosphorTiles::TilingState::windowOrder ( ) const

Get the ordered list of window IDs.

Returns: Window IDs in tiling order (first = master, rest = stack)

◆ windowOrderChanged

void PhosphorTiles::TilingState::windowOrderChanged ( )

signal

Emitted when window order changes (move/swap)

◆ windowPosition()

int PhosphorTiles::TilingState::windowPosition ( const QString & windowId ) const

Get the position of a window (alias for windowIndex)

Parameters

windowId Window to find

Returns: Index in the raw window order (floating windows included), or -1 if not found. Use tiledWindowIndex() for the tiled-only index.

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

phosphor-tiles/include/PhosphorTiles/TilingState.h

Phosphor Qt6 / Wayland library suite for window-management tools

Signals

Public Member Functions

Static Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ TilingState() [1/2]

◆ ~TilingState()

◆ TilingState() [2/2]

Member Function Documentation

◆ addWindow()

◆ calculatedZones()

◆ clear()

◆ clearSplitTree()

◆ containsWindow()

◆ decreaseSplitRatio()

◆ floatingChanged

◆ floatingHasFocus()

◆ floatingWindows()

◆ focusedTiledIndex()

◆ focusedWindow()

◆ focusedWindowChanged

◆ increaseSplitRatio()

◆ insertAfterFocused()

◆ isFloating()

◆ isMaster()

◆ lastFloatingFocus()

◆ lastTiledFocus()

◆ managedWindows()

◆ masterCount()

◆ masterCountChanged

◆ masterWindows()

◆ moveToFront()

◆ moveToPosition()

◆ moveToTiledPosition()

◆ moveWindow()

◆ operator=()

◆ placementIdForWindow()

◆ promoteToMaster()

◆ rebuildSplitTree()

◆ removeWindow()

◆ rotateWindows()

◆ sanitizeScriptState()

◆ screenId()

◆ scriptState()

◆ setCalculatedZones()

◆ setFloating()

◆ setFocusedWindow()

◆ setMasterCount()

◆ setScriptState()

◆ setSplitRatio()

◆ setSplitTree()

◆ splitRatio()

◆ splitRatioChanged

◆ splitTree()

◆ stackWindows()

◆ stateChanged

◆ swapWindows()

◆ swapWindowsById()

◆ takeSplitTree()

◆ tiledWindowCount()

◆ tiledWindowIndex()

◆ tiledWindows()

◆ toggleFloating()

◆ windowCount()

◆ windowCountChanged

◆ windowIndex()

◆ windowOrder()

◆ windowOrderChanged

◆ windowPosition()