Engine for manual zone-based window snapping. More...

#include <phosphor-snap-engine/include/PhosphorSnapEngine/SnapEngine.h>

Inheritance diagram for PhosphorSnapEngine::SnapEngine:

Public Types
using	ShouldRestorePredicate = std::function< bool(const QString &screenId)>
	Predicate consulted on the auto-snap entry path to suppress zone restores onto a context the user disabled.

Signals
void	windowSnapStateChanged (const QString &windowId, const PhosphorProtocol::WindowStateEntry &entry)
	Snap state changed (commit / uncommit). WTA relays to D-Bus windowStateChanged.

void	windowFloatingClearedForSnap (const QString &windowId, const QString &screenId)
	Floating state cleared as part of a commit. WTA relays as windowFloatingChanged(id, false, screen).

void	applyGeometryRequested (const QString &windowId, int x, int y, int width, int height, const QString &zoneId, const QString &screenId, bool sizeOnly)
	Daemon-driven geometry application (used by autotile float restore)

void	resnapToNewLayoutRequested (const QString &resnapData)
	Batched resnap data (routed through WTA::handleBatchedResnap for bookkeeping)

void	snapAllWindowsRequested (const QString &screenId)
	Request KWin effect to collect unsnapped windows and snap them all.

void	applyGeometriesBatch (const PhosphorProtocol::WindowGeometryList &geometries, const QString &action)
	Batch of window-geometry updates, applied by the KWin effect in a single operation (rotate, resnap, snap-all paths).

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

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

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

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

void	activateWindowRequested (const QString &windowId)

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

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

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

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

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

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

Public Member Functions
	SnapEngine (PhosphorZones::LayoutRegistry layoutManager, PhosphorEngine::IWindowTrackingService windowTracker, PhosphorZones::IZoneDetector zoneDetector, PhosphorEngine::IVirtualDesktopManager vdm, QObject *parent=nullptr)

	~SnapEngine () override

int	currentVirtualDesktop () const
	Current virtual desktop (1-based; 0 when no virtual-desktop manager is wired) and activity, forwarded from the injected managers.

QString	currentActivity () const

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

bool	isEnabled () const noexcept override
	True when snapping is globally enabled.

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

void	setShouldRestorePredicate (ShouldRestorePredicate predicate)
	Inject the auto-snap-restore gate.

void	windowClosed (const QString &windowId) override
	A window was closed.

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

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

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

void	saveState () override

void	loadState () override

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.

bool	isWindowTracked (const QString &windowId) const override
	Whether this engine considers the window owned (snapped, snap-floated, or otherwise carried in SnapState's screen/zone maps).

void	resnapToNewLayout ()
	Resnap windows from previous layout to current layout after layout switch.

void	resnapCurrentAssignments (const QString &screenFilter=QString())
	Resnap windows to their current zone assignments (re-apply geometries)

void	resnapFromAutotileOrder (const QStringList &autotileWindowOrder, const QString &screenId)
	Resnap windows using autotile window order as assignment source.

QVector< PhosphorEngine::ZoneAssignmentEntry >	calculateResnapEntriesFromAutotileOrder (const QStringList &autotileWindowOrder, const QString &screenId)
	Calculate resnap entries from autotile order WITHOUT emitting signal.

PhosphorProtocol::SnapAllResultList	calculateSnapAllWindows (const QStringList &windowIds, const QString &screenId)
	Calculate snap-all-windows assignments without applying them.

void	emitBatchedResnap (const QVector< PhosphorEngine::ZoneAssignmentEntry > &entries)
	Emit a single batched resnapToNewLayoutRequested signal.

void	snapAllWindows (const QString &screenId)
	Request the KWin effect to collect and snap all unsnapped windows.

PhosphorEngine::SnapResult	resolveWindowRestore (const QString &windowId, const QString &screenId, bool sticky, PhosphorEngine::WindowKind kind=PhosphorEngine::WindowKind::Unknown)
	Resolve auto-snap for a newly opened window.

void	setAutotileEngine (PhosphorEngine::IPlacementEngine *engine)
	Set the autotile engine for screen ownership checks.

SnapState *	snapState () const

void	setZoneAdjacencyResolver (IZoneAdjacencyResolver *resolver)
	Set typed zone-adjacency resolver for directional navigation.

void	setNavigationStateProvider (INavigationStateProvider *provider)
	Wire the typed navigation-state provider.

void	focusInDirection (const QString &direction, const PhosphorEngine::NavigationContext &ctx) override
	Walk to the adjacent window in `direction` and transfer keyboard focus.

void	moveFocusedInDirection (const QString &direction, const PhosphorEngine::NavigationContext &ctx) override
	Move the focused window into the adjacent zone in `direction` (displacing or filling the target).

void	swapFocusedInDirection (const QString &direction, const PhosphorEngine::NavigationContext &ctx) override
	Swap the focused window with whatever's in the adjacent zone in `direction`.

void	moveFocusedToPosition (int zoneNumber, const PhosphorEngine::NavigationContext &ctx) override
	Move the focused window to the layout zone with `zoneNumber` (1-based) on ctx.screenId.

void	rotateWindows (bool clockwise, const PhosphorEngine::NavigationContext &ctx) override
	Rotate snapped windows through the layout's zone order, dispatched via IPlacementEngine.

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

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

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

void	restoreFocusedWindow (const PhosphorEngine::NavigationContext &ctx) override
	Restore the focused window to its captured pre-snap size and unsnap.

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

void	cycleFocus (bool forward, const PhosphorEngine::NavigationContext &ctx) override
	Cycle keyboard focus forward/backward through managed windows in the active zone (or the layout cycle order if single-window per zone).

void	commitSnap (const QString &windowId, const QString &zoneId, const QString &screenId, PhosphorEngine::SnapIntent intent=PhosphorEngine::SnapIntent::UserInitiated)

void	commitMultiZoneSnap (const QString &windowId, const QStringList &zoneIds, const QString &screenId, PhosphorEngine::SnapIntent intent=PhosphorEngine::SnapIntent::UserInitiated)

void	uncommitSnap (const QString &windowId)

PhosphorEngine::UnfloatResult	resolveUnfloatGeometry (const QString &windowId, const QString &fallbackScreen) const

PhosphorProtocol::WindowGeometryList	applyBatchAssignments (const QVector< PhosphorEngine::ZoneAssignmentEntry > &entries, PhosphorEngine::SnapIntent intent=PhosphorEngine::SnapIntent::UserInitiated, std::function< QString()> fallbackScreenResolver={})

PhosphorEngine::SnapResult	calculateSnapToAppRule (const QString &windowId, const QString &windowScreenName, bool isSticky) const

PhosphorEngine::SnapResult	calculateSnapToLastZone (const QString &windowId, const QString &windowScreenId, bool isSticky) const

PhosphorEngine::SnapResult	calculateSnapToEmptyZone (const QString &windowId, const QString &windowScreenId, bool isSticky) const

PhosphorEngine::SnapResult	calculateRestoreFromSession (const QString &windowId, const QString &screenId, bool isSticky, PhosphorEngine::WindowKind kind=PhosphorEngine::WindowKind::Unknown) const

QVector< PhosphorEngine::ZoneAssignmentEntry >	calculateResnapFromPreviousLayout ()

QVector< PhosphorEngine::ZoneAssignmentEntry >	calculateResnapFromCurrentAssignments (const QString &screenFilter=QString()) const

QVector< PhosphorEngine::ZoneAssignmentEntry >	calculateResnapFromAutotileOrder (const QStringList &autotileWindowOrder, const QString &screenId) const

QVector< PhosphorEngine::ZoneAssignmentEntry >	calculateSnapAllWindowEntries (const QStringList &windowIds, const QString &screenId) const

QVector< PhosphorEngine::ZoneAssignmentEntry >	calculateRotation (bool clockwise, const QString &screenFilter=QString()) const

void	saveSnapFloating (const QString &windowId)

bool	restoreSnapFloating (const QString &windowId)

void	clearSavedSnapFloating ()

bool	restoreSavedModeFloat (const QString &windowId) override

void	clearSavedFloatingForWindows (const QStringList &windowIds) override
	Remove saved floating state for the given windows (per-window, not bulk clear).

void	saveModeFloat (const QString &windowId) override

void	clearSavedModeFloating () override

void	markWindowReported (const QString &windowId)

const QSet< QString > &	effectReportedWindows () const

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

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

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

void	pushFocusedToEmptyZone (const PhosphorEngine::NavigationContext &ctx)
	Move the focused window to the first empty zone on ctx.screenId.

void	rotateWindowsInLayout (bool clockwise, const QString &screenId)
	Rotate snapped windows through the layout's zone order on `screenId`.

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

QString	lastActiveScreenId () const
	Last screen the engine saw via windowFocused.

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

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

void	releaseWindow (const QString &windowId)

void	floatWindow (const QString &windowId)

void	unfloatWindow (const QString &windowId)

QRect	unmanagedGeometry (const QString &windowId) const

QString	unmanagedScreen (const QString &windowId) const

bool	hasUnmanagedGeometry (const QString &windowId) const

void	clearUnmanagedGeometry (const QString &windowId)

void	forgetWindow (const QString &windowId)

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

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

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

QJsonObject	serializeBaseState () const

void	deserializeBaseState (const QJsonObject &state)

void	setEngineSettings (QObject *settings)

QObject *	engineSettings () const

	~PlacementEngineBase () override

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

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

virtual QSet< QString >	activeScreens () const

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

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	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 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 QString	activeScreen () const

virtual void	setActiveScreenHint (const QString &screenId)

virtual void	setCurrentDesktop (int desktop)

virtual void	setCurrentActivity (const QString &activity)

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	clearAllSavedFloating ()

virtual QJsonArray	serializeWindowOrders () const

virtual void	deserializeWindowOrders (const QJsonArray &orders)

virtual QJsonObject	serializePendingRestores () const

virtual void	deserializePendingRestores (const QJsonObject &obj)

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

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

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)

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

void	onWindowReleased (const QString &windowId) override

void	onWindowFloated (const QString &windowId) override

void	onWindowUnfloated (const QString &windowId) override

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

Detailed Description

Engine for manual zone-based window snapping.

Implements IPlacementEngine for screens using manual zone layouts (non-autotile). Handles auto-snap on window open, zone-based navigation, floating state, rotation, and resnap operations.

Uses WindowTrackingService as a shared state store for zone assignments, pre-tile geometries, and floating state. The snap engine adds behavior on top: auto-snap fallback chains, directional navigation via zone adjacency, and layout-change resnapping.

See also: PhosphorEngine::IPlacementEngine, AutotileEngine, WindowTrackingService

Member Typedef Documentation

◆ ShouldRestorePredicate

using PhosphorSnapEngine::SnapEngine::ShouldRestorePredicate = std::function<bool(const QString& screenId)>

Predicate consulted on the auto-snap entry path to suppress zone restores onto a context the user disabled.

Returns true if the screenId is currently active for snap mode, false if disabled. The engine library is intentionally settings-agnostic (LGPL boundary) so the daemon adaptor injects the predicate; SnapEngine itself has no notion of disabled contexts. The daemon-side closure is responsible for resolving the current virtual desktop / activity at call time — SnapState does not track those.

Applied inside resolveWindowRestore so BOTH the engine's own windowOpened path AND the D-Bus SnapAdaptor::resolveWindowRestore path (used by the KWin effect for per-window restores) hit the same gate. A PendingRestore authored before the user disabled the context can no longer drag a freshly opened window into a zone the user told us to stay out of (discussion #461 item 7). Without this gate, restarting the daemon was the only way to evict stale in-memory entries — the isPersistedContextDisabled filter on disk load only fires on startup, so any restore queued during the running session leaked through.

When unset (default), the engine behaves as if every context is active — the historical default that unit tests rely on.

Constructor & Destructor Documentation

◆ SnapEngine()

PhosphorSnapEngine::SnapEngine::SnapEngine	(	PhosphorZones::LayoutRegistry *	layoutManager,
		PhosphorEngine::IWindowTrackingService *	windowTracker,
		PhosphorZones::IZoneDetector *	zoneDetector,
		PhosphorEngine::IVirtualDesktopManager *	vdm,
		QObject *	parent = `nullptr`
	)

explicit

◆ ~SnapEngine()

PhosphorSnapEngine::SnapEngine::~SnapEngine ( )

override

Member Function Documentation

◆ applyBatchAssignments()

PhosphorProtocol::WindowGeometryList PhosphorSnapEngine::SnapEngine::applyBatchAssignments	(	const QVector< PhosphorEngine::ZoneAssignmentEntry > &	entries,
		PhosphorEngine::SnapIntent	intent = `PhosphorEngine::SnapIntent::UserInitiated`,
		std::function< QString()>	fallbackScreenResolver = `{}`
	)

◆ applyGeometriesBatch

void PhosphorSnapEngine::SnapEngine::applyGeometriesBatch	(	const PhosphorProtocol::WindowGeometryList &	geometries,
		const QString &	action
	)

signal

Batch of window-geometry updates, applied by the KWin effect in a single operation (rotate, resnap, snap-all paths).

The action label disambiguates the cause downstream ("rotate", "resnap", "snap_all", "vs_reconfigure"). Relayed to D-Bus via WTA.

◆ applyGeometryRequested

void PhosphorSnapEngine::SnapEngine::applyGeometryRequested	(	const QString &	windowId,
		int	x,
		int	y,
		int	width,
		int	height,
		const QString &	zoneId,
		const QString &	screenId,
		bool	sizeOnly
	)

signal

Daemon-driven geometry application (used by autotile float restore)

◆ calculateResnapEntriesFromAutotileOrder()

QVector< PhosphorEngine::ZoneAssignmentEntry > PhosphorSnapEngine::SnapEngine::calculateResnapEntriesFromAutotileOrder	(	const QStringList &	autotileWindowOrder,
		const QString &	screenId
	)

Calculate resnap entries from autotile order WITHOUT emitting signal.

Returns the computed PhosphorEngine::ZoneAssignmentEntry vector so the caller can batch entries from multiple screens into a single resnapToNewLayoutRequested emission. Falls back to current-assignment entries if autotile order yields nothing.

Parameters

autotileWindowOrder	Ordered list of window IDs from autotile engine
screenId	Screen to resnap on

Returns: Vector of PhosphorEngine::ZoneAssignmentEntry (may be empty)

◆ calculateResnapFromAutotileOrder()

QVector< PhosphorEngine::ZoneAssignmentEntry > PhosphorSnapEngine::SnapEngine::calculateResnapFromAutotileOrder	(	const QStringList &	autotileWindowOrder,
		const QString &	screenId
	)		const

◆ calculateResnapFromCurrentAssignments()

QVector< PhosphorEngine::ZoneAssignmentEntry > PhosphorSnapEngine::SnapEngine::calculateResnapFromCurrentAssignments ( const QString & screenFilter = QString() ) const

◆ calculateResnapFromPreviousLayout()

QVector< PhosphorEngine::ZoneAssignmentEntry > PhosphorSnapEngine::SnapEngine::calculateResnapFromPreviousLayout ( )

◆ calculateRestoreFromSession()

PhosphorEngine::SnapResult PhosphorSnapEngine::SnapEngine::calculateRestoreFromSession	(	const QString &	windowId,
		const QString &	screenId,
		bool	isSticky,
		PhosphorEngine::WindowKind	kind = `PhosphorEngine::WindowKind::Unknown`
	)		const

◆ calculateRotation()

QVector< PhosphorEngine::ZoneAssignmentEntry > PhosphorSnapEngine::SnapEngine::calculateRotation	(	bool	clockwise,
		const QString &	screenFilter = `QString()`
	)		const

◆ calculateSnapAllWindowEntries()

QVector< PhosphorEngine::ZoneAssignmentEntry > PhosphorSnapEngine::SnapEngine::calculateSnapAllWindowEntries	(	const QStringList &	windowIds,
		const QString &	screenId
	)		const

◆ calculateSnapAllWindows()

PhosphorProtocol::SnapAllResultList PhosphorSnapEngine::SnapEngine::calculateSnapAllWindows	(	const QStringList &	windowIds,
		const QString &	screenId
	)

Calculate snap-all-windows assignments without applying them.

Parameters

windowIds	List of window IDs to snap
screenId	Screen to snap on

Returns: JSON array of zone assignment entries for KWin effect to apply

◆ calculateSnapToAppRule()

PhosphorEngine::SnapResult PhosphorSnapEngine::SnapEngine::calculateSnapToAppRule	(	const QString &	windowId,
		const QString &	windowScreenName,
		bool	isSticky
	)		const

◆ calculateSnapToEmptyZone()

PhosphorEngine::SnapResult PhosphorSnapEngine::SnapEngine::calculateSnapToEmptyZone	(	const QString &	windowId,
		const QString &	windowScreenId,
		bool	isSticky
	)		const

◆ calculateSnapToLastZone()

PhosphorEngine::SnapResult PhosphorSnapEngine::SnapEngine::calculateSnapToLastZone	(	const QString &	windowId,
		const QString &	windowScreenId,
		bool	isSticky
	)		const

◆ clearSavedFloatingForWindows()

void PhosphorSnapEngine::SnapEngine::clearSavedFloatingForWindows ( const QStringList & windowIds )

inlineoverridevirtual

Remove saved floating state for the given windows (per-window, not bulk clear).

Reimplemented from PhosphorEngine::IPlacementEngine.

◆ clearSavedModeFloating()

void PhosphorSnapEngine::SnapEngine::clearSavedModeFloating ( )

inlineoverridevirtual

Reimplemented from PhosphorEngine::IPlacementEngine.

◆ clearSavedSnapFloating()

void PhosphorSnapEngine::SnapEngine::clearSavedSnapFloating ( )

◆ commitMultiZoneSnap()

void PhosphorSnapEngine::SnapEngine::commitMultiZoneSnap	(	const QString &	windowId,
		const QStringList &	zoneIds,
		const QString &	screenId,
		PhosphorEngine::SnapIntent	intent = `PhosphorEngine::SnapIntent::UserInitiated`
	)

◆ commitSnap()

void PhosphorSnapEngine::SnapEngine::commitSnap	(	const QString &	windowId,
		const QString &	zoneId,
		const QString &	screenId,
		PhosphorEngine::SnapIntent	intent = `PhosphorEngine::SnapIntent::UserInitiated`
	)

◆ currentActivity()

QString PhosphorSnapEngine::SnapEngine::currentActivity ( ) const

◆ currentVirtualDesktop()

int PhosphorSnapEngine::SnapEngine::currentVirtualDesktop ( ) const

Current virtual desktop (1-based; 0 when no virtual-desktop manager is wired) and activity, forwarded from the injected managers.

Exposed so daemon adaptors that gate on disabled context (see isContextDisabled) can read the same values the engine's own restore logic uses, without each adaptor wiring its own managers.

◆ cycleFocus()

void PhosphorSnapEngine::SnapEngine::cycleFocus	(	bool	forward,
		const PhosphorEngine::NavigationContext &	ctx
	)

overridevirtual

Cycle keyboard focus forward/backward through managed windows in the active zone (or the layout cycle order if single-window per zone).

Implements PhosphorEngine::IPlacementEngine.

◆ effectReportedWindows()

const QSet< QString > & PhosphorSnapEngine::SnapEngine::effectReportedWindows ( ) const

inline

◆ emitBatchedResnap()

void PhosphorSnapEngine::SnapEngine::emitBatchedResnap ( const QVector< PhosphorEngine::ZoneAssignmentEntry > & entries )

Emit a single batched resnapToNewLayoutRequested signal.

Serializes the given entries and emits the D-Bus signal once. Used by the daemon to combine entries from multiple screens into one signal, eliminating the per-screen race condition.

Parameters

entries Combined PhosphorEngine::ZoneAssignmentEntry vector from all screens

◆ engineId()

QString PhosphorSnapEngine::SnapEngine::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.

◆ focusInDirection()

void PhosphorSnapEngine::SnapEngine::focusInDirection	(	const QString &	direction,
		const PhosphorEngine::NavigationContext &	ctx
	)

overridevirtual

Walk to the adjacent window in direction and transfer keyboard focus.

Empty direction is a no-op with feedback.

Implements PhosphorEngine::IPlacementEngine.

◆ handoffReceive()

void PhosphorSnapEngine::SnapEngine::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 PhosphorSnapEngine::SnapEngine::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.

◆ isActiveOnScreen()

bool PhosphorSnapEngine::SnapEngine::isActiveOnScreen ( const QString & screenId ) const

overridevirtual

Whether this engine is active on the given screen.

Implements PhosphorEngine::IPlacementEngine.

◆ isEnabled()

bool PhosphorSnapEngine::SnapEngine::isEnabled ( ) const

overridevirtualnoexcept

True when snapping is globally enabled.

Mirrors AutotileEngine::isEnabled() so callers (daemon shortcut dispatch, mode routing) can gate snap-mode operations through the IPlacementEngine interface uniformly. Without this override SnapEngine inherits IPlacementEngine's return false default, which made every snap engine a no-op to any isEnabled() caller.

Reimplemented from PhosphorEngine::IPlacementEngine.

◆ isWindowTracked()

bool PhosphorSnapEngine::SnapEngine::isWindowTracked ( const QString & windowId ) const

overridevirtual

Whether this engine considers the window owned (snapped, snap-floated, or otherwise carried in SnapState's screen/zone maps).

Used by the daemon to disambiguate which engine should handle a shortcut and to decide whether a cross-engine handoff is needed.

Reimplemented from PhosphorEngine::IPlacementEngine.

◆ lastActiveScreenId()

QString PhosphorSnapEngine::SnapEngine::lastActiveScreenId ( ) const

inline

Last screen the engine saw via windowFocused.

Used for OSD fallback when a navigation failure needs to cite a screen and the live cursor hasn't landed on one yet. Exposed as a const getter so tests can verify the focus-tracking contract without dummy signal stubs.

◆ loadState()

void PhosphorSnapEngine::SnapEngine::loadState ( )

overridevirtual

Implements PhosphorEngine::IPlacementEngine.

◆ markWindowReported()

void PhosphorSnapEngine::SnapEngine::markWindowReported ( const QString & windowId )

◆ moveFocusedInDirection()

void PhosphorSnapEngine::SnapEngine::moveFocusedInDirection	(	const QString &	direction,
		const PhosphorEngine::NavigationContext &	ctx
	)

overridevirtual

Move the focused window into the adjacent zone in direction (displacing or filling the target).

Empty direction is a no-op.

Implements PhosphorEngine::IPlacementEngine.

◆ moveFocusedToPosition()

void PhosphorSnapEngine::SnapEngine::moveFocusedToPosition	(	int	zoneNumber,
		const PhosphorEngine::NavigationContext &	ctx
	)

overridevirtual

Move the focused window to the layout zone with zoneNumber (1-based) on ctx.screenId.

PhosphorZones::Zone numbers outside [1,9] are rejected.

Implements PhosphorEngine::IPlacementEngine.

◆ onWindowClaimed()

void PhosphorSnapEngine::SnapEngine::onWindowClaimed ( const QString & windowId )

overrideprotectedvirtual

Implements PhosphorEngine::PlacementEngineBase.

◆ onWindowFloated()

void PhosphorSnapEngine::SnapEngine::onWindowFloated ( const QString & windowId )

overrideprotectedvirtual

Implements PhosphorEngine::PlacementEngineBase.

◆ onWindowReleased()

void PhosphorSnapEngine::SnapEngine::onWindowReleased ( const QString & windowId )

overrideprotectedvirtual

Implements PhosphorEngine::PlacementEngineBase.

◆ onWindowUnfloated()

void PhosphorSnapEngine::SnapEngine::onWindowUnfloated ( const QString & windowId )

overrideprotectedvirtual

Implements PhosphorEngine::PlacementEngineBase.

◆ pruneStaleWindows()

int PhosphorSnapEngine::SnapEngine::pruneStaleWindows ( const QSet< QString > & aliveWindowIds )

overridevirtual

Reimplemented from PhosphorEngine::PlacementEngineBase.

◆ pushFocusedToEmptyZone()

void PhosphorSnapEngine::SnapEngine::pushFocusedToEmptyZone ( const PhosphorEngine::NavigationContext & ctx )

Move the focused window to the first empty zone on ctx.screenId.

The IPlacementEngine override pushToEmptyZone() delegates here.

◆ pushToEmptyZone()

void PhosphorSnapEngine::SnapEngine::pushToEmptyZone ( const PhosphorEngine::NavigationContext & ctx )

overridevirtual

Move the focused window to the first empty zone on ctx.screenId.

Implements PhosphorEngine::IPlacementEngine.

◆ reapplyLayout()

void PhosphorSnapEngine::SnapEngine::reapplyLayout ( const PhosphorEngine::NavigationContext & ctx )

overridevirtual

Re-apply the current layout to all managed windows.

Forwards to resnapToNewLayout().

Implements PhosphorEngine::IPlacementEngine.

◆ resnapCurrentAssignments()

void PhosphorSnapEngine::SnapEngine::resnapCurrentAssignments ( const QString & screenFilter = QString() )

Resnap windows to their current zone assignments (re-apply geometries)

Parameters

screenFilter Optional screen name filter (empty = all screens)

◆ resnapFromAutotileOrder()

void PhosphorSnapEngine::SnapEngine::resnapFromAutotileOrder	(	const QStringList &	autotileWindowOrder,
		const QString &	screenId
	)

Resnap windows using autotile window order as assignment source.

Parameters

autotileWindowOrder	Ordered list of window IDs from autotile engine
screenId	Screen to resnap on

Note: Falls back to resnapCurrentAssignments if no entries are calculated

◆ resnapToNewLayout()

void PhosphorSnapEngine::SnapEngine::resnapToNewLayout ( )

Resnap windows from previous layout to current layout after layout switch.

Maps windows by zone number (1->1, 2->2, etc.) with wrapping when new layout has fewer zones.

◆ resnapToNewLayoutRequested

void PhosphorSnapEngine::SnapEngine::resnapToNewLayoutRequested ( const QString & resnapData )

signal

Batched resnap data (routed through WTA::handleBatchedResnap for bookkeeping)

◆ resolveUnfloatGeometry()

PhosphorEngine::UnfloatResult PhosphorSnapEngine::SnapEngine::resolveUnfloatGeometry	(	const QString &	windowId,
		const QString &	fallbackScreen
	)		const

◆ resolveWindowRestore()

PhosphorEngine::SnapResult PhosphorSnapEngine::SnapEngine::resolveWindowRestore	(	const QString &	windowId,
		const QString &	screenId,
		bool	sticky,
		PhosphorEngine::WindowKind	kind = `PhosphorEngine::WindowKind::Unknown`
	)

Resolve auto-snap for a newly opened window.

Runs the 4-level fallback chain:

App rules (highest priority)
Persisted zone (session restore)
Auto-assign to empty zone
Snap to last zone (final fallback)

Returns a PhosphorEngine::SnapResult so the D-Bus adaptor can unpack geometry for the KWin effect. Also handles floating windows (skips snap, emits feedback).

Parameters

windowId	Window identifier
screenId	Screen where the window appeared
sticky	Whether the window is on all desktops
kind	Structural kind of the opening window. Compared against the kind recorded on the matching PendingRestore entry; when both sides are concrete and disagree, the restore is refused and the entry is left intact for the next-opening window of the right kind. Default `Unknown` is permissive.

Returns: PhosphorEngine::SnapResult with geometry and zone info, or PhosphorEngine::SnapResult::noSnap()

◆ restoreFocusedWindow()

void PhosphorSnapEngine::SnapEngine::restoreFocusedWindow ( const PhosphorEngine::NavigationContext & ctx )

overridevirtual

Restore the focused window to its captured pre-snap size and unsnap.

Implements PhosphorEngine::IPlacementEngine.

◆ restoreSavedModeFloat()

bool PhosphorSnapEngine::SnapEngine::restoreSavedModeFloat ( const QString & windowId )

inlineoverridevirtual

Reimplemented from PhosphorEngine::IPlacementEngine.

◆ restoreSnapFloating()

bool PhosphorSnapEngine::SnapEngine::restoreSnapFloating ( const QString & windowId )

◆ rotateWindows()

void PhosphorSnapEngine::SnapEngine::rotateWindows	(	bool	clockwise,
		const PhosphorEngine::NavigationContext &	ctx
	)

overridevirtual

Rotate snapped windows through the layout's zone order, dispatched via IPlacementEngine.

Forwards to rotateWindowsInLayout().

Implements PhosphorEngine::IPlacementEngine.

◆ rotateWindowsInLayout()

void PhosphorSnapEngine::SnapEngine::rotateWindowsInLayout	(	bool	clockwise,
		const QString &	screenId
	)

Rotate snapped windows through the layout's zone order on screenId.

◆ saveModeFloat()

void PhosphorSnapEngine::SnapEngine::saveModeFloat ( const QString & windowId )

inlineoverridevirtual

Reimplemented from PhosphorEngine::IPlacementEngine.

◆ saveSnapFloating()

void PhosphorSnapEngine::SnapEngine::saveSnapFloating ( const QString & windowId )

◆ saveState()

void PhosphorSnapEngine::SnapEngine::saveState ( )

overridevirtual

Implements PhosphorEngine::IPlacementEngine.

◆ screenForTrackedWindow()

QString PhosphorSnapEngine::SnapEngine::screenForTrackedWindow ( const QString & windowId ) const

overridevirtual

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.

◆ setAutotileEngine()

void PhosphorSnapEngine::SnapEngine::setAutotileEngine ( PhosphorEngine::IPlacementEngine * engine )

Set the autotile engine for screen ownership checks.

SnapEngine is active on screens where AutotileEngine is NOT active. This must be called after the AutotileEngine is created.

Parameters

engine AutotileEngine instance (not owned, must outlive SnapEngine)

◆ setNavigationStateProvider()

void PhosphorSnapEngine::SnapEngine::setNavigationStateProvider ( INavigationStateProvider * provider )

Wire the typed navigation-state provider.

Replaces the opaque QObject* setWindowTrackingAdaptor() that dispatched lastActiveWindowId / lastActiveScreenName / lastCursorScreenName / frameGeometry via QMetaObject::invokeMethod. The daemon's WindowTrackingAdaptor must implement (or wrap) INavigationStateProvider.

Must be set after construction and before any navigation method is called. Not owned; must outlive SnapEngine.

◆ setPersistenceDelegate()

void PhosphorSnapEngine::SnapEngine::setPersistenceDelegate	(	std::function< void()>	saveFn,
		std::function< void()>	loadFn
	)

inline

Set persistence callbacks for save/load.

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

Parameters

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

◆ setShouldRestorePredicate()

void PhosphorSnapEngine::SnapEngine::setShouldRestorePredicate ( ShouldRestorePredicate predicate )

inline

Inject the auto-snap-restore gate.

See ShouldRestorePredicate.

Ownership: the caller keeps any captured state valid for the engine's lifetime. To detach safely, clear via setShouldRestorePredicate({}) before destroying the captured object.

◆ setWindowFloat()

void PhosphorSnapEngine::SnapEngine::setWindowFloat	(	const QString &	windowId,
		bool	shouldFloat
	)

overridevirtual

Set floating state explicitly (directional, not toggle).

Implements PhosphorEngine::IPlacementEngine.

◆ setZoneAdjacencyResolver()

void PhosphorSnapEngine::SnapEngine::setZoneAdjacencyResolver ( IZoneAdjacencyResolver * resolver )

Set typed zone-adjacency resolver for directional navigation.

Replaces the opaque QObject* setZoneDetectionAdaptor() that dispatched via QMetaObject::invokeMethod. The daemon's ZoneDetectionAdaptor must implement (or wrap) IZoneAdjacencyResolver.

Parameters

resolver Non-owning pointer; must outlive SnapEngine.

◆ snapAllWindows() [1/2]

void PhosphorSnapEngine::SnapEngine::snapAllWindows ( const PhosphorEngine::NavigationContext & ctx )

overridevirtual

Snap every unmanaged window on the screen.

The IPlacementEngine override takes PhosphorEngine::NavigationContext; coexists with the existing snapAllWindows(const QString&) method which it delegates to.

Implements PhosphorEngine::IPlacementEngine.

◆ snapAllWindows() [2/2]

void PhosphorSnapEngine::SnapEngine::snapAllWindows ( const QString & screenId )

Request the KWin effect to collect and snap all unsnapped windows.

Parameters

screenId Screen to operate on

◆ snapAllWindowsRequested

void PhosphorSnapEngine::SnapEngine::snapAllWindowsRequested ( const QString & screenId )

signal

Request KWin effect to collect unsnapped windows and snap them all.

◆ snapState()

SnapState * PhosphorSnapEngine::SnapEngine::snapState ( ) const

inline

◆ stateForScreen() [1/2]

const PhosphorEngine::IPlacementState * PhosphorSnapEngine::SnapEngine::stateForScreen ( const QString & screenId ) const

overridevirtual

Implements PhosphorEngine::IPlacementEngine.

◆ stateForScreen() [2/2]

PhosphorEngine::IPlacementState * PhosphorSnapEngine::SnapEngine::stateForScreen ( const QString & screenId )

overridevirtual

Per-screen state object for the given screen.

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

Implements PhosphorEngine::IPlacementEngine.

◆ swapFocusedInDirection()

void PhosphorSnapEngine::SnapEngine::swapFocusedInDirection	(	const QString &	direction,
		const PhosphorEngine::NavigationContext &	ctx
	)

overridevirtual

Swap the focused window with whatever's in the adjacent zone in direction.

Empty direction is a no-op.

Implements PhosphorEngine::IPlacementEngine.

◆ toggleFocusedFloat()

void PhosphorSnapEngine::SnapEngine::toggleFocusedFloat ( const PhosphorEngine::NavigationContext & ctx )

overridevirtual

Toggle the focused window between snapped and floating.

Implements PhosphorEngine::IPlacementEngine.

◆ toggleWindowFloat()

void PhosphorSnapEngine::SnapEngine::toggleWindowFloat	(	const QString &	windowId,
		const QString &	screenId
	)

overridevirtual

Toggle between managed and floating.

Implements PhosphorEngine::IPlacementEngine.

◆ uncommitSnap()

void PhosphorSnapEngine::SnapEngine::uncommitSnap ( const QString & windowId )

◆ windowClosed()

void PhosphorSnapEngine::SnapEngine::windowClosed ( const QString & windowId )

overridevirtual

A window was closed.

Implements PhosphorEngine::IPlacementEngine.

◆ windowFloatingClearedForSnap

void PhosphorSnapEngine::SnapEngine::windowFloatingClearedForSnap	(	const QString &	windowId,
		const QString &	screenId
	)

signal

Floating state cleared as part of a commit. WTA relays as windowFloatingChanged(id, false, screen).

◆ windowFocused()

void PhosphorSnapEngine::SnapEngine::windowFocused	(	const QString &	windowId,
		const QString &	screenId
	)

overridevirtual

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.

Implements PhosphorEngine::IPlacementEngine.

◆ windowOpened()

void PhosphorSnapEngine::SnapEngine::windowOpened	(	const QString &	windowId,
		const QString &	screenId,
		int	minWidth,
		int	minHeight
	)

overridevirtual

A new window appeared on this engine's screen.

Implements PhosphorEngine::IPlacementEngine.

◆ windowSnapStateChanged

void PhosphorSnapEngine::SnapEngine::windowSnapStateChanged	(	const QString &	windowId,
		const PhosphorProtocol::WindowStateEntry &	entry
	)

signal

Snap state changed (commit / uncommit). WTA relays to D-Bus windowStateChanged.

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

phosphor-snap-engine/include/PhosphorSnapEngine/SnapEngine.h

Phosphor Qt6 / Wayland library suite for window-management tools

Public Types

Signals

Public Member Functions

Protected Member Functions

Detailed Description

Member Typedef Documentation

◆ ShouldRestorePredicate

Constructor & Destructor Documentation

◆ SnapEngine()

◆ ~SnapEngine()

Member Function Documentation

◆ applyBatchAssignments()

◆ applyGeometriesBatch

◆ applyGeometryRequested

◆ calculateResnapEntriesFromAutotileOrder()

◆ calculateResnapFromAutotileOrder()

◆ calculateResnapFromCurrentAssignments()

◆ calculateResnapFromPreviousLayout()

◆ calculateRestoreFromSession()

◆ calculateRotation()

◆ calculateSnapAllWindowEntries()

◆ calculateSnapAllWindows()

◆ calculateSnapToAppRule()

◆ calculateSnapToEmptyZone()

◆ calculateSnapToLastZone()

◆ clearSavedFloatingForWindows()

◆ clearSavedModeFloating()

◆ clearSavedSnapFloating()

◆ commitMultiZoneSnap()

◆ commitSnap()

◆ currentActivity()

◆ currentVirtualDesktop()

◆ cycleFocus()

◆ effectReportedWindows()

◆ emitBatchedResnap()

◆ engineId()

◆ focusInDirection()

◆ handoffReceive()

◆ handoffRelease()

◆ isActiveOnScreen()

◆ isEnabled()

◆ isWindowTracked()

◆ lastActiveScreenId()

◆ loadState()

◆ markWindowReported()

◆ moveFocusedInDirection()

◆ moveFocusedToPosition()

◆ onWindowClaimed()

◆ onWindowFloated()

◆ onWindowReleased()

◆ onWindowUnfloated()

◆ pruneStaleWindows()

◆ pushFocusedToEmptyZone()

◆ pushToEmptyZone()

◆ reapplyLayout()

◆ resnapCurrentAssignments()

◆ resnapFromAutotileOrder()

◆ resnapToNewLayout()

◆ resnapToNewLayoutRequested

◆ resolveUnfloatGeometry()

◆ resolveWindowRestore()

◆ restoreFocusedWindow()

◆ restoreSavedModeFloat()

◆ restoreSnapFloating()

◆ rotateWindows()

◆ rotateWindowsInLayout()

◆ saveModeFloat()

◆ saveSnapFloating()

◆ saveState()

◆ screenForTrackedWindow()

◆ setAutotileEngine()

◆ setNavigationStateProvider()

◆ setPersistenceDelegate()

◆ setShouldRestorePredicate()

◆ setWindowFloat()

◆ setZoneAdjacencyResolver()

◆ snapAllWindows() [1/2]

◆ snapAllWindows() [2/2]

◆ snapAllWindowsRequested

◆ snapState()