Core engine for automatic window tiling. More...

#include <phosphor-tile-engine/include/PhosphorTileEngine/AutotileEngine.h>

Inheritance diagram for PhosphorTileEngine::AutotileEngine:

Public Types
using	ShouldPersistRestorePredicate = std::function< bool(const QString &screenId, int desktop, const QString &activity)>
	Predicate consulted before persisting or honoring a pending restore.

Signals
void	enabledChanged (bool enabled)
	Emitted when the enabled state changes.

void	autotileScreensChanged (const QStringList &screenIds, bool isDesktopSwitch)
	Emitted when the set of autotile screens changes.

void	windowsTiled (const QString &tileRequestsJson)
	Emitted when a window's floating state changes due to a user action.

Signals inherited from PhosphorEngine::PlacementEngineBase
void	geometryRestoreRequested (const QString &windowId, const QRect &geometry, const QString &screenId)

void	windowStateTransitioned (const QString &windowId, WindowState oldState, WindowState newState)

void	navigationFeedback (bool success, const QString &action, const QString &reason, const QString &sourceId, const QString &targetId, const QString &screenId)

void	windowFloatingChanged (const QString &windowId, bool floating, const QString &screenId)

void	activateWindowRequested (const QString &windowId)

void	windowFloatingStateSynced (const QString &windowId, bool floating, const QString &screenId)
	Emitted to sync floating state without restoring geometry.

void	windowsBatchFloated (const QStringList &windowIds, const QString &screenId)
	Emitted when overflow windows are batch-floated during applyTiling.

void	algorithmChanged (const QString &algorithmId)
	Emitted when the active tiling algorithm changes.

void	placementChanged (const QString &screenId)
	Emitted when the placement layout changes for a screen.

void	windowsReleased (const QStringList &windowIds, const QSet< QString > &releasedScreenIds)
	Emitted when windows are released from engine management.

void	settingsPersistRequested ()
	Emitted when the engine writes tuning values back to the settings object and wants the daemon to persist them to disk.

Public Member Functions
	AutotileEngine (PhosphorZones::LayoutRegistry layoutManager, PhosphorEngine::IWindowTrackingService windowTracker, Phosphor::Screens::ScreenManager screenManager, PhosphorTiles::ITileAlgorithmRegistry algorithmRegistry, QObject *parent=nullptr)

	~AutotileEngine () override

PhosphorTiles::ITileAlgorithmRegistry *	algorithmRegistry () const
	The injected tile-algorithm registry. Borrowed — owner outlives the engine.

void	setWindowRegistry (QObject *registry) override
	Wire up the shared WindowRegistry.

bool	isEnabled () const noexcept override
	Check if any screen has autotile enabled.

QSet< int >	desktopsWithActiveState () const override
	Return the set of virtual-desktop numbers that currently have any tiling state.

bool	isAutotileScreen (const QString &screenId) const
	Check if a specific screen uses autotile.

bool	isWindowTracked (const QString &windowId) const override
	Check if a window is currently tracked in any autotile state.

bool	isWindowTiled (const QString &windowId) const override
	Check if a window is currently tiled (tracked AND not floating).

bool	isActiveOnScreen (const QString &screenId) const override
	Whether this engine is active on the given screen.

QSet< QString >	activeScreens () const override

void	setActiveScreens (const QSet< QString > &screens) override

QStringList	managedWindowOrder (const QString &screenId) const override

bool	isModeSpecificFloated (const QString &windowId) const override

void	clearModeSpecificFloatMarker (const QString &windowId) override

bool	isWindowManaged (const QString &windowId) const override
	Whether the engine considers the window "managed" (eligible for layout operations).

QString	algorithmId () const override

void	markModeSpecificFloated (const QString &windowId) override

const QSet< QString > &	autotileScreens () const
	Get the set of screens currently using autotile.

QString	activeScreen () const override
	Get the last-focused screen (updated by onWindowFocused)

void	setAutotileScreens (const QSet< QString > &screens)
	Set which screens use autotile (derived from layout assignments)

void	setCurrentDesktop (int desktop) override
	Set the current virtual desktop for per-desktop tiling state.

void	setCurrentActivity (const QString &activity) override
	Set the current activity for per-activity tiling state.

void	updateStickyScreenPins (const std::function< bool(const QString &)> &isWindowSticky) override
	Pin screens where all autotiled windows are sticky (on all desktops)

void	pruneStatesForDesktop (int removedDesktop) override
	Prune PhosphorTiles::TilingState and saved floating entries for a removed desktop.

void	pruneStatesForActivities (const QStringList &validActivities) override
	Prune PhosphorTiles::TilingState entries for activities not in the given set.

int	currentDesktop () const noexcept
	Get the current virtual desktop tracked by the engine.

const QString &	currentActivity () const noexcept
	Get the current activity tracked by the engine.

QString	algorithm () const noexcept
	Get current algorithm ID.

void	setAlgorithm (const QString &algorithmId) override
	Set the tiling algorithm.

PhosphorTiles::TilingAlgorithm *	currentAlgorithm () const
	Get the current algorithm instance.

PhosphorTiles::TilingState *	tilingStateForScreen (const QString &screenId)
	Get the tiling state for a specific screen.

PhosphorEngine::IPlacementState *	stateForScreen (const QString &screenId) override
	Per-screen state object for the given screen.

const PhosphorEngine::IPlacementState *	stateForScreen (const QString &screenId) const override

AutotileConfig *	config () const noexcept
	Get the autotile configuration.

void	saveState () override
	Save tiling state via persistence delegate (IPlacementEngine contract)

void	loadState () override
	Load tiling state via persistence delegate (IPlacementEngine contract)

void	setPersistenceDelegate (std::function< void()> saveFn, std::function< void()> loadFn)
	Set persistence callbacks for save/load.

void	setIsWindowFloatingFn (std::function< bool(const QString &)> fn) override
	Set callback to query daemon-side window floating state.

QString	engineId () const override
	Stable engine identity for HandoffContext.fromEngineId.

void	handoffReceive (const HandoffContext &ctx) override
	Receive ownership of a window from another engine.

void	handoffRelease (const QString &windowId) override
	Release ownership of a window WITHOUT modifying its geometry.

QString	screenForTrackedWindow (const QString &windowId) const override
	Return the screen this engine considers the window to be on, or empty if the window isn't tracked by this engine.

QJsonArray	serializeWindowOrders () const override
	Serialize per-context autotile window orders to JSON.

void	deserializeWindowOrders (const QJsonArray &orders) override
	Deserialize per-context autotile window orders from JSON.

QJsonObject	serializePendingRestores () const override
	Serialize pending autotile restore queues to JSON.

void	deserializePendingRestores (const QJsonObject &obj) override
	Deserialize pending autotile restore queues from JSON.

int	pruneExcludedPendingRestores (const QStringList &exclusionPatterns)
	Drop pending-restore queues whose appId matches any exclusion pattern.

void	setShouldPersistRestorePredicate (ShouldPersistRestorePredicate predicate)
	Inject the persist-restore gate.

PhosphorEngine::IAutotileSettings *	autotileSettings () const

void	writeBackTuning ()

void	refreshConfigFromSettings () override
	Re-read all tuning values from the engine's settings interface.

void	applyPerScreenConfig (const QString &screenId, const QVariantMap &overrides) override

void	clearPerScreenConfig (const QString &screenId) override

QVariantMap	perScreenOverrides (const QString &screenId) const override

bool	hasPerScreenOverride (const QString &screenId, const QString &key) const

void	updatePerScreenOverride (const QString &screenId, const QString &key, const QVariant &value)

int	effectiveInnerGap (const QString &screenId) const

int	effectiveOuterGap (const QString &screenId) const

::PhosphorLayout::EdgeGaps	effectiveOuterGaps (const QString &screenId) const

bool	effectiveSmartGaps (const QString &screenId) const

bool	effectiveRespectMinimumSize (const QString &screenId) const

int	effectiveMaxWindows (const QString &screenId) const

qreal	effectiveSplitRatioStep (const QString &screenId) const override

int	runtimeMaxWindows () const override
	Runtime max-windows limit.

QString	effectiveAlgorithmId (const QString &screenId) const

PhosphorTiles::TilingAlgorithm *	effectiveAlgorithm (const QString &screenId) const

void	setInnerGap (int gap)

void	setOuterGap (int gap)

void	setSmartGaps (bool enabled)

void	setFocusNewWindows (bool enabled)

void	retile (const QString &screenId=QString()) override
	Force retiling of windows.

void	swapWindows (const QString &windowId1, const QString &windowId2)
	Swap positions of two tiled windows.

void	promoteToMaster (const QString &windowId)
	Promote a window to the master area.

void	demoteFromMaster (const QString &windowId)
	Demote a window from the master area.

void	swapFocusedWithMaster () override
	Swap the currently focused window with the master window.

void	focusNext ()
	Focus the next tiled window.

void	focusPrevious ()
	Focus the previous tiled window.

void	focusMaster () override
	Focus the master window.

void	setFocusedWindow (const QString &windowId)
	Notify the engine that a window has been focused.

void	setActiveScreenHint (const QString &screenId) override
	Set the active screen hint for keyboard shortcut handlers.

void	increaseMasterRatio (qreal delta=0.05) override
	Increase the master area ratio.

void	decreaseMasterRatio (qreal delta=0.05) override
	Decrease the master area ratio.

void	setGlobalSplitRatio (qreal ratio)
	Set master ratio globally (config + all per-screen states)

void	setGlobalMasterCount (int count)
	Set master count globally (config + all per-screen states)

void	increaseMasterCount () override
	Increase the number of master windows.

void	decreaseMasterCount () override
	Decrease the number of master windows.

void	rotateWindowOrder (bool clockwise=true)
	Rotate all tiled windows by one position.

void	toggleFocusedWindowFloat ()
	Toggle the focused window between tiled and floating states.

void	toggleWindowFloat (const QString &windowId, const QString &screenId) override
	Toggle a specific window between tiled and floating states.

void	swapFocusedInDirection (const QString &direction, const QString &action=QStringLiteral("move"))
	Swap the focused window with the adjacent window in tiling order.

void	focusInDirection (const QString &direction, const QString &action=QStringLiteral("focus"))
	Focus the adjacent window in tiling order with OSD feedback.

void	moveFocusedToPosition (int position)
	Move the focused window to a specific position in the tiling order.

void	focusInDirection (const QString &direction, const PhosphorEngine::NavigationContext &ctx) override
	Move keyboard focus to the adjacent window.

void	moveFocusedInDirection (const QString &direction, const PhosphorEngine::NavigationContext &ctx) override
	Move the focused window to the adjacent slot.

void	swapFocusedInDirection (const QString &direction, const PhosphorEngine::NavigationContext &ctx) override
	Swap the focused window with the adjacent window.

void	moveFocusedToPosition (int position, const PhosphorEngine::NavigationContext &ctx) override
	Move the focused window to the Nth position.

void	rotateWindows (bool clockwise, const PhosphorEngine::NavigationContext &ctx) override
	Rotate all managed windows on the screen.

void	reapplyLayout (const PhosphorEngine::NavigationContext &ctx) override
	Re-apply the current layout to all managed windows.

void	snapAllWindows (const PhosphorEngine::NavigationContext &ctx) override
	Snap every unmanaged window on the screen to the current layout.

void	toggleFocusedFloat (const PhosphorEngine::NavigationContext &ctx) override
	Toggle the focused window between managed and floating.

void	cycleFocus (bool forward, const PhosphorEngine::NavigationContext &ctx) override
	Cycle keyboard focus through managed windows.

void	pushToEmptyZone (const PhosphorEngine::NavigationContext &ctx) override
	Move the focused window to the first empty slot.

void	restoreFocusedWindow (const PhosphorEngine::NavigationContext &ctx) override
	Restore the focused window out of its managed state.

void	swapInDirection (const QString &direction, const QString &action)

void	rotateWindows (bool clockwise, const QString &screenId)

void	moveToPosition (const QString &windowId, int position, const QString &screenId)

void	setWindowFloat (const QString &windowId, bool shouldFloat) override
	Set the floating state of a specific window.

void	floatWindow (const QString &windowId)
	Float a specific window by its ID (convenience forwarder)

void	unfloatWindow (const QString &windowId)
	Unfloat a specific window by its ID (convenience forwarder)

void	setInitialWindowOrder (const QString &screenId, const QStringList &windowIds) override
	Pre-seed initial window order for deterministic snapping → autotile transitions.

void	clearSavedFloatingForWindows (const QStringList &windowIds) override
	Clear saved floating state for windows that are actively zone-snapped.

void	clearAllSavedFloating () override
	Clear ALL saved floating state (used when autotile is disabled globally)

QStringList	tiledWindowOrder (const QString &screenId) const
	Get the current tiled window order for a screen.

void	windowOpened (const QString &windowId, const QString &screenId, int minWidth, int minHeight) override
	A new window appeared on this engine's screen.

void	windowMinSizeUpdated (const QString &windowId, int minWidth, int minHeight)
	Update a window's minimum size at runtime.

void	windowClosed (const QString &windowId) override
	Notify the engine that a window was closed.

void	windowFocused (const QString &windowId, const QString &screenId) override
	Notify the engine that a window was focused.

void	scheduleRetileForScreen (const QString &screenId) override
	Schedule a deferred retile for a screen.

bool	beginDragInsertPreview (const QString &windowId, const QString &screenId) override
	Begin a drag-insert preview for a window already tiled on a screen.

void	updateDragInsertPreview (int insertIndex) override
	Update the target insert index for the active drag preview.

void	commitDragInsertPreview () override
	Commit the active drag-insert preview.

void	cancelDragInsertPreview () override
	Cancel the active drag-insert preview, restoring the original order.

int	computeDragInsertIndexAtPoint (const QString &screenId, const QPoint &cursorPos) const override
	Compute the insert index for a cursor position on an autotile screen.

bool	hasDragInsertPreview () const override
	Query whether a drag-insert preview is currently active.

QString	dragInsertPreviewWindowId () const
	Get the window ID of the active drag-insert preview, or empty.

QString	dragInsertPreviewScreenId () const override
	Get the target screen ID of the active drag-insert preview, or empty.

void	retileAfterOperation (const QString &screenId, bool operationSucceeded)
	Helper to retile a screen after a window operation.

void	markAutotileFloated (const QString &windowId)

void	clearAutotileFloated (const QString &windowId)

bool	isAutotileFloated (const QString &windowId) const

int	pruneStaleWindows (const QSet< QString > &aliveWindowIds) override

Public Member Functions inherited from PhosphorEngine::PlacementEngineBase
WindowState	windowState (const QString &windowId) const

void	claimWindow (const QString &windowId, const QRect &geometry, const QString &screenId, bool overwrite=false)

void	releaseWindow (const QString &windowId)

void	floatWindow (const QString &windowId)

void	unfloatWindow (const QString &windowId)

QRect	unmanagedGeometry (const QString &windowId) const

QString	unmanagedScreen (const QString &windowId) const

bool	hasUnmanagedGeometry (const QString &windowId) const

void	clearUnmanagedGeometry (const QString &windowId)

void	forgetWindow (const QString &windowId)

void	storeUnmanagedGeometry (const QString &windowId, const QRect &geometry, const QString &screenId, bool overwrite=false)

const QHash< QString, UnmanagedEntry > &	unmanagedGeometries () const

void	setUnmanagedGeometries (const QHash< QString, UnmanagedEntry > &geos)

QJsonObject	serializeBaseState () const

void	deserializeBaseState (const QJsonObject &state)

void	setEngineSettings (QObject *settings)

QObject *	engineSettings () const

	~PlacementEngineBase () override

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

void	windowOpened (const QString &windowId, const QString &screenId)
	Convenience overload — equivalent to windowOpened(id, screen, 0, 0).

virtual bool	restoreSavedModeFloat (const QString &windowId)

virtual void	saveModeFloat (const QString &windowId)

virtual void	clearSavedModeFloating ()

virtual QJsonObject	serializeEngineState () const

virtual void	deserializeEngineState (const QJsonObject &state)

Protected Member Functions
void	onWindowClaimed (const QString &windowId) override

void	onWindowReleased (const QString &windowId) override

void	onWindowFloated (const QString &windowId) override

void	onWindowUnfloated (const QString &windowId) override

Protected Member Functions inherited from PhosphorEngine::PlacementEngineBase
	PlacementEngineBase (QObject *parent=nullptr)

Detailed Description

Core engine for automatic window tiling.

Coordinates per-screen PhosphorTiles::TilingState, invokes tiling algorithms (Master-Stack, Columns, BSP), and applies calculated zone geometries to window positions. Only tiles windows on screens where autotiling is enabled.

See also: PhosphorTiles::TilingAlgorithm, PhosphorTiles::TilingState, PhosphorTiles::AlgorithmRegistry

Member Typedef Documentation

◆ ShouldPersistRestorePredicate

using PhosphorTileEngine::AutotileEngine::ShouldPersistRestorePredicate = std::function<bool(const QString& screenId, int desktop, const QString& activity)>

Predicate consulted before persisting or honoring a pending restore.

Returns true to keep the entry, false to drop it. Mirrors the snap-side PhosphorPlacement::WindowTrackingService::ShouldTrackPredicate but adds an activity parameter because autotile pending-restore entries carry an activity tag (snap does not — see SnapState).

Applied at three points:

removeWindow() — live write gate: a closed window on a disabled context is never appended to m_pendingAutotileRestores in the first place. Matches snap's gate in WindowTrackingService::windowClosed.
serializePendingRestores() — drops in-memory entries that became disabled mid-session before they reach disk.
deserializePendingRestores() — drops on-disk entries authored under an older config or by a daemon that didn't have the gate.

The engine library is intentionally settings-agnostic (LGPL boundary), so the daemon adaptor injects the predicate. When unset the engine behaves as if every context is active — the historical default that unit tests rely on.

Constructor & Destructor Documentation

◆ AutotileEngine()

PhosphorTileEngine::AutotileEngine::AutotileEngine	(	PhosphorZones::LayoutRegistry *	layoutManager,
		PhosphorEngine::IWindowTrackingService *	windowTracker,
		Phosphor::Screens::ScreenManager *	screenManager,
		PhosphorTiles::ITileAlgorithmRegistry *	algorithmRegistry,
		QObject *	parent = `nullptr`
	)

explicit

◆ ~AutotileEngine()

PhosphorTileEngine::AutotileEngine::~AutotileEngine ( )

override

Member Function Documentation

◆ activeScreen()

QString PhosphorTileEngine::AutotileEngine::activeScreen ( ) const

inlineoverridevirtual

Get the last-focused screen (updated by onWindowFocused)

Returns: Screen ID of the most recently focused screen, or empty string

Reimplemented from PhosphorEngine::IPlacementEngine.

◆ activeScreens()

QSet< QString > PhosphorTileEngine::AutotileEngine::activeScreens ( ) const

inlineoverridevirtual

Reimplemented from PhosphorEngine::IPlacementEngine.

◆ algorithm()

QString PhosphorTileEngine::AutotileEngine::algorithm ( ) const

noexcept

Get current algorithm ID.

Returns: Algorithm identifier (e.g., "master-stack")

◆ algorithmId()

QString PhosphorTileEngine::AutotileEngine::algorithmId ( ) const

inlineoverridevirtual

Reimplemented from PhosphorEngine::IPlacementEngine.

◆ algorithmRegistry()

PhosphorTiles::ITileAlgorithmRegistry * PhosphorTileEngine::AutotileEngine::algorithmRegistry ( ) const

inline

The injected tile-algorithm registry. Borrowed — owner outlives the engine.

◆ applyPerScreenConfig()

void PhosphorTileEngine::AutotileEngine::applyPerScreenConfig	(	const QString &	screenId,
		const QVariantMap &	overrides
	)

overridevirtual

Reimplemented from PhosphorEngine::IPlacementEngine.

◆ autotileScreens()

const QSet< QString > & PhosphorTileEngine::AutotileEngine::autotileScreens ( ) const

inline

Get the set of screens currently using autotile.

Returns: Set of screen names with autotile assignments

◆ autotileScreensChanged

void PhosphorTileEngine::AutotileEngine::autotileScreensChanged	(	const QStringList &	screenIds,
		bool	isDesktopSwitch
	)

signal

Emitted when the set of autotile screens changes.

Parameters

screenIds	List of screen IDs using autotile
isDesktopSwitch	True if caused by desktop/activity switch (not user toggle)

◆ autotileSettings()

PhosphorEngine::IAutotileSettings * PhosphorTileEngine::AutotileEngine::autotileSettings ( ) const

◆ beginDragInsertPreview()

bool PhosphorTileEngine::AutotileEngine::beginDragInsertPreview	(	const QString &	windowId,
		const QString &	screenId
	)

overridevirtual

Begin a drag-insert preview for a window already tiled on a screen.

Captures the window's current position so it can be restored on cancel. While a preview is active, applyTiling() skips emitting geometry for the dragged window — KWin's interactive move remains in control — but still animates the other windows shifting to leave a gap at the preview index.

Returns: true if the window is tiled on the screen and preview was started.

Reimplemented from PhosphorEngine::IPlacementEngine.

◆ cancelDragInsertPreview()

void PhosphorTileEngine::AutotileEngine::cancelDragInsertPreview ( )

overridevirtual

Cancel the active drag-insert preview, restoring the original order.

Reimplemented from PhosphorEngine::IPlacementEngine.

◆ clearAllSavedFloating()

void PhosphorTileEngine::AutotileEngine::clearAllSavedFloating ( )

overridevirtual

Clear ALL saved floating state (used when autotile is disabled globally)

Prevents stale entries from incorrectly floating windows on next activation.

Reimplemented from PhosphorEngine::IPlacementEngine.

◆ clearAutotileFloated()

void PhosphorTileEngine::AutotileEngine::clearAutotileFloated ( const QString & windowId )

◆ clearModeSpecificFloatMarker()

void PhosphorTileEngine::AutotileEngine::clearModeSpecificFloatMarker ( const QString & windowId )

inlineoverridevirtual

Reimplemented from PhosphorEngine::IPlacementEngine.

◆ clearPerScreenConfig()

void PhosphorTileEngine::AutotileEngine::clearPerScreenConfig ( const QString & screenId )

overridevirtual

Reimplemented from PhosphorEngine::IPlacementEngine.

◆ clearSavedFloatingForWindows()

void PhosphorTileEngine::AutotileEngine::clearSavedFloatingForWindows ( const QStringList & windowIds )

overridevirtual

Clear saved floating state for windows that are actively zone-snapped.

Called during snapping → autotile transitions so that windows the user re-snapped in manual mode aren't incorrectly restored as floating.

Parameters

windowIds Windows to remove from the saved floating set

Reimplemented from PhosphorEngine::IPlacementEngine.

◆ commitDragInsertPreview()

void PhosphorTileEngine::AutotileEngine::commitDragInsertPreview ( )

overridevirtual

Commit the active drag-insert preview.

Clears preview state and retiles normally so the dragged window's geometry is applied (KWin is finishing the interactive move and will accept the geometry set).

Reimplemented from PhosphorEngine::IPlacementEngine.

◆ computeDragInsertIndexAtPoint()

int PhosphorTileEngine::AutotileEngine::computeDragInsertIndexAtPoint	(	const QString &	screenId,
		const QPoint &	cursorPos
	)		const

overridevirtual

Compute the insert index for a cursor position on an autotile screen.

Walks the screen's current calculated zones and returns the index of the first zone that contains the cursor. Returns the last tiled index as a fallback when the cursor is beyond all zones, or -1 if the screen has no tiling state. updateDragInsertPreview() clamps to [0, tiledWindowCount()-1], so returning the last slot is equivalent to "append".

The dragged window's zone is intentionally NOT excluded from the hit test: cursor-over-own-zone returns its current index (stable identity), preventing an oscillating shuffle where moving to a neighbour slot immediately re-matches under the cursor every dragMoved tick.

Reimplemented from PhosphorEngine::IPlacementEngine.

◆ config()

AutotileConfig * PhosphorTileEngine::AutotileEngine::config ( ) const

noexcept

Get the autotile configuration.

Returns: Pointer to configuration

◆ currentActivity()

const QString & PhosphorTileEngine::AutotileEngine::currentActivity ( ) const

inlinenoexcept

Get the current activity tracked by the engine.

◆ currentAlgorithm()

PhosphorTiles::TilingAlgorithm * PhosphorTileEngine::AutotileEngine::currentAlgorithm ( ) const

Get the current algorithm instance.

Returns: Pointer to algorithm, or nullptr if none set

◆ currentDesktop()

int PhosphorTileEngine::AutotileEngine::currentDesktop ( ) const

inlinenoexcept

Get the current virtual desktop tracked by the engine.

◆ cycleFocus()

void PhosphorTileEngine::AutotileEngine::cycleFocus	(	bool	forward,
		const PhosphorEngine::NavigationContext &	ctx
	)

overridevirtual

Cycle keyboard focus through managed windows.

Implements PhosphorEngine::IPlacementEngine.

◆ decreaseMasterCount()

void PhosphorTileEngine::AutotileEngine::decreaseMasterCount ( )

overridevirtual

Decrease the number of master windows.

Reimplemented from PhosphorEngine::IPlacementEngine.

◆ decreaseMasterRatio()

void PhosphorTileEngine::AutotileEngine::decreaseMasterRatio ( qreal delta = 0.05 )

overridevirtual

Decrease the master area ratio.

Makes the master area smaller by the specified delta.

Parameters

delta Amount to decrease (default 0.05 = 5%)

Reimplemented from PhosphorEngine::IPlacementEngine.

◆ demoteFromMaster()

void PhosphorTileEngine::AutotileEngine::demoteFromMaster ( const QString & windowId )

Demote a window from the master area.

Moves the window from master to the stack area.

Parameters

windowId Window to demote

◆ deserializePendingRestores()

void PhosphorTileEngine::AutotileEngine::deserializePendingRestores ( const QJsonObject & obj )

overridevirtual

Deserialize pending autotile restore queues from JSON.

Forwarded to SettingsBridge. Restores close/reopen queue.

Reimplemented from PhosphorEngine::IPlacementEngine.

◆ deserializeWindowOrders()

void PhosphorTileEngine::AutotileEngine::deserializeWindowOrders ( const QJsonArray & orders )

overridevirtual

Deserialize per-context autotile window orders from JSON.

Forwarded to SettingsBridge. Restores window order and floating state.

Parameters

orders JSON array produced by serializeWindowOrders()

Reimplemented from PhosphorEngine::IPlacementEngine.

◆ desktopsWithActiveState()

QSet< int > PhosphorTileEngine::AutotileEngine::desktopsWithActiveState ( ) const

overridevirtual

Return the set of virtual-desktop numbers that currently have any tiling state.

Used by the daemon's desktop-count-changed handler to find stale desktops (states on desktop > newCount) so they can be pruned via pruneStatesForDesktop(). Replaces an older screenStates() accessor that returned a const-ref to a QHash<TilingStateKey, PhosphorTiles::TilingState*> — that accessor leaked mutable PhosphorTiles::TilingState pointers via the const-reference loophole (const on the hash doesn't propagate to the pointed-to values), for a single caller that only needed desktop numbers.

Callers that need the raw state map should add a purpose-built query method rather than iterating private state. The intent here is that external consumers can't iterate or mutate PhosphorTiles::TilingState objects through any public accessor — that's why screenStates() is private.

Reimplemented from PhosphorEngine::IPlacementEngine.

◆ dragInsertPreviewScreenId()

QString PhosphorTileEngine::AutotileEngine::dragInsertPreviewScreenId ( ) const

inlineoverridevirtual

Get the target screen ID of the active drag-insert preview, or empty.

Reimplemented from PhosphorEngine::IPlacementEngine.

◆ dragInsertPreviewWindowId()

QString PhosphorTileEngine::AutotileEngine::dragInsertPreviewWindowId ( ) const

inline

Get the window ID of the active drag-insert preview, or empty.

◆ effectiveAlgorithm()

PhosphorTiles::TilingAlgorithm * PhosphorTileEngine::AutotileEngine::effectiveAlgorithm ( const QString & screenId ) const

◆ effectiveAlgorithmId()

QString PhosphorTileEngine::AutotileEngine::effectiveAlgorithmId ( const QString & screenId ) const

◆ effectiveInnerGap()

int PhosphorTileEngine::AutotileEngine::effectiveInnerGap ( const QString & screenId ) const

◆ effectiveMaxWindows()

int PhosphorTileEngine::AutotileEngine::effectiveMaxWindows ( const QString & screenId ) const

◆ effectiveOuterGap()

int PhosphorTileEngine::AutotileEngine::effectiveOuterGap ( const QString & screenId ) const

◆ effectiveOuterGaps()

::PhosphorLayout::EdgeGaps PhosphorTileEngine::AutotileEngine::effectiveOuterGaps ( const QString & screenId ) const

◆ effectiveRespectMinimumSize()

bool PhosphorTileEngine::AutotileEngine::effectiveRespectMinimumSize ( const QString & screenId ) const

◆ effectiveSmartGaps()

bool PhosphorTileEngine::AutotileEngine::effectiveSmartGaps ( const QString & screenId ) const

◆ effectiveSplitRatioStep()

qreal PhosphorTileEngine::AutotileEngine::effectiveSplitRatioStep ( const QString & screenId ) const

overridevirtual

Reimplemented from PhosphorEngine::IPlacementEngine.

◆ enabledChanged

void PhosphorTileEngine::AutotileEngine::enabledChanged ( bool enabled )

signal

Emitted when the enabled state changes.

Parameters

enabled New enabled state

◆ engineId()

QString PhosphorTileEngine::AutotileEngine::engineId ( ) const

inlineoverridevirtual

Stable engine identity for HandoffContext.fromEngineId.

Conventional values: "snap" / "autotile". Empty string means "unidentified" and disables receive-side reasoning that depends on the source mode.

Reimplemented from PhosphorEngine::IPlacementEngine.

◆ floatWindow()

void PhosphorTileEngine::AutotileEngine::floatWindow ( const QString & windowId )

Float a specific window by its ID (convenience forwarder)

◆ focusInDirection() [1/2]

void PhosphorTileEngine::AutotileEngine::focusInDirection	(	const QString &	direction,
		const PhosphorEngine::NavigationContext &	ctx
	)

overridevirtual

Move keyboard focus to the adjacent window.

Implements PhosphorEngine::IPlacementEngine.

◆ focusInDirection() [2/2]

void PhosphorTileEngine::AutotileEngine::focusInDirection	(	const QString &	direction,
		const QString &	action = `QStringLiteral("focus")`
	)

Focus the adjacent window in tiling order with OSD feedback.

Maps directional focus/cycle shortcuts to autotile's linear order.

Parameters

direction	Direction string ("left", "right", "up", "down")
action	OSD action label — "focus" or "cycle" (defaults to "focus")

◆ focusMaster()

void PhosphorTileEngine::AutotileEngine::focusMaster ( )

overridevirtual

Focus the master window.

For algorithms with a master concept, focuses the master window.

Reimplemented from PhosphorEngine::IPlacementEngine.

◆ focusNext()

void PhosphorTileEngine::AutotileEngine::focusNext ( )

Focus the next tiled window.

Cycles forward through the tiled window list.

◆ focusPrevious()

void PhosphorTileEngine::AutotileEngine::focusPrevious ( )

Focus the previous tiled window.

Cycles backward through the tiled window list.

◆ handoffReceive()

void PhosphorTileEngine::AutotileEngine::handoffReceive ( const HandoffContext & ctx )

overridevirtual

Receive ownership of a window from another engine.

Implementations should:

Add the window to their own tracking (per-screen/per-state).
Decide placement (snap to zone / tile / float) using the context and engine-local policy. Drag drops typically place at dropPos; non-drag handoffs (cross-engine focus changes, programmatic moves) typically respect wasFloating + sourceGeometry.
Emit any windowFloatingChanged / placement signals their normal placement paths emit, so downstream state stays consistent.

Default is a no-op so engines that don't yet implement the handoff don't reject the call — the orchestrator falls back to its legacy path.

Reimplemented from PhosphorEngine::IPlacementEngine.

◆ handoffRelease()

void PhosphorTileEngine::AutotileEngine::handoffRelease ( const QString & windowId )

overridevirtual

Release ownership of a window WITHOUT modifying its geometry.

Implementations should:

Remove the window from per-screen/per-state tracking.
Clear zone assignments (if any) WITHOUT triggering a resnap of neighbours — that's the receiving engine's job once it places the window in its layout.
Preserve any pre-tile / pre-float captured geometry that should survive the cross-engine move (the receiving engine may consult it via the HandoffContext for size preservation).

Default is a no-op for the same reason as handoffReceive.

Reimplemented from PhosphorEngine::IPlacementEngine.

◆ hasDragInsertPreview()

bool PhosphorTileEngine::AutotileEngine::hasDragInsertPreview ( ) const

inlineoverridevirtual

Query whether a drag-insert preview is currently active.

Reimplemented from PhosphorEngine::IPlacementEngine.

◆ hasPerScreenOverride()

bool PhosphorTileEngine::AutotileEngine::hasPerScreenOverride	(	const QString &	screenId,
		const QString &	key
	)		const

◆ increaseMasterCount()

void PhosphorTileEngine::AutotileEngine::increaseMasterCount ( )

overridevirtual

Increase the number of master windows.

Reimplemented from PhosphorEngine::IPlacementEngine.

◆ increaseMasterRatio()

void PhosphorTileEngine::AutotileEngine::increaseMasterRatio ( qreal delta = 0.05 )

overridevirtual

Increase the master area ratio.

Makes the master area larger by the specified delta.

Parameters

delta Amount to increase (default 0.05 = 5%)

Reimplemented from PhosphorEngine::IPlacementEngine.

◆ isActiveOnScreen()

bool PhosphorTileEngine::AutotileEngine::isActiveOnScreen ( const QString & screenId ) const

overridevirtual

Whether this engine is active on the given screen.

Implements PhosphorEngine::IPlacementEngine.

◆ isAutotileFloated()

bool PhosphorTileEngine::AutotileEngine::isAutotileFloated ( const QString & windowId ) const

◆ isAutotileScreen()

bool PhosphorTileEngine::AutotileEngine::isAutotileScreen ( const QString & screenId ) const

Check if a specific screen uses autotile.

Parameters

screenId Screen to check

Returns: true if the screen has an autotile assignment

◆ isEnabled()

bool PhosphorTileEngine::AutotileEngine::isEnabled ( ) const

overridevirtualnoexcept

Check if any screen has autotile enabled.

Returns: true if at least one screen uses autotile

Reimplemented from PhosphorEngine::IPlacementEngine.

◆ isModeSpecificFloated()

bool PhosphorTileEngine::AutotileEngine::isModeSpecificFloated ( const QString & windowId ) const

inlineoverridevirtual

Reimplemented from PhosphorEngine::IPlacementEngine.

◆ isWindowManaged()

bool PhosphorTileEngine::AutotileEngine::isWindowManaged ( const QString & windowId ) const

inlineoverridevirtual

Whether the engine considers the window "managed" (eligible for layout operations).

Semantics are engine-specific:

Autotile: equivalent to isWindowTiled (floating windows excluded).
Snap: a window assigned to a zone (including floated-in-zone). Callers that need a consistent cross-engine check for "engine owns this window at all" should use isWindowTracked instead.

Reimplemented from PhosphorEngine::IPlacementEngine.

◆ isWindowTiled()

bool PhosphorTileEngine::AutotileEngine::isWindowTiled ( const QString & windowId ) const

overridevirtual

Check if a window is currently tiled (tracked AND not floating).

Used by the drag protocol's Reorder mode to decide whether a dragged window should enter the drag-insert preview (tiled windows reorder; floating / untracked windows drag free and float on drop as before).

Reimplemented from PhosphorEngine::IPlacementEngine.

◆ isWindowTracked()

bool PhosphorTileEngine::AutotileEngine::isWindowTracked ( const QString & windowId ) const

inlineoverridevirtual

Check if a window is currently tracked in any autotile state.

Used by the drag protocol (beginDrag) to decide whether to apply an immediate free-floating-size restore when a tiled window is picked up. Reads m_windowToStateKey which is authoritative.

Reimplemented from PhosphorEngine::IPlacementEngine.

◆ loadState()

void PhosphorTileEngine::AutotileEngine::loadState ( )

overridevirtual

Load tiling state via persistence delegate (IPlacementEngine contract)

Delegates to the load function set by setPersistenceDelegate(). Wired by the daemon to WTA's loadState(), which triggers a full WTA load including autotile window order restoration via setTilingStateDelegates.

Implements PhosphorEngine::IPlacementEngine.

◆ managedWindowOrder()

QStringList PhosphorTileEngine::AutotileEngine::managedWindowOrder ( const QString & screenId ) const

inlineoverridevirtual

Reimplemented from PhosphorEngine::IPlacementEngine.

◆ markAutotileFloated()

void PhosphorTileEngine::AutotileEngine::markAutotileFloated ( const QString & windowId )

◆ markModeSpecificFloated()

void PhosphorTileEngine::AutotileEngine::markModeSpecificFloated ( const QString & windowId )

inlineoverridevirtual

Reimplemented from PhosphorEngine::IPlacementEngine.

◆ moveFocusedInDirection()

void PhosphorTileEngine::AutotileEngine::moveFocusedInDirection	(	const QString &	direction,
		const PhosphorEngine::NavigationContext &	ctx
	)

overridevirtual

Move the focused window to the adjacent slot.

Implements PhosphorEngine::IPlacementEngine.

◆ moveFocusedToPosition() [1/2]

void PhosphorTileEngine::AutotileEngine::moveFocusedToPosition ( int position )

Move the focused window to a specific position in the tiling order.

Maps "snap to zone N" shortcuts to autotile positions.

Parameters

position Target position (1-based, clamped to valid range)

◆ moveFocusedToPosition() [2/2]

void PhosphorTileEngine::AutotileEngine::moveFocusedToPosition	(	int	position,
		const PhosphorEngine::NavigationContext &	ctx
	)

overridevirtual

Move the focused window to the Nth position.

Implements PhosphorEngine::IPlacementEngine.

◆ moveToPosition()

void PhosphorTileEngine::AutotileEngine::moveToPosition	(	const QString &	windowId,
		int	position,
		const QString &	screenId
	)

◆ onWindowClaimed()

void PhosphorTileEngine::AutotileEngine::onWindowClaimed ( const QString & windowId )

overrideprotectedvirtual

Implements PhosphorEngine::PlacementEngineBase.

◆ onWindowFloated()

void PhosphorTileEngine::AutotileEngine::onWindowFloated ( const QString & windowId )

overrideprotectedvirtual

Implements PhosphorEngine::PlacementEngineBase.

◆ onWindowReleased()

void PhosphorTileEngine::AutotileEngine::onWindowReleased ( const QString & windowId )

overrideprotectedvirtual

Implements PhosphorEngine::PlacementEngineBase.

◆ onWindowUnfloated()

void PhosphorTileEngine::AutotileEngine::onWindowUnfloated ( const QString & windowId )

overrideprotectedvirtual

Implements PhosphorEngine::PlacementEngineBase.

◆ perScreenOverrides()

QVariantMap PhosphorTileEngine::AutotileEngine::perScreenOverrides ( const QString & screenId ) const

overridevirtual

Reimplemented from PhosphorEngine::IPlacementEngine.

◆ promoteToMaster()

void PhosphorTileEngine::AutotileEngine::promoteToMaster ( const QString & windowId )

Promote a window to the master area.

For algorithms with a master concept, moves the window to the master position. For other algorithms, moves to the first position.

Parameters

windowId Window to promote

◆ pruneExcludedPendingRestores()

int PhosphorTileEngine::AutotileEngine::pruneExcludedPendingRestores ( const QStringList & exclusionPatterns )

Drop pending-restore queues whose appId matches any exclusion pattern.

Mirror of PhosphorPlacement::WindowTrackingService::pruneExcludedPendingRestores for the autotile side. Patterns are compared via PhosphorIdentity::WindowId::appIdMatches. The snap engine uses the same predicate when it gates runtime restores against the user's exclusion lists, so the disk-pruning verdict here matches what the runtime would already do.

The existing ShouldPersistRestorePredicate filters entries by disabled context across screen, desktop, and activity but is blind to the exclusion-list axis. Entries authored before the user excluded an app remain on disk and bloat AutotilePendingRestores until this method runs at the next save.

The engine is settings-agnostic by design to keep the LGPL boundary clean. It takes plain patterns and does NOT mark dirty. The WTA caller wraps this and calls service()->markDirty(DirtyAutotilePending) when the return value is greater than zero, so the next debounced save persists the prune.

Parameters

exclusionPatterns combined list of excludedApplications and excludedWindowClasses entries. Empty patterns are skipped. An empty list is a no-op.

Returns: number of appId entries fully removed.

◆ pruneStaleWindows()

int PhosphorTileEngine::AutotileEngine::pruneStaleWindows ( const QSet< QString > & aliveWindowIds )

overridevirtual

Reimplemented from PhosphorEngine::PlacementEngineBase.

◆ pruneStatesForActivities()

void PhosphorTileEngine::AutotileEngine::pruneStatesForActivities ( const QStringList & validActivities )

overridevirtual

Prune PhosphorTiles::TilingState entries for activities not in the given set.

Removes states whose activity is non-empty and not in validActivities. Called when activities change so stale entries don't accumulate.

Reimplemented from PhosphorEngine::IPlacementEngine.

◆ pruneStatesForDesktop()

void PhosphorTileEngine::AutotileEngine::pruneStatesForDesktop ( int removedDesktop )

overridevirtual

Prune PhosphorTiles::TilingState and saved floating entries for a removed desktop.

Removes all states where key.desktop == removedDesktop. Called when a virtual desktop is deleted so stale entries don't accumulate.

Reimplemented from PhosphorEngine::IPlacementEngine.

◆ pushToEmptyZone()

void PhosphorTileEngine::AutotileEngine::pushToEmptyZone ( const PhosphorEngine::NavigationContext & ctx )

overridevirtual

Move the focused window to the first empty slot.

Implements PhosphorEngine::IPlacementEngine.

◆ reapplyLayout()

void PhosphorTileEngine::AutotileEngine::reapplyLayout ( const PhosphorEngine::NavigationContext & ctx )

overridevirtual

Re-apply the current layout to all managed windows.

Implements PhosphorEngine::IPlacementEngine.

◆ refreshConfigFromSettings()

void PhosphorTileEngine::AutotileEngine::refreshConfigFromSettings ( )

overridevirtual

Re-read all tuning values from the engine's settings interface.

Called by the daemon after any settings change. Engines that cache config values (e.g. AutotileEngine) override this to repopulate their config struct. Engines that read on demand (e.g. SnapEngine) leave this as a no-op.

Reimplemented from PhosphorEngine::IPlacementEngine.

◆ restoreFocusedWindow()

void PhosphorTileEngine::AutotileEngine::restoreFocusedWindow ( const PhosphorEngine::NavigationContext & ctx )

overridevirtual

Restore the focused window out of its managed state.

Implements PhosphorEngine::IPlacementEngine.

◆ retile()

void PhosphorTileEngine::AutotileEngine::retile ( const QString & screenId = QString() )

overridevirtual

Force retiling of windows.

Recalculates and applies tiling for the specified screen, or all screens if screenId is empty.

Parameters

screenId Screen to retile, or empty for all screens

Reimplemented from PhosphorEngine::IPlacementEngine.

◆ retileAfterOperation()

void PhosphorTileEngine::AutotileEngine::retileAfterOperation	(	const QString &	screenId,
		bool	operationSucceeded
	)

Helper to retile a screen after a window operation.

Recalculates layout and applies tiling if enabled, then emits placementChanged. Only emits signal if operationSucceeded is true.

Parameters

screenId	Screen to retile
operationSucceeded	Whether the triggering operation actually changed something

◆ rotateWindowOrder()

void PhosphorTileEngine::AutotileEngine::rotateWindowOrder ( bool clockwise = true )

Rotate all tiled windows by one position.

Shifts all windows in the tiling order. Clockwise moves each window to the next position (first becomes last), counterclockwise moves each to the previous position (last becomes first).

Parameters

clockwise Direction of rotation

◆ rotateWindows() [1/2]

void PhosphorTileEngine::AutotileEngine::rotateWindows	(	bool	clockwise,
		const PhosphorEngine::NavigationContext &	ctx
	)

overridevirtual

Rotate all managed windows on the screen.

Implements PhosphorEngine::IPlacementEngine.

◆ rotateWindows() [2/2]

void PhosphorTileEngine::AutotileEngine::rotateWindows	(	bool	clockwise,
		const QString &	screenId
	)

◆ runtimeMaxWindows()

int PhosphorTileEngine::AutotileEngine::runtimeMaxWindows ( ) const

overridevirtual

Runtime max-windows limit.

Returns -1 (unlimited sentinel) by default; engines that enforce a cap override with the actual value. Callers must treat -1 as "no limit" — never use as a divisor.

Reimplemented from PhosphorEngine::IPlacementEngine.

◆ saveState()

void PhosphorTileEngine::AutotileEngine::saveState ( )

overridevirtual

Save tiling state via persistence delegate (IPlacementEngine contract)

Delegates to the save function set by setPersistenceDelegate(). Wired by the daemon to WTA's saveState(), which triggers a full WTA save including both snap and autotile state. Autotile window orders are embedded in WTA's save cycle via setTilingStateDelegates — this method exists to satisfy the IPlacementEngine interface. For autotile-only persistence, the placementChanged signal → WTA::scheduleSaveState() connection is the primary path.

Implements PhosphorEngine::IPlacementEngine.

◆ scheduleRetileForScreen()

void PhosphorTileEngine::AutotileEngine::scheduleRetileForScreen ( const QString & screenId )

overridevirtual

Schedule a deferred retile for a screen.

Adds the screen to the pending set and posts a QueuedConnection call to processPendingRetiles(). Multiple calls in the same event loop pass are coalesced — only one retile fires per screen.

Reimplemented from PhosphorEngine::IPlacementEngine.

◆ screenForTrackedWindow()

QString PhosphorTileEngine::AutotileEngine::screenForTrackedWindow ( const QString & windowId ) const

inlineoverridevirtual

Return the screen this engine considers the window to be on, or empty if the window isn't tracked by this engine.

The daemon-side shortcut router consults this across engines to resolve the active window's current screen for routing decisions (float, focus, move). Without it, a cross-engine handoff (e.g. drag-insert from snap into autotile) leaves the daemon's screenAssignments lookup empty because the source engine has released its tracking, and the next shortcut routes to whichever engine the cached focus screen pointed at rather than the engine that now owns the window.

Reimplemented from PhosphorEngine::IPlacementEngine.

◆ serializePendingRestores()

QJsonObject PhosphorTileEngine::AutotileEngine::serializePendingRestores ( ) const

overridevirtual

Serialize pending autotile restore queues to JSON.

Forwarded to SettingsBridge. Returns appId-keyed pending restore entries.

Reimplemented from PhosphorEngine::IPlacementEngine.

◆ serializeWindowOrders()

QJsonArray PhosphorTileEngine::AutotileEngine::serializeWindowOrders ( ) const

overridevirtual

Serialize per-context autotile window orders to JSON.

Forwarded to SettingsBridge. Called by WTA's save cycle via persistence delegate. masterCount/splitRatio are NOT included — Settings owns those.

Reimplemented from PhosphorEngine::IPlacementEngine.

◆ setActiveScreenHint()

void PhosphorTileEngine::AutotileEngine::setActiveScreenHint ( const QString & screenId )

overridevirtual

Set the active screen hint for keyboard shortcut handlers.

Called before parameterless engine methods (focusMaster, increaseMasterCount, etc.) to ensure the engine operates on the correct virtual screen when no focused window has been tracked yet on that screen.

Parameters

screenId Resolved screen ID (virtual or physical)

Reimplemented from PhosphorEngine::IPlacementEngine.

◆ setActiveScreens()

void PhosphorTileEngine::AutotileEngine::setActiveScreens ( const QSet< QString > & screens )

inlineoverridevirtual

Reimplemented from PhosphorEngine::IPlacementEngine.

◆ setAlgorithm()

void PhosphorTileEngine::AutotileEngine::setAlgorithm ( const QString & algorithmId )

overridevirtual

Set the tiling algorithm.

If the algorithm ID is invalid, falls back to the default algorithm.

Parameters

algorithmId Algorithm identifier from PhosphorTiles::AlgorithmRegistry

Reimplemented from PhosphorEngine::IPlacementEngine.

◆ setAutotileScreens()

void PhosphorTileEngine::AutotileEngine::setAutotileScreens ( const QSet< QString > & screens )

Set which screens use autotile (derived from layout assignments)

Computes added/removed screens, retiles newly-added ones, and emits enabledChanged if the overall state flips. Only processes states for the current desktop/activity — states for other desktops are preserved.

Parameters

screens Set of screen names that should use autotile

◆ setCurrentActivity()

void PhosphorTileEngine::AutotileEngine::setCurrentActivity ( const QString & activity )

overridevirtual

Set the current activity for per-activity tiling state.

Swaps the active PhosphorTiles::TilingState set without releasing windows. Must be called BEFORE updateAutotileScreens() on activity switch so the engine resolves states for the correct activity.

Parameters

activity Activity ID (empty string for no activity)

Reimplemented from PhosphorEngine::IPlacementEngine.

◆ setCurrentDesktop()

void PhosphorTileEngine::AutotileEngine::setCurrentDesktop ( int desktop )

overridevirtual

Set the current virtual desktop for per-desktop tiling state.

Swaps the active PhosphorTiles::TilingState set without releasing windows. Must be called BEFORE updateAutotileScreens() on desktop switch so the engine resolves states for the correct desktop.

Parameters

desktop Virtual desktop number (1-based from KWin)

Reimplemented from PhosphorEngine::IPlacementEngine.

◆ setFocusedWindow()

void PhosphorTileEngine::AutotileEngine::setFocusedWindow ( const QString & windowId )

Notify the engine that a window has been focused.

Called by D-Bus adaptor when KWin reports a window focus change. Updates the focused window in the appropriate PhosphorTiles::TilingState.

Parameters

windowId Window ID that gained focus

◆ setFocusNewWindows()

void PhosphorTileEngine::AutotileEngine::setFocusNewWindows ( bool enabled )

◆ setGlobalMasterCount()

void PhosphorTileEngine::AutotileEngine::setGlobalMasterCount ( int count )

Set master count globally (config + all per-screen states)

Used by D-Bus adaptor to set the count as an absolute value, updating both the global config and all existing per-screen states.

Parameters

count New master count (clamped to valid range)

◆ setGlobalSplitRatio()

void PhosphorTileEngine::AutotileEngine::setGlobalSplitRatio ( qreal ratio )

Set master ratio globally (config + all per-screen states)

Used by D-Bus adaptor to set the ratio as an absolute value, updating both the global config and all existing per-screen states.

Parameters

ratio New split ratio (clamped to valid range)

◆ setInitialWindowOrder()

void PhosphorTileEngine::AutotileEngine::setInitialWindowOrder	(	const QString &	screenId,
		const QStringList &	windowIds
	)

overridevirtual

Pre-seed initial window order for deterministic snapping → autotile transitions.

When toggling from manual snapping to autotile, windows arrive in KWin stacking order (focus-based). This method stores a zone-ordered list so that insertWindow() can place windows in the correct autotile positions (zone 1 → master, etc.).

Only takes effect when the screen's PhosphorTiles::TilingState is empty (no prior windows from session restore). The pending order is consumed as windows are inserted.

Parameters

screenId	Screen to set initial order for
windowIds	Window IDs in desired order (zone-number ascending)

Reimplemented from PhosphorEngine::IPlacementEngine.

◆ setInnerGap()

void PhosphorTileEngine::AutotileEngine::setInnerGap ( int gap )

◆ setIsWindowFloatingFn()

void PhosphorTileEngine::AutotileEngine::setIsWindowFloatingFn ( std::function< bool(const QString &)> fn )

inlineoverridevirtual

Set callback to query daemon-side window floating state.

Used by toggleWindowFloat to adopt untracked floating windows into autotile.

Reimplemented from PhosphorEngine::IPlacementEngine.

◆ setOuterGap()

void PhosphorTileEngine::AutotileEngine::setOuterGap ( int gap )

◆ setPersistenceDelegate()

void PhosphorTileEngine::AutotileEngine::setPersistenceDelegate	(	std::function< void()>	saveFn,
		std::function< void()>	loadFn
	)

inline

Set persistence callbacks for save/load.

KConfig persistence is owned by WindowTrackingAdaptor (engine is KConfig-free). These callbacks allow AutotileEngine to fulfill the IPlacementEngine persistence contract without introducing KConfig as a dependency.

Parameters

saveFn	Called by saveState() to persist tiling state
loadFn	Called by loadState() to restore tiling state

◆ setShouldPersistRestorePredicate()

void PhosphorTileEngine::AutotileEngine::setShouldPersistRestorePredicate ( ShouldPersistRestorePredicate predicate )

inline

Inject the persist-restore gate.

See ShouldPersistRestorePredicate.

Ownership: the caller is responsible for keeping any captured state (e.g. this pointers to a settings adaptor) valid for the lifetime of this AutotileEngine. If the captured object is destroyed before the engine, clear the predicate first (setShouldPersistRestorePredicate({})) — otherwise a subsequent removeWindow()/serialize()/deserialize() call dereferences freed memory.

◆ setSmartGaps()

void PhosphorTileEngine::AutotileEngine::setSmartGaps ( bool enabled )

◆ setWindowFloat()

void PhosphorTileEngine::AutotileEngine::setWindowFloat	(	const QString &	windowId,
		bool	shouldFloat
	)

overridevirtual

Set the floating state of a specific window.

When shouldFloat is true, marks the window as floating (excluded from automatic tiling) and retiles the remaining windows. When false, removes the floating flag and re-inserts the window into the tiling layout.

Parameters

windowId	Window identifier from KWin
shouldFloat	True to float, false to unfloat

Implements PhosphorEngine::IPlacementEngine.

◆ setWindowRegistry()

void PhosphorTileEngine::AutotileEngine::setWindowRegistry ( QObject * registry )

overridevirtual

Wire up the shared WindowRegistry.

Optional — tests construct the engine without a registry and fall back to string parsing (PhosphorIdentity::WindowId::extractAppId). Production daemons set this to the daemon-root registry so class lookups return the latest value after an Electron/CEF app renames itself mid-session.

Side effect: installs a live-class resolver on every PhosphorTiles::TilingAlgorithm in the PhosphorTiles::AlgorithmRegistry so PhosphorTiles::ScriptedAlgorithm's lifecycle hooks see the current appId on each tiled window. Future algorithm registrations (hot-reloaded JS algorithms) pick up the resolver from the algorithmRegistered signal bound inside this method.

Must be set before start. Not owned.

Reimplemented from PhosphorEngine::IPlacementEngine.

◆ snapAllWindows()

void PhosphorTileEngine::AutotileEngine::snapAllWindows ( const PhosphorEngine::NavigationContext & ctx )

overridevirtual

Snap every unmanaged window on the screen to the current layout.

Implements PhosphorEngine::IPlacementEngine.

◆ stateForScreen() [1/2]

const PhosphorEngine::IPlacementState * PhosphorTileEngine::AutotileEngine::stateForScreen ( const QString & screenId ) const

overridevirtual

Implements PhosphorEngine::IPlacementEngine.

◆ stateForScreen() [2/2]

PhosphorEngine::IPlacementState * PhosphorTileEngine::AutotileEngine::stateForScreen ( const QString & screenId )

overridevirtual

Per-screen state object for the given screen.

May return nullptr if the engine does not manage the screen OR if per-screen state ownership has not yet been wired (e.g., SnapEngine before PR 2). Callers must not use a non-null return as a proxy for "engine manages this screen" — use isActiveOnScreen() for that check.

Implements PhosphorEngine::IPlacementEngine.

◆ swapFocusedInDirection() [1/2]

void PhosphorTileEngine::AutotileEngine::swapFocusedInDirection	(	const QString &	direction,
		const PhosphorEngine::NavigationContext &	ctx
	)

overridevirtual

Swap the focused window with the adjacent window.

Implements PhosphorEngine::IPlacementEngine.

◆ swapFocusedInDirection() [2/2]

void PhosphorTileEngine::AutotileEngine::swapFocusedInDirection	(	const QString &	direction,
		const QString &	action = `QStringLiteral("move")`
	)

Swap the focused window with the adjacent window in tiling order.

Maps directional keyboard shortcuts (move/swap window left/right/up/down) to autotile's linear tiling order. Forward swaps with the next window, backward swaps with the previous.

Parameters

direction	Direction string ("left", "right", "up", "down")
action	OSD action label — "move" or "swap" (defaults to "move")

◆ swapFocusedWithMaster()

void PhosphorTileEngine::AutotileEngine::swapFocusedWithMaster ( )

overridevirtual

Swap the currently focused window with the master window.

Convenience method that promotes the focused window to master position. If the focused window is already master, this is a no-op.

Reimplemented from PhosphorEngine::IPlacementEngine.

◆ swapInDirection()

void PhosphorTileEngine::AutotileEngine::swapInDirection	(	const QString &	direction,
		const QString &	action
	)

◆ swapWindows()

void PhosphorTileEngine::AutotileEngine::swapWindows	(	const QString &	windowId1,
		const QString &	windowId2
	)

Swap positions of two tiled windows.

Parameters

windowId1	First window ID
windowId2	Second window ID

◆ tiledWindowOrder()

QStringList PhosphorTileEngine::AutotileEngine::tiledWindowOrder ( const QString & screenId ) const

Get the current tiled window order for a screen.

Returns the autotile engine's tiled window list for deterministic autotile → snapping transitions. Call BEFORE switching layouts so the PhosphorTiles::TilingState still exists.

Parameters

screenId Screen to query

Returns: Ordered list of tiled window IDs (master first), or empty if no state

◆ tilingStateForScreen()

PhosphorTiles::TilingState * PhosphorTileEngine::AutotileEngine::tilingStateForScreen ( const QString & screenId )

Get the tiling state for a specific screen.

Creates the state if it doesn't exist.

Parameters

screenId Screen identifier

Returns: Pointer to PhosphorTiles::TilingState (owned by engine)

◆ toggleFocusedFloat()

void PhosphorTileEngine::AutotileEngine::toggleFocusedFloat ( const PhosphorEngine::NavigationContext & ctx )

overridevirtual

Toggle the focused window between managed and floating.

Implements PhosphorEngine::IPlacementEngine.

◆ toggleFocusedWindowFloat()

void PhosphorTileEngine::AutotileEngine::toggleFocusedWindowFloat ( )

Toggle the focused window between tiled and floating states.

When the window is tiled, it becomes floating and is excluded from automatic tiling. When floating, it re-enters the tiling layout.

Note: Prefer toggleWindowFloat() which takes explicit IDs and avoids focus-tracking desync issues.

◆ toggleWindowFloat()

void PhosphorTileEngine::AutotileEngine::toggleWindowFloat	(	const QString &	windowId,
		const QString &	screenId
	)

overridevirtual

Toggle a specific window between tiled and floating states.

Bypasses internal focus tracking by using the caller-supplied windowId and screenId directly. This avoids silent no-ops caused by m_activeScreen or focusedWindow() desyncing from KWin's actual state after rapid repeated toggles.

Parameters

windowId	Window identifier from KWin
screenId	Screen where the window is located

Implements PhosphorEngine::IPlacementEngine.

◆ unfloatWindow()

void PhosphorTileEngine::AutotileEngine::unfloatWindow ( const QString & windowId )

Unfloat a specific window by its ID (convenience forwarder)

◆ updateDragInsertPreview()

void PhosphorTileEngine::AutotileEngine::updateDragInsertPreview ( int insertIndex )

overridevirtual

Update the target insert index for the active drag preview.

Moves the dragged window within PhosphorTiles::TilingState to the new index (clamped to [0, tiledWindowCount()-1]) and retiles. No-op if the index hasn't changed from the last update.

Reimplemented from PhosphorEngine::IPlacementEngine.

◆ updatePerScreenOverride()

void PhosphorTileEngine::AutotileEngine::updatePerScreenOverride	(	const QString &	screenId,
		const QString &	key,
		const QVariant &	value
	)

◆ updateStickyScreenPins()

void PhosphorTileEngine::AutotileEngine::updateStickyScreenPins ( const std::function< bool(const QString &)> & isWindowSticky )

overridevirtual

Pin screens where all autotiled windows are sticky (on all desktops)

For screens where every tiled/floating window is sticky, pins the TilingStateKey desktop to the current effective desktop so that currentKeyForScreen() continues to resolve the existing state after a desktop switch. Screens where not all windows are sticky are unpinned, with state migrated to m_currentDesktop if necessary.

Must be called BEFORE setCurrentDesktop()/setCurrentActivity() so the pins are evaluated against the pre-switch context.

Parameters

isWindowSticky Callback returning true if the window is on all desktops

Reimplemented from PhosphorEngine::IPlacementEngine.

◆ windowClosed()

void PhosphorTileEngine::AutotileEngine::windowClosed ( const QString & windowId )

overridevirtual

Notify the engine that a window was closed.

Called by Daemon when KWin reports a window closed. Triggers retiling to fill the gap left by the closed window.

Parameters

windowId Window identifier from KWin

Implements PhosphorEngine::IPlacementEngine.

◆ windowFocused()

void PhosphorTileEngine::AutotileEngine::windowFocused	(	const QString &	windowId,
		const QString &	screenId
	)

overridevirtual

Notify the engine that a window was focused.

Called by Daemon when KWin reports window activation. Updates focus tracking for tiling operations.

Parameters

windowId	Window identifier from KWin
screenId	Screen where the window is located

Implements PhosphorEngine::IPlacementEngine.

◆ windowMinSizeUpdated()

void PhosphorTileEngine::AutotileEngine::windowMinSizeUpdated	(	const QString &	windowId,
		int	minWidth,
		int	minHeight
	)

Update a window's minimum size at runtime.

Called when a window's minimum size changes after initial windowOpened. Triggers retiling if the new minimum differs from the stored value.

Parameters

windowId	Window identifier from KWin
minWidth	New minimum width in pixels (0 if unconstrained)
minHeight	New minimum height in pixels (0 if unconstrained)

◆ windowOpened()

void PhosphorTileEngine::AutotileEngine::windowOpened	(	const QString &	windowId,
		const QString &	screenId,
		int	minWidth,
		int	minHeight
	)

overridevirtual

A new window appeared on this engine's screen.

Implements PhosphorEngine::IPlacementEngine.

◆ windowsTiled

void PhosphorTileEngine::AutotileEngine::windowsTiled ( const QString & tileRequestsJson )

signal

Emitted when a window's floating state changes due to a user action.

User-intent semantics: the downstream handler restores pre-tile geometry, shows the navigation OSD, etc. Emitted from performToggleFloat and setWindowFloat (explicit user/caller toggles).

windowFloatingChanged, activateWindowRequested, and navigationFeedback are inherited from PlacementEngineBase.

Emitted when windows are tiled to new geometries (batch)

JSON array of objects with windowId, x, y, width, height. The adaptor forwards to KWin effect.

Parameters

tileRequestsJson JSON array of {windowId,x,y,width,height}

◆ writeBackTuning()

void PhosphorTileEngine::AutotileEngine::writeBackTuning ( )

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

phosphor-tile-engine/include/PhosphorTileEngine/AutotileEngine.h

Phosphor Qt6 / Wayland library suite for window-management tools

Public Types

Signals

Public Member Functions

Protected Member Functions

Detailed Description

Member Typedef Documentation

◆ ShouldPersistRestorePredicate

Constructor & Destructor Documentation

◆ AutotileEngine()

◆ ~AutotileEngine()

Member Function Documentation

◆ activeScreen()

◆ activeScreens()

◆ algorithm()

◆ algorithmId()

◆ algorithmRegistry()

◆ applyPerScreenConfig()

◆ autotileScreens()

◆ autotileScreensChanged

◆ autotileSettings()

◆ beginDragInsertPreview()

◆ cancelDragInsertPreview()

◆ clearAllSavedFloating()

◆ clearAutotileFloated()

◆ clearModeSpecificFloatMarker()

◆ clearPerScreenConfig()

◆ clearSavedFloatingForWindows()

◆ commitDragInsertPreview()

◆ computeDragInsertIndexAtPoint()

◆ config()

◆ currentActivity()

◆ currentAlgorithm()

◆ currentDesktop()

◆ cycleFocus()

◆ decreaseMasterCount()

◆ decreaseMasterRatio()

◆ demoteFromMaster()

◆ deserializePendingRestores()

◆ deserializeWindowOrders()

◆ desktopsWithActiveState()

◆ dragInsertPreviewScreenId()

◆ dragInsertPreviewWindowId()

◆ effectiveAlgorithm()

◆ effectiveAlgorithmId()

◆ effectiveInnerGap()

◆ effectiveMaxWindows()

◆ effectiveOuterGap()

◆ effectiveOuterGaps()

◆ effectiveRespectMinimumSize()

◆ effectiveSmartGaps()

◆ effectiveSplitRatioStep()

◆ enabledChanged

◆ engineId()

◆ floatWindow()

◆ focusInDirection() [1/2]

◆ focusInDirection() [2/2]

◆ focusMaster()

◆ focusNext()

◆ focusPrevious()

◆ handoffReceive()

◆ handoffRelease()

◆ hasDragInsertPreview()

◆ hasPerScreenOverride()

◆ increaseMasterCount()

◆ increaseMasterRatio()

◆ isActiveOnScreen()

◆ isAutotileFloated()

◆ isAutotileScreen()

◆ isEnabled()

◆ isModeSpecificFloated()

◆ isWindowManaged()

◆ isWindowTiled()

◆ isWindowTracked()

◆ loadState()

◆ managedWindowOrder()

◆ markAutotileFloated()

◆ markModeSpecificFloated()

◆ moveFocusedInDirection()

◆ moveFocusedToPosition() [1/2]

◆ moveFocusedToPosition() [2/2]