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.

using	RestorePositionPredicate = std::function< bool(const QString &windowId)>
	Predicate consulted in `resolveWindowRestore` to decide whether a FLOATED window should have its previous global position restored on open.

using	ManagedRestorePredicate = std::function< bool(const QString &windowId)>
	Predicate consulted in `resolveWindowRestore` to decide whether a window that was SNAPPED at logout should be restored to its recorded zone on reopen/login (the "managed restore").

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

using	PlacementZonesResolver = std::function< PlacementDirective(const QString &windowId, const QString &screenId)>
	Resolver yielding the open-placement directive — SnapToZone ordinals plus an optional RouteToScreen target and an optional RouteToDesktop target — for an opening window because a placement window rule matched it.

using	ExclusionQueryProvider = std::function< std::optional< PhosphorWindowRules::WindowQuery >(const QString &windowId)>
	Provider that builds the full WindowQuery (window class / title / role / frame size / flags) for a live windowId.

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.

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

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

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

void	activateWindowRequested (const QString &windowId)

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

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

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

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

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

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

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

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

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

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

Public Member Functions
	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.

int	currentVirtualDesktopForScreen (const QString &screenId) const
	This screen's current virtual desktop (Plasma 6.7 per-output virtual desktops, #648), falling back to the global currentVirtualDesktop().

QString	currentActivity () const

std::pair< QString, QRect >	resolveCrossDesktopZone (const QString &currentZoneId, const QString &screenId, int targetDesktop) const
	Resolve the zone on `screenId's` `targetDesktop` layout that is positionally equivalent to `currentZoneId` (1-based index of zones sorted by number), plus its pixel geometry.

QString	entryZoneForCrossing (const QString &direction, const QString &neighbourScreen) const
	The zone a window ENTERS when it crosses onto `neighbourScreen` moving in `direction:` the first zone on the edge facing back toward the source (crossing "right" enters the neighbour's left-edge zone).

QString	windowInZoneOnScreen (const QString &zoneId, const QString &screenId) const
	The window snapped to `zoneId` on `screenId` (the daemon's stored assignment pins it to that output), or empty if the zone is unoccupied there.

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

void	setManagedRestorePredicate (ManagedRestorePredicate predicate)
	Inject the managed (snapped-to-zone) restore gate.

void	setFloatPredicate (FloatPredicate predicate)

void	setPlacementZonesResolver (PlacementZonesResolver resolver)

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, const QStringList &preClaimedZoneIds={})
	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	setCrossSurfaceResolver (PhosphorEngine::ICrossSurfaceResolver *resolver) override
	Inject the cross-surface resolver (neighbour output / desktop lookup), threaded into the navigation target resolver so a no-adjacent-zone boundary crosses into the neighbouring output instead of failing.

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	reapplyManagedWindowAppearance () override
	Re-emit the snap geometry for every currently-snapped (non-floating) window so the compositor re-applies its snap border / hidden title bar after a bridge reconnect.

std::optional< PhosphorEngine::WindowPlacement >	capturePlacement (const QString &windowId) const override
	Unified placement model — report this window's current snap state (snapped or floated) for persistence, or nullopt if untracked.

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, int virtualDesktop=0)
	`virtualDesktop` pins the assignment to a specific 1-based desktop; 0 (default) records it on the window's current desktop.

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

void	uncommitSnap (const QString &windowId)

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

PhosphorEngine::UnfloatResult	resolveFallbackUnfloatGeometry (const QString &windowId, const QString &fallbackScreen) const
	Fallback unfloat target for a window with NO pre-float zone (a never-snapped window that defaulted to floating).

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

PhosphorEngine::SnapResult	calculateSnapToPlacementRule (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

QVector< PhosphorEngine::ZoneAssignmentEntry >	calculateResnapFromPreviousLayout ()

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

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

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

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

void	markWindowReported (const QString &windowId)

const QSet< QString > &	effectReportedWindows () const

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

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.

void	setExcludeRuleSet (const PhosphorWindowRules::WindowRuleSet *ruleSet)
	Wire the daemon's filtered Exclude rule set into the snap engine.

void	setExclusionQueryProvider (ExclusionQueryProvider provider)
	Inject the exclusion query provider.

bool	isAppIdExcluded (const QString &appId) const
	True if `appId` matches an enabled `Exclude`-action WindowRule resolved against an appId-ONLY `WindowQuery`.

bool	isWindowExcluded (const QString &windowId) const
	Resolve exclusion for a live windowId using the FULL window attributes when the exclusion query provider is wired (matching the autotile engine): evaluates the Exclude rule set against the complete WindowQuery and applies the minimum-window-size thresholds to the query's frame size.

Public Member Functions inherited from PhosphorEngine::PlacementEngineBase
void	setEngineSettings (QObject *settings)

QObject *	engineSettings () const

	~PlacementEngineBase () override

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

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

virtual QSet< QString >	activeScreens () const

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

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

Additional Inherited Members
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

◆ ExclusionQueryProvider

using PhosphorSnapEngine::SnapEngine::ExclusionQueryProvider = std::function<std::optional<PhosphorWindowRules::WindowQuery>(const QString& windowId)>

Provider that builds the full WindowQuery (window class / title / role / frame size / flags) for a live windowId.

Daemon-injected, keyed by the live windowId — the daemon resolves it from its WindowRegistry (the same buildRuleQueryForWindow the float / restore predicates use). When set, exclusion evaluates a window's FULL attributes (matching the autotile engine) instead of appId alone, and the frame size carried in the query is checked against the minimum-window-size thresholds. When UNSET (default) the engine falls back to the appId-only query — the historical behaviour unit tests rely on. A null/empty optional from the provider (metadata not yet known) also falls back to appId-only.

◆ FloatPredicate

using PhosphorSnapEngine::SnapEngine::FloatPredicate = std::function<bool(const QString& windowId)>

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

Daemon-injected, keyed by the live windowId, evaluated on the window-open path. When UNSET (default) no window is rule-floated and the engine keeps its historical open behaviour (path unit tests rely on this). Same lifetime contract as setRestorePositionPredicate — clear with {} before destroying any state the closure captured.

◆ ManagedRestorePredicate

using PhosphorSnapEngine::SnapEngine::ManagedRestorePredicate = std::function<bool(const QString& windowId)>

Predicate consulted in resolveWindowRestore to decide whether a window that was SNAPPED at logout should be restored to its recorded zone on reopen/login (the "managed restore").

This is the snapped-to-zone analogue of RestorePositionPredicate (which governs FLOATED records). Keyed by the live windowId so the daemon closure stays settings-agnostic (LGPL boundary) — the engine only asks. The daemon wires it to the restoreWindowsToZonesOnLogin setting.

When the predicate returns false the stored snap is not re-applied; the window falls through to the normal auto-snap policy chain, exactly as a disabled-context rejection does. When UNSET (default) the engine restores snapped records unconditionally — the historical behaviour unit tests rely on. This gate is independent of ShouldRestorePredicate (the disabled-context gate); both must opt in for a managed restore to proceed.

◆ PlacementZonesResolver

using PhosphorSnapEngine::SnapEngine::PlacementZonesResolver = std::function<PlacementDirective(const QString& windowId, const QString& screenId)>

Resolver yielding the open-placement directive — SnapToZone ordinals plus an optional RouteToScreen target and an optional RouteToDesktop target — for an opening window because a placement window rule matched it.

Daemon-injected, keyed by the live windowId plus the screen the window is opening on (so a rule carrying a ScreenId constraint resolves against the window's current screen), evaluated on the window-open path (calculateSnapToPlacementRule, the highest-priority restore chain level). See PhosphorSnapEngine::PlacementDirective. Empty ordinals ⇒ no SnapToZone rule matched; multiple ordinals request a zone span (their unioned bounding rect). The engine stays settings/rule- store-agnostic (LGPL boundary) — it only asks. When UNSET (default) no window is rule-snapped and the engine keeps its historical open behaviour (path unit tests rely on this). Same lifetime contract as setFloatPredicate — clear with {} before destroying any captured state.

◆ RestorePositionPredicate

using PhosphorSnapEngine::SnapEngine::RestorePositionPredicate = std::function<bool(const QString& windowId)>

Predicate consulted in resolveWindowRestore to decide whether a FLOATED window should have its previous global position restored on open.

(Snapping is two-state — snapped or floated; "floated" is the only unsnapped state.)

Keyed by the live windowId so the daemon closure can build a full WindowQuery (window class / title / role) from its WindowRegistry and evaluate the per-window RestorePosition rule, falling back to the snappingRestoreFloatedWindowsOnLogin setting. Like ShouldRestorePredicate the engine stays settings-agnostic (LGPL boundary) — it only asks.

Returns true to restore the recorded position (cross-screen allowed — stored geometry is in global compositor coordinates, so re-applying it lands the window back on its original monitor).

The gate governs two things for FLOATED records (snapped-to-zone restore is unaffected):

cross-screen CONSUMPTION eligibility — a record whose recorded screen differs from the reopening screen is only consumed when the predicate opts the window in; otherwise consumption stays gated on the opening screen;
the geometry MOVE — a floated record ALWAYS re-marks the window floating (windowFloatingChanged), but its recorded position is re-applied only when the predicate opts in.

When the predicate is UNSET (default), the engine preserves its historical behaviour: a floated record is consumed only on the screen it reopens on and is marked floating without a position move — the path unit tests rely on.

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

The engine itself only ever emits action="rotate"; the SnapAdaptor layer attaches "resnap" / "vs_reconfigure" when it relays its own batches over the same WTA D-Bus signal ("snap_all" batches never cross the wire — the effect builds those locally). The action label disambiguates the cause downstream.

◆ 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,
		const QStringList &	preClaimedZoneIds = `{}`
	)

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
preClaimedZoneIds	Zone IDs already reserved by OTHER restore producers (e.g. the daemon's windowsReleased snap-zone restores for windows that were floated in autotile and are absent from the tile order). Seeds the claim ledger so the positional fallback never re-uses a zone another producer is reclaiming — the two-windows-one-zone collision.

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

◆ calculateResnapFromAutotileOrder()

QVector< PhosphorEngine::ZoneAssignmentEntry > PhosphorSnapEngine::SnapEngine::calculateResnapFromAutotileOrder	(	const QStringList &	autotileWindowOrder,
		const QString &	screenId,
		const QStringList &	preClaimedZoneIds = `{}`
	)		const

◆ calculateResnapFromCurrentAssignments()

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

◆ calculateResnapFromPreviousLayout()

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

◆ 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

◆ 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

◆ calculateSnapToPlacementRule()

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

◆ capturePlacement()

std::optional< PhosphorEngine::WindowPlacement > PhosphorSnapEngine::SnapEngine::capturePlacement ( const QString & windowId ) const

overridevirtual

Unified placement model — report this window's current snap state (snapped or floated) for persistence, or nullopt if untracked.

Reimplemented from PhosphorEngine::IPlacementEngine.

◆ commitMultiZoneSnap()

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

◆ commitSnap()

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

virtualDesktop pins the assignment to a specific 1-based desktop; 0 (default) records it on the window's current desktop.

Non-zero is used by the RouteToDesktop placement path so the zone assignment is tracked on the desktop the window is being moved to.

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

Public for symmetry with AutotileEngine's analogous accessors and to keep the engine's "current context" surface coherent — the daemon uses Daemon::currentDesktop() / Daemon::currentActivity() directly rather than going through the engine. The only current in-tree caller of these two is lifecycle.cpp (snap-engine- internal restore logic); kept public so a future adaptor that wants the engine's own view (e.g. for a per-engine OSD) doesn't have to wire its own VDM.

◆ currentVirtualDesktopForScreen()

int PhosphorSnapEngine::SnapEngine::currentVirtualDesktopForScreen ( const QString & screenId ) const

This screen's current virtual desktop (Plasma 6.7 per-output virtual desktops, #648), falling back to the global currentVirtualDesktop().

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

◆ entryZoneForCrossing()

QString PhosphorSnapEngine::SnapEngine::entryZoneForCrossing	(	const QString &	direction,
		const QString &	neighbourScreen
	)		const

The zone a window ENTERS when it crosses onto neighbourScreen moving in direction: the first zone on the edge facing back toward the source (crossing "right" enters the neighbour's left-edge zone).

Empty when no zone-adjacency resolver is wired or the neighbour has no such zone. Used by the daemon cross-mode handoff to place a window arriving on a snap monitor.

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

◆ isAppIdExcluded()

bool PhosphorSnapEngine::SnapEngine::isAppIdExcluded ( const QString & appId ) const

True if appId matches an enabled Exclude-action WindowRule resolved against an appId-ONLY WindowQuery.

This is a narrow seam: the runtime exclusion path is isWindowExcluded, which evaluates the FULL window attributes; this method survives as (a) the early-init / no-metadata fallback inside isWindowExcluded and (b) a directly testable hook for the rule-set wiring (nullptr borrow, empty-set short-circuit, evaluator rebind on pointer change, revision-bump invalidation). An Exclude rule keyed on a non-AppId field (WindowClass Contains …, Title Regex …) does NOT match here — use isWindowExcluded for that. Pure const observer — no side effects beyond the mutable evaluator cache.

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

◆ isWindowExcluded()

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

Resolve exclusion for a live windowId using the FULL window attributes when the exclusion query provider is wired (matching the autotile engine): evaluates the Exclude rule set against the complete WindowQuery and applies the minimum-window-size thresholds to the query's frame size.

Falls back to the appId-only path (isAppIdExcluded's query shape) when no provider is set or window metadata is not yet known. Public so the unit-test layer can drive the wiring directly.

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

◆ pruneStaleWindows()

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

overridevirtual

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

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

Reimplemented from PhosphorEngine::PlacementEngineBase.

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

◆ reapplyManagedWindowAppearance()

void PhosphorSnapEngine::SnapEngine::reapplyManagedWindowAppearance ( )

overridevirtual

Re-emit the snap geometry for every currently-snapped (non-floating) window so the compositor re-applies its snap border / hidden title bar after a bridge reconnect.

Does not recompute zone assignments. See IPlacementEngine::reapplyManagedWindowAppearance().

Reimplemented from 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)

◆ resolveCrossDesktopZone()

std::pair< QString, QRect > PhosphorSnapEngine::SnapEngine::resolveCrossDesktopZone	(	const QString &	currentZoneId,
		const QString &	screenId,
		int	targetDesktop
	)		const

Resolve the zone on screenId's targetDesktop layout that is positionally equivalent to currentZoneId (1-based index of zones sorted by number), plus its pixel geometry.

Returns an empty pair when the target desktop has no layout, no matching slot, or invalid geometry. Public (like the desktop/activity accessors) so cross-surface handoff logic and tests can map a window's slot onto another desktop's layout.

◆ resolveFallbackUnfloatGeometry()

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

Fallback unfloat target for a window with NO pre-float zone (a never-snapped window that defaulted to floating).

Returns a found result ONLY when the unfloatFallbackToZone setting is on, resolving last-used → first-empty → first zone in the window's screen's layout. Returns not-found when the setting is off or no zone can be resolved (so the caller keeps the window floating with feedback).

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

A matched SnapToZone placement rule has highest priority and overrides any stored placement (the store still re-binds the record first, so the window's float-back geometry survives the override). Otherwise the unified WindowPlacementStore reopens the window from its snapped or floated record (cross-screen where the predicates allow). With neither, the fallback chain runs:

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. Accepted for D-Bus wire-compatibility but no longer gates restore — the matched WindowPlacement record carries its own kind.

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.

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

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

◆ setCrossSurfaceResolver()

void PhosphorSnapEngine::SnapEngine::setCrossSurfaceResolver ( PhosphorEngine::ICrossSurfaceResolver * resolver )

overridevirtual

Inject the cross-surface resolver (neighbour output / desktop lookup), threaded into the navigation target resolver so a no-adjacent-zone boundary crosses into the neighbouring output instead of failing.

Reimplemented from PhosphorEngine::IPlacementEngine.

◆ setExcludeRuleSet()

void PhosphorSnapEngine::SnapEngine::setExcludeRuleSet ( const PhosphorWindowRules::WindowRuleSet * ruleSet )

Wire the daemon's filtered Exclude rule set into the snap engine.

See the comment block on the private members and the impl in navigation_actions.cpp for the lifetime contract — the pointer is borrowed and the cached evaluator drops on a pointer change.

The borrowed rule set MUST outlive every subsequent exclusion resolve (isWindowExcluded / evaluateExcludeRules, and the legacy isAppIdExcluded seam). The Daemon currently guarantees this through member-declaration order (m_excludeRuleSet is declared before m_snapEngine so reverse-order destruction tears the engine down first), AND additionally clears the borrow symmetrically by calling setExcludeRuleSet(nullptr) in Daemon::stop() before m_snapEngine.reset() — that explicit teardown survives a future reordering or ownership move that would otherwise silently introduce a dangling pointer.

Declared OUTSIDE the Q_SIGNALS section below: MOC treats every declaration in Q_SIGNALS: as a signal and generates a stub body for it, so placing this setter inside that section makes the translation unit redefine the function and the link fails.

◆ setExclusionQueryProvider()

void PhosphorSnapEngine::SnapEngine::setExclusionQueryProvider ( ExclusionQueryProvider provider )

inline

Inject the exclusion query provider.

See ExclusionQueryProvider. Same lifetime contract as setExcludeRuleSet — the caller keeps captured state valid for the engine's lifetime; clear with {} before destroying it.

◆ setFloatPredicate()

void PhosphorSnapEngine::SnapEngine::setFloatPredicate ( FloatPredicate predicate )

inline

◆ setManagedRestorePredicate()

void PhosphorSnapEngine::SnapEngine::setManagedRestorePredicate ( ManagedRestorePredicate predicate )

inline

Inject the managed (snapped-to-zone) restore gate.

See ManagedRestorePredicate. Same lifetime contract as setRestorePositionPredicate — clear with {} before destroying any captured state.

◆ 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

◆ setPlacementZonesResolver()

void PhosphorSnapEngine::SnapEngine::setPlacementZonesResolver ( PlacementZonesResolver resolver )

inline

◆ setRestorePositionPredicate()

void PhosphorSnapEngine::SnapEngine::setRestorePositionPredicate ( RestorePositionPredicate predicate )

inline

Inject the unsnapped-position-restore gate.

See RestorePositionPredicate. Same lifetime contract as setShouldRestorePredicate — clear with {} before destroying any captured 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 for that engine. Callers must not use a non-null return as a proxy for "engine manages this screen" — use isActiveOnScreen() for that check.

Implements PhosphorEngine::IPlacementEngine.

◆ swapFocusedInDirection()

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.

◆ windowInZoneOnScreen()

QString PhosphorSnapEngine::SnapEngine::windowInZoneOnScreen	(	const QString &	zoneId,
		const QString &	screenId
	)		const

The window snapped to zoneId on screenId (the daemon's stored assignment pins it to that output), or empty if the zone is unoccupied there.

Used by the cross-mode swap to find the snap partner when THIS engine is the swap target.

◆ 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

Additional Inherited Members

Detailed Description

Member Typedef Documentation

◆ ExclusionQueryProvider

◆ FloatPredicate

◆ ManagedRestorePredicate

◆ PlacementZonesResolver

◆ RestorePositionPredicate

◆ ShouldRestorePredicate

Constructor & Destructor Documentation

◆ SnapEngine()

◆ ~SnapEngine()

Member Function Documentation

◆ applyBatchAssignments()

◆ applyGeometriesBatch

◆ applyGeometryRequested

◆ calculateResnapEntriesFromAutotileOrder()

◆ calculateResnapFromAutotileOrder()

◆ calculateResnapFromCurrentAssignments()

◆ calculateResnapFromPreviousLayout()

◆ calculateRotation()

◆ calculateSnapAllWindowEntries()

◆ calculateSnapAllWindows()

◆ calculateSnapToEmptyZone()

◆ calculateSnapToLastZone()

◆ calculateSnapToPlacementRule()

◆ capturePlacement()

◆ commitMultiZoneSnap()

◆ commitSnap()

◆ currentActivity()

◆ currentVirtualDesktop()

◆ currentVirtualDesktopForScreen()

◆ cycleFocus()

◆ effectReportedWindows()

◆ emitBatchedResnap()

◆ engineId()

◆ entryZoneForCrossing()

◆ focusInDirection()

◆ handoffReceive()

◆ handoffRelease()

◆ isActiveOnScreen()

◆ isAppIdExcluded()

◆ isEnabled()

◆ isWindowExcluded()

◆ isWindowTracked()

◆ lastActiveScreenId()

◆ loadState()

◆ markWindowReported()

◆ moveFocusedInDirection()

◆ moveFocusedToPosition()

◆ pruneStaleWindows()

◆ pushFocusedToEmptyZone()

◆ pushToEmptyZone()

◆ reapplyLayout()

◆ reapplyManagedWindowAppearance()

◆ resnapCurrentAssignments()

◆ resnapFromAutotileOrder()

◆ resnapToNewLayout()

◆ resnapToNewLayoutRequested

◆ resolveCrossDesktopZone()

◆ resolveFallbackUnfloatGeometry()

◆ resolveUnfloatGeometry()

◆ resolveWindowRestore()

◆ restoreFocusedWindow()

◆ rotateWindows()

◆ rotateWindowsInLayout()

◆ saveState()

◆ screenForTrackedWindow()

◆ setAutotileEngine()

◆ setCrossSurfaceResolver()

◆ setExcludeRuleSet()

◆ setExclusionQueryProvider()

◆ setFloatPredicate()

◆ setManagedRestorePredicate()

◆ setNavigationStateProvider()

◆ setPersistenceDelegate()

◆ setPlacementZonesResolver()