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

Abstract base class for placement engines. More...

#include <PhosphorEngine/PlacementEngineBase.h>

Inheritance diagram for PhosphorEngine::PlacementEngineBase:
[legend]

Signals

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

virtual int pruneStaleWindows (const QSet< QString > &aliveWindowIds)
 Drop any per-engine bookkeeping for windows not in aliveWindowIds.
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.
void releaseWindowOffScreen (const QString &windowId, const QString &keepScreenId) override
 A window is held on one output, so a hold on any screen but keepScreenId is released whole through handoffRelease (every context plus the durable slot), which never reaches the snap engine.
Public Member Functions inherited from PhosphorEngine::IPlacementEngine
virtual ~IPlacementEngine ()=default
 IPlacementEngine (const IPlacementEngine &)=delete
IPlacementEngine & operator= (const IPlacementEngine &)=delete
virtual bool isActiveOnScreen (const QString &screenId) const =0
 Whether this engine is active on the given screen.
virtual void windowOpened (const QString &windowId, const QString &screenId, int minWidth=0, int minHeight=0)=0
 A new window appeared on this engine's screen.
void windowOpened (const QString &windowId, const QString &screenId)
 Convenience overload — equivalent to windowOpened(id, screen, 0, 0).
virtual 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 std::optional< PlacementStateKey > heldKeyForWindow (const QString &windowId) const
 The (screen, desktop, activity) key of the state that genuinely holds windowId, tiled or floating, in ANY context, or nullopt when none does.
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 void windowClosed (const QString &windowId)=0
 A window was closed.
virtual void windowFocused (const QString &windowId, const QString &screenId)=0
 A window gained focus (called when the compositor reports activation).
virtual void toggleWindowFloat (const QString &windowId, const QString &screenId)=0
 Toggle between managed and floating.
virtual void setWindowFloat (const QString &windowId, bool shouldFloat, const QString &screenId=QString())=0
 Set floating state explicitly (directional, not toggle).
virtual void focusInDirection (const QString &direction, const NavigationContext &ctx)=0
 Move keyboard focus to the adjacent window.
virtual void moveFocusedInDirection (const QString &direction, const NavigationContext &ctx)=0
 Move the focused window to the adjacent slot.
virtual void spanFocusedInDirection (const QString &direction, const NavigationContext &ctx)
 Grow or shrink the focused window's zone span toward the direction: extend into the adjacent zone(s) when some exist beyond that edge, otherwise retract the opposite edge.
virtual void switchFocusBetweenFloatingAndTiling (const QString &screenId)
 Jump focus between the float layer and the engine's placement layer (niri's switch-focus-between-floating-and-tiling): activate the last focused window on the OTHER layer, falling back to a scan when that memory is stale.
virtual void swapFocusedInDirection (const QString &direction, const NavigationContext &ctx)=0
 Swap the focused window with the adjacent window.
virtual void moveFocusedToPosition (int position, const NavigationContext &ctx)=0
 Move the focused window to the Nth position.
virtual void rotateWindows (bool clockwise, const NavigationContext &ctx)=0
 Rotate all managed windows on the screen.
virtual void reapplyLayout (const NavigationContext &ctx)=0
 Re-apply the current layout to all managed windows.
virtual void snapAllWindows (const NavigationContext &ctx)=0
 Bring every unmanaged window on the screen back under this engine's placement (zones for snap, the strip for scrolling).
virtual void cycleFocus (bool forward, const NavigationContext &ctx)=0
 Cycle keyboard focus through managed windows.
virtual void pushToEmptyZone (const NavigationContext &ctx)=0
 Move the focused window to the first empty slot.
virtual void restoreFocusedWindow (const NavigationContext &ctx)=0
 Restore the focused window out of its managed state.
virtual void toggleFocusedFloat (const NavigationContext &ctx)=0
 Toggle the focused window between managed and floating.
virtual QSet< QString > activeScreens () const
virtual void setActiveScreens (const QSet< QString > &screens)
virtual void reapplyManagedWindowAppearance ()
 Re-drive the compositor's per-window appearance (border, hidden title bar) for every window this engine currently manages, WITHOUT recomputing the layout — windows keep their current zones/positions.
virtual std::optional< WindowPlacement > capturePlacement (const QString &windowId) const
 Report windowId's CURRENT placement for persistence, or nullopt if this engine does not manage it.
virtual bool restorePlacement (const WindowPlacement &placement, const QString &screenId)
 Apply placement to a (re)opening window on screenId.
virtual QStringList managedWindowOrder (const QString &screenId) const
virtual void setInitialWindowOrder (const QString &screenId, const QStringList &windowIds)
virtual 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 isWindowTracked (const QString &windowId) const
virtual bool isWindowManaged (const QString &windowId) const
 Whether the engine considers the window "managed" (eligible for layout operations).
virtual bool isWindowTiled (const QString &windowId) const
 Whether the window is actively tiled (engine-owned, non-floating).
virtual QString screenForTrackedWindow (const QString &windowId) const
 Return the screen this engine considers the window to be on (any context), or empty if the window isn't tracked by this engine.
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 void handoffReceive (const HandoffContext &ctx)
 Receive ownership of a window from another engine.
virtual void handoffRelease (const QString &windowId)
 Release ownership of a window WITHOUT modifying its geometry.
virtual QString engineId () const
 Stable engine identity for HandoffContext.fromEngineId.
virtual LayoutSupport layoutSupport () const
 Default None: an engine must opt in to being a layout consumer.
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 bool isEnabled () const noexcept
virtual QString activeScreen () const
virtual void setActiveScreenHint (const QString &screenId)
virtual void setCurrentDesktop (int desktop)
virtual void setCurrentDesktopForScreen (const QString &screenId, int desktop)
 Set a single screen's current virtual desktop (Plasma 6.7 "switch desktops independently for each screen").
virtual void clearCurrentDesktopForScreen (const QString &screenId)
 Drop a screen's per-output desktop, reverting it to the global current.
virtual void setCurrentActivity (const QString &activity)
virtual void setCrossSurfaceResolver (ICrossSurfaceResolver *resolver)
 Inject the cross-surface resolver used to find a neighbouring output / desktop when directional navigation reaches a surface boundary.
virtual void updateStickyScreenPins (const 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 MembershipReconcileResult reconcileDesktopMemberships (const QString &screenId, const DesktopSpanQuery &spanOf)
 Give every window whose span covers screenId's current context a place in it, and take back the places on that screen the span no longer covers.
virtual MembershipReconcileResult reconcileWindowMemberships (const QString &windowId, const DesktopSpanQuery &spanOf)
 The same pass for ONE window, on the screen it is held on.
virtual QSet< int > desktopsWithActiveState () const
virtual void pruneStatesForDesktop (int removedDesktop)
virtual void renumberDesktopsAfterRemoval (int removedDesktop)
 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).
virtual void pruneStatesForActivities (const QStringList &validActivities)
virtual void pruneStatesForRemovedScreen (const QString &physicalScreenId)
 Prune per-(screen, desktop, activity) state for a PHYSICALLY REMOVED output (monitor hot-unplug), matching every virtual sub-screen of the removed physical id.
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 setWindowRegistry (QObject *registry)
 Attach a window-class registry (QObject carrying WindowRegistry).
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 saveState ()=0
virtual void loadState ()=0
virtual IPlacementState * stateForScreen (const QString &screenId)=0
 Per-screen state object for the given screen.
virtual const IPlacementState * stateForScreen (const QString &screenId) const =0
virtual QStringList parkOutput (const QString &physicalScreenId)
 Copy every context of physicalScreenId (each of its virtual screens) into the park, before the prune drops them.
virtual bool readoptParked (const QString &windowId, const QString &parkedPhysicalId, const QString &returnedPhysicalId)
 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.
virtual void dropParked (const QString &windowId, const QString &physicalScreenId, int desktop, const QString &activity)
 Forget windowId's parked contexts; an empty physicalScreenId, a desktop of 0 or an empty activity matches every one.
virtual bool hasParked (const QString &windowId, const QString &physicalScreenId) const
 Whether windowId has a context parked under physicalScreenId (any output when it is empty).
virtual void remapDesktops (const DesktopRemap &remap)
 OPTIONAL: KWin's desktop list changed (a removal, an insert or a reorder).
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.

Protected Member Functions

 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

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

Additional Inherited Members

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

Detailed Description

Abstract base class for placement engines.

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

Engines subclass this and implement the placement-specific hooks.

Constructor & Destructor Documentation

◆ ~PlacementEngineBase()

PhosphorEngine::PlacementEngineBase::~PlacementEngineBase ( )
override

◆ PlacementEngineBase()

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

Member Function Documentation

◆ activateWindowRequested

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

◆ algorithmChanged

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

Emitted when the active tiling algorithm changes.

◆ announceLayerSwitch()

void PhosphorEngine::PlacementEngineBase::announceLayerSwitch ( const LayerSwitchResult & result,
const QString & action,
const QString & screenId )
protected

Emit the activation + navigationFeedback pair for a resolved layer focus switch (resolveLayerFocusSwitch).

Success: activation first, then feedback with the result's reason/source/target. Failure: feedback only, empty target. Precondition: a successful result carries a non-empty target (the resolver guarantees it; callers that mutate the result may only remap the reason token, never flip success or blank the target). Engine-specific bookkeeping that must precede the activation (the scroll engine's eager flag clear and self-activation echo queue) happens BEFORE calling this.

◆ crossModeFocusRequested

void PhosphorEngine::PlacementEngineBase::crossModeFocusRequested ( const QString & targetScreenId,
const QString & direction,
bool * handled )
signal

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.

No window travels and no engine state changes; the compositor's answering focus report is what updates each engine. Monitor crossings only — a focus has no cross-desktop arm.

handled is an OUT parameter the handler sets true only when it actually issued an activation. The connection is DirectConnection by contract (enginewiring.cpp), so the emitter reads the verdict on return and can report no_target instead of announcing a crossing that never happened — an empty neighbour output is an ordinary state for a focus, unlike a move, which always has a mover to hand over. A null pointer is permitted for callers that do not need the verdict.

◆ crossModeMoveRequested

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

Emitted when a directional MOVE reaches a context boundary whose target is a DIFFERENT tiling mode than the source — the source engine cannot place the window itself (it has no state for the other mode), so it defers to the daemon.

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

◆ crossModeSwapRequested

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

Emitted when a directional SWAP reaches a context boundary whose target is a DIFFERENT tiling mode than the source — the two-way cross-mode exchange.

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

◆ engineSettings()

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

◆ geometryRestoreRequested

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

◆ isManagedSize()

bool PhosphorEngine::PlacementEngineBase::isManagedSize ( const QList< QSize > & managedSizes,
const QSize & size )
staticprotected

Whether size is within two pixels of any entry of managedSizes on both axes.

Within a couple of pixels, not exact: a fractional-scale round-trip or a size-increment client (terminal cells) lands the frame a pixel or two off the requested rect. Shared by the size restore above and by the engines' position-restore move branches, which must not re-apply a recorded rect of a managed size either: a window that missed its first size restore closes with the managed-sized frame as its "free" rect, and re-applying it would keep that record alive for every later reopen.

◆ lastManagedRect()

virtual QRect PhosphorEngine::PlacementEngineBase::lastManagedRect ( const QString & windowId) const
inlinevirtual

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.

On a float toggle the engine flips its managed bit before the compositor repositions the window, so state predicates (isWindowTiled et al.) already answer "not managed" while the live frame still IS the managed rect — the capture orchestrator compares against this to refuse adopting such a frame as free/float geometry. Invalid when the engine never applied a rect (the base default: engines whose managed rects are resolvable from persisted state, like snap's zone geometry, don't need it).

Reimplemented in PhosphorScrollEngine::ScrollEngine, and PhosphorTileEngine::AutotileEngine.

◆ navigationFeedback

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

◆ openFocusEligible()

bool PhosphorEngine::PlacementEngineBase::openFocusEligible ( ) const
inlineprotected

Whether the open being handled may take focus (see IPlacementEngine::setOpenFocusEligible).

True unless the dispatching adaptor said this is a re-placement, so a direct windowOpened call (tests, embedders without the adaptor) keeps the setting's behaviour.

◆ placedByPreviousLineage()

bool PhosphorEngine::PlacementEngineBase::placedByPreviousLineage ( const WindowPlacementStore & store,
const QString & windowId )
staticprotected

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

A slot-less record is an open's own pre-tile capture. Every engine takes it BEFORE its take() or takeForReopen, which re-bind a FIFO-matched sibling record under the live id and would make a fresh window read as already placed.

◆ placementChanged

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

Emitted when the placement layout changes for a screen.

◆ pruneStaleWindows()

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

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

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

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

◆ releaseWindowOffScreen()

void PhosphorEngine::PlacementEngineBase::releaseWindowOffScreen ( const QString & windowId,
const QString & keepScreenId )
overridevirtual

A window is held on one output, so a hold on any screen but keepScreenId is released whole through handoffRelease (every context plus the durable slot), which never reaches the snap engine.

Reimplemented from PhosphorEngine::IPlacementEngine.

Reimplemented in PhosphorScrollEngine::ScrollEngine, and PhosphorSnapEngine::SnapEngine.

◆ restoreFreeSizeWhereItStands()

void PhosphorEngine::PlacementEngineBase::restoreFreeSizeWhereItStands ( IWindowTrackingService * tracker,
const QString & windowId,
const QString & screenId,
RestoreReason reason,
bool placedBefore,
const QList< QSize > & managedSizes )
protected

The size-only half of a float verdict, shared by every engine (#1106).

A window an engine leaves floating at open sits where the compositor placed it, at the size the client asked for. KDE apps save their window size to their own config on every resize, and a snap or a tile is a resize, so an app with a managed window opens its next window at the zone's, tile's or column's size. Nothing else undoes that: the position restore is gated and moves only a window with its own screen-local record, and a fresh second instance has no record of its own. The size comes from, in order:

  1. the window's OWN record, when it carries an engine slot (a reopen whose managed record was declined, or whose floated record restored without a move, re-bound to the live id before this runs). A slot-less record under the live id is the pre-tile capture of this very open and its rect is the spawn frame, so it is never a source;
  2. the earliest-recorded LIVE SIBLING's record with a usable rect;
  3. a CLOSED same-app record with a usable rect, read but never consumed: the tiling engines re-bind only a record they consume, and they consume floating records only, so a window that closed tiled and reopens under a Float rule has neither an own rect nor a live sibling, yet its old record still knows its free size.

A rect on screenId is preferred (the containment check fails open without a screen manager, accepted for embedders and tests). With none in any record, the same order is run again for the record's rects from other screens, of which only the size is used. Either way its size, clamped as below, is not within two pixels of any of managedSizes (isManagedSize), the sizes a managed window on that screen can have (zones and live spans for snap, the live tile or column rects for the tiling engines): a sibling the engine placed at open carries the managed-sized spawn frame as its own "free" rect, which is the very size this exists to undo, and record order alone cannot tell such a sibling from the first instance. The compare is between FRAME sizes, so under the opt-in hide-title-bars decoration a managed frame (no title bar) and a fresh one (with) differ by the decoration height and the refusal misses; the effect then skips an apply that would leave the size unchanged. The size is clamped to the screen's available area when tracker can resolve one.

Gated on two facts, not on the driver. placedBefore says the store already held a record WITH AN ENGINE SLOT under this exact uuid before the open consumed anything: a previous daemon lineage placed this window (a daemon-only restart re-announce, a mode-swap re-announce), the user has been looking at it since, and it is left alone. Every other driver, the bring-up sweeps included, can be a window's first placement (an open the readiness gate refused is placed by the daemon-restart sweep) and resizes. reason refuses only Unminimize, a re-drive of a window whose engine state is warm. Emits sizeRestoreRequested; the adaptor relays it as a size-only apply the effect performs as a teleport under first-frame suppression. The snap and tile callers guard against repeats with their own already-floating checks; the scroll caller's same-key early return does the same, and its migration re-entry skips the arm. No-op without tracker, or with an empty windowId or screenId.

◆ setEngineSettings()

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

◆ setOpenFocusEligible()

void PhosphorEngine::PlacementEngineBase::setOpenFocusEligible ( bool eligible)
inlineoverridevirtual

OPTIONAL: whether the opens dispatched next may take focus ("Focus new windows"): true for a genuine open, false for a re-placement.

The tiling adaptor sets it around each dispatch. Appended last for ABI.

Reimplemented from PhosphorEngine::IPlacementEngine.

◆ settingsPersistRequested

void PhosphorEngine::PlacementEngineBase::settingsPersistRequested ( )
signal

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

◆ sizeRestoreRequested

void PhosphorEngine::PlacementEngineBase::sizeRestoreRequested ( const QString & windowId,
const QSize & size,
const QString & screenId )
signal

Resize windowId to size where it stands, leaving the position to the compositor.

The size-only sibling of geometryRestoreRequested: a window nothing places is given back its remembered free size, not its remembered spot. Relayed to the effect as a size-only apply. Emitted by restoreFreeSizeWhereItStands from every engine's float-at-open arm and wired for all three.

◆ windowDesktopMoveRequested

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

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

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

◆ windowFloatingChanged

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

◆ windowFloatingStateSynced

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

Emitted to sync floating state without restoring geometry: 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.

◆ windowOutputMoveExpected

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

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

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

◆ windowsBatchFloated

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

Emitted when overflow windows are batch-floated during applyTiling.

◆ windowsReleased

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

Emitted when windows are released from engine management.


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