Unified placement engine interface. More...

#include <phosphor-engine/include/PhosphorEngine/IPlacementEngine.h>

Inheritance diagram for PhosphorEngine::IPlacementEngine:

Classes
struct	HandoffContext
	Context for a cross-engine window handoff. More...

Public Member Functions
virtual	~IPlacementEngine ()=default

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

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

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

virtual void	windowClosed (const QString &windowId)=0
	A window was closed.

virtual void	windowFocused (const QString &windowId, const QString &screenId)=0
	A window gained focus (called when the compositor reports activation).

virtual void	toggleWindowFloat (const QString &windowId, const QString &screenId)=0
	Toggle between managed and floating.

virtual void	setWindowFloat (const QString &windowId, bool shouldFloat)=0
	Set floating state explicitly (directional, not toggle).

virtual void	focusInDirection (const QString &direction, const NavigationContext &ctx)=0
	Move keyboard focus to the adjacent window.

virtual void	moveFocusedInDirection (const QString &direction, const NavigationContext &ctx)=0
	Move the focused window to the adjacent slot.

virtual void	swapFocusedInDirection (const QString &direction, const NavigationContext &ctx)=0
	Swap the focused window with the adjacent window.

virtual void	moveFocusedToPosition (int position, const NavigationContext &ctx)=0
	Move the focused window to the Nth position.

virtual void	rotateWindows (bool clockwise, const NavigationContext &ctx)=0
	Rotate all managed windows on the screen.

virtual void	reapplyLayout (const NavigationContext &ctx)=0
	Re-apply the current layout to all managed windows.

virtual void	snapAllWindows (const NavigationContext &ctx)=0
	Snap every unmanaged window on the screen to the current layout.

virtual void	cycleFocus (bool forward, const NavigationContext &ctx)=0
	Cycle keyboard focus through managed windows.

virtual void	pushToEmptyZone (const NavigationContext &ctx)=0
	Move the focused window to the first empty slot.

virtual void	restoreFocusedWindow (const NavigationContext &ctx)=0
	Restore the focused window out of its managed state.

virtual void	toggleFocusedFloat (const NavigationContext &ctx)=0
	Toggle the focused window between managed and floating.

virtual QSet< QString >	activeScreens () const

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

virtual void	reapplyManagedWindowAppearance ()
	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.

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

virtual bool	restorePlacement (const WindowPlacement &placement, const QString &screenId)
	Apply `placement` to a (re)opening window on `screenId`.

virtual QStringList	managedWindowOrder (const QString &screenId) const

virtual void	setInitialWindowOrder (const QString &screenId, const QStringList &windowIds)

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

virtual void	clearPerScreenConfig (const QString &screenId)

virtual QVariantMap	perScreenOverrides (const QString &screenId) const

virtual bool	isModeSpecificFloated (const QString &windowId) const

virtual void	clearModeSpecificFloatMarker (const QString &windowId)

virtual bool	hasDragInsertPreview () const

virtual bool	beginDragInsertPreview (const QString &windowId, const QString &screenId)

virtual void	commitDragInsertPreview ()

virtual void	cancelDragInsertPreview ()

virtual QString	dragInsertPreviewScreenId () const

virtual bool	isWindowTracked (const QString &windowId) const

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

virtual bool	isWindowTiled (const QString &windowId) const
	Whether the window is actively tiled (engine-owned, non-floating).

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

virtual void	onWindowResized (const QString &windowId, const QRect &oldFrame, const QRect &newFrame, const QString &screenId)
	Notify the engine that a tracked window finished an interactive resize.

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

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

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

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

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

virtual QString	algorithmId () const

virtual void	setAlgorithm (const QString &algorithmId)

virtual bool	isEnabled () const noexcept

virtual QString	activeScreen () const

virtual void	setActiveScreenHint (const QString &screenId)

virtual void	setCurrentDesktop (int desktop)

virtual void	setCurrentDesktopForScreen (const QString &screenId, int desktop)
	Set a single screen's current virtual desktop (Plasma 6.7 "switch desktops independently for each screen").

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

virtual void	setCurrentActivity (const QString &activity)

virtual void	setCrossSurfaceResolver (ICrossSurfaceResolver *resolver)
	Inject the cross-surface resolver used to find a neighbouring output / desktop when directional navigation reaches a surface boundary.

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

virtual QSet< int >	desktopsWithActiveState () const

virtual void	pruneStatesForDesktop (int removedDesktop)

virtual void	pruneStatesForActivities (const QStringList &validActivities)

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

virtual qreal	effectiveSplitRatioStep (const QString &screenId) const

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

virtual void	retile (const QString &screenId=QString())

virtual void	scheduleRetileForScreen (const QString &screenId)

virtual void	markModeSpecificFloated (const QString &windowId)

virtual void	setWindowRegistry (QObject *registry)
	Attach a window-class registry (QObject carrying WindowRegistry).

virtual void	increaseMasterRatio (qreal delta=0.05)

virtual void	decreaseMasterRatio (qreal delta=0.05)

virtual void	increaseMasterCount ()

virtual void	decreaseMasterCount ()

virtual void	focusMaster ()

virtual void	swapFocusedWithMaster ()

virtual QJsonObject	serializeEngineState () const

virtual void	deserializeEngineState (const QJsonObject &state)

virtual void	saveState ()=0

virtual void	loadState ()=0

virtual IPlacementState *	stateForScreen (const QString &screenId)=0
	Per-screen state object for the given screen.

virtual const IPlacementState *	stateForScreen (const QString &screenId) const =0

Detailed Description

Unified placement engine interface.

Required vs Optional Methods

Methods are divided into two categories:

REQUIRED (pure virtual, = 0): Every engine MUST implement these. They represent the core contract: screen ownership, window lifecycle, float management, and navigation intents.

OPTIONAL (have default no-op implementations): Engines override only the capabilities they support. A snap engine ignores master operations; an autotile engine ignores per-screen config. The defaults are safe no-ops so the daemon can call any method without branching on engine type.

Design Rationale

Both snap-mode (manual zone layouts) and autotile-mode (automatic tiling algorithms) implement this so the daemon can dispatch all window lifecycle events and user navigation intents through a single polymorphic call — zero mode branches.

Each method represents a USER INTENT, not a mode-specific implementation step. "Move focused window left" has different internal meaning in tile-swap mode vs. zone-snap mode, but the user's request is the same — the interface names the request and each engine fulfills it in its own terms.

All methods are idempotent with respect to "no focused window" — each implementation emits navigation feedback with a sensible reason code when there's nothing to act on, rather than erroring out.

Constructor & Destructor Documentation

◆ ~IPlacementEngine()

virtual PhosphorEngine::IPlacementEngine::~IPlacementEngine ( )

virtualdefault

Member Function Documentation

◆ activeScreen()

virtual QString PhosphorEngine::IPlacementEngine::activeScreen ( ) const

inlinevirtual

Reimplemented in PhosphorTileEngine::AutotileEngine.

◆ activeScreens()

virtual QSet< QString > PhosphorEngine::IPlacementEngine::activeScreens ( ) const

inlinevirtual

Reimplemented in PhosphorTileEngine::AutotileEngine.

◆ algorithmId()

virtual QString PhosphorEngine::IPlacementEngine::algorithmId ( ) const

inlinevirtual

Reimplemented in PhosphorTileEngine::AutotileEngine.

◆ applyPerScreenConfig()

virtual void PhosphorEngine::IPlacementEngine::applyPerScreenConfig	(	const QString &	screenId,
		const QVariantMap &	overrides
	)

inlinevirtual

Reimplemented in PhosphorTileEngine::AutotileEngine.

◆ beginDragInsertPreview()

virtual bool PhosphorEngine::IPlacementEngine::beginDragInsertPreview	(	const QString &	windowId,
		const QString &	screenId
	)

inlinevirtual

Reimplemented in PhosphorTileEngine::AutotileEngine.

◆ cancelDragInsertPreview()

virtual void PhosphorEngine::IPlacementEngine::cancelDragInsertPreview ( )

inlinevirtual

Reimplemented in PhosphorTileEngine::AutotileEngine.

◆ capturePlacement()

virtual std::optional< WindowPlacement > PhosphorEngine::IPlacementEngine::capturePlacement ( const QString & windowId ) const

inlinevirtual

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 in PhosphorSnapEngine::SnapEngine, and PhosphorTileEngine::AutotileEngine.

◆ clearCurrentDesktopForScreen()

virtual void PhosphorEngine::IPlacementEngine::clearCurrentDesktopForScreen ( const QString & screenId )

inlinevirtual

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

Reimplemented in PhosphorTileEngine::AutotileEngine.

◆ clearModeSpecificFloatMarker()

virtual void PhosphorEngine::IPlacementEngine::clearModeSpecificFloatMarker ( const QString & windowId )

inlinevirtual

Reimplemented in PhosphorTileEngine::AutotileEngine.

◆ clearPerScreenConfig()

virtual void PhosphorEngine::IPlacementEngine::clearPerScreenConfig ( const QString & screenId )

inlinevirtual

Reimplemented in PhosphorTileEngine::AutotileEngine.

◆ commitDragInsertPreview()

virtual void PhosphorEngine::IPlacementEngine::commitDragInsertPreview ( )

inlinevirtual

Reimplemented in PhosphorTileEngine::AutotileEngine.

◆ computeDragInsertIndexAtPoint()

virtual int PhosphorEngine::IPlacementEngine::computeDragInsertIndexAtPoint	(	const QString &	screenId,
		const QPoint &	cursorPos
	)		const

inlinevirtual

Compute the insert index for a cursor position on a managed screen.

Returns -1 if the screen has no active state.

Reimplemented in PhosphorTileEngine::AutotileEngine.

◆ cycleFocus()

virtual void PhosphorEngine::IPlacementEngine::cycleFocus	(	bool	forward,
		const NavigationContext &	ctx
	)

pure virtual

Cycle keyboard focus through managed windows.

Implemented in PhosphorSnapEngine::SnapEngine, and PhosphorTileEngine::AutotileEngine.

◆ decreaseMasterCount()

virtual void PhosphorEngine::IPlacementEngine::decreaseMasterCount ( )

inlinevirtual

Reimplemented in PhosphorTileEngine::AutotileEngine.

◆ decreaseMasterRatio()

virtual void PhosphorEngine::IPlacementEngine::decreaseMasterRatio ( qreal delta = 0.05 )

inlinevirtual

Reimplemented in PhosphorTileEngine::AutotileEngine.

◆ deserializeEngineState()

virtual void PhosphorEngine::IPlacementEngine::deserializeEngineState ( const QJsonObject & state )

inlinevirtual

◆ desktopsWithActiveState()

virtual QSet< int > PhosphorEngine::IPlacementEngine::desktopsWithActiveState ( ) const

inlinevirtual

Reimplemented in PhosphorTileEngine::AutotileEngine.

◆ dragInsertPreviewScreenId()

virtual QString PhosphorEngine::IPlacementEngine::dragInsertPreviewScreenId ( ) const

inlinevirtual

Reimplemented in PhosphorTileEngine::AutotileEngine.

◆ effectiveSplitRatioStep()

virtual qreal PhosphorEngine::IPlacementEngine::effectiveSplitRatioStep ( const QString & screenId ) const

inlinevirtual

Reimplemented in PhosphorTileEngine::AutotileEngine.

◆ engineId()

virtual QString PhosphorEngine::IPlacementEngine::engineId ( ) const

inlinevirtual

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 in PhosphorSnapEngine::SnapEngine, and PhosphorTileEngine::AutotileEngine.

◆ focusInDirection()

virtual void PhosphorEngine::IPlacementEngine::focusInDirection	(	const QString &	direction,
		const NavigationContext &	ctx
	)

pure virtual

Move keyboard focus to the adjacent window.

Implemented in PhosphorSnapEngine::SnapEngine, and PhosphorTileEngine::AutotileEngine.

◆ focusMaster()

virtual void PhosphorEngine::IPlacementEngine::focusMaster ( )

inlinevirtual

Reimplemented in PhosphorTileEngine::AutotileEngine.

◆ handoffReceive()

virtual void PhosphorEngine::IPlacementEngine::handoffReceive ( const HandoffContext & ctx )

inlinevirtual

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 in PhosphorSnapEngine::SnapEngine, and PhosphorTileEngine::AutotileEngine.

◆ handoffRelease()

virtual void PhosphorEngine::IPlacementEngine::handoffRelease ( const QString & windowId )

inlinevirtual

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 in PhosphorSnapEngine::SnapEngine, and PhosphorTileEngine::AutotileEngine.

◆ hasDragInsertPreview()

virtual bool PhosphorEngine::IPlacementEngine::hasDragInsertPreview ( ) const

inlinevirtual

Reimplemented in PhosphorTileEngine::AutotileEngine.

◆ increaseMasterCount()

virtual void PhosphorEngine::IPlacementEngine::increaseMasterCount ( )

inlinevirtual

Reimplemented in PhosphorTileEngine::AutotileEngine.

◆ increaseMasterRatio()

virtual void PhosphorEngine::IPlacementEngine::increaseMasterRatio ( qreal delta = 0.05 )

inlinevirtual

Reimplemented in PhosphorTileEngine::AutotileEngine.

◆ isActiveOnScreen()

virtual bool PhosphorEngine::IPlacementEngine::isActiveOnScreen ( const QString & screenId ) const

pure virtual

Whether this engine is active on the given screen.

Implemented in PhosphorSnapEngine::SnapEngine, and PhosphorTileEngine::AutotileEngine.

◆ isEnabled()

virtual bool PhosphorEngine::IPlacementEngine::isEnabled ( ) const

inlinevirtualnoexcept

Reimplemented in PhosphorSnapEngine::SnapEngine, and PhosphorTileEngine::AutotileEngine.

◆ isModeSpecificFloated()

virtual bool PhosphorEngine::IPlacementEngine::isModeSpecificFloated ( const QString & windowId ) const

inlinevirtual

Reimplemented in PhosphorTileEngine::AutotileEngine.

◆ isWindowManaged()

virtual bool PhosphorEngine::IPlacementEngine::isWindowManaged ( const QString & windowId ) const

inlinevirtual

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 in PhosphorTileEngine::AutotileEngine.

◆ isWindowTiled()

virtual bool PhosphorEngine::IPlacementEngine::isWindowTiled ( const QString & windowId ) const

inlinevirtual

Whether the window is actively tiled (engine-owned, non-floating).

Distinct from isWindowTracked (which includes floating windows).

Reimplemented in PhosphorTileEngine::AutotileEngine.

◆ isWindowTracked()

virtual bool PhosphorEngine::IPlacementEngine::isWindowTracked ( const QString & windowId ) const

inlinevirtual

Reimplemented in PhosphorSnapEngine::SnapEngine, and PhosphorTileEngine::AutotileEngine.

◆ loadState()

virtual void PhosphorEngine::IPlacementEngine::loadState ( )

pure virtual

Implemented in PhosphorSnapEngine::SnapEngine, and PhosphorTileEngine::AutotileEngine.

◆ managedWindowOrder()

virtual QStringList PhosphorEngine::IPlacementEngine::managedWindowOrder ( const QString & screenId ) const

inlinevirtual

Reimplemented in PhosphorTileEngine::AutotileEngine.

◆ markModeSpecificFloated()

virtual void PhosphorEngine::IPlacementEngine::markModeSpecificFloated ( const QString & windowId )

inlinevirtual

Reimplemented in PhosphorTileEngine::AutotileEngine.

◆ moveFocusedInDirection()

virtual void PhosphorEngine::IPlacementEngine::moveFocusedInDirection	(	const QString &	direction,
		const NavigationContext &	ctx
	)

pure virtual

Move the focused window to the adjacent slot.

Implemented in PhosphorSnapEngine::SnapEngine, and PhosphorTileEngine::AutotileEngine.

◆ moveFocusedToPosition()

virtual void PhosphorEngine::IPlacementEngine::moveFocusedToPosition	(	int	position,
		const NavigationContext &	ctx
	)

pure virtual

Move the focused window to the Nth position.

Implemented in PhosphorTileEngine::AutotileEngine, and PhosphorSnapEngine::SnapEngine.

◆ onWindowResized()

virtual void PhosphorEngine::IPlacementEngine::onWindowResized	(	const QString &	windowId,
		const QRect &	oldFrame,
		const QRect &	newFrame,
		const QString &	screenId
	)

inlinevirtual

Notify the engine that a tracked window finished an interactive resize.

The daemon's WindowTracking adaptor forwards the compositor's interactive-resize-finished event here so an engine can reflow the rest of its layout to absorb the change (autotile fills the freed gap; GitHub #652). oldFrame / newFrame are the window's frame geometry before and after the resize; screenId is the screen the daemon resolved the window to. Default is a no-op for engines (e.g. snap) that have no neighbour-reflow model.

Reimplemented in PhosphorTileEngine::AutotileEngine.

◆ perScreenOverrides()

virtual QVariantMap PhosphorEngine::IPlacementEngine::perScreenOverrides ( const QString & screenId ) const

inlinevirtual

Reimplemented in PhosphorTileEngine::AutotileEngine.

◆ pruneStatesForActivities()

virtual void PhosphorEngine::IPlacementEngine::pruneStatesForActivities ( const QStringList & validActivities )

inlinevirtual

Reimplemented in PhosphorTileEngine::AutotileEngine.

◆ pruneStatesForDesktop()

virtual void PhosphorEngine::IPlacementEngine::pruneStatesForDesktop ( int removedDesktop )

inlinevirtual

Reimplemented in PhosphorTileEngine::AutotileEngine.

◆ pushToEmptyZone()

virtual void PhosphorEngine::IPlacementEngine::pushToEmptyZone ( const NavigationContext & ctx )

pure virtual

Move the focused window to the first empty slot.

Implemented in PhosphorSnapEngine::SnapEngine, and PhosphorTileEngine::AutotileEngine.

◆ reapplyLayout()

virtual void PhosphorEngine::IPlacementEngine::reapplyLayout ( const NavigationContext & ctx )

pure virtual

Re-apply the current layout to all managed windows.

Implemented in PhosphorSnapEngine::SnapEngine, and PhosphorTileEngine::AutotileEngine.

◆ reapplyManagedWindowAppearance()

virtual void PhosphorEngine::IPlacementEngine::reapplyManagedWindowAppearance ( )

inlinevirtual

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 in PhosphorSnapEngine::SnapEngine, and PhosphorTileEngine::AutotileEngine.

◆ refreshConfigFromSettings()

virtual void PhosphorEngine::IPlacementEngine::refreshConfigFromSettings ( )

inlinevirtual

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 in PhosphorTileEngine::AutotileEngine.

◆ restoreFocusedWindow()

virtual void PhosphorEngine::IPlacementEngine::restoreFocusedWindow ( const NavigationContext & ctx )

pure virtual

Restore the focused window out of its managed state.

Implemented in PhosphorSnapEngine::SnapEngine, and PhosphorTileEngine::AutotileEngine.

◆ restorePlacement()

virtual bool PhosphorEngine::IPlacementEngine::restorePlacement	(	const WindowPlacement &	placement,
		const QString &	screenId
	)

inlinevirtual

Apply placement to a (re)opening window on screenId.

Return true if this engine claimed and applied it. Dispatch on placement.slotFor(engineId()) .state, reading the engine's slot reference and the shared freeGeometryByScreen.

Contract pair of capturePlacement() and the engine-agnostic entry point for a new engine. NOTE: the built-in snap and autotile engines do NOT route through this method — they apply restore inline in their own open paths (SnapEngine::resolveWindowRestore consults the store and returns a SnapResult to the effect; AutotileEngine::insertWindow take()s the record and inserts at position) because those paths carry engine-specific policy (snap's auto-snap fallback chain; autotile's burst-insert coalescing) that a single apply-this-record call cannot express. A minimal future engine may instead implement only this method and have its own open path invoke it directly.

◆ retile()

virtual void PhosphorEngine::IPlacementEngine::retile ( const QString & screenId = QString() )

inlinevirtual

Reimplemented in PhosphorTileEngine::AutotileEngine.

◆ rotateWindows()

virtual void PhosphorEngine::IPlacementEngine::rotateWindows	(	bool	clockwise,
		const NavigationContext &	ctx
	)

pure virtual

Rotate all managed windows on the screen.

Implemented in PhosphorSnapEngine::SnapEngine, and PhosphorTileEngine::AutotileEngine.

◆ runtimeMaxWindows()

virtual int PhosphorEngine::IPlacementEngine::runtimeMaxWindows ( ) const

inlinevirtual

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 in PhosphorTileEngine::AutotileEngine.

◆ saveState()

virtual void PhosphorEngine::IPlacementEngine::saveState ( )

pure virtual

Implemented in PhosphorSnapEngine::SnapEngine, and PhosphorTileEngine::AutotileEngine.

◆ scheduleRetileForScreen()

virtual void PhosphorEngine::IPlacementEngine::scheduleRetileForScreen ( const QString & screenId )

inlinevirtual

Reimplemented in PhosphorTileEngine::AutotileEngine.

◆ screenForTrackedWindow()

virtual QString PhosphorEngine::IPlacementEngine::screenForTrackedWindow ( const QString & windowId ) const

inlinevirtual

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 in PhosphorSnapEngine::SnapEngine, and PhosphorTileEngine::AutotileEngine.

◆ serializeEngineState()

virtual QJsonObject PhosphorEngine::IPlacementEngine::serializeEngineState ( ) const

inlinevirtual

◆ setActiveScreenHint()

virtual void PhosphorEngine::IPlacementEngine::setActiveScreenHint ( const QString & screenId )

inlinevirtual

Reimplemented in PhosphorTileEngine::AutotileEngine.

◆ setActiveScreens()

virtual void PhosphorEngine::IPlacementEngine::setActiveScreens ( const QSet< QString > & screens )

inlinevirtual

Reimplemented in PhosphorTileEngine::AutotileEngine.

◆ setAlgorithm()

virtual void PhosphorEngine::IPlacementEngine::setAlgorithm ( const QString & algorithmId )

inlinevirtual

Reimplemented in PhosphorTileEngine::AutotileEngine.

◆ setCrossSurfaceResolver()

virtual void PhosphorEngine::IPlacementEngine::setCrossSurfaceResolver ( ICrossSurfaceResolver * resolver )

inlinevirtual

Inject the cross-surface resolver used to find a neighbouring output / desktop when directional navigation reaches a surface boundary.

The resolver is borrowed, not owned; the caller must keep it alive for the engine's lifetime (in the daemon it outlives both engines by member order). Engines that don't support cross-surface navigation ignore it.

Reimplemented in PhosphorSnapEngine::SnapEngine, and PhosphorTileEngine::AutotileEngine.

◆ setCurrentActivity()

virtual void PhosphorEngine::IPlacementEngine::setCurrentActivity ( const QString & activity )

inlinevirtual

Reimplemented in PhosphorTileEngine::AutotileEngine.

◆ setCurrentDesktop()

virtual void PhosphorEngine::IPlacementEngine::setCurrentDesktop ( int desktop )

inlinevirtual

Reimplemented in PhosphorTileEngine::AutotileEngine.

◆ setCurrentDesktopForScreen()

virtual void PhosphorEngine::IPlacementEngine::setCurrentDesktopForScreen	(	const QString &	screenId,
		int	desktop
	)

inlinevirtual

Set a single screen's current virtual desktop (Plasma 6.7 "switch desktops independently for each screen").

A PURE context swap — it selects which per-(screen, desktop) tiling state is current for this screen; it does NOT migrate windows between desktop states (the other desktop's state must stay put so it reappears when that screen returns). Default no-op for engines that are not per-screen-desktop-aware.

Reimplemented in PhosphorTileEngine::AutotileEngine.

◆ setInitialWindowOrder()

virtual void PhosphorEngine::IPlacementEngine::setInitialWindowOrder	(	const QString &	screenId,
		const QStringList &	windowIds
	)

inlinevirtual

Reimplemented in PhosphorTileEngine::AutotileEngine.

◆ setWindowFloat()

virtual void PhosphorEngine::IPlacementEngine::setWindowFloat	(	const QString &	windowId,
		bool	shouldFloat
	)

pure virtual

Set floating state explicitly (directional, not toggle).

Implemented in PhosphorSnapEngine::SnapEngine, and PhosphorTileEngine::AutotileEngine.

◆ setWindowRegistry()

virtual void PhosphorEngine::IPlacementEngine::setWindowRegistry ( QObject * registry )

inlinevirtual

Attach a window-class registry (QObject carrying WindowRegistry).

Engines qobject_cast to their concrete type internally.

Parameters

registry Not owned; must outlive this engine.

Reimplemented in PhosphorTileEngine::AutotileEngine.

◆ snapAllWindows()

virtual void PhosphorEngine::IPlacementEngine::snapAllWindows ( const NavigationContext & ctx )

pure virtual

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

Implemented in PhosphorSnapEngine::SnapEngine, and PhosphorTileEngine::AutotileEngine.

◆ stateForScreen() [1/2]

virtual const IPlacementState * PhosphorEngine::IPlacementEngine::stateForScreen ( const QString & screenId ) const

pure virtual

Implemented in PhosphorSnapEngine::SnapEngine, and PhosphorTileEngine::AutotileEngine.

◆ stateForScreen() [2/2]

virtual IPlacementState * PhosphorEngine::IPlacementEngine::stateForScreen ( const QString & screenId )

pure virtual

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.

Implemented in PhosphorSnapEngine::SnapEngine, and PhosphorTileEngine::AutotileEngine.

◆ swapFocusedInDirection()

virtual void PhosphorEngine::IPlacementEngine::swapFocusedInDirection	(	const QString &	direction,
		const NavigationContext &	ctx
	)

pure virtual

Swap the focused window with the adjacent window.

Implemented in PhosphorSnapEngine::SnapEngine, and PhosphorTileEngine::AutotileEngine.

◆ swapFocusedWithMaster()

virtual void PhosphorEngine::IPlacementEngine::swapFocusedWithMaster ( )

inlinevirtual

Reimplemented in PhosphorTileEngine::AutotileEngine.

◆ toggleFocusedFloat()

virtual void PhosphorEngine::IPlacementEngine::toggleFocusedFloat ( const NavigationContext & ctx )

pure virtual

Toggle the focused window between managed and floating.

Implemented in PhosphorSnapEngine::SnapEngine, and PhosphorTileEngine::AutotileEngine.

◆ toggleWindowFloat()

virtual void PhosphorEngine::IPlacementEngine::toggleWindowFloat	(	const QString &	windowId,
		const QString &	screenId
	)

pure virtual

Toggle between managed and floating.

Implemented in PhosphorSnapEngine::SnapEngine, and PhosphorTileEngine::AutotileEngine.

◆ updateDragInsertPreview()

virtual void PhosphorEngine::IPlacementEngine::updateDragInsertPreview ( int insertIndex )

inlinevirtual

Update the target insert index for an active drag-insert preview.

Reimplemented in PhosphorTileEngine::AutotileEngine.

◆ updateStickyScreenPins()

virtual void PhosphorEngine::IPlacementEngine::updateStickyScreenPins ( const std::function< bool(const QString &)> & isWindowSticky )

inlinevirtual

Reimplemented in PhosphorTileEngine::AutotileEngine.

◆ windowClosed()

virtual void PhosphorEngine::IPlacementEngine::windowClosed ( const QString & windowId )

pure virtual

A window was closed.

Implemented in PhosphorSnapEngine::SnapEngine, and PhosphorTileEngine::AutotileEngine.

◆ windowFocused()

virtual void PhosphorEngine::IPlacementEngine::windowFocused	(	const QString &	windowId,
		const QString &	screenId
	)

pure virtual

A window gained focus (called when the compositor reports activation).

Named "focused" here because it's the engine's perspective; the D-Bus protocol and DaemonClient use "windowActivated" — same event.

Implemented in PhosphorSnapEngine::SnapEngine, and PhosphorTileEngine::AutotileEngine.

◆ windowOpened() [1/2]

void PhosphorEngine::IPlacementEngine::windowOpened	(	const QString &	windowId,
		const QString &	screenId
	)

inline

Convenience overload — equivalent to windowOpened(id, screen, 0, 0).

◆ windowOpened() [2/2]

virtual void PhosphorEngine::IPlacementEngine::windowOpened	(	const QString &	windowId,
		const QString &	screenId,
		int	minWidth = `0`,
		int	minHeight = `0`
	)

pure virtual

A new window appeared on this engine's screen.

Implemented in PhosphorSnapEngine::SnapEngine, and PhosphorTileEngine::AutotileEngine.

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

phosphor-engine/include/PhosphorEngine/IPlacementEngine.h

Phosphor Qt6 / Wayland library suite for window-management tools

Classes

Public Member Functions

Detailed Description

Required vs Optional Methods

Design Rationale

Constructor & Destructor Documentation

◆ ~IPlacementEngine()

Member Function Documentation

◆ activeScreen()

◆ activeScreens()

◆ algorithmId()

◆ applyPerScreenConfig()

◆ beginDragInsertPreview()

◆ cancelDragInsertPreview()

◆ capturePlacement()

◆ clearCurrentDesktopForScreen()

◆ clearModeSpecificFloatMarker()

◆ clearPerScreenConfig()

◆ commitDragInsertPreview()

◆ computeDragInsertIndexAtPoint()

◆ cycleFocus()

◆ decreaseMasterCount()

◆ decreaseMasterRatio()

◆ deserializeEngineState()

◆ desktopsWithActiveState()

◆ dragInsertPreviewScreenId()

◆ effectiveSplitRatioStep()

◆ engineId()

◆ focusInDirection()

◆ focusMaster()

◆ handoffReceive()

◆ handoffRelease()

◆ hasDragInsertPreview()

◆ increaseMasterCount()

◆ increaseMasterRatio()

◆ isActiveOnScreen()

◆ isEnabled()

◆ isModeSpecificFloated()

◆ isWindowManaged()

◆ isWindowTiled()

◆ isWindowTracked()

◆ loadState()

◆ managedWindowOrder()

◆ markModeSpecificFloated()

◆ moveFocusedInDirection()

◆ moveFocusedToPosition()

◆ onWindowResized()

◆ perScreenOverrides()

◆ pruneStatesForActivities()

◆ pruneStatesForDesktop()

◆ pushToEmptyZone()

◆ reapplyLayout()

◆ reapplyManagedWindowAppearance()

◆ refreshConfigFromSettings()

◆ restoreFocusedWindow()

◆ restorePlacement()

◆ retile()

◆ rotateWindows()

◆ runtimeMaxWindows()

◆ saveState()

◆ scheduleRetileForScreen()

◆ screenForTrackedWindow()

◆ serializeEngineState()

◆ setActiveScreenHint()

◆ setActiveScreens()

◆ setAlgorithm()

◆ setCrossSurfaceResolver()

◆ setCurrentActivity()

◆ setCurrentDesktop()

◆ setCurrentDesktopForScreen()

◆ setInitialWindowOrder()

◆ setWindowFloat()

◆ setWindowRegistry()

◆ snapAllWindows()

◆ stateForScreen() [1/2]

◆ stateForScreen() [2/2]

◆ swapFocusedInDirection()

◆ swapFocusedWithMaster()

◆ toggleFocusedFloat()

◆ toggleWindowFloat()