IPlacementEngine.h

Go to the documentation of this file.

// SPDX-FileCopyrightText: 2026 fuddlesworth
// SPDX-License-Identifier: LGPL-2.1-or-later
 
// FILE-SIZE EXCEPTION (sanctioned): one interface, one header. The whole
// file is a single abstract class — the placement-engine contract every
// engine implements and the daemon dispatches against — and C++ cannot
// split one class's members across headers. Extracting groups of virtuals
// into secondary bases would change the contract's shape (and every
// implementer and mock) purely to satisfy a line count.
 
#pragma once
 
#include <phosphorengine_export.h>
 
#include <PhosphorEngine/IPlacementState.h>
#include <PhosphorEngine/NavigationContext.h>
#include <PhosphorEngine/WindowPlacement.h>
 
#include <QPoint>
#include <QRect>
#include <QSize>
#include <QSet>
#include <QString>
#include <QStringList>
#include <QVariantMap>
 
#include <functional>
#include <optional>
 
class QObject;
 
namespace PhosphorEngine {
 
class ICrossSurfaceResolver;
 
class PHOSPHORENGINE_EXPORT IPlacementEngine
{
protected:
    IPlacementEngine() = default;
 
public:
    virtual ~IPlacementEngine() = default;
    // Polymorphic base: never copied or moved (every concrete engine is a
    // QObject anyway; this makes slicing a compile error at the interface).
    IPlacementEngine(const IPlacementEngine&) = delete;
    IPlacementEngine& operator=(const IPlacementEngine&) = delete;
 
    // ═══════════════════════════════════════════════════════════════════════════
    // Screen ownership
    // ═══════════════════════════════════════════════════════════════════════════
 
    virtual bool isActiveOnScreen(const QString& screenId) const = 0;
 
    // ═══════════════════════════════════════════════════════════════════════════
    // Window lifecycle
    // ═══════════════════════════════════════════════════════════════════════════
 
    virtual void windowOpened(const QString& windowId, const QString& screenId, int minWidth = 0,
                              int minHeight = 0) = 0;
 
    void windowOpened(const QString& windowId, const QString& screenId)
    {
        windowOpened(windowId, screenId, 0, 0);
    }
 
    virtual bool claimCrossScreenReopen(const QString& windowId, const QString& openingScreenId, int minWidth = 0,
                                        int minHeight = 0)
    {
        Q_UNUSED(windowId)
        Q_UNUSED(openingScreenId)
        Q_UNUSED(minWidth)
        Q_UNUSED(minHeight)
        return false;
    }
 
    virtual QString heldScreenForWindow(const QString& windowId) const
    {
        Q_UNUSED(windowId)
        return {};
    }
 
    virtual void beginArrivalBurst()
    {
    }
    virtual void endArrivalBurst()
    {
    }
 
    virtual void windowClosed(const QString& windowId) = 0;
 
    virtual void windowFocused(const QString& windowId, const QString& screenId) = 0;
 
    // ═══════════════════════════════════════════════════════════════════════════
    // Float management (explicit window ID)
    //
    // These take a concrete window ID — used by the D-Bus adaptor and
    // engine-internal paths that already know which window to act on.
    // toggleFocusedFloat() in the Navigation section is the user-intent
    // entry point that resolves the focused window from NavigationContext.
    // ═══════════════════════════════════════════════════════════════════════════
 
    virtual void toggleWindowFloat(const QString& windowId, const QString& screenId) = 0;
 
    virtual void setWindowFloat(const QString& windowId, bool shouldFloat, const QString& screenId = QString()) = 0;
 
    // ═══════════════════════════════════════════════════════════════════════════
    // Navigation (user intents)
    // ═══════════════════════════════════════════════════════════════════════════
 
    virtual void focusInDirection(const QString& direction, const NavigationContext& ctx) = 0;
 
    virtual void moveFocusedInDirection(const QString& direction, const NavigationContext& ctx) = 0;
 
    virtual void spanFocusedInDirection(const QString& direction, const NavigationContext& ctx)
    {
        Q_UNUSED(direction)
        Q_UNUSED(ctx)
    }
 
    virtual void switchFocusBetweenFloatingAndTiling(const QString& screenId)
    {
        Q_UNUSED(screenId)
    }
 
    virtual void swapFocusedInDirection(const QString& direction, const NavigationContext& ctx) = 0;
 
    virtual void moveFocusedToPosition(int position, const NavigationContext& ctx) = 0;
 
    virtual void rotateWindows(bool clockwise, const NavigationContext& ctx) = 0;
 
    virtual void reapplyLayout(const NavigationContext& ctx) = 0;
 
    virtual void snapAllWindows(const NavigationContext& ctx) = 0;
 
    virtual void cycleFocus(bool forward, const NavigationContext& ctx) = 0;
 
    virtual void pushToEmptyZone(const NavigationContext& ctx) = 0;
 
    virtual void restoreFocusedWindow(const NavigationContext& ctx) = 0;
 
    virtual void toggleFocusedFloat(const NavigationContext& ctx) = 0;
 
    // ═══════════════════════════════════════════════════════════════════════════
    // OPTIONAL: Screen management (override if engine tracks multi-screen state)
    // ═══════════════════════════════════════════════════════════════════════════
 
    virtual QSet<QString> activeScreens() const
    {
        return {};
    }
    virtual void setActiveScreens(const QSet<QString>& screens)
    {
        Q_UNUSED(screens)
    }
 
    // ═══════════════════════════════════════════════════════════════════════════
    // OPTIONAL: Window-appearance re-application (compositor reconnect)
    // ═══════════════════════════════════════════════════════════════════════════
 
    virtual void reapplyManagedWindowAppearance()
    {
    }
 
    // ═══════════════════════════════════════════════════════════════════════════
    // OPTIONAL: Unified placement capture/restore (engine-agnostic restore model)
    //
    // The single seam for the unified WindowPlacement restore model. An engine
    // implements exactly these two methods to participate in save+restore; a new
    // engine (e.g. the scrolling engine) needs no core/schema change — it keys
    // its own EngineSlot (state token + slot reference) under its engineId() in the
    // single per-window record and reads/writes the shared freeGeometryByScreen.
    // ═══════════════════════════════════════════════════════════════════════════
 
    virtual std::optional<WindowPlacement> capturePlacement(const QString& windowId) const
    {
        Q_UNUSED(windowId)
        return std::nullopt;
    }
 
    virtual bool restorePlacement(const WindowPlacement& placement, const QString& screenId)
    {
        Q_UNUSED(placement)
        Q_UNUSED(screenId)
        return false;
    }
 
    // ═══════════════════════════════════════════════════════════════════════════
    // OPTIONAL: Window ordering and focus (mode-transition capture and seed)
    // ═══════════════════════════════════════════════════════════════════════════
 
    virtual QStringList managedWindowOrder(const QString& screenId) const
    {
        Q_UNUSED(screenId)
        return {};
    }
    virtual void setInitialWindowOrder(const QString& screenId, const QStringList& windowIds)
    {
        Q_UNUSED(screenId)
        Q_UNUSED(windowIds)
    }
 
    virtual QString managedFocusedWindow(const QString& screenId) const
    {
        Q_UNUSED(screenId)
        return {};
    }
    virtual int stickyPinnedDesktopForScreen(const QString& screenId) const
    {
        Q_UNUSED(screenId)
        return 0;
    }
    virtual void setInitialFocusedWindow(const QString& screenId, const QString& windowId)
    {
        Q_UNUSED(screenId)
        Q_UNUSED(windowId)
    }
 
    // ═══════════════════════════════════════════════════════════════════════════
    // OPTIONAL: Per-screen config (override if engine supports per-screen overrides)
    //
    // SCOPE IS THE IMPLEMENTATION'S CHOICE, and the two in-tree engines differ.
    // AutotileEngine stores one map per SCREEN. ScrollEngine stores one per
    // (screen, desktop, activity) and answers for the screen's CURRENT context,
    // because its templates are resolved per context and keying by screen let
    // one desktop's template overwrite another's. A caller holding this
    // interface must therefore not assume a map it pushed survives a desktop or
    // activity switch, nor that the accessor replays what it last wrote.
    // clearPerScreenConfig is the whole-SCREEN door in both: it drops every
    // context's entry, so an engine keyed per context needs an empty
    // applyPerScreenConfig push, not a clear, to say "this context has none".
    // ═══════════════════════════════════════════════════════════════════════════
 
    virtual void applyPerScreenConfig(const QString& screenId, const QVariantMap& overrides)
    {
        Q_UNUSED(screenId)
        Q_UNUSED(overrides)
    }
    virtual void clearPerScreenConfig(const QString& screenId)
    {
        Q_UNUSED(screenId)
    }
    virtual QVariantMap perScreenOverrides(const QString& screenId) const
    {
        Q_UNUSED(screenId)
        return {};
    }
 
    // ═══════════════════════════════════════════════════════════════════════════
    // OPTIONAL: Mode-specific float MARKER (runtime discriminator, NOT persistence)
    //
    // Distinguishes a USER float in this engine's mode from an incidental float
    // (e.g. autotile overflow). It is live runtime state the capture funnel reads
    // to decide whether a float should persist into the record — there is no
    // parallel "saved floats" store; the WindowPlacement record is the single
    // source of truth for cross-mode float state. All three verbs live here,
    // in one section (mark / query / clear).
    // ═══════════════════════════════════════════════════════════════════════════
 
    virtual void markModeSpecificFloated(const QString& windowId)
    {
        Q_UNUSED(windowId)
    }
    virtual bool isModeSpecificFloated(const QString& windowId) const
    {
        Q_UNUSED(windowId)
        return false;
    }
    virtual void clearModeSpecificFloatMarker(const QString& windowId)
    {
        Q_UNUSED(windowId)
    }
 
    // ═══════════════════════════════════════════════════════════════════════════
    // OPTIONAL: Drag insert preview (override if engine supports drag-to-insert)
    // ═══════════════════════════════════════════════════════════════════════════
 
    struct DragInsertTarget
    {
        int primary = -1;
        int secondary = -1;
        bool newSlot = false;
        bool leadingEdge = false;
 
        bool isValid() const
        {
            return primary >= 0;
        }
        bool operator==(const DragInsertTarget& other) const = default;
    };
 
    // Contract shared by the preview verbs, which the two implementations
    // honour with OPPOSITE internal shapes:
    //  - begin MAY mutate managed state, and MAY adopt the window from
    //    another screen, from a floating set, or from untracked entirely
    //    (both engines do all three).
    //  - an engine may or may not keep the window MANAGED while its preview
    //    is live — autotile keeps it a tile and restructures per update;
    //    scrolling DETACHES it until commit. Cross-engine callers must not
    //    use isWindowTiled/isWindowManaged as a drag-state probe.
    //  - begin on an engine already holding a preview cancels the old one
    //    first; commit/cancel are no-ops with no preview live; and
    //    dragInsertPreviewScreenId is empty with no preview live.
 
    virtual bool hasDragInsertPreview() const
    {
        return false;
    }
    virtual bool beginDragInsertPreview(const QString& windowId, const QString& screenId)
    {
        Q_UNUSED(windowId)
        Q_UNUSED(screenId)
        return false;
    }
    virtual void commitDragInsertPreview()
    {
    }
    virtual void cancelDragInsertPreview()
    {
    }
    virtual QString dragInsertPreviewScreenId() const
    {
        return {};
    }
 
    virtual QString dragInsertPreviewPriorScreenId() const
    {
        return {};
    }
 
    virtual DragInsertTarget computeDragInsertTargetAtPoint(const QString& screenId, const QPoint& cursorPos) const
    {
        Q_UNUSED(screenId)
        Q_UNUSED(cursorPos)
        return {};
    }
 
    virtual void updateDragInsertPreview(const DragInsertTarget& target)
    {
        Q_UNUSED(target)
    }
 
    virtual bool dragAutoScrollTick(const QString& screenId, const QPoint& cursorPos, qreal dtSeconds)
    {
        Q_UNUSED(screenId)
        Q_UNUSED(cursorPos)
        Q_UNUSED(dtSeconds)
        return false;
    }
 
    virtual bool dragAutoScrollActive() const
    {
        return false;
    }
 
    virtual void cancelDragAutoScroll()
    {
    }
 
    virtual QRect dragInsertIndicatorRect(const QString& screenId) const
    {
        Q_UNUSED(screenId)
        return {};
    }
 
    virtual void setInteractiveDragWindow(const QString& windowId)
    {
        Q_UNUSED(windowId)
    }
 
    // ═══════════════════════════════════════════════════════════════════════════
    // OPTIONAL: Per-window tracking state
    //
    // What the daemon asks an engine about ONE window: does it track it, does
    // it manage/tile it, which screen does it think the window is on, what min
    // size does it model — plus the two per-window updates that follow from
    // those answers (a late min-size discovery, an interactive resize). The
    // drag-preview verbs above are a separate group; these have nothing to do
    // with a drag.
    // ═══════════════════════════════════════════════════════════════════════════
 
    virtual bool isWindowTracked(const QString& windowId) const
    {
        Q_UNUSED(windowId)
        return false;
    }
    virtual bool isWindowManaged(const QString& windowId) const
    {
        Q_UNUSED(windowId)
        return false;
    }
 
    virtual bool isWindowTiled(const QString& windowId) const
    {
        Q_UNUSED(windowId)
        return false;
    }
 
    virtual QString screenForTrackedWindow(const QString& windowId) const
    {
        Q_UNUSED(windowId)
        return {};
    }
 
    virtual QSize windowMinimumSize(const QString& windowId) const
    {
        Q_UNUSED(windowId)
        return {};
    }
 
    virtual void windowMinSizeUpdated(const QString& windowId, int minWidth, int minHeight)
    {
        Q_UNUSED(windowId)
        Q_UNUSED(minWidth)
        Q_UNUSED(minHeight)
    }
 
    virtual void onWindowResized(const QString& windowId, const QRect& oldFrame, const QRect& newFrame,
                                 const QString& screenId)
    {
        Q_UNUSED(windowId)
        Q_UNUSED(oldFrame)
        Q_UNUSED(newFrame)
        Q_UNUSED(screenId)
    }
 
    // ═══════════════════════════════════════════════════════════════════════════
    // Cross-engine handoff
    //
    // When a window crosses screens whose owning engines differ (e.g. a snap
    // screen → an autotile screen, via drag drop), ownership has to transfer
    // between two engines. Without an explicit contract, each engine makes
    // local guesses (autotile's "is this a floating window I should adopt?"
    // branch, snap's "do I know this window?" early-return) and the daemon
    // misroutes user intents during the transition window.
    //
    // The handoff is a two-step transaction the daemon orchestrates:
    //   1. fromEngine->handoffRelease(windowId)
    //   2. toEngine->handoffReceive(ctx)
    //
    // Each engine's release is a tracking-only clear (no geometry mutation —
    // the receiving engine places the window). Each engine's receive applies
    // its own placement policy (autotile picks an insert slot or floats;
    // snap picks the nearest zone or floats) using the context fields.
    //
    // Engines that don't currently distinguish ownership across screens can
    // leave both as no-ops; the defaults are safe.
    //
    // The verbs are prefixed `handoff*` to keep them distinct from an engine
    // dropping a window entirely (the window is no longer engine-managed at all
    // — a different concept from "transferring ownership to another engine").
    // ═══════════════════════════════════════════════════════════════════════════
 
    struct HandoffContext
    {
        QString windowId;
        QString fromEngineId; 
        QString toScreenId; 
        int toDesktop = 0; 
        QPoint dropPos; 
        QRect sourceGeometry; 
        QSize minSize; 
        QStringList sourceZoneIds; 
        bool wasFloating = false; 
        bool heldFocus = false; 
        int insertIndex = -1; 
    };
 
    virtual void handoffReceive(const HandoffContext& ctx)
    {
        Q_UNUSED(ctx)
    }
 
    virtual void handoffRelease(const QString& windowId)
    {
        Q_UNUSED(windowId)
    }
 
    virtual QString engineId() const
    {
        return {};
    }
 
    // ═══════════════════════════════════════════════════════════════════════════
    // OPTIONAL: Layout capability (UI-facing; distinct from algorithm identity)
    // ═══════════════════════════════════════════════════════════════════════════
 
    enum class LayoutSupport {
        None,
        Placement,
        Templates
    };
 
    virtual LayoutSupport layoutSupport() const
    {
        return LayoutSupport::None;
    }
 
    virtual bool providesDragInsertSelector() const
    {
        return false;
    }
 
    // ═══════════════════════════════════════════════════════════════════════════
    // OPTIONAL: Algorithm / mode identity (override if engine has switchable algorithms)
    // ═══════════════════════════════════════════════════════════════════════════
 
    virtual QString algorithmId() const
    {
        return {};
    }
    virtual void setAlgorithm(const QString& algorithmId)
    {
        Q_UNUSED(algorithmId)
    }
    virtual bool isEnabled() const noexcept
    {
        return false;
    }
    virtual QString activeScreen() const
    {
        return {};
    }
    virtual void setActiveScreenHint(const QString& screenId)
    {
        Q_UNUSED(screenId)
    }
 
    // ═══════════════════════════════════════════════════════════════════════════
    // OPTIONAL: Desktop/activity context (override if engine is desktop-aware)
    // ═══════════════════════════════════════════════════════════════════════════
 
    virtual void setCurrentDesktop(int desktop)
    {
        Q_UNUSED(desktop)
    }
    virtual void setCurrentDesktopForScreen(const QString& screenId, int desktop)
    {
        Q_UNUSED(screenId)
        Q_UNUSED(desktop)
    }
    virtual void clearCurrentDesktopForScreen(const QString& screenId)
    {
        Q_UNUSED(screenId)
    }
    virtual void setCurrentActivity(const QString& activity)
    {
        Q_UNUSED(activity)
    }
    virtual void setCrossSurfaceResolver(ICrossSurfaceResolver* resolver)
    {
        Q_UNUSED(resolver)
    }
    virtual void updateStickyScreenPins(const std::function<bool(const QString&)>& isWindowSticky)
    {
        Q_UNUSED(isWindowSticky)
    }
    virtual QSet<int> desktopsWithActiveState() const
    {
        return {};
    }
    virtual void pruneStatesForDesktop(int removedDesktop)
    {
        Q_UNUSED(removedDesktop)
    }
    virtual void pruneStatesForActivities(const QStringList& validActivities)
    {
        Q_UNUSED(validActivities)
    }
    virtual void pruneStatesForRemovedScreen(const QString& physicalScreenId)
    {
        Q_UNUSED(physicalScreenId)
    }
 
    // ═══════════════════════════════════════════════════════════════════════════
    // OPTIONAL: Settings synchronization (override if engine caches config)
    // ═══════════════════════════════════════════════════════════════════════════
 
    virtual void refreshConfigFromSettings()
    {
    }
    static constexpr qreal kDefaultSplitRatioStep = 0.05;
    virtual qreal effectiveSplitRatioStep(const QString& screenId) const
    {
        Q_UNUSED(screenId)
        return kDefaultSplitRatioStep;
    }
    virtual int runtimeMaxWindows() const
    {
        return -1;
    }
    virtual std::optional<int> savedMaxWindowsForAlgorithm(const QString& algorithmId) const
    {
        Q_UNUSED(algorithmId)
        return std::nullopt;
    }
 
    // ═══════════════════════════════════════════════════════════════════════════
    // OPTIONAL: Retile / refresh (override if engine supports on-demand retile)
    // ═══════════════════════════════════════════════════════════════════════════
 
    virtual void retile(const QString& screenId = QString())
    {
        Q_UNUSED(screenId)
    }
    virtual void scheduleRetileForScreen(const QString& screenId)
    {
        Q_UNUSED(screenId)
    }
 
    // Per-window restore persistence is unified: engines implement
    // capturePlacement()/restorePlacement() (above) and the common
    // WindowPlacementStore handles capture timing, serialization, and the single
    // WindowPlacements config key. No engine-specific serialize/deserialize hooks.
 
    // ═══════════════════════════════════════════════════════════════════════════
    // OPTIONAL: Init hooks (override to receive shared services)
    // ═══════════════════════════════════════════════════════════════════════════
 
    virtual void setWindowRegistry(QObject* registry)
    {
        Q_UNUSED(registry)
    }
    // ═══════════════════════════════════════════════════════════════════════════
    // OPTIONAL: Master operations (autotile-specific, no-op on snap engine)
    // ═══════════════════════════════════════════════════════════════════════════
 
    virtual void increaseMasterRatio(qreal delta = kDefaultSplitRatioStep)
    {
        Q_UNUSED(delta)
    }
    virtual void decreaseMasterRatio(qreal delta = kDefaultSplitRatioStep)
    {
        Q_UNUSED(delta)
    }
    virtual void increaseMasterCount()
    {
    }
    virtual void decreaseMasterCount()
    {
    }
    virtual void focusMaster()
    {
    }
    virtual void swapFocusedWithMaster()
    {
    }
 
    // ═══════════════════════════════════════════════════════════════════════════
    // Persistence
    // ═══════════════════════════════════════════════════════════════════════════
 
    virtual void saveState() = 0;
    virtual void loadState() = 0;
 
    // ═══════════════════════════════════════════════════════════════════════════
    // State access
    // ═══════════════════════════════════════════════════════════════════════════
 
    virtual IPlacementState* stateForScreen(const QString& screenId) = 0;
    virtual const IPlacementState* stateForScreen(const QString& screenId) const = 0;
};
 
} // namespace PhosphorEngine