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 <QJsonArray>
#include <QJsonObject>
#include <QPoint>
#include <QRect>
#include <QSet>
#include <QString>
#include <QStringList>
#include <QVariantMap>
 
#include <functional>
 
class QObject;
 
namespace PhosphorEngine {
 
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 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)
    }
    virtual bool restoreSavedModeFloat(const QString& windowId)
    {
        Q_UNUSED(windowId)
        return false;
    }
    virtual void clearSavedFloatingForWindows(const QStringList& windowIds)
    {
        Q_UNUSED(windowIds)
    }
 
    // ═══════════════════════════════════════════════════════════════════════════
    // 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 {};
    }
 
    // ═══════════════════════════════════════════════════════════════════════════
    // 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
    // PlacementEngineBase::releaseWindow (which is part of the base FSM
    // lifecycle and means "this 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; 
        QPoint dropPos; 
        QRect sourceGeometry; 
        QStringList sourceZoneIds; 
        bool wasFloating = false; 
    };
 
    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 setCurrentActivity(const QString& activity)
    {
        Q_UNUSED(activity)
    }
    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: Float origin (override if engine persists float state across mode switches)
    // ═══════════════════════════════════════════════════════════════════════════
 
    virtual void markModeSpecificFloated(const QString& windowId)
    {
        Q_UNUSED(windowId)
    }
    virtual void clearAllSavedFloating()
    {
    }
    virtual void saveModeFloat(const QString& windowId)
    {
        Q_UNUSED(windowId)
    }
    virtual void clearSavedModeFloating()
    {
    }
 
    // ═══════════════════════════════════════════════════════════════════════════
    // OPTIONAL: Serialization (override if engine has persistent state)
    // ═══════════════════════════════════════════════════════════════════════════
 
    virtual QJsonArray serializeWindowOrders() const
    {
        return {};
    }
    virtual void deserializeWindowOrders(const QJsonArray& orders)
    {
        Q_UNUSED(orders)
    }
    virtual QJsonObject serializePendingRestores() const
    {
        return {};
    }
    virtual void deserializePendingRestores(const QJsonObject& obj)
    {
        Q_UNUSED(obj)
    }
 
    // ═══════════════════════════════════════════════════════════════════════════
    // OPTIONAL: Init hooks (override to receive shared services)
    // ═══════════════════════════════════════════════════════════════════════════
 
    virtual void setWindowRegistry(QObject* registry)
    {
        Q_UNUSED(registry)
    }
    virtual void setIsWindowFloatingFn(std::function<bool(const QString&)> fn)
    {
        Q_UNUSED(fn)
    }
 
    // ═══════════════════════════════════════════════════════════════════════════
    // 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