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 <phosphor-engine/include/PhosphorEngine/PlacementEngineBase.h>

Inheritance diagram for PhosphorEngine::PlacementEngineBase:
[legend]

Signals

void geometryRestoreRequested (const QString &windowId, const QRect &geometry, const QString &screenId)
 
void navigationFeedback (bool success, const QString &action, const QString &reason, const QString &sourceId, const QString &targetId, const QString &screenId)
 
void windowFloatingChanged (const QString &windowId, bool floating, const QString &screenId)
 
void activateWindowRequested (const QString &windowId)
 
void windowDesktopMoveRequested (const QString &windowId, int desktop)
 Emitted when directional navigation moves a window across virtual desktops: the engine has already re-keyed its own tiling state, and the compositor must move the real window to desktop (1-based).
 
void windowOutputMoveExpected (const QString &windowId, const QString &targetScreenId)
 Emitted when daemon-initiated directional navigation moves a window across physical outputs: the engine has already migrated its own tiling state (removed from the source key, re-added on targetScreenId) and scheduled both reflows.
 
void crossModeMoveRequested (const QString &windowId, const QString &targetScreenId, int targetDesktop, const QString &direction)
 Emitted when a directional MOVE reaches a context boundary whose target is a DIFFERENT tiling mode than the source — the source engine cannot place the window itself (it has no state for the other mode), so it defers to the daemon.
 
void crossModeSwapRequested (const QString &windowId, const QString &targetScreenId, int targetDesktop, const QString &direction)
 Emitted when a directional SWAP reaches a context boundary whose target is a DIFFERENT tiling mode than the source — the two-way cross-mode exchange.
 
void 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.
 
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
 
- Public Member Functions inherited from PhosphorEngine::IPlacementEngine
virtual ~IPlacementEngine ()=default
 
 IPlacementEngine (const IPlacementEngine &)=delete
 
IPlacementEngineoperator= (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: cross-screen session reclaim, the tiling-engine counterpart of the snap engine's recorded-screen restore.
 
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).
 
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< WindowPlacementcapturePlacement (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 ()
 
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 wants to PAINT 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, 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 std::function< bool(const QString &)> &isWindowSticky)
 
virtual QSet< int > desktopsWithActiveState () const
 
virtual void pruneStatesForDesktop (int removedDesktop)
 
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 IPlacementStatestateForScreen (const QString &screenId)=0
 Per-screen state object for the given screen.
 
virtual const IPlacementStatestateForScreen (const QString &screenId) const =0
 

Protected Member Functions

 PlacementEngineBase (QObject *parent=nullptr)
 
void announceLayerSwitch (const LayerSwitchResult &result, const QString &action, const QString &screenId)
 Emit the activation + navigationFeedback pair for a resolved layer focus switch (resolveLayerFocusSwitch).
 
- Protected Member Functions inherited from PhosphorEngine::IPlacementEngine
 IPlacementEngine ()=default
 

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

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

◆ placementChanged

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

Emitted when the placement layout changes for a screen.

◆ pruneStaleWindows()

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

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

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

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

◆ setEngineSettings()

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

◆ settingsPersistRequested

void PhosphorEngine::PlacementEngineBase::settingsPersistRequested ( )
signal

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

◆ windowDesktopMoveRequested

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

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

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

◆ windowFloatingChanged

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

◆ windowFloatingStateSynced

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

Emitted to sync floating state without restoring geometry.

Passive state-sync: engine-internal divergence correction.

◆ windowOutputMoveExpected

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

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

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

◆ windowsBatchFloated

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

Emitted when overflow windows are batch-floated during applyTiling.

◆ windowsReleased

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

Emitted when windows are released from engine management.


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