Abstract base class for placement engines. More...

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

Inheritance diagram for PhosphorEngine::PlacementEngineBase:

Signals
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
virtual int	pruneStaleWindows (const QSet< QString > &aliveWindowIds)
	Drop any per-engine bookkeeping for windows not in `aliveWindowIds`.

void	setEngineSettings (QObject *settings)

QObject *	engineSettings () const

	~PlacementEngineBase () override

Public Member Functions inherited from PhosphorEngine::IPlacementEngine
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

Protected Member Functions
	PlacementEngineBase (QObject *parent=nullptr)

Detailed Description

Abstract base class for placement engines.

Handles the universal mechanics every engine shares: settings injection and stale-window pruning. Float-back / free geometry is NOT stored here — it lives in the single unified WindowPlacementStore (one record per window, shared freeGeometryByScreen), reached through IWindowTrackingService. The previous per-engine m_unmanagedGeometries store was removed: two parallel float-back stores drifted and leaked the zone/tile rect into float restores.

Engines subclass this and implement the placement-specific hooks.

Constructor & Destructor Documentation

◆ ~PlacementEngineBase()

PhosphorEngine::PlacementEngineBase::~PlacementEngineBase ( )

override

◆ PlacementEngineBase()

PhosphorEngine::PlacementEngineBase::PlacementEngineBase ( QObject * parent = nullptr )

explicitprotected

Member Function Documentation

◆ activateWindowRequested

void PhosphorEngine::PlacementEngineBase::activateWindowRequested ( const QString & windowId )

signal

◆ algorithmChanged

void PhosphorEngine::PlacementEngineBase::algorithmChanged ( const QString & algorithmId )

signal

Emitted when the active tiling algorithm changes.

◆ crossModeMoveRequested

void PhosphorEngine::PlacementEngineBase::crossModeMoveRequested	(	const QString &	windowId,
		const QString &	targetScreenId,
		int	targetDesktop,
		const QString &	direction
	)

signal

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.

The daemon resolves the target mode, relinquishes the window from this engine (handoffRelease) and hands it to the target engine (handoffReceive): autotile inserts it into the stack, snap snaps it into the entry zone (monitor crossing) or equivalent zone (desktop crossing). targetDesktop is 0 for a same-desktop monitor crossing, or the 1-based destination desktop for a virtual-desktop crossing. direction is the move direction ("left"/"right"/"up"/"down").

◆ crossModeSwapRequested

void PhosphorEngine::PlacementEngineBase::crossModeSwapRequested	(	const QString &	windowId,
		const QString &	targetScreenId,
		int	targetDesktop,
		const QString &	direction
	)

signal

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.

The daemon resolves the target's entry-edge window (the partner facing the source in direction) and trades the two: the focused window crosses to the partner's position on the target surface, the partner returns to the focused window's vacated position on the source. With no partner (empty entry edge) it degrades to a plain cross-mode move. Same parameter meaning as crossModeMoveRequested: targetDesktop is 0 for a monitor crossing, else the 1-based destination desktop; direction is the swap direction.

◆ engineSettings()

QObject * PhosphorEngine::PlacementEngineBase::engineSettings ( ) const

inline

◆ geometryRestoreRequested

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

signal

◆ navigationFeedback

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

signal

◆ placementChanged

void PhosphorEngine::PlacementEngineBase::placementChanged ( const QString & screenId )

signal

Emitted when the placement layout changes for a screen.

◆ pruneStaleWindows()

virtual int PhosphorEngine::PlacementEngineBase::pruneStaleWindows ( const QSet< QString > & aliveWindowIds )

virtual

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

◆ setEngineSettings()

void PhosphorEngine::PlacementEngineBase::setEngineSettings ( QObject * settings )

◆ settingsPersistRequested

void PhosphorEngine::PlacementEngineBase::settingsPersistRequested ( )

signal

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

◆ windowDesktopMoveRequested

void PhosphorEngine::PlacementEngineBase::windowDesktopMoveRequested	(	const QString &	windowId,
		int	desktop
	)

signal

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

Relayed over D-Bus to the KWin effect, which calls windowToDesktops.

◆ windowFloatingChanged

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

signal

◆ windowFloatingStateSynced

void PhosphorEngine::PlacementEngineBase::windowFloatingStateSynced	(	const QString &	windowId,
		bool	floating,
		const QString &	screenId
	)

signal

Emitted to sync floating state without restoring geometry.

Passive state-sync: engine-internal divergence correction.

◆ windowOutputMoveExpected

void PhosphorEngine::PlacementEngineBase::windowOutputMoveExpected	(	const QString &	windowId,
		const QString &	targetScreenId
	)

signal

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.

The compositor's resulting KWin::Window:: outputChanged for this window is therefore EXPECTED and must NOT be re-processed as a fresh close/open — doing so re-resolves the window to the already-updated destination key and tears down the daemon's placement (the source monitor's gap then never reflows). The effect records this one-shot and, on the matching outputChanged, only refreshes its bookkeeping + moves the decoration claim. Genuine USER-DRAG cross-output moves carry no such marker and still drive close/open.

◆ windowsBatchFloated

void PhosphorEngine::PlacementEngineBase::windowsBatchFloated	(	const QStringList &	windowIds,
		const QString &	screenId
	)

signal

Emitted when overflow windows are batch-floated during applyTiling.

◆ windowsReleased

void PhosphorEngine::PlacementEngineBase::windowsReleased	(	const QStringList &	windowIds,
		const QSet< QString > &	releasedScreenIds
	)

signal

Emitted when windows are released from engine management.

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

phosphor-engine/include/PhosphorEngine/PlacementEngineBase.h

Phosphor Qt6 / Wayland library suite for window-management tools

Signals

Public Member Functions

Protected Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ ~PlacementEngineBase()

◆ PlacementEngineBase()

Member Function Documentation

◆ activateWindowRequested

◆ algorithmChanged

◆ crossModeMoveRequested

◆ crossModeSwapRequested

◆ engineSettings()

◆ geometryRestoreRequested

◆ navigationFeedback

◆ placementChanged

◆ pruneStaleWindows()

◆ setEngineSettings()

◆ settingsPersistRequested

◆ windowDesktopMoveRequested

◆ windowFloatingChanged

◆ windowFloatingStateSynced

◆ windowOutputMoveExpected

◆ windowsBatchFloated

◆ windowsReleased