Core engine for automatic window tiling. More...

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

Inheritance diagram for PhosphorTileEngine::AutotileEngine:

Public Types
using	RestorePositionPredicate = std::function< bool(const QString &windowId)>
	Predicate consulted on reopen to decide whether a FLOATED (untiled) window should have its previous global position re-applied.

using	FloatPredicate = std::function< bool(const QString &windowId)>
	Predicate deciding whether an opening window should start FLOATING because a "Float this app" window rule matched it.

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	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	windowDesktopMoveRequested (const QString &windowId, int desktop)
	Emitted when directional navigation moves a window across virtual desktops: the engine has already re-keyed its own tiling state, and the compositor must move the real window to `desktop` (1-based).

void	windowOutputMoveExpected (const QString &windowId, const QString &targetScreenId)
	Emitted when daemon-initiated directional navigation moves a window across physical outputs: the engine has already migrated its own tiling state (removed from the source key, re-added on `targetScreenId`) and scheduled both reflows.

void	crossModeMoveRequested (const QString &windowId, const QString &targetScreenId, int targetDesktop, const QString &direction)
	Emitted when a directional MOVE reaches a context boundary whose target is a DIFFERENT tiling mode than the source — the source engine cannot place the window itself (it has no state for the other mode), so it defers to the daemon.

void	crossModeSwapRequested (const QString &windowId, const QString &targetScreenId, int targetDesktop, const QString &direction)
	Emitted when a directional SWAP reaches a context boundary whose target is a DIFFERENT tiling mode than the source — the two-way cross-mode exchange.

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, PhosphorScreens::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 &rawWindowId) const override
	Check if a window is currently tiled (tracked AND not floating).

bool	isWindowFloatingInAutotile (const QString &windowId) const
	Authoritative per-window autotile float state.

QStringList	allFloatingWindows () const
	All windows currently floating in autotile across every tracked state.

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	setCurrentDesktopForScreen (const QString &screenId, int desktop) override
	Set a single screen's current virtual desktop (Plasma 6.7 per-output virtual desktops, #648)

void	clearCurrentDesktopForScreen (const QString &screenId) override
	Drop a screen's per-output desktop, reverting it to the global m_currentDesktop.

void	setCrossSurfaceResolver (PhosphorEngine::ICrossSurfaceResolver *resolver) override
	Inject the cross-surface resolver (neighbouring output / desktop lookup) used by directional navigation when it reaches a layout boundary.

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	setRestorePositionPredicate (RestorePositionPredicate predicate)
	Inject the floated-position-restore gate.

void	setFloatPredicate (FloatPredicate predicate)

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.

void	onWindowResized (const QString &rawWindowId, const QRect &oldFrame, const QRect &newFrame, const QString &screenId) override
	Reflow neighbors after a window was interactively resized.

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)

void	setContextGapProvider (std::function< QVariantMap(const QString &screenId)> provider)

void	noteSplitRatioUserTuned (const QString &screenId)

void	noteMasterCountUserTuned (const QString &screenId)

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.

QString	entryWindowForCrossing (const QString &screenId, const QString &direction) const
	Cross-mode swap support (queried by the daemon when THIS engine is the target): the tiled window at `screenId's` entry edge facing the source for a crossing arriving in `direction` — the swap partner.

int	windowOrderIndexForWindow (const QString &screenId, const QString &windowId) const
	The RAW window-order index of `windowId` on `screenId` (current desktop; counts floats, matching TilingState::addWindow), or -1 when not present — lets the daemon land a swap counterpart in the same slot the departing window held when re-inserted via HandoffContext.insertIndex.

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

void	reapplyManagedWindowAppearance () override
	Re-drive the compositor's per-window appearance (border, hidden title bar) for every window this engine currently manages, WITHOUT recomputing the layout — windows keep their current zones/positions.

std::optional< PhosphorEngine::WindowPlacement >	capturePlacement (const QString &windowId) const override
	Report `windowId's` CURRENT placement for persistence, or nullopt if this engine does not manage it.

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.

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 &rawWindowId)

void	clearAutotileFloated (const QString &rawWindowId)

bool	isAutotileFloated (const QString &rawWindowId) const

int	pruneStaleWindows (const QSet< QString > &aliveWindowIds) override
	Drop any per-engine bookkeeping for windows not in `aliveWindowIds`.

Public Member Functions inherited from PhosphorEngine::PlacementEngineBase
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	restorePlacement (const WindowPlacement &placement, const QString &screenId)
	Apply `placement` to a (re)opening window on `screenId`.

virtual QJsonObject	serializeEngineState () const

virtual void	deserializeEngineState (const QJsonObject &state)

Additional Inherited Members
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 the active tiling algorithm (a Luau script, via the PhosphorTiles::TilingAlgorithm interface), 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

◆ FloatPredicate

using PhosphorTileEngine::AutotileEngine::FloatPredicate = std::function<bool(const QString& windowId)>

Predicate deciding whether an opening window should start FLOATING because a "Float this app" window rule matched it.

Daemon-injected, keyed by the live windowId. The window is still inserted (so it stays managed and Meta+F can re-tile it); it is just marked floating, identical to a manual float. When UNSET (default) no window is rule-floated. Clear with {} before destroying any state the closure captured.

◆ RestorePositionPredicate

using PhosphorTileEngine::AutotileEngine::RestorePositionPredicate = std::function<bool(const QString& windowId)>

Predicate consulted on reopen to decide whether a FLOATED (untiled) window should have its previous global position re-applied.

Mirrors SnapEngine::RestorePositionPredicate: the daemon resolves the global autotileRestoreFloatedWindowsOnLogin setting plus the per-window RestorePosition rule and injects the result here, keyed by the live windowId. The float STATE is always restored (the window comes back floating); only the geometry MOVE is gated. When UNSET (default), the engine preserves its historical behaviour of always re-applying the recorded position — the path unit tests rely on.

Constructor & Destructor Documentation

◆ AutotileEngine()

PhosphorTileEngine::AutotileEngine::AutotileEngine	(	PhosphorZones::LayoutRegistry *	layoutManager,
		PhosphorEngine::IWindowTrackingService *	windowTracker,
		PhosphorScreens::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.

◆ allFloatingWindows()

QStringList PhosphorTileEngine::AutotileEngine::allFloatingWindows ( ) const

All windows currently floating in autotile across every tracked state.

Used by the daemon's WTS floating-windows aggregator so the engine-agnostic floatingWindows() enumeration (effect float-cache seed, getAllWindowStates) still sees autotile floats now that they live in TilingState rather than the old shared WTS set.

◆ 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.

Also RE-EMITTED with an unchanged set on a desktop/activity switch between two contexts whose autotile sets are identical (with isDesktopSwitch=true, discussion #219) — a wire-contract wakeup for the compositor effect's catch-scan, not a set change. Receivers must be idempotent for the same-set case.

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.

◆ capturePlacement()

std::optional< PhosphorEngine::WindowPlacement > PhosphorTileEngine::AutotileEngine::capturePlacement ( const QString & windowId ) const

overridevirtual

Report windowId's CURRENT placement for persistence, or nullopt if this engine does not manage it.

Fill the engine's EngineSlot — state from its token vocabulary (free/floating/snapped/tiled/...) plus its slot reference (zone IDs / tile order) — under engines[engineId()], and the screen/desktop/ activity context. Do NOT set freeGeometryByScreen: the capture orchestrator fills the shared free/float geometry from the live frame, and only when the state is free/floating, so a managed rect never becomes the float-back.

This is the polymorphic capture seam the common layer drives — the WTA close hook and the save-time snapshot call it for every window.

Reimplemented from PhosphorEngine::IPlacementEngine.

◆ clearAutotileFloated()

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

◆ clearCurrentDesktopForScreen()

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

overridevirtual

Drop a screen's per-output desktop, reverting it to the global m_currentDesktop.

Reimplemented from PhosphorEngine::IPlacementEngine.

◆ 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.

◆ 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. When the cursor is beyond all zones: holds at the active preview's lastInsertIndex if a preview is live (the normal call context — keeps the slot stable while the cursor crosses gaps), otherwise falls back to the last tiled index. Returns 0 when the state exists but has no zones yet, and -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

◆ 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 m_screenStates map itself stays private (no public map accessor exists); per-screen lookup is available through tilingStateForScreen(screenId) which returns a (non-const) PhosphorTiles::TilingState* for the read/mutate sites that explicitly key off one screen. That accessor is public, so the restraint on mutating through it is convention only (not enforced by access level or friend): the intended writers are the engine's own call paths and the per-screen config resolver, while tests use it for read-only access.

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.

◆ entryWindowForCrossing()

QString PhosphorTileEngine::AutotileEngine::entryWindowForCrossing	(	const QString &	screenId,
		const QString &	direction
	)		const

Cross-mode swap support (queried by the daemon when THIS engine is the target): the tiled window at screenId's entry edge facing the source for a crossing arriving in direction — the swap partner.

Empty when the screen has no tiled windows.

◆ 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 & rawWindowId ) 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.

◆ isWindowFloatingInAutotile()

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

Authoritative per-window autotile float state.

Returns true iff the window is tracked by autotile AND its owning TilingState marks it floating. This is the autotile engine's half of the per-engine float contract: the daemon's WTS float resolver consults this for windows whose current screen mode is Autotile (the snap half is SnapState::isFloating). Distinct from isModeSpecificFloated(), which reports the mode-transition MARKER (autotile-originated float), not the live TilingState float.

◆ 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 & rawWindowId ) 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(). Autotiled windows reopen at their saved position from the unified WindowPlacementStore (insertWindow consumes the record), not from a separate window-order key.

Implements PhosphorEngine::IPlacementEngine.

◆ managedWindowOrder()

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

inlineoverridevirtual

Reimplemented from PhosphorEngine::IPlacementEngine.

◆ markAutotileFloated()

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

◆ 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
	)

◆ noteMasterCountUserTuned()

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

◆ noteSplitRatioUserTuned()

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

◆ onWindowResized()

void PhosphorTileEngine::AutotileEngine::onWindowResized	(	const QString &	rawWindowId,
		const QRect &	oldFrame,
		const QRect &	newFrame,
		const QString &	screenId
	)

overridevirtual

Reflow neighbors after a window was interactively resized.

Entry point for the "drag an edge, neighbors fill the gap" behaviour (GitHub #652). Called by the daemon's WindowTracking adaptor when the compositor reports an interactive resize of a tiled window has finished.

For tree/memory algorithms the moved edge(s) are mapped to the owning PhosphorTiles::SplitTree split(s), whose ratio is adjusted so the neighbour subtree absorbs the change, then the screen is retiled gap-free. Floating windows, single-window screens, cross-output drags, and algorithms without a reflow model are no-ops.

Parameters

rawWindowId	The interactively-resized window (raw instance id; canonicalized internally to match the state/tree keys)
oldFrame	The window's frame geometry before the resize (drag baseline)
newFrame	The window's frame geometry after the resize
screenId	Screen the daemon resolved the window to (authoritative)

Reimplemented from PhosphorEngine::IPlacementEngine.

◆ 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

◆ pruneStaleWindows()

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

overridevirtual

Drop any per-engine bookkeeping for windows not in aliveWindowIds.

The base keeps no per-window state of its own now, so it returns 0; engines override and add their own pruning (then call the base).

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.

◆ reapplyManagedWindowAppearance()

void PhosphorTileEngine::AutotileEngine::reapplyManagedWindowAppearance ( )

overridevirtual

Re-drive the compositor's per-window appearance (border, hidden title bar) for every window this engine currently manages, WITHOUT recomputing the layout — windows keep their current zones/positions.

The compositor derives each window's chrome from the geometry/state this re-emits.

Called by the daemon when the compositor bridge (re)registers: on a daemon or effect restart the compositor drops its per-window appearance state, so it must be re-driven from the daemon's authoritative placement state. Distinct from reapplyLayout(), which is a user navigation action that recomputes the layout and may move windows. Default is a no-op for engines that don't manage compositor-side window chrome.

Reimplemented from 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(). Per-window autotile restore state is persisted by the common WindowPlacementStore (each window's tiled position is captured into the store); the placementChanged → WTA::scheduleSaveState() connection is what triggers that save.

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.

◆ 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.

Identical-set re-emit (discussion #219): when called for a desktop/activity switch whose autotile set matches the previous context's, the set comparison early-returns but the engine still RE-EMITS autotileScreensChanged with the unchanged set and isDesktopSwitch=true — the compositor effect's catch-scan depends on that wakeup to re-add windows moved to this desktop while the user was away. An empty identical set skips the re-emit (nothing to catch).

Parameters

screens Set of screen names that should use autotile

◆ setContextGapProvider()

void PhosphorTileEngine::AutotileEngine::setContextGapProvider ( std::function< QVariantMap(const QString &screenId)> provider )

◆ setCrossSurfaceResolver()

void PhosphorTileEngine::AutotileEngine::setCrossSurfaceResolver ( PhosphorEngine::ICrossSurfaceResolver * resolver )

inlineoverridevirtual

Inject the cross-surface resolver (neighbouring output / desktop lookup) used by directional navigation when it reaches a layout boundary.

Reimplemented from PhosphorEngine::IPlacementEngine.

◆ 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.

◆ setCurrentDesktopForScreen()

void PhosphorTileEngine::AutotileEngine::setCurrentDesktopForScreen	(	const QString &	screenId,
		int	desktop
	)

overridevirtual

Set a single screen's current virtual desktop (Plasma 6.7 per-output virtual desktops, #648)

Pure context swap: records the screen's desktop in m_screenCurrentDesktop so currentKeyForScreen() resolves that screen's per-(screen, desktop) state. Does NOT migrate windows between states — the other desktop's state stays put so it reappears when the screen returns. Like setCurrentDesktop(), call BEFORE updateAutotileScreens() so the new key resolves.

Reimplemented from PhosphorEngine::IPlacementEngine.

◆ setFloatPredicate()

void PhosphorTileEngine::AutotileEngine::setFloatPredicate ( FloatPredicate predicate )

inline

◆ 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 )

◆ 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

◆ setRestorePositionPredicate()

void PhosphorTileEngine::AutotileEngine::setRestorePositionPredicate ( RestorePositionPredicate predicate )

inline

Inject the floated-position-restore gate.

Clear with {} before destroying any state captured by the closure (the daemon honours this on re-wire).

◆ 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::LuauTileAlgorithm's lifecycle hooks see the current appId on each tiled window. Future algorithm registrations (hot-reloaded Luau 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 for that engine. 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.

◆ windowOrderIndexForWindow()

int PhosphorTileEngine::AutotileEngine::windowOrderIndexForWindow	(	const QString &	screenId,
		const QString &	windowId
	)		const

The RAW window-order index of windowId on screenId (current desktop; counts floats, matching TilingState::addWindow), or -1 when not present — lets the daemon land a swap counterpart in the same slot the departing window held when re-inserted via HandoffContext.insertIndex.

◆ 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

Additional Inherited Members

Detailed Description

Member Typedef Documentation

◆ FloatPredicate

◆ RestorePositionPredicate

Constructor & Destructor Documentation

◆ AutotileEngine()

◆ ~AutotileEngine()

Member Function Documentation

◆ activeScreen()

◆ activeScreens()

◆ algorithm()

◆ algorithmId()

◆ algorithmRegistry()

◆ allFloatingWindows()

◆ applyPerScreenConfig()

◆ autotileScreens()

◆ autotileScreensChanged

◆ autotileSettings()

◆ beginDragInsertPreview()

◆ cancelDragInsertPreview()

◆ capturePlacement()

◆ clearAutotileFloated()

◆ clearCurrentDesktopForScreen()

◆ clearModeSpecificFloatMarker()

◆ clearPerScreenConfig()

◆ commitDragInsertPreview()

◆ computeDragInsertIndexAtPoint()

◆ config()

◆ currentActivity()

◆ currentAlgorithm()

◆ currentDesktop()

◆ cycleFocus()

◆ decreaseMasterCount()

◆ decreaseMasterRatio()

◆ demoteFromMaster()

◆ desktopsWithActiveState()

◆ dragInsertPreviewScreenId()

◆ dragInsertPreviewWindowId()

◆ effectiveAlgorithm()

◆ effectiveAlgorithmId()

◆ effectiveInnerGap()

◆ effectiveMaxWindows()

◆ effectiveOuterGap()

◆ effectiveOuterGaps()

◆ effectiveRespectMinimumSize()

◆ effectiveSmartGaps()

◆ effectiveSplitRatioStep()

◆ enabledChanged

◆ engineId()

◆ entryWindowForCrossing()

◆ floatWindow()

◆ focusInDirection() [1/2]

◆ focusInDirection() [2/2]

◆ focusMaster()

◆ focusNext()

◆ focusPrevious()

◆ handoffReceive()

◆ handoffRelease()

◆ hasDragInsertPreview()

◆ hasPerScreenOverride()

◆ increaseMasterCount()

◆ increaseMasterRatio()

◆ isActiveOnScreen()

◆ isAutotileFloated()

◆ isAutotileScreen()

◆ isEnabled()

◆ isModeSpecificFloated()

◆ isWindowFloatingInAutotile()

◆ isWindowManaged()

◆ isWindowTiled()

◆ isWindowTracked()

◆ loadState()

◆ managedWindowOrder()

◆ markAutotileFloated()

◆ markModeSpecificFloated()

◆ moveFocusedInDirection()