Phosphor
Qt6 / Wayland library suite for window-management tools
Loading...
Searching...
No Matches
PhosphorSnapEngine::SnapEngine Class Reference

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

#include <PhosphorSnapEngine/SnapEngine.h>

Inheritance diagram for PhosphorSnapEngine::SnapEngine:
[legend]

Public Types

enum class  ResnapFeedback { Report , Silent }
 Whether a resnap that finds nothing says so (no_windows_to_resnap): a user verb does, a layout switch or a settings reflow does not. More...
using ShouldRestorePredicate = std::function<bool(const QString& screenId, int desktop)>
 Predicate deciding whether snapping may place a window on (screenId, desktop), so nothing is placed in a context the user disabled snapping for.
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 LiveModeResolver = std::function<PhosphorZones::AssignmentEntry::Mode(const QString& screenId)>
 The daemon's live mode resolver (its ScreenModeRouter, an unclaimed tiling mode downgraded to Snapping).
using ContextModeResolver
 The mode the daemon resolves for a (screenId, desktop, activity) context, in view or hidden: readoptParked takes a parked zone back only into one answered Snapping (F1137).
using TilingEngineLiveResolver
 INERT, kept for ABI: nothing reads it since snap no longer defers an open to another engine's reclaim (the reopen contract), and the daemon does not wire it.
using FloatPredicate = std::function<bool(const QString& windowId, const QString& screenId)>
 Predicate deciding whether an opening window should start FLOATING because a "Float this app" rule matched it.
using UnfloatFallbackPredicate = std::function<bool(const QString& windowId, const QString& screenId)>
 Predicate deciding whether an unfloat with NO remembered pre-float zone falls back to a zone anyway (the SetUnfloatFallbackToZone rule layered over the global unfloatFallbackToZone setting — the predicate itself implements rule ?
using PlacementZonesResolver = std::function<PlacementDirective(const QString& windowId, const QString& screenId)>
 Resolver yielding the open-placement directive — SnapToZone ordinals and/or zone names, plus an optional RouteToScreen target and an optional RouteToDesktop target — for an opening window because a placement rule matched it.
using ExclusionQueryProvider
 Provider that builds the full WindowQuery for a live windowId.
using ExclusionAdmission
 Builds the rule admission for an exclusion query: a rule naming a field the query left unstamped is skipped, since a negated leaf on it would match every window.
Public Types inherited from PhosphorEngine::IPlacementEngine
enum class  LayoutSupport { None , Placement , Templates }
 How this engine relates to user-selectable layouts — the entries the layout picker, drag layout popup, quick-layout slots and layout cycle operate on. More...

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)
 Places the window a user verb is about (relayed as PlacementPurpose::UserVerb).
void resnapToNewLayoutRequested (const QString &resnapData)
 Batched resnap data, committed by SnapAdaptor's applyEngineResnap relay.
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)
 Window geometries the effect applies in one go; the engine itself emits only action="rotate".
void restatementGeometryRequested (const QString &windowId, int x, int y, int width, int height, const QString &zoneId, const QString &screenId)
 Re-states a placement the window already has (relayed as PlacementPurpose::Restatement).
void fullscreenHandBackRequested (const QString &windowId)
 a user verb with no apply: end its fullscreen
Signals inherited from PhosphorEngine::PlacementEngineBase
void geometryRestoreRequested (const QString &windowId, const QRect &geometry, const QString &screenId)
void sizeRestoreRequested (const QString &windowId, const QSize &size, const QString &screenId)
 Resize windowId to size where it stands, leaving the position to the compositor.
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 crossModeFocusRequested (const QString &targetScreenId, const QString &direction, bool *handled)
 Emitted when a directional FOCUS reaches a monitor boundary whose neighbour context runs a DIFFERENT tiling mode — the source engine cannot name that surface's entry-edge window (it holds no state for the other mode), so it defers to the daemon, which asks the target engine for the window facing the source in direction and activates it.
void windowFloatingStateSynced (const QString &windowId, bool floating, const QString &screenId)
 Emitted to sync floating state without restoring geometry: engine-internal divergence correction, an engine-initiated float (rules, oversize, the compositor's own-fullscreen hold), and a release-time clear, which carries an EMPTY screenId.
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).
QString currentActivity () const
bool isSnapModeScreen (const QString &screenId) const
 Whether screenId resolves to SNAPPING mode in its current (desktop, activity) context — the same verdict resolveWindowRestore's screen-mode ownership gate reads, permissive when no layout manager is wired (tests).
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 crossing onto neighbourScreen in direction: the edge zone facing back toward the source (crossing "right" enters the left-edge zone), on desktop's layout (<= 0: the one shown).
QString entryZoneForCrossing (const QString &direction, const QString &neighbourScreen, int desktop) const
QString windowInZoneOnScreen (const QString &zoneId, const QString &screenId) const
 The window snapped to zoneId on screenId in the context the screen shows, 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 disabled-context placement gate.
void setRestorePositionPredicate (RestorePositionPredicate predicate)
 Inject the unsnapped-position-restore gate (see RestorePositionPredicate).
void setManagedRestorePredicate (ManagedRestorePredicate predicate)
 Inject the managed (snapped-to-zone) restore gate (see ManagedRestorePredicate).
void setLiveModeResolver (LiveModeResolver resolver)
void setContextModeResolver (ContextModeResolver resolver)
void setTilingEngineLiveResolver (TilingEngineLiveResolver resolver)
void setFloatPredicate (FloatPredicate predicate)
void setUnfloatFallbackPredicate (UnfloatFallbackPredicate predicate)
void setPlacementZonesResolver (PlacementZonesResolver resolver)
void windowClosed (const QString &windowId) override
 A no-op: snap's close is WindowTrackingService-driven (WTS::windowClosed clears the window's SnapState), so the daemon's engine close loop skips it.
std::optional< PhosphorEngine::PlacementStateKey > heldKeyForWindow (const QString &windowId) const override
 The key of the store that genuinely holds windowId, in ANY context: membership-grade, NOT scoped to the screen's current desktop.
void releaseWindowOffScreen (const QString &windowId, const QString &keepScreenId) override
 Silently release every membership off keepScreenId (every one when it is empty): zone with the last-used naming it, float bit, residence, pre-float home and persisted per-desktop entry.
PhosphorEngine::MembershipReconcileResult releaseWindowOutsideSpan (const QString &windowId, const QString &screenId, const PhosphorEngine::DesktopSpan &span)
 Silently release every membership windowId holds outside where it actually is: one off screenId (in any spelling of it), and, when span is known, one in a context span does not cover.
QStringList parkOutput (const QString &physicalScreenId) override
 Copy every context of physicalScreenId (each of its virtual screens) into the park, before the prune drops them.
bool readoptParked (const QString &windowId, const QString &parkedPhysicalId, const QString &returnedPhysicalId) override
 Re-seat windowId's contexts parked under parkedPhysicalId on returnedPhysicalId as a re-statement (no focus, no last-used), each in its own (screen, desktop, activity): its virtual screen on the returned output (or the bare output), never the context in view.
void dropParked (const QString &windowId, const QString &physicalScreenId, int desktop, const QString &activity) override
 Forget windowId's parked contexts; an empty physicalScreenId, a desktop of 0 or an empty activity matches every one.
bool hasParked (const QString &windowId, const QString &physicalScreenId) const override
 Whether windowId has a context parked under physicalScreenId (any output when it is empty).
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, const QString &screenId=QString()) override
 Set floating state explicitly (directional, not toggle).
void saveState () override
void loadState () override
LayoutSupport layoutSupport () const override
 Snap placement is driven by user-selectable zone layouts.
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
 Per context: keeps a membership on another desktop still in snapping mode (the window stays snapped there); forgets the window otherwise.
QString screenForTrackedWindow (const QString &windowId) const override
 Return the screen this engine considers the window to be on (any context), or empty if the window isn't tracked by this engine.
bool isWindowTracked (const QString &windowId) const override
 Whether some store of this engine holds the window, in any context: snapped, snap-floated, a residence, a screenless float in the global holder, or another desktop's store (heldKeyForWindow).
void resnapToNewLayout ()
 Resnap a switch's populated buffer into the new layouts: a window back in the layout it was snapped in gets the zones of it that layout still holds (a span stays a span), any other window the zone at its primary zone's position, or its pre-tile geometry when the new layout has no zone there.
void resnapToNewLayout (ResnapFeedback feedback)
void resnapCurrentAssignments (const QString &screenFilter=QString(), const QSet< QString > &onlyWindows={})
 Re-apply the zones windows hold, on screenFilter (all when empty), only onlyWindows when it is not empty.
void resnapCurrentAssignments (const QString &screenFilter, const QSet< QString > &onlyWindows, ResnapFeedback feedback)
void resnapFromAutotileOrder (const QStringList &autotileWindowOrder, const QString &screenId)
 No in-tree caller (the SnapAdaptor slot of this name calls calculateResnapEntriesFromAutotileOrder and commits the batch itself); kept as installed API.
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, PhosphorEngine::RestoreReason reason=PhosphorEngine::RestoreReason::Open)
 Resolve auto-snap for a newly opened window.
void setAutotileEngine (PhosphorEngine::IPlacementEngine *engine)
 Set the autotile engine for screen ownership checks.
void setWindowRegistry (QObject *registry) override
 Attach the daemon's shared window registry.
SnapState * stateForWindow (const QString &windowId)
 The SnapState that owns windowId (via the reverse map), or the global holder when the window is untracked — NEVER null (the holder is constructed in the ctor; see the fallback rationale on the definition).
const SnapState * stateForWindow (const QString &windowId) const
SnapState * globalState () const
 The global-scalar holder (last-used-zone + user-snapped classes).
SnapState * snapState () const
 The global-scalar holder (alias of globalState), for callers that only need the last-used-zone / user-snapped scalars; per-window data lives in the per-screen stores, reached via stateForWindow.
QList< SnapState * > allSnapStates () const
 Every SnapState the engine owns, including the global holder, for whole-store enumerations (occupied zones, snapped/floating windows, flat-map views).
SnapState * stateForWindowOnScreen (const QString &windowId, const QString &screenId, int desktop=0)
 Resolve-or-register the state windowId's data belongs in for a write on screenId, and return it.
void forgetWindow (const QString &windowId)
 Drop every membership windowId holds AND its data in each member store (closed / removed): a window on several desktops holds a zone in each, and clearing only the one in view left a dead zone occupant.
bool holdsWindowInState (const QString &windowId, const SnapState *state) const
 Whether state holds a MEMBERSHIP for windowId, not a leftover from before a re-key (the WTS facade's aggregate walks, via the resolver seam).
std::optional< PhosphorEngine::PlacementStateKey > keyForState (const SnapState *state) const
 The key state is filed under; nullopt for the global holder or a foreign store.
QString navigationScreenFor (const QString &windowId, const QString &preferredScreen) const
 The screen a navigation verb on windowId acts on: its stored screen when snapped, else preferredScreen, else the cursor's, else the last active one.
bool migrateWindowToScreen (const QString &windowId, const QString &newScreenId)
 Re-home a tracked window onto the store for newScreenId's current context.
void rekeyMembershipsToRecordedScreens (const QString &physicalScreenId)
 After a split or un-split of physicalScreenId rewrote the stores' screen values, re-file each membership on the monitor under the key for the screen its store records (else its pre-float screen), desktop, activity and zone kept.
void renameScreen (const QString &oldPhysicalId, const QString &newPhysicalId)
 Re-file every membership keyed on monitor oldPhysicalId (its virtual screens too) under the same key on newPhysicalId, desktop, activity and zone kept: an EDID twin's identifier flip (F189), after the WTS facade rewrote the screen values.
void setCurrentDesktop (int desktop) override
void setCurrentDesktopForScreen (const QString &screenId, int desktop) override
 Set a single screen's current virtual desktop (Plasma 6.7 "switch desktops independently for each screen").
PhosphorEngine::MembershipReconcileResult reconcileDesktopMemberships (const QString &screenId, const PhosphorEngine::DesktopSpanQuery &spanOf) override
 A window on several desktops holds its own zone on each.
PhosphorEngine::MembershipReconcileResult reconcileWindowMemberships (const QString &windowId, const PhosphorEngine::DesktopSpanQuery &spanOf) override
 The same pass for ONE window, on the screen it is held on.
void installContextResolver ()
 Point the container's primary resolution at currentKeyForScreen.
void setFloatingWithResidence (const QString &windowId, const QString &screenId)
 Float windowId in its primary store.
void seedPersistedDesktopZones (const QString &windowId, const PhosphorEngine::EngineSlot &slot, const QString &screenId, int restoreDesktop, const QString &activity)
 Re-seed a restored record's other desktops' zones into their stores under activity, which every caller passes as the live one (currentActivity()), never the record's: the restore's commit lands there.
void setCurrentActivity (const QString &activity) override
QSet< int > desktopsWithActiveState () const override
void pruneStatesForDesktop (int removedDesktop) override
void renumberDesktopsAfterRemoval (int removedDesktop) override
 Shift every per-(screen, desktop, activity) state ABOVE removedDesktop down by one, because Plasma renumbers x11 desktop numbers when a desktop in the middle is deleted (removing 2 of 4 makes 3 become 2 and 4 become 3).
void remapDesktops (const PhosphorEngine::DesktopRemap &remap) override
 OPTIONAL: KWin's desktop list changed (a removal, an insert or a reorder).
void pruneStatesForActivities (const QStringList &validActivities) override
void pruneStatesForRemovedScreen (const QString &physicalScreenId) override
 Prune per-(screen, desktop, activity) state for a PHYSICALLY REMOVED output (monitor hot-unplug), matching every virtual sub-screen of the removed physical id.
bool isFloating (const QString &windowId) const
void setFloating (const QString &windowId, bool floating)
QStringList floatingWindows () const
void applyNoMatchFloatDefault (const QString &windowId, const QString &screenId, PhosphorEngine::RestoreReason reason, bool placedBefore)
 The no-match float-default terminal of resolveWindowRestore for a caller outside it.
bool wasPlacedByPreviousLineage (const QString &windowId) const
 That snapshot, taken before anything can re-bind a slot-bearing record under this uuid.
QString zoneForWindow (const QString &windowId) const
 The zone of windowId's PRIMARY membership (the store in view when it is a member there, else its first): empty there even when another desktop holds one.
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.
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; at the layout edge, into a neighbour output's entry zone, a tiling neighbour's engine, or the next desktop.
void moveFocusedInDirection (const QString &direction, const PhosphorEngine::NavigationContext &ctx) override
 Move the focused window into the adjacent zone in direction (it stacks with an occupant; swap exchanges), or snap an unsnapped one into the edge zone that way.
void spanFocusedInDirection (const QString &direction, const PhosphorEngine::NavigationContext &ctx) override
 Grow the focused window's zone span into the adjacent zone(s) in direction, or retract the opposite edge when nothing lies that way (pressing back toward the span undoes the last grow).
void swapFocusedInDirection (const QString &direction, const PhosphorEngine::NavigationContext &ctx) override
 Swap the focused window with the window in the adjacent zone in direction, exchanging whole zone sets; into an empty zone it moves (moved_to_empty).
void moveFocusedToPosition (int zoneNumber, const PhosphorEngine::NavigationContext &ctx) override
 Move the focused window to the layout zone with zoneNumber (1-based) on the screen the verb acts on (navigationScreenFor).
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 zones the windows on ctx.screenId hold in the context in view.
void reapplyManagedWindowAppearance () override
 Re-emit the zone geometry of every non-floating window snapped in view (the shown desktop's store on a screen snap runs) 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.
std::optional< PhosphorEngine::WindowPlacement > capturePlacementAtDesktop (const QString &windowId, int gateDesktop) const
 capturePlacement with the mode gate resolved at an EXPLICIT desktop.
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 the screen it acts on.
void restoreFocusedWindow (const PhosphorEngine::NavigationContext &ctx) override
 Restore the focused window in a zone to its float-back on its screen and float it; one in no zone is refused.
void toggleFocusedFloat (const PhosphorEngine::NavigationContext &ctx) override
 Toggle the focused window between snapped and floating.
void switchFocusBetweenFloatingAndTiling (const QString &screenId) override
 Jump focus between the float layer and the snapped layout (niri's switch-focus-between-floating-and-tiling).
void cycleFocus (bool forward, const PhosphorEngine::NavigationContext &ctx) override
 Cycle keyboard focus forward/backward through the windows stacked in the focused window's zone on its output; a lone window reports single_window.
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 screenId's current desktop, and a screenId other than the window's tracked one re-homes it (stateForWindowOnScreen).
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)
void recordFreeFrameBeforeUserSnap (const QString &windowId, const QString &screenId)
 Record a window's live frame as its float-back, ahead of a user snap the DAEMON drives (keys, snap-all, every user unfloat, the D-Bus snap), the free frame's last chance before the commit makes the effect's capture refused.
void commitUserSnap (const QString &windowId, const QStringList &zoneIds, const QString &screenId, const QRect &geometry, const QString &captureScreen, int virtualDesktop=0)
 The tail of every user snap the daemon drives: record the free frame the window leaves (on captureScreen; nothing when empty), commit zoneIds on screenId pinned to virtualDesktop (0: the window's own), record the snap intent and apply geometry as the user's verb.
PhosphorEngine::UnfloatResult resolveUnfloatGeometry (const QString &windowId, const QString &fallbackScreen) const
 The ABI-stable signature exported before the confinement parameter.
PhosphorEngine::UnfloatResult resolveUnfloatGeometry (const QString &windowId, const QString &fallbackScreen, bool confineToFallbackScreen) const
 Not-found when the RECORDED (raw) home screen names a different physical monitor than fallbackScreen, for every cause: a window moved to another monitor forgets the zone it floated from, so a home there can only be stale.
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 &screenId, bool isSticky) const
 The SnapToZone placement of a matched rule on screenId; the four-argument form takes a resolved directive.
PhosphorEngine::SnapResult calculateSnapToPlacementRule (const QString &windowId, const QString &screenId, bool isSticky, const PlacementDirective &directive) 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 QSet< QString > &onlyWindows={}) 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
int pruneStaleWindows (const QSet< QString > &aliveWindowIds) override
 Drops the state-index membership of every window not in the (canonical) alive set.
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 the screen it acts on.
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 (each activation and each focused-screen report).
void setExcludeRuleSet (const PhosphorRules::RuleSet *ruleSet)
 Wire the daemon's filtered placement-exclusion rule set (rules carrying an Exclude or ExcludePlacement action).
void setExclusionQueryProvider (ExclusionQueryProvider provider)
 Inject the exclusion query provider.
void setExclusionAdmission (ExclusionAdmission admission)
bool isAppIdExcluded (const QString &appId) const
 True if appId matches an enabled rule of the borrowed exclusion set (Exclude or ExcludePlacement) on an appId-ONLY query.
bool isWindowExcluded (const QString &windowId, const QString &screenHint=QString()) 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.
bool isWindowExcludedByRule (const QString &windowId, const QString &screenHint=QString()) const
 isWindowExcluded without the minimum-window-size floor: the Exclude rule set alone, against the same full query.
Public Member Functions inherited from PhosphorEngine::PlacementEngineBase
virtual QRect lastManagedRect (const QString &windowId) const
 The exact rect this engine last APPLIED to windowId while managing it (its tile rect), remembered PAST the window's transition out of the managed state.
void setEngineSettings (QObject *settings)
QObject * engineSettings () const
 ~PlacementEngineBase () override
void setOpenFocusEligible (bool eligible) override
 OPTIONAL: whether the opens dispatched next may take focus ("Focus new windows"): true for a genuine open, false for a re-placement.
Public Member Functions inherited from PhosphorEngine::IPlacementEngine
virtual ~IPlacementEngine ()=default
 IPlacementEngine (const IPlacementEngine &)=delete
IPlacementEngine & operator= (const IPlacementEngine &)=delete
void windowOpened (const QString &windowId, const QString &screenId)
 Convenience overload — equivalent to windowOpened(id, screen, 0, 0).
virtual bool claimCrossScreenReopen (const QString &windowId, const QString &openingScreenId, int minWidth=0, int minHeight=0)
 OPTIONAL: the reopen claim, under the reopen contract (restores happen where a window opens).
virtual void noteCrossScreenClaimsExhausted (const QString &windowId, bool exhausted)
 INERT, kept for ABI: fed the removed cross-screen defer gates.
virtual QString heldScreenForWindow (const QString &windowId) const
 OPTIONAL: the screen this engine genuinely HOLDS the window on IN THE SCREEN'S CURRENT CONTEXT — a MEMBERSHIP answer (tiled or engine-floating both count; a phantom reverse-map key does not), empty when the engine does not hold it or holds it only in a background context.
virtual void beginArrivalBurst ()
 Bracket a BURST of windowOpened calls delivered together (the adaptor's three dispatch loops: windowsOpenedBatch, the deferred-open flush, and the parked-open replay — daemon bring-up re-announce and mode flips; a reopen claim's re-entry inherits the loop's bracket, while the snap facade's is deliberately UNBRACKETED since each resolveWindowRestore is its own D-Bus message).
virtual void endArrivalBurst ()
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 QString managedFocusedWindow (const QString &screenId) const
 The window this engine considers focused on screenId, or empty.
virtual int stickyPinnedDesktopForScreen (const QString &screenId) const
 The desktop this engine has PINNED screenId to, or 0 when it has not pinned it (which is the normal case, and the default here).
virtual void setInitialFocusedWindow (const QString &screenId, const QString &windowId)
 Hand the incoming engine the focus captured from the outgoing one.
virtual void applyPerScreenConfig (const QString &screenId, const QVariantMap &overrides)
virtual void clearPerScreenConfig (const QString &screenId)
virtual QVariantMap perScreenOverrides (const QString &screenId) const
virtual void markModeSpecificFloated (const QString &windowId)
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 (bool dragStillActive=false)
 dragStillActive: the previewed window is still under an interactive move when the cancel runs (mid-drag trigger release, or a screen / desktop change during the drag).
virtual QString dragInsertPreviewScreenId () const
virtual QString dragInsertPreviewPriorScreenId () const
 The screen the previewed window was on BEFORE begin adopted it, or empty when it had no prior state (begin took it from untracked) or no preview is live.
virtual DragInsertTarget computeDragInsertTargetAtPoint (const QString &screenId, const QPoint &cursorPos) const
 Compute the drop target for a cursor position on a managed screen.
virtual void updateDragInsertPreview (const DragInsertTarget &target)
 Update the drop target for an active drag-insert preview.
virtual bool dragAutoScrollTick (const QString &screenId, const QPoint &cursorPos, qreal dtSeconds)
 Advance edge auto-scroll for a live drag-insert preview (niri's dnd-edge-view-scroll): an engine whose layout is a scrollable viewport moves its VIEW while the cursor sits inside a band at the work area's edge, so a drop can reach a column that is off screen.
virtual bool dragAutoScrollActive () const
 Whether edge auto-scroll currently owns the drop target.
virtual void cancelDragAutoScroll ()
 Give the drop target back and forget any armed band, WITHOUT moving the view or re-aiming.
virtual QRect dragInsertIndicatorRect (const QString &screenId) const
 The rect the dragged window would occupy if the live preview were dropped now, in absolute px on screenId, for a caller that PAINTS the drop target.
virtual void setInteractiveDragWindow (const QString &windowId)
 The window currently under a compositor interactive move (the whole drag, preview or not).
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 QSize windowMinimumSize (const QString &windowId) const
 The window's client-reported minimum size as last known by this engine, or an UNKNOWN answer when it has none.
virtual void windowMinSizeUpdated (const QString &windowId, int minWidth, int minHeight)
 Update a window's minimum size after the initial windowOpened.
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 bool providesDragInsertSelector () const
 Whether the daemon's edge-triggered drag popup (the zone selector surface) should render this engine's DRAG-INSERT vocabulary — strip column cards whose gap / join / half targets translate into DragInsertTarget — instead of zone layouts, on screens this engine owns.
virtual QString algorithmId () const
virtual void setAlgorithm (const QString &algorithmId)
virtual QString activeScreen () const
virtual void setActiveScreenHint (const QString &screenId)
virtual void clearCurrentDesktopForScreen (const QString &screenId)
 Drop a screen's per-output desktop, reverting it to the global current.
virtual void updateStickyScreenPins (const StickyPredicate &isSticky, StickyPinPhase phase)
 Run one phase of the sticky-screen pin pass; see StickyPinPhase for why the two phases bracket a context change rather than sharing a call site.
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 std::optional< int > savedMaxWindowsForAlgorithm (const QString &algorithmId) const
 The user's saved per-algorithm max-windows tuning for algorithmId, or std::nullopt when the engine keeps no such slot.
virtual void retile (const QString &screenId=QString())
virtual void scheduleRetileForScreen (const QString &screenId)
virtual void increaseMasterRatio (qreal delta=kDefaultSplitRatioStep)
virtual void decreaseMasterRatio (qreal delta=kDefaultSplitRatioStep)
virtual void increaseMasterCount ()
virtual void decreaseMasterCount ()
virtual void focusMaster ()
virtual void swapFocusedWithMaster ()
virtual void setDragInsertClientSize (const QSize &size)
 OPTIONAL: the size the client chose for the window under the live drag-insert preview, handed over right after a successful beginDragInsertPreview so the drop indicator and the commit both see it.

Additional Inherited Members

Static Public Attributes inherited from PhosphorEngine::IPlacementEngine
static constexpr qreal kDefaultSplitRatioStep = 0.05
 One home for the master/split ratio step so the default return below and the two default arguments cannot drift apart.
Protected Member Functions inherited from PhosphorEngine::PlacementEngineBase
 PlacementEngineBase (QObject *parent=nullptr)
bool openFocusEligible () const
 Whether the open being handled may take focus (see IPlacementEngine::setOpenFocusEligible).
void announceLayerSwitch (const LayerSwitchResult &result, const QString &action, const QString &screenId)
 Emit the activation + navigationFeedback pair for a resolved layer focus switch (resolveLayerFocusSwitch).
void restoreFreeSizeWhereItStands (IWindowTrackingService *tracker, const QString &windowId, const QString &screenId, RestoreReason reason, bool placedBefore, const QList< QSize > &managedSizes)
 The size-only half of a float verdict, shared by every engine (#1106).
Protected Member Functions inherited from PhosphorEngine::IPlacementEngine
 IPlacementEngine ()=default
Static Protected Member Functions inherited from PhosphorEngine::PlacementEngineBase
static bool isManagedSize (const QList< QSize > &managedSizes, const QSize &size)
 Whether size is within two pixels of any entry of managedSizes on both axes.
static bool placedByPreviousLineage (const WindowPlacementStore &store, const QString &windowId)
 The placedBefore snapshot for restoreFreeSizeWhereItStands: store holds a record WITH AN ENGINE SLOT under this exact uuid, so a previous daemon lineage placed the window (a daemon-only restart or mode-swap re-announce).

Detailed Description

Engine for manual zone-based window snapping.

Implements IPlacementEngine for screens running snapping (autotile and scrolling screens have their own engines): auto-snap on window open, zone navigation, floating state, rotation and resnap.

The engine owns the per-(screen, desktop, activity) SnapState stores. WindowTrackingService is the facade the daemon writes through, and it keeps the placement records and the float-back geometry.

See also
PhosphorEngine::IPlacementEngine, AutotileEngine, WindowTrackingService

Member Typedef Documentation

◆ ContextModeResolver

Initial value:
std::function<PhosphorZones::AssignmentEntry::Mode(const QString&, int, const QString&)>
Mode
Per-context engine selection.
Definition AssignmentEntry.h:213

The mode the daemon resolves for a (screenId, desktop, activity) context, in view or hidden: readoptParked takes a parked zone back only into one answered Snapping (F1137).

Unset, the raw assignment answers. A floating handoffReceive floats only in one answered Snapping too, and anywhere while it is unset.

◆ ExclusionAdmission

Initial value:
std::function<std::function<bool(const PhosphorRules::Rule&)>(const PhosphorRules::WindowQuery&)>
The evaluation input — an attribute bag matched against a MatchExpression.
Definition WindowQuery.h:37

Builds the rule admission for an exclusion query: a rule naming a field the query left unstamped is skipped, since a negated leaf on it would match every window.

Unset admits every rule.

◆ ExclusionQueryProvider

Initial value:
std::function<std::optional<PhosphorRules::WindowQuery>(const QString& windowId, const QString& screenHint)>

Provider that builds the full WindowQuery for a live windowId.

Its only producer is the daemon's buildContextualRuleQuery, which stamps the window's attributes, ScreenId / ActiveLayout / Mode and the screen shape (orientation, width, height, aspect ratio) for screenHint (or the screen the daemon tracks the window on) and the live frame, which the minimum-window-size thresholds are checked against. Every caller passes the screen it asks about: the open path the one the window lands on, the navigation verbs the one they act on, the drag selector the source screen or none. Unset, or an empty optional (no metadata yet), falls back to the appId-only query unit tests rely on.

◆ FloatPredicate

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

Predicate deciding whether an opening window should start FLOATING because a "Float this app" 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. Takes the OPENING SCREEN as well, so the resolver can stamp ScreenId and derive Mode — without which a rule pairing either with Float is silently inert.

◆ LiveModeResolver

The daemon's live mode resolver (its ScreenModeRouter, an unclaimed tiling mode downgraded to Snapping).

isActiveOnScreen, isSnapModeScreen, the capture gate and isTilingOutput consult it, so a screen ENTERING a tiling mode can still presave its snap state, which the raw cascade would refuse. Unset, isActiveOnScreen falls back to "not autotile" and the others to the registry's cascade. Clear with {} at teardown.

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

The snapped-to-zone analogue of RestorePositionPredicate. Keyed by the live windowId so the daemon closure stays settings-agnostic (LGPL boundary). The daemon wires it to restoreWindowsToZonesOnLogin and the per-window SetRestoreToZoneOnLogin rule. It governs an Open and a FIFO match only: a re-entry of the window's own record skips it.

When it returns false the stored snap is not re-applied and the window falls through to the auto-snap chain, as a disabled-context rejection does. It governs every zone the record remembers, not only the restore desktop's: a FLOATED record's zones on its other desktops are seeded into their stores only when it opts in, and a decline, on either leg, forgets every per-desktop zone the record keeps. The forget is durable, so the adoption on a first visit to another of the window's desktops does not put the declined zone back either. Asked only where the record remembers a zone. When UNSET (default) snapped records restore unconditionally, the behaviour unit tests rely on. Independent of ShouldRestorePredicate (the disabled-context gate); both must opt in.

◆ PlacementZonesResolver

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

Resolver yielding the open-placement directive — SnapToZone ordinals and/or zone names, plus an optional RouteToScreen target and an optional RouteToDesktop target — for an opening window because a placement 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). The open path (resolveWindowRestore) resolves it ONCE per pass and feeds the same directive to calculateSnapToPlacementRule and to the desktop its float terminals pin to; the Meta+F unfloat's rule tier and the Snap.snapToAppRule bus slot resolve it on their own. See PlacementDirective. Both lists empty ⇒ no SnapToZone rule matched; multiple targets across the two lists request a zone span (their unioned bounding rect). The engine stays settings/rule-store-agnostic (LGPL boundary) — it only asks.

Not a pure query. The daemon's resolver hands the open's routing verdict (the desktop and monitor its routing pass sent the window to, a realized RouteToWorkspace included) to the FIRST resolve of the pass and to nothing after it, so a second resolve in the same pass sees only the rules' own RouteToScreen and RouteToDesktop. Resolve once and pass the directive along. 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.)

Keyed by the live windowId so the daemon closure can evaluate the per-window RestorePosition rule from its WindowRegistry, falling back to the snappingRestoreFloatedWindowsOnLogin setting. Returns true to restore the position, the ONE thing it governs for a FLOATED record: such a record always re-marks the window floating, but its position is re-applied only when the predicate opts in, the rect is not a managed size (a zone-sized "free" rect is a spawn frame) and this is no re-entry (the window's own record, any reason but Open). A declined move still gets a first placement its free SIZE. When UNSET (default), a floated record is consumed only on the screen it reopens on and is marked floating without a move, the path unit tests rely on.

◆ ShouldRestorePredicate

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

Predicate deciding whether snapping may place a window on (screenId, desktop), so nothing is placed in a context the user disabled snapping for.

True if the context is active for snap mode. The daemon injects it (the engine library is settings-agnostic); its closure reads the current activity itself. Asked for the desktop a restore puts the window ONTO (not always the one the screen shows), the context a SnapToZone rule targets, or the opening screen's current desktop for the auto-snap levels. Applied by, among others, resolveWindowRestore, the desktop carry, the adoption's remembered-zone restore, the membership re-apply, the layout-switch resnap, the rotation and the landing of a keyboard move or swap (#461 item 7, F445, F208). Unset, every context is active.

◆ TilingEngineLiveResolver

Initial value:
std::function<bool(PhosphorZones::AssignmentEntry::Mode mode, const QString& screenId)>

INERT, kept for ABI: nothing reads it since snap no longer defers an open to another engine's reclaim (the reopen contract), and the daemon does not wire it.

Clear with {} at teardown.

◆ UnfloatFallbackPredicate

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

Predicate deciding whether an unfloat with NO remembered pre-float zone falls back to a zone anyway (the SetUnfloatFallbackToZone rule layered over the global unfloatFallbackToZone setting — the predicate itself implements rule ?

? config). Daemon-injected, keyed by the live windowId plus the RESOLVED restore screen (so the resolver can stamp ScreenId and derive Mode), consulted inside resolveFallbackUnfloatGeometry — which covers both the live user-toggle unfloat and SnapAdaptor::calculateUnfloatRestore. When UNSET (default) the engine reads the ISnapSettings bool directly, preserving the historical behaviour the unit tests rely on. Same lifetime contract as setFloatPredicate — clear with {} before destroying any state the closure captured.

Member Enumeration Documentation

◆ ResnapFeedback

Whether a resnap that finds nothing says so (no_windows_to_resnap): a user verb does, a layout switch or a settings reflow does not.

Enumerator
Report 
Silent 

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

◆ allSnapStates()

QList< SnapState * > PhosphorSnapEngine::SnapEngine::allSnapStates ( ) const

Every SnapState the engine owns, including the global holder, for whole-store enumerations (occupied zones, snapped/floating windows, flat-map views).

◆ 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

Window geometries the effect applies in one go; the engine itself emits only action="rotate".

Named for the action it requests, like the D-Bus signal it feeds: the interface names a request by its verb and an effect-to-daemon notice by the event it reports (orchestrator_phaseb_1, F820).

◆ 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

Places the window a user verb is about (relayed as PlacementPurpose::UserVerb).

◆ applyNoMatchFloatDefault()

void PhosphorSnapEngine::SnapEngine::applyNoMatchFloatDefault ( const QString & windowId,
const QString & screenId,
PhosphorEngine::RestoreReason reason,
bool placedBefore )

The no-match float-default terminal of resolveWindowRestore for a caller outside it.

No in-tree caller since the tile-defer channel was removed (installed API, kept). No-op with a definite snap state, snapping off, or empty args. Pins the residence and restores the free size like the in-line terminals; the caller must establish that the screen snaps. placedBefore is the caller's lineage snapshot (wasPlacedByPreviousLineage). placedBefore has no default: false lets the resize through.

◆ 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 entries without committing them, falling back to the current-assignment entries when the order yields nothing. Its caller is the SnapAdaptor's single-screen D-Bus slot; the daemon's multi-screen autotile → snap batch calls calculateResnapFromAutotileOrder with its pre-claims.

Parameters
autotileWindowOrderOrdered list of window IDs from autotile engine
screenIdScreen to resnap on
preClaimedZoneIdsZones another producer is already restoring into: they seed the claim ledger so the positional fallback never reuses one (two windows, one zone).
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 QSet< QString > & onlyWindows = {} ) 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
windowIdsList of window IDs to snap
screenIdScreen to snap on
Returns
the snap-all entries the KWin effect applies

◆ 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() [1/2]

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

The SnapToZone placement of a matched rule on screenId; the four-argument form takes a resolved directive.

◆ calculateSnapToPlacementRule() [2/2]

PhosphorEngine::SnapResult PhosphorSnapEngine::SnapEngine::calculateSnapToPlacementRule ( const QString & windowId,
const QString & screenId,
bool isSticky,
const PlacementDirective & directive ) 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.

◆ capturePlacementAtDesktop()

std::optional< PhosphorEngine::WindowPlacement > PhosphorSnapEngine::SnapEngine::capturePlacementAtDesktop ( const QString & windowId,
int gateDesktop ) const

capturePlacement with the mode gate resolved at an EXPLICIT desktop.

The public capture gates on the window's screen at its CURRENT desktop, which is the right question for the periodic refresh but the wrong one for a cross-desktop handoff: the daemon routed the handoff here because (screen, toDesktop) resolves to Snapping, yet the screen's visible desktop may be a tiling one, so the current-desktop gate refused the capture and the durable record silently kept the OLD desktop. gateDesktop <= 0 means "the screen's current desktop" (the public capture's behaviour, including its live-resolver fast path).

◆ 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 screenId's current desktop, and a screenId other than the window's tracked one re-homes it (stateForWindowOnScreen).

Non-zero is used by the RouteToDesktop placement path (track the assignment on the destination desktop) and by batch resnap entries that preserve a window's recorded desktop through the commit (see ZoneAssignmentEntry::virtualDesktop).

◆ commitUserSnap()

void PhosphorSnapEngine::SnapEngine::commitUserSnap ( const QString & windowId,
const QStringList & zoneIds,
const QString & screenId,
const QRect & geometry,
const QString & captureScreen,
int virtualDesktop = 0 )

The tail of every user snap the daemon drives: record the free frame the window leaves (on captureScreen; nothing when empty), commit zoneIds on screenId pinned to virtualDesktop (0: the window's own), record the snap intent and apply geometry as the user's verb.

Refuses an invalid geometry or no zone; the resolvers validate first.

◆ 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. currentActivity() is read throughout the engine's sources; the no-arg currentVirtualDesktop() has no in-tree caller. Note the fallback it mirrors lives in IVirtualDesktopManager, not here: currentVirtualDesktopForScreen goes straight to the VDM's currentDesktopForScreen and never routes through this accessor. Both stay 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).

Goes STRAIGHT to the VDM's currentDesktopForScreen — the per-screen-to-global fallback lives inside IVirtualDesktopManager, not here, so this never routes through currentVirtualDesktop().

◆ cycleFocus()

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

Cycle keyboard focus forward/backward through the windows stacked in the focused window's zone on its output; a lone window reports single_window.

Implements PhosphorEngine::IPlacementEngine.

◆ desktopsWithActiveState()

QSet< int > PhosphorSnapEngine::SnapEngine::desktopsWithActiveState ( ) const
overridevirtual

Reimplemented from PhosphorEngine::IPlacementEngine.

◆ dropParked()

void PhosphorSnapEngine::SnapEngine::dropParked ( const QString & windowId,
const QString & physicalScreenId,
int desktop,
const QString & activity )
overridevirtual

Forget windowId's parked contexts; an empty physicalScreenId, a desktop of 0 or an empty activity matches every one.

Reimplemented from PhosphorEngine::IPlacementEngine.

◆ 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
entriesCombined PhosphorEngine::ZoneAssignmentEntry vector from all screens

◆ engineId()

QString PhosphorSnapEngine::SnapEngine::engineId ( ) const
inlineoverridevirtual

Stable engine identity for HandoffContext.fromEngineId.

Conventional values: "snap" / "autotile" / "scrolling". Empty string means "unidentified" and disables receive-side reasoning that depends on the source mode.

Reimplemented from PhosphorEngine::IPlacementEngine.

◆ entryZoneForCrossing() [1/2]

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

The zone a window ENTERS crossing onto neighbourScreen in direction: the edge zone facing back toward the source (crossing "right" enters the left-edge zone), on desktop's layout (<= 0: the one shown).

Empty with no adjacency resolver or no such zone. The cross-mode handoff lands a window there, and the cross-mode focus and swap read their target there.

◆ entryZoneForCrossing() [2/2]

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

◆ floatingWindows()

QStringList PhosphorSnapEngine::SnapEngine::floatingWindows ( ) const

◆ focusInDirection()

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

Walk to the adjacent window in direction and transfer keyboard focus; at the layout edge, into a neighbour output's entry zone, a tiling neighbour's engine, or the next desktop.

An empty direction refuses (invalid_direction).

Implements PhosphorEngine::IPlacementEngine.

◆ forgetWindow()

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

Drop every membership windowId holds AND its data in each member store (closed / removed): a window on several desktops holds a zone in each, and clearing only the one in view left a dead zone occupant.

◆ fullscreenHandBackRequested

void PhosphorSnapEngine::SnapEngine::fullscreenHandBackRequested ( const QString & windowId)
signal

a user verb with no apply: end its fullscreen

◆ globalState()

SnapState * PhosphorSnapEngine::SnapEngine::globalState ( ) const
inline

The global-scalar holder (last-used-zone + user-snapped classes).

Also the fallback home for screenless float bookkeeping. Never null after construction.

◆ 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 (the window keeps its live frame, so no geometry is carried in the context).
  • 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

Per context: keeps a membership on another desktop still in snapping mode (the window stays snapped there); forgets the window otherwise.

Reimplemented from PhosphorEngine::IPlacementEngine.

◆ hasParked()

bool PhosphorSnapEngine::SnapEngine::hasParked ( const QString & windowId,
const QString & physicalScreenId ) const
overridevirtual

Whether windowId has a context parked under physicalScreenId (any output when it is empty).

Reimplemented from PhosphorEngine::IPlacementEngine.

◆ heldKeyForWindow()

std::optional< PhosphorEngine::PlacementStateKey > PhosphorSnapEngine::SnapEngine::heldKeyForWindow ( const QString & windowId) const
overridevirtual

The key of the store that genuinely holds windowId, in ANY context: membership-grade, NOT scoped to the screen's current desktop.

Read by isWindowTracked's multi-desktop arm, toggleWindowFloat's managed test, the Snap adaptor's swapWindowsById and the WindowTracking state query; the daemon's desktop reconcile asks only the lifecycle engines. The globals holder is excluded (it has no desktop identity).

Reimplemented from PhosphorEngine::IPlacementEngine.

◆ holdsWindowInState()

bool PhosphorSnapEngine::SnapEngine::holdsWindowInState ( const QString & windowId,
const SnapState * state ) const

Whether state holds a MEMBERSHIP for windowId, not a leftover from before a re-key (the WTS facade's aggregate walks, via the resolver seam).

◆ installContextResolver()

void PhosphorSnapEngine::SnapEngine::installContextResolver ( )

Point the container's primary resolution at currentKeyForScreen.

◆ 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 rule of the borrowed exclusion set (Exclude or ExcludePlacement) on an appId-ONLY query.

A test seam for the rule-set wiring (null borrow, empty set, rebind, revision bump): isWindowExcluded builds the same appId-only query itself when it has no metadata, and only its full query sees a rule on another field. Const, apart from the mutable evaluator cache.

◆ isEnabled()

bool PhosphorSnapEngine::SnapEngine::isEnabled ( ) const
overridevirtualnoexcept

True when snapping is globally enabled.

Read by the daemon's shortcut dispatch after the router picks the engine (the router itself asks only isActiveOnScreen), by resolveWindowRestore's kill switch and by the no-match float default. 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.

◆ isFloating()

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

◆ isSnapModeScreen()

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

Whether screenId resolves to SNAPPING mode in its current (desktop, activity) context — the same verdict resolveWindowRestore's screen-mode ownership gate reads, permissive when no layout manager is wired (tests).

Public for the SnapAdaptor: its open claim names the opening screen's engine from it, and its DesktopArrival held-zone re-apply only runs on a screen that snaps (a re-statement of a zone on a screen another engine runs would fight that engine).

◆ isWindowExcluded()

bool PhosphorSnapEngine::SnapEngine::isWindowExcluded ( const QString & windowId,
const QString & screenHint = QString() ) 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. screenHint is forwarded to the provider (see ExclusionQueryProvider): the screen the navigation verbs act on, the open path's landing screen, or the drag selector's source screen.

◆ isWindowExcludedByRule()

bool PhosphorSnapEngine::SnapEngine::isWindowExcludedByRule ( const QString & windowId,
const QString & screenHint = QString() ) const

isWindowExcluded without the minimum-window-size floor: the Exclude rule set alone, against the same full query.

For a caller that judges the floor on a size of its own, as the drag selector does on the size the window holds as its own rather than the frame a zone or tile gave it.

◆ isWindowTracked()

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

Whether some store of this engine holds the window, in any context: snapped, snap-floated, a residence, a screenless float in the global holder, or another desktop's store (heldKeyForWindow).

Read by, among others, the daemon's handoff verification and its float routing's source and destination picks.

Reimplemented from PhosphorEngine::IPlacementEngine.

◆ keyForState()

std::optional< PhosphorEngine::PlacementStateKey > PhosphorSnapEngine::SnapEngine::keyForState ( const SnapState * state) const

The key state is filed under; nullopt for the global holder or a foreign store.

◆ lastActiveScreenId()

QString PhosphorSnapEngine::SnapEngine::lastActiveScreenId ( ) const
inline

Last screen the engine saw via windowFocused (each activation and each focused-screen report).

Two readers: the resnap OSD feedback's screen, and the float verb's last screen fallback (float.cpp). A const getter so tests can verify the focus-tracking contract without signal stubs.

◆ layoutSupport()

LayoutSupport PhosphorSnapEngine::SnapEngine::layoutSupport ( ) const
inlineoverridevirtual

Snap placement is driven by user-selectable zone layouts.

Reimplemented from PhosphorEngine::IPlacementEngine.

◆ loadState()

void PhosphorSnapEngine::SnapEngine::loadState ( )
overridevirtual

◆ migrateWindowToScreen()

bool PhosphorSnapEngine::SnapEngine::migrateWindowToScreen ( const QString & windowId,
const QString & newScreenId )

Re-home a tracked window onto the store for newScreenId's current context.

On a screen change every membership on the screen left is released as releaseWindowOffScreen does; the float bit, auto-snap flag and residence move, re-stamped to the destination key's desktop. A same-screen move only re-keys. True when it moved.

◆ moveFocusedInDirection()

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

Move the focused window into the adjacent zone in direction (it stacks with an occupant; swap exchanges), or snap an unsnapped one into the edge zone that way.

At the layout edge it enters a neighbour output's entry zone, hands off to a tiling neighbour, or moves to the next desktop. An empty direction refuses (invalid_direction).

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 the screen the verb acts on (navigationScreenFor).

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

Implements PhosphorEngine::IPlacementEngine.

◆ navigationScreenFor()

QString PhosphorSnapEngine::SnapEngine::navigationScreenFor ( const QString & windowId,
const QString & preferredScreen ) const

The screen a navigation verb on windowId acts on: its stored screen when snapped, else preferredScreen, else the cursor's, else the last active one.

◆ parkOutput()

QStringList PhosphorSnapEngine::SnapEngine::parkOutput ( const QString & physicalScreenId)
overridevirtual

Copy every context of physicalScreenId (each of its virtual screens) into the park, before the prune drops them.

Returns the parked windows.

Reimplemented from PhosphorEngine::IPlacementEngine.

◆ pruneStaleWindows()

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

Drops the state-index membership of every window not in the (canonical) alive set.

See the definition for why only the membership.

Reimplemented from PhosphorEngine::PlacementEngineBase.

◆ pruneStatesForActivities()

void PhosphorSnapEngine::SnapEngine::pruneStatesForActivities ( const QStringList & validActivities)
overridevirtual

Reimplemented from PhosphorEngine::IPlacementEngine.

◆ pruneStatesForDesktop()

void PhosphorSnapEngine::SnapEngine::pruneStatesForDesktop ( int removedDesktop)
overridevirtual

Reimplemented from PhosphorEngine::IPlacementEngine.

◆ pruneStatesForRemovedScreen()

void PhosphorSnapEngine::SnapEngine::pruneStatesForRemovedScreen ( const QString & physicalScreenId)
overridevirtual

Prune per-(screen, desktop, activity) state for a PHYSICALLY REMOVED output (monitor hot-unplug), matching every virtual sub-screen of the removed physical id.

All three engines override this and the daemon drives each from its screenRemoved handling: snap's stores are created lazily on placement with no screens set to reap them, and the two tiling engines' screens-set sweeps only reap CURRENT-context states, so sibling-context states (other desktops/activities) of the removed output would leak without the explicit whole-output prune. A tiling-family engine must emit windowsReleased for the windows it drops here, AFTER its reverse-map cleanup, so the daemon's restore consumers can re-home them; snap does not, because it is the engine those releases are restored INTO.

Reimplemented from PhosphorEngine::IPlacementEngine.

◆ pushFocusedToEmptyZone()

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

Move the focused window to the first empty zone on the screen it acts on.

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 the screen it acts on.

Implements PhosphorEngine::IPlacementEngine.

◆ readoptParked()

bool PhosphorSnapEngine::SnapEngine::readoptParked ( const QString & windowId,
const QString & parkedPhysicalId,
const QString & returnedPhysicalId )
overridevirtual

Re-seat windowId's contexts parked under parkedPhysicalId on returnedPhysicalId as a re-statement (no focus, no last-used), each in its own (screen, desktop, activity): its virtual screen on the returned output (or the bare output), never the context in view.

One that no longer runs the engine's mode as the daemon resolves it gets nothing (snap also refuses one switched off, disabled or excluding the window); one out of view is seated at once, or granted to the arrival path on a screen not running the mode yet. True if any was.

Reimplemented from PhosphorEngine::IPlacementEngine.

◆ reapplyLayout()

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

Re-apply the zones the windows on ctx.screenId hold in the context in view.

Never replays a pending layout-switch buffer.

Implements PhosphorEngine::IPlacementEngine.

◆ reapplyManagedWindowAppearance()

void PhosphorSnapEngine::SnapEngine::reapplyManagedWindowAppearance ( )
overridevirtual

Re-emit the zone geometry of every non-floating window snapped in view (the shown desktop's store on a screen snap runs) so the compositor re-applies its snap border / hidden title bar after a bridge reconnect.

See IPlacementEngine::reapplyManagedWindowAppearance().

Reimplemented from PhosphorEngine::IPlacementEngine.

◆ reconcileDesktopMemberships()

PhosphorEngine::MembershipReconcileResult PhosphorSnapEngine::SnapEngine::reconcileDesktopMemberships ( const QString & screenId,
const PhosphorEngine::DesktopSpanQuery & spanOf )
overridevirtual

A window on several desktops holds its own zone on each.

The pass grants and releases memberships, carries a moved window's state and re-states the context entered (membership.cpp).

Reimplemented from PhosphorEngine::IPlacementEngine.

◆ reconcileWindowMemberships()

PhosphorEngine::MembershipReconcileResult PhosphorSnapEngine::SnapEngine::reconcileWindowMemberships ( const QString & windowId,
const PhosphorEngine::DesktopSpanQuery & spanOf )
overridevirtual

The same pass for ONE window, on the screen it is held on.

The daemon calls it when the compositor reports that window's desktop set or activity changed, so a span shrink releases only the contexts the window left and a sticky transition adopts the context in view without waiting for a desktop switch.

Reimplemented from PhosphorEngine::IPlacementEngine.

◆ recordFreeFrameBeforeUserSnap()

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

Record a window's live frame as its float-back, ahead of a user snap the DAEMON drives (keys, snap-all, every user unfloat, the D-Bus snap), the free frame's last chance before the commit makes the effect's capture refused.

Filed under the screen the frame is on, which a cross-screen snap is leaving; screenId when no screen manager can place it. Refuses a minimized, suspension-floated, maximized (either axis) or fullscreen window.

◆ rekeyMembershipsToRecordedScreens()

void PhosphorSnapEngine::SnapEngine::rekeyMembershipsToRecordedScreens ( const QString & physicalScreenId)

After a split or un-split of physicalScreenId rewrote the stores' screen values, re-file each membership on the monitor under the key for the screen its store records (else its pre-float screen), desktop, activity and zone kept.

Releases nothing (F105): left on the old key, the next pinned commit on the new id read as a move off the monitor and released the window's other desktops. Reached through the WTS resolver seam.

◆ releaseWindowOffScreen()

void PhosphorSnapEngine::SnapEngine::releaseWindowOffScreen ( const QString & windowId,
const QString & keepScreenId )
overridevirtual

Silently release every membership off keepScreenId (every one when it is empty): zone with the last-used naming it, float bit, residence, pre-float home and persisted per-desktop entry.

Emits nothing.

Reimplemented from PhosphorEngine::PlacementEngineBase.

◆ releaseWindowOutsideSpan()

PhosphorEngine::MembershipReconcileResult PhosphorSnapEngine::SnapEngine::releaseWindowOutsideSpan ( const QString & windowId,
const QString & screenId,
const PhosphorEngine::DesktopSpan & span )

Silently release every membership windowId holds outside where it actually is: one off screenId (in any spelling of it), and, when span is known, one in a context span does not cover.

This is what a refused workspace move leaves behind: the snap-target handoff re-keyed the window into the destination's store before the compositor was asked, and the compositor kept the window where it was. Each membership goes the way releaseWindowOffScreen releases one (zone with the last-used naming it, float bit, residence, pre-float home and persisted per-desktop entry), and a pre-float home off screenId goes too. An unknown span releases only the memberships off screenId.

Emits nothing. The answer lists each released (window, key) in MembershipReconcileResult::released so the caller drives the placement re-capture and the effect's zone mirror as it does after a membership pass.

◆ remapDesktops()

void PhosphorSnapEngine::SnapEngine::remapDesktops ( const PhosphorEngine::DesktopRemap & remap)
overridevirtual

OPTIONAL: KWin's desktop list changed (a removal, an insert or a reorder).

Move every structure keyed by a desktop number through remap and prune the removed desktops' (F763, F787). The default runs a change that only removes desktops as pruneStatesForDesktop then renumberDesktopsAfterRemoval per removal, highest first, and only logs an insert or a reorder, which it cannot apply. Defined in PlacementEngineBase.cpp. Appended last for ABI.

Reimplemented from PhosphorEngine::IPlacementEngine.

◆ renameScreen()

void PhosphorSnapEngine::SnapEngine::renameScreen ( const QString & oldPhysicalId,
const QString & newPhysicalId )

Re-file every membership keyed on monitor oldPhysicalId (its virtual screens too) under the same key on newPhysicalId, desktop, activity and zone kept: an EDID twin's identifier flip (F189), after the WTS facade rewrote the screen values.

Nothing is released. Reached through the WTS resolver seam.

◆ renumberDesktopsAfterRemoval()

void PhosphorSnapEngine::SnapEngine::renumberDesktopsAfterRemoval ( int removedDesktop)
overridevirtual

Shift every per-(screen, desktop, activity) state ABOVE removedDesktop down by one, because Plasma renumbers x11 desktop numbers when a desktop in the middle is deleted (removing 2 of 4 makes 3 become 2 and 4 become 3).

The companion to pruneStatesForDesktop, which only drops the removed desktop's own state: without the shift every surviving higher state keeps its old number, and a consumer comparing a stored key against the compositor's numbers (the daemon's desktop-membership reconcile above all) reads a window that never moved as having left its desktop. The caller drives prune first, then this, knowing which desktop was removed (desktopCountChanged alone cannot tell). An implementation must move EVERY structure keyed by a PlacementStateKey or by a bare desktop number, walking the affected desktops in ASCENDING order so each target key is vacant when written. The single-removal form of remapDesktops.

Reimplemented from PhosphorEngine::IPlacementEngine.

◆ resnapCurrentAssignments() [1/2]

void PhosphorSnapEngine::SnapEngine::resnapCurrentAssignments ( const QString & screenFilter,
const QSet< QString > & onlyWindows,
ResnapFeedback feedback )

◆ resnapCurrentAssignments() [2/2]

void PhosphorSnapEngine::SnapEngine::resnapCurrentAssignments ( const QString & screenFilter = QString(),
const QSet< QString > & onlyWindows = {} )

Re-apply the zones windows hold, on screenFilter (all when empty), only onlyWindows when it is not empty.

Reports.

◆ resnapFromAutotileOrder()

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

No in-tree caller (the SnapAdaptor slot of this name calls calculateResnapEntriesFromAutotileOrder and commits the batch itself); kept as installed API.

Falls back to the current zones when the order yields nothing.

◆ resnapToNewLayout() [1/2]

void PhosphorSnapEngine::SnapEngine::resnapToNewLayout ( )

Resnap a switch's populated buffer into the new layouts: a window back in the layout it was snapped in gets the zones of it that layout still holds (a span stays a span), any other window the zone at its primary zone's position, or its pre-tile geometry when the new layout has no zone there.

◆ resnapToNewLayout() [2/2]

void PhosphorSnapEngine::SnapEngine::resnapToNewLayout ( ResnapFeedback feedback)

◆ resnapToNewLayoutRequested

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

Batched resnap data, committed by SnapAdaptor's applyEngineResnap relay.

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

Opt-in: it returns a found result only when the fallback is enabled for this window, which is the injected predicate's verdict (rule ?? config layering) when one is wired via setUnfloatFallbackPredicate, else the unfloatFallbackToZone setting read through ISnapSettings. Enabled, it resolves last-used → first-empty → first zone in the resolved screen's layout. The screen is fallbackScreen (the caller's live output) when it still exists, else the window's tracked float screen, and it is resolved BEFORE the opt-in gate because the predicate is evaluated against it. Returns not-found when the fallback is disabled or no zone resolves (so the caller keeps the window floating with feedback).

◆ resolveUnfloatGeometry() [1/2]

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

The ABI-stable signature exported before the confinement parameter.

◆ resolveUnfloatGeometry() [2/2]

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

Not-found when the RECORDED (raw) home screen names a different physical monitor than fallbackScreen, for every cause: a window moved to another monitor forgets the zone it floated from, so a home there can only be stale.

Compared before resolveUnfloatScreen, so an unplugged home refuses too. confineToFallbackScreen is inert.

◆ resolveWindowRestore()

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

Resolve auto-snap for a newly opened window.

A matched SnapToZone rule (chain level 1) outranks any stored placement (the store still re-binds the record first, so the float-back geometry survives). Otherwise the WindowPlacementStore reopens the window from a record it may restore WHERE IT OPENS (its own, on its screen; another instance's, on its output), never one that would move it to another monitor; a window whose own record names another screen left it and is released. Then levels 2 (empty zone) and 3 (last-used zone). A window nothing places is FLOATED; a re-entry never re-snaps a floating one.

Parameters
windowIdWindow identifier
screenIdScreen where the window appeared
stickyWhether the window is on all desktops
kindAccepted for wire compatibility and ignored: nothing sets a placement record's kind from a live window.
reasonWhy this resolve runs: gates the size restore, the FIFO, a re-entry re-snap and a leaver's rule.
Returns
PhosphorEngine::SnapResult with geometry and zone info, or PhosphorEngine::SnapResult::noSnap()

◆ restatementGeometryRequested

void PhosphorSnapEngine::SnapEngine::restatementGeometryRequested ( const QString & windowId,
int x,
int y,
int width,
int height,
const QString & zoneId,
const QString & screenId )
signal

Re-states a placement the window already has (relayed as PlacementPurpose::Restatement).

◆ restoreFocusedWindow()

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

Restore the focused window in a zone to its float-back on its screen and float it; one in no zone is refused.

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

◆ screenForTrackedWindow()

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

Return the screen this engine considers the window to be on (any context), or empty if the window isn't tracked by this engine.

The daemon's shortcut router consults it across engines, so a cross-engine handoff that emptied the source's tracking still routes the next shortcut to the engine that now owns the window.

Reimplemented from PhosphorEngine::IPlacementEngine.

◆ seedPersistedDesktopZones()

void PhosphorSnapEngine::SnapEngine::seedPersistedDesktopZones ( const QString & windowId,
const PhosphorEngine::EngineSlot & slot,
const QString & screenId,
int restoreDesktop,
const QString & activity )

Re-seed a restored record's other desktops' zones into their stores under activity, which every caller passes as the live one (currentActivity()), never the record's: the restore's commit lands there.

◆ setAutotileEngine()

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

Set the autotile engine for screen ownership checks.

Read by isActiveOnScreen only when no live mode resolver is wired (unit tests): there snapping is active wherever AutotileEngine is not. The daemon wires the resolver, which also answers for scrolling.

Parameters
engineAutotileEngine instance (not owned; its destroyed signal nulls it)

◆ setContextModeResolver()

void PhosphorSnapEngine::SnapEngine::setContextModeResolver ( ContextModeResolver resolver)
inline

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

Not owned.

Reimplemented from PhosphorEngine::IPlacementEngine.

◆ setCurrentActivity()

void PhosphorSnapEngine::SnapEngine::setCurrentActivity ( const QString & activity)
overridevirtual

Reimplemented from PhosphorEngine::IPlacementEngine.

◆ setCurrentDesktop()

void PhosphorSnapEngine::SnapEngine::setCurrentDesktop ( int desktop)
overridevirtual

Reimplemented from PhosphorEngine::IPlacementEngine.

◆ setCurrentDesktopForScreen()

void PhosphorSnapEngine::SnapEngine::setCurrentDesktopForScreen ( const QString & screenId,
int desktop )
overridevirtual

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

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

Reimplemented from PhosphorEngine::IPlacementEngine.

◆ setExcludeRuleSet()

void PhosphorSnapEngine::SnapEngine::setExcludeRuleSet ( const PhosphorRules::RuleSet * ruleSet)

Wire the daemon's filtered placement-exclusion rule set (rules carrying an Exclude or ExcludePlacement action).

Borrowed: it must outlive every later exclusion resolve (isWindowExcluded, evaluateExcludeRules, the isAppIdExcluded test seam). The daemon declares m_excludeRuleSet before m_snapEngine and also clears the borrow in its teardown before the engine goes. The cached evaluator drops on a pointer change. Declared outside Q_SIGNALS: moc would make it a signal there and the link would fail.

◆ setExclusionAdmission()

void PhosphorSnapEngine::SnapEngine::setExclusionAdmission ( ExclusionAdmission admission)
inline

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

◆ setFloating()

void PhosphorSnapEngine::SnapEngine::setFloating ( const QString & windowId,
bool floating )

◆ setFloatingWithResidence()

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

Float windowId in its primary store.

A window present on several desktops that holds no screen in that store (adopted into the desktop in view, never snapped there) has its screen and desktop residence recorded with the float (setFloatingOnScreen), so the capture and the cross-desktop focus walk can place it; every other float is the bare bit, as before.

◆ setFloatPredicate()

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

◆ setLiveModeResolver()

void PhosphorSnapEngine::SnapEngine::setLiveModeResolver ( LiveModeResolver resolver)
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; a QObject provider's destroyed signal nulls it, any other must outlive SnapEngine.

◆ setPersistenceDelegate()

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

Set persistence callbacks for save/load.

Persistence is owned by WindowTrackingAdaptor (its PhosphorConfig session backend). These callbacks let SnapEngine fulfil the IPlacementEngine persistence contract without a config dependency.

Parameters
saveFnCalled by saveState() to persist WTS state
loadFnCalled 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 disabled-context placement 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.

◆ setTilingEngineLiveResolver()

void PhosphorSnapEngine::SnapEngine::setTilingEngineLiveResolver ( TilingEngineLiveResolver resolver)
inline

◆ setUnfloatFallbackPredicate()

void PhosphorSnapEngine::SnapEngine::setUnfloatFallbackPredicate ( UnfloatFallbackPredicate predicate)
inline

◆ setWindowFloat()

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

Set floating state explicitly (directional, not toggle).

Parameters
screenIdThe window's authoritative current screen, when the caller knows it (the D-Bus setWindowFloatingForScreen threads the effect's live output here). An engine WITHOUT live per-window screen tracking MUST prefer this over its own tracked association, which can be stale after a floating window drifts across monitors — using the stale screen makes the unfloat's cross-monitor guard non-deterministic (snap and scroll honour it for exactly that reason). AutotileEngine deliberately resolves from its own tracking instead: its focus-driven migration keeps the association current, and the parameter can lag it mid-handoff. Empty (the default) means "resolve it yourself" for internal callers.

Implements PhosphorEngine::IPlacementEngine.

◆ setWindowRegistry()

void PhosphorSnapEngine::SnapEngine::setWindowRegistry ( QObject * registry)
overridevirtual

Attach the daemon's shared window registry.

Threaded into every SnapState (the per-screen stores, the global-scalar holder, and any created later) plus the engine's own canonicalization so the reverse map keys on the same stable first-seen composite the stores do (issue #628). Not owned.

Overrides IPlacementEngine::setWindowRegistry(QObject*): the interface hands engines a QObject carrying the registry and each casts to its concrete type.

Reimplemented from 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
resolverNot owned; a QObject one's destroyed signal nulls it, any other 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
screenIdScreen 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

The global-scalar holder (alias of globalState), for callers that only need the last-used-zone / user-snapped scalars; per-window data lives in the per-screen stores, reached via stateForWindow.

◆ spanFocusedInDirection()

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

Grow the focused window's zone span into the adjacent zone(s) in direction, or retract the opposite edge when nothing lies that way (pressing back toward the span undoes the last grow).

An unsnapped window is snapped into the edge zone in direction. Never crosses outputs or desktops. An empty direction refuses (invalid_direction).

Reimplemented from PhosphorEngine::IPlacementEngine.

◆ stateForScreen() [1/2]

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

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

◆ stateForWindow() [1/2]

SnapState * PhosphorSnapEngine::SnapEngine::stateForWindow ( const QString & windowId)

The SnapState that owns windowId (via the reverse map), or the global holder when the window is untracked — NEVER null (the holder is constructed in the ctor; see the fallback rationale on the definition).

An untracked window then reads the holder's per-window data: empty, except a screenless float parked there (isFloating and commitSnapImpl read it). Never creates. Callers must not null-check the result as a tracked/untracked test; use isWindowTracked() for that.

◆ stateForWindow() [2/2]

const SnapState * PhosphorSnapEngine::SnapEngine::stateForWindow ( const QString & windowId) const

◆ stateForWindowOnScreen()

SnapState * PhosphorSnapEngine::SnapEngine::stateForWindowOnScreen ( const QString & windowId,
const QString & screenId,
int desktop = 0 )

Resolve-or-register the state windowId's data belongs in for a write on screenId, and return it.

With desktop pinned (>= 1) that is the store for (screen, desktop, activity), created and granted a membership on first use: a commit that names a desktop other than the one the screen is showing (a RouteToDesktop rule, a cross-desktop move, a restore onto a background desktop) has to land in THAT desktop's store, or the membership pass reads the store's key as the assignment's desktop and releases it on the next switch. A pinned write naming another screen than the window's tracked one re-homes it there first: a window is on one screen. In the daemon every zone commit is pinned (commitSnap pins the screen's current desktop from the desktop manager, a copy the daemon keeps in step with the key in view). Unpinned (0: restoreFocusedWindow's float, a handoff naming no desktop, every write in a fixture without a desktop manager), a tracked window keeps its primary store whatever screen it names, and a first placement derives the key from the screen's current context, or takes the global holder when screenless. Public so the WTS facade routes its writes here.

◆ swapFocusedInDirection()

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

Swap the focused window with the window in the adjacent zone in direction, exchanging whole zone sets; into an empty zone it moves (moved_to_empty).

At the layout edge it swaps across a neighbour output or with a tiling neighbour, never across desktops. An empty direction refuses.

Implements PhosphorEngine::IPlacementEngine.

◆ switchFocusBetweenFloatingAndTiling()

void PhosphorSnapEngine::SnapEngine::switchFocusBetweenFloatingAndTiling ( const QString & screenId)
overridevirtual

Jump focus between the float layer and the snapped layout (niri's switch-focus-between-floating-and-tiling).

Activates the last focused window on the OTHER layer, falling back to a scan when the memory is stale; windows the compositor has reported minimized are skipped (an unreported state is treated as visible — a focus verb must not refuse a window merely because its state is unknown). Whether the float layer holds focus is derived live from the navigation state provider's active window, not stored. Only windows on the screen's current desktop count. Success reports "snapped" or "floating"; no screen or no store reports "no_windows", nothing on the other layer "no_target".

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

◆ wasPlacedByPreviousLineage()

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

That snapshot, taken before anything can re-bind a slot-bearing record under this uuid.

No in-tree caller (see applyNoMatchFloatDefault).

◆ windowClosed()

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

A no-op: snap's close is WindowTrackingService-driven (WTS::windowClosed clears the window's SnapState), so the daemon's engine close loop skips it.

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 in the context the screen shows, or empty if the zone is unoccupied there.

Read by the cross-mode swap (its partner when THIS engine is the target) and the cross-mode focus (the window to activate).

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

◆ zoneForWindow()

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

The zone of windowId's PRIMARY membership (the store in view when it is a member there, else its first): empty there even when another desktop holds one.

Read by, among others, uncommitSnap, tryCrossDesktopMove, restoreFocusedWindow and the cross-mode handoff.


The documentation for this class was generated from the following file:
  • phosphor-snap-engine/include/PhosphorSnapEngine/SnapEngine.h