IPlacementEngine.h

Go to the documentation of this file.

// SPDX-FileCopyrightText: 2026 fuddlesworth
// SPDX-License-Identifier: LGPL-2.1-or-later
 
#pragma once
 
#include <PhosphorEngine/IPlacementState.h>
#include <PhosphorEngine/NavigationContext.h>
#include <PhosphorEngine/WindowPlacement.h>
 
#include <QJsonArray>
#include <QJsonObject>
#include <QPoint>
#include <QRect>
#include <QSet>
#include <QString>
#include <QStringList>
#include <QVariantMap>
 
#include <functional>
#include <optional>
 
class QObject;
 
namespace PhosphorEngine {
 
class ICrossSurfaceResolver;
 
class PHOSPHORENGINE_EXPORT IPlacementEngine
{
public:
    virtual ~IPlacementEngine() = default;
 
    // ═══════════════════════════════════════════════════════════════════════════
    // 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 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) = 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 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. a future 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 (override if engine maintains stacking order)
    // ═══════════════════════════════════════════════════════════════════════════
 
    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)
    }
 
    // ═══════════════════════════════════════════════════════════════════════════
    // OPTIONAL: Per-screen config (override if engine supports per-screen overrides)
    // ═══════════════════════════════════════════════════════════════════════════
 
    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 tracking (override if engine has mode-aware float)
    // ═══════════════════════════════════════════════════════════════════════════
 
    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)
    // ═══════════════════════════════════════════════════════════════════════════
 
    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 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 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; 
        QStringList sourceZoneIds; 
        bool wasFloating = 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 {};
    }
 
    virtual int computeDragInsertIndexAtPoint(const QString& screenId, const QPoint& cursorPos) const
    {
        Q_UNUSED(screenId)
        Q_UNUSED(cursorPos)
        return -1;
    }
 
    virtual void updateDragInsertPreview(int insertIndex)
    {
        Q_UNUSED(insertIndex)
    }
 
    // ═══════════════════════════════════════════════════════════════════════════
    // 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)
    }
 
    // ═══════════════════════════════════════════════════════════════════════════
    // OPTIONAL: Settings synchronization (override if engine caches config)
    // ═══════════════════════════════════════════════════════════════════════════
 
    virtual void refreshConfigFromSettings()
    {
    }
    virtual qreal effectiveSplitRatioStep(const QString& screenId) const
    {
        Q_UNUSED(screenId)
        return 0.05;
    }
    virtual int runtimeMaxWindows() const
    {
        return -1;
    }
 
    // ═══════════════════════════════════════════════════════════════════════════
    // 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)
    }
 
    // ═══════════════════════════════════════════════════════════════════════════
    // 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.
    // ═══════════════════════════════════════════════════════════════════════════
 
    virtual void markModeSpecificFloated(const QString& windowId)
    {
        Q_UNUSED(windowId)
    }
 
    // Per-window restore persistence is unified: engines implement
    // capturePlacement()/restorePlacement() (below) 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 = 0.05)
    {
        Q_UNUSED(delta)
    }
    virtual void decreaseMasterRatio(qreal delta = 0.05)
    {
        Q_UNUSED(delta)
    }
    virtual void increaseMasterCount()
    {
    }
    virtual void decreaseMasterCount()
    {
    }
    virtual void focusMaster()
    {
    }
    virtual void swapFocusedWithMaster()
    {
    }
 
    // ═══════════════════════════════════════════════════════════════════════════
    // Engine state serialization
    // ═══════════════════════════════════════════════════════════════════════════
 
    virtual QJsonObject serializeEngineState() const
    {
        return {};
    }
    virtual void deserializeEngineState(const QJsonObject& state)
    {
        Q_UNUSED(state)
    }
 
    // ═══════════════════════════════════════════════════════════════════════════
    // 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