SnapEngine.h

Go to the documentation of this file.

// SPDX-FileCopyrightText: 2026 fuddlesworth
// SPDX-License-Identifier: LGPL-2.1-or-later
 
#pragma once
 
#include <phosphorsnapengine_export.h>
#include <PhosphorEngine/EngineTypes.h>
#include <PhosphorEngine/IVirtualDesktopManager.h>
#include <PhosphorSnapEngine/ISnapSettings.h>
#include <PhosphorEngine/IWindowTrackingService.h>
#include <PhosphorEngine/PlacementEngineBase.h>
#include <PhosphorLayoutApi/EdgeGaps.h>
#include <PhosphorSnapEngine/PlacementDirective.h>
#include <PhosphorProtocol/NavigationTypes.h>
#include <PhosphorProtocol/WindowTypes.h>
#include <PhosphorWindowRules/RuleEvaluator.h>
#include <QObject>
#include <QPointer>
#include <QRect>
#include <QString>
#include <QStringList>
#include <functional>
#include <optional>
#include <memory>
 
namespace PhosphorZones {
class IZoneDetector;
class LayoutRegistry;
class Layout;
}
 
// PhosphorWindowRules::RuleEvaluator is included as a member type of
// std::optional below (needs a complete type at declaration); WindowRuleSet
// is referenced only by pointer / reference, so a forward declaration would
// suffice — but including RuleEvaluator.h pulls in WindowRuleSet.h
// transitively anyway, so leave the explicit forward decls out and let
// RuleEvaluator.h provide both.
 
namespace PhosphorSnapEngine {
 
class INavigationStateProvider;
class IZoneAdjacencyResolver;
class SnapNavigationTargetResolver;
class SnapState;
 
class PHOSPHORSNAPENGINE_EXPORT SnapEngine : public PhosphorEngine::PlacementEngineBase
{
    Q_OBJECT
 
public:
    explicit SnapEngine(PhosphorZones::LayoutRegistry* layoutManager,
                        PhosphorEngine::IWindowTrackingService* windowTracker,
                        PhosphorZones::IZoneDetector* zoneDetector, PhosphorEngine::IVirtualDesktopManager* vdm,
                        QObject* parent = nullptr);
    ~SnapEngine() override;
 
    int currentVirtualDesktop() const;
    int currentVirtualDesktopForScreen(const QString& screenId) const;
    QString currentActivity() const;
 
    std::pair<QString, QRect> resolveCrossDesktopZone(const QString& currentZoneId, const QString& screenId,
                                                      int targetDesktop) const;
 
    QString entryZoneForCrossing(const QString& direction, const QString& neighbourScreen) const;
 
    QString windowInZoneOnScreen(const QString& zoneId, const QString& screenId) const;
 
    // ═══════════════════════════════════════════════════════════════════════════
    // IPlacementEngine — lifecycle
    // ═══════════════════════════════════════════════════════════════════════════
 
    bool isActiveOnScreen(const QString& screenId) const override;
    bool isEnabled() const noexcept override;
    using IPlacementEngine::windowOpened;
    void windowOpened(const QString& windowId, const QString& screenId, int minWidth, int minHeight) override;
 
    using ShouldRestorePredicate = std::function<bool(const QString& screenId)>;
 
    void setShouldRestorePredicate(ShouldRestorePredicate predicate)
    {
        m_shouldRestorePredicate = std::move(predicate);
    }
 
    using RestorePositionPredicate = std::function<bool(const QString& windowId)>;
 
    void setRestorePositionPredicate(RestorePositionPredicate predicate)
    {
        m_restorePositionPredicate = std::move(predicate);
    }
 
    using ManagedRestorePredicate = std::function<bool(const QString& windowId)>;
 
    void setManagedRestorePredicate(ManagedRestorePredicate predicate)
    {
        m_managedRestorePredicate = std::move(predicate);
    }
 
    using FloatPredicate = std::function<bool(const QString& windowId)>;
 
    void setFloatPredicate(FloatPredicate predicate)
    {
        m_floatPredicate = std::move(predicate);
    }
 
    using PlacementZonesResolver = std::function<PlacementDirective(const QString& windowId, const QString& screenId)>;
 
    void setPlacementZonesResolver(PlacementZonesResolver resolver)
    {
        m_placementZonesResolver = std::move(resolver);
    }
 
    void windowClosed(const QString& windowId) override;
    void windowFocused(const QString& windowId, const QString& screenId) override;
    void toggleWindowFloat(const QString& windowId, const QString& screenId) override;
    void setWindowFloat(const QString& windowId, bool shouldFloat) override;
    void saveState() override;
    void loadState() override;
 
    // Cross-engine handoff
    QString engineId() const override
    {
        return QStringLiteral("snap");
    }
    void handoffReceive(const HandoffContext& ctx) override;
    void handoffRelease(const QString& windowId) override;
    QString screenForTrackedWindow(const QString& windowId) const override;
    bool isWindowTracked(const QString& windowId) const override;
 
    void resnapToNewLayout();
 
    void resnapCurrentAssignments(const QString& screenFilter = QString());
 
    void resnapFromAutotileOrder(const QStringList& autotileWindowOrder, const QString& screenId);
 
    QVector<PhosphorEngine::ZoneAssignmentEntry>
    calculateResnapEntriesFromAutotileOrder(const QStringList& autotileWindowOrder, const QString& screenId,
                                            const QStringList& preClaimedZoneIds = {});
 
    PhosphorProtocol::SnapAllResultList calculateSnapAllWindows(const QStringList& windowIds, const QString& screenId);
 
    void emitBatchedResnap(const QVector<PhosphorEngine::ZoneAssignmentEntry>& entries);
 
    void snapAllWindows(const QString& screenId);
 
    // ═══════════════════════════════════════════════════════════════════════════
    // Window restore (auto-snap on window open)
    // ═══════════════════════════════════════════════════════════════════════════
 
    PhosphorEngine::SnapResult
    resolveWindowRestore(const QString& windowId, const QString& screenId, bool sticky,
                         PhosphorEngine::WindowKind kind = PhosphorEngine::WindowKind::Unknown);
 
    // ═══════════════════════════════════════════════════════════════════════════
    // Autotile engine reference (for isActiveOnScreen routing)
    // ═══════════════════════════════════════════════════════════════════════════
 
    void setAutotileEngine(PhosphorEngine::IPlacementEngine* engine);
 
    SnapState* snapState() const
    {
        return m_snapState;
    }
 
    // ═══════════════════════════════════════════════════════════════════════════
    // Zone adjacency resolver (for daemon-driven navigation)
    // ═══════════════════════════════════════════════════════════════════════════
 
    void setZoneAdjacencyResolver(IZoneAdjacencyResolver* resolver);
 
    void setCrossSurfaceResolver(PhosphorEngine::ICrossSurfaceResolver* resolver) override;
 
    // ═══════════════════════════════════════════════════════════════════════════
    // Navigation state provider
    // ═══════════════════════════════════════════════════════════════════════════
 
    void setNavigationStateProvider(INavigationStateProvider* provider);
 
    // ═══════════════════════════════════════════════════════════════════════════
    // Navigation (moved out of WindowTrackingAdaptor)
    //
    // Every method takes a PhosphorEngine::NavigationContext populated by the daemon's
    // shortcut handler. The engine uses ctx.windowId directly rather than
    // re-reading it from the WTA shadow, which is a step toward retiring
    // the SnapEngine -> WTA back-reference entirely. When ctx.windowId is
    // empty, the engine may consult m_navState->lastActiveWindowId() as a
    // best-effort fallback -- but in the normal path the daemon always
    // provides a resolved target.
    // ═══════════════════════════════════════════════════════════════════════════
 
    // ═══════════════════════════════════════════════════════════════════════════
    // IPlacementEngine — navigation overrides
    // ═══════════════════════════════════════════════════════════════════════════
 
    void focusInDirection(const QString& direction, const PhosphorEngine::NavigationContext& ctx) override;
 
    void moveFocusedInDirection(const QString& direction, const PhosphorEngine::NavigationContext& ctx) override;
 
    void swapFocusedInDirection(const QString& direction, const PhosphorEngine::NavigationContext& ctx) override;
 
    void moveFocusedToPosition(int zoneNumber, const PhosphorEngine::NavigationContext& ctx) override;
 
    void rotateWindows(bool clockwise, const PhosphorEngine::NavigationContext& ctx) override;
 
    void reapplyLayout(const PhosphorEngine::NavigationContext& ctx) override;
 
    void reapplyManagedWindowAppearance() override;
 
    std::optional<PhosphorEngine::WindowPlacement> capturePlacement(const QString& windowId) const override;
 
    void snapAllWindows(const PhosphorEngine::NavigationContext& ctx) override;
 
    void pushToEmptyZone(const PhosphorEngine::NavigationContext& ctx) override;
 
    void restoreFocusedWindow(const PhosphorEngine::NavigationContext& ctx) override;
 
    void toggleFocusedFloat(const PhosphorEngine::NavigationContext& ctx) override;
 
    void cycleFocus(bool forward, const PhosphorEngine::NavigationContext& ctx) override;
 
    // ═══════════════════════════════════════════════════════════════════════════
    // Snap commit orchestration
    //
    // Full snap lifecycle: clear floating, assign to zone, update tracking,
    // emit state-changed signals. Owns the orchestration that was previously
    // on WindowTrackingService.
    // ═══════════════════════════════════════════════════════════════════════════
 
    void commitSnap(const QString& windowId, const QString& zoneId, const QString& screenId,
                    PhosphorEngine::SnapIntent intent = PhosphorEngine::SnapIntent::UserInitiated,
                    int virtualDesktop = 0);
 
    void commitMultiZoneSnap(const QString& windowId, const QStringList& zoneIds, const QString& screenId,
                             PhosphorEngine::SnapIntent intent = PhosphorEngine::SnapIntent::UserInitiated,
                             int virtualDesktop = 0);
 
    void uncommitSnap(const QString& windowId);
 
    PhosphorEngine::UnfloatResult resolveUnfloatGeometry(const QString& windowId, const QString& fallbackScreen) const;
 
    PhosphorEngine::UnfloatResult resolveFallbackUnfloatGeometry(const QString& windowId,
                                                                 const QString& fallbackScreen) const;
 
    PhosphorProtocol::WindowGeometryList
    applyBatchAssignments(const QVector<PhosphorEngine::ZoneAssignmentEntry>& entries,
                          PhosphorEngine::SnapIntent intent = PhosphorEngine::SnapIntent::UserInitiated,
                          std::function<QString()> fallbackScreenResolver = {});
 
    // ═══════════════════════════════════════════════════════════════════════════
    // Auto-snap calculations (moved from WTS)
    // ═══════════════════════════════════════════════════════════════════════════
 
    PhosphorEngine::SnapResult calculateSnapToPlacementRule(const QString& windowId, const QString& windowScreenName,
                                                            bool isSticky) const;
    PhosphorEngine::SnapResult calculateSnapToLastZone(const QString& windowId, const QString& windowScreenId,
                                                       bool isSticky) const;
    PhosphorEngine::SnapResult calculateSnapToEmptyZone(const QString& windowId, const QString& windowScreenId,
                                                        bool isSticky) const;
 
    // ═══════════════════════════════════════════════════════════════════════════
    // Resnap / rotation calculations (moved from WTS)
    // ═══════════════════════════════════════════════════════════════════════════
 
    QVector<PhosphorEngine::ZoneAssignmentEntry> calculateResnapFromPreviousLayout();
    QVector<PhosphorEngine::ZoneAssignmentEntry>
    calculateResnapFromCurrentAssignments(const QString& screenFilter = QString()) const;
    QVector<PhosphorEngine::ZoneAssignmentEntry>
    calculateResnapFromAutotileOrder(const QStringList& autotileWindowOrder, const QString& screenId,
                                     const QStringList& preClaimedZoneIds = {}) const;
    QVector<PhosphorEngine::ZoneAssignmentEntry> calculateSnapAllWindowEntries(const QStringList& windowIds,
                                                                               const QString& screenId) const;
    QVector<PhosphorEngine::ZoneAssignmentEntry> calculateRotation(bool clockwise,
                                                                   const QString& screenFilter = QString()) const;
 
    // ═══════════════════════════════════════════════════════════════════════════
    // Effect-reported windows (runtime flag — not persisted)
    // ═══════════════════════════════════════════════════════════════════════════
 
    void markWindowReported(const QString& windowId);
    const QSet<QString>& effectReportedWindows() const
    {
        return m_effectReportedWindows;
    }
 
    int pruneStaleWindows(const QSet<QString>& aliveWindowIds) override;
 
    // ═══════════════════════════════════════════════════════════════════════════
    // IPlacementEngine — state access
    //
    // Returns the single SnapState wired by Daemon::init(). Currently a
    // global state (not per-screen); a future PR will introduce per-screen
    // ownership. Returns nullptr in headless unit tests that don't wire a
    // SnapState.
    // ═══════════════════════════════════════════════════════════════════════════
 
    PhosphorEngine::IPlacementState* stateForScreen(const QString& screenId) override;
    const PhosphorEngine::IPlacementState* stateForScreen(const QString& screenId) const override;
 
    // ═══════════════════════════════════════════════════════════════════════════
    // Internal navigation helpers (concrete SnapEngine methods that the
    // IPlacementEngine overrides delegate to)
    // ═══════════════════════════════════════════════════════════════════════════
 
    void pushFocusedToEmptyZone(const PhosphorEngine::NavigationContext& ctx);
 
    void rotateWindowsInLayout(bool clockwise, const QString& screenId);
 
    // ═══════════════════════════════════════════════════════════════════════════
    // Persistence delegate
    // ═══════════════════════════════════════════════════════════════════════════
 
    void setPersistenceDelegate(std::function<void()> saveFn, std::function<void()> loadFn)
    {
        m_saveFn = std::move(saveFn);
        m_loadFn = std::move(loadFn);
    }
 
    QString lastActiveScreenId() const
    {
        return m_lastActiveScreenId;
    }
 
    void setExcludeRuleSet(const PhosphorWindowRules::WindowRuleSet* ruleSet);
 
    using ExclusionQueryProvider =
        std::function<std::optional<PhosphorWindowRules::WindowQuery>(const QString& windowId)>;
 
    void setExclusionQueryProvider(ExclusionQueryProvider provider)
    {
        m_exclusionQueryProvider = std::move(provider);
    }
 
    bool isAppIdExcluded(const QString& appId) const;
 
    bool isWindowExcluded(const QString& windowId) const;
 
Q_SIGNALS:
    // ═══════════════════════════════════════════════════════════════════════════
    // Signals (relayed via SnapAdaptor -> WTA -> D-Bus -> effect)
    // ═══════════════════════════════════════════════════════════════════════════
 
    void windowSnapStateChanged(const QString& windowId, const PhosphorProtocol::WindowStateEntry& entry);
 
    void windowFloatingClearedForSnap(const QString& windowId, const QString& screenId);
 
    void applyGeometryRequested(const QString& windowId, int x, int y, int width, int height, const QString& zoneId,
                                const QString& screenId, bool sizeOnly);
 
    void resnapToNewLayoutRequested(const QString& resnapData);
 
    void snapAllWindowsRequested(const QString& screenId);
 
    void applyGeometriesBatch(const PhosphorProtocol::WindowGeometryList& geometries, const QString& action);
 
private:
    PhosphorEngine::ISnapSettings* snapSettings() const;
 
    struct GapParams
    {
        int zonePadding;
        ::PhosphorLayout::EdgeGaps outerGaps;
    };
    // Resolve zone padding + outer gaps for @p screenId, honoring the same
    // precedence the main geometry pipeline uses (minus the context-rule tier,
    // which the engine has no registry for): per-screen snapping override (with
    // virtual->physical fallback) -> @p layout override -> global. An empty
    // screenId skips the per-screen tier; a null layout skips the layout tier.
    GapParams resolveGapParams(const QString& screenId, PhosphorZones::Layout* layout) const;
 
    void commitSnapImpl(const QString& windowId, const QStringList& zoneIds, const QString& screenId,
                        PhosphorEngine::SnapIntent intent, int virtualDesktop = 0);
 
    QString resolveUnfloatScreen(const QString& primaryScreen, const QString& fallbackScreen) const;
 
    PhosphorZones::LayoutRegistry* m_layoutManager = nullptr;
    PhosphorEngine::IWindowTrackingService* m_windowTracker = nullptr;
    SnapState* m_snapState = nullptr;
    PhosphorZones::IZoneDetector* m_zoneDetector = nullptr;
    PhosphorEngine::IVirtualDesktopManager* m_virtualDesktopManager = nullptr;
    QPointer<QObject> m_autotileEngineObj;
    PhosphorEngine::IPlacementEngine* m_autotileEngineTyped = nullptr;
    IZoneAdjacencyResolver* m_zoneAdjacencyResolver = nullptr;
    PhosphorEngine::ICrossSurfaceResolver* m_crossSurfaceResolver = nullptr;
    // Typed navigation-state provider — replaces the opaque QObject* m_wta
    // back-reference. Provides read-only access to compositor-layer shadows
    // (last-active window, last-active screen, last-cursor screen, frame
    // geometry). Not owned; must outlive SnapEngine.
    INavigationStateProvider* m_navState = nullptr;
    // Snap-mode navigation target resolver. Owned by SnapEngine — moved
    // here in Phase 5E from WindowTrackingAdaptor. Constructed lazily on
    // first navigation call (so the construction order isn't constrained
    // by the fact that SnapEngine has to exist before a resolver that
    // takes WTS + PhosphorZones::LayoutRegistry can be built).
    std::unique_ptr<SnapNavigationTargetResolver> m_targetResolver;
    QSet<QString> m_effectReportedWindows;
 
    // ═══════════════════════════════════════════════════════════════════════════
    // Float helpers (snapengine/float.cpp)
    //
    // The historical clearFloatingStateForSnap / assignToZones pair was
    // removed — all snap commits now route through commitSnapImpl.
    // ═══════════════════════════════════════════════════════════════════════════
 
    bool unfloatToZone(const QString& windowId, const QString& screenId);
    bool applyGeometryForFloat(const QString& windowId, const QString& screenId);
 
    SnapNavigationTargetResolver* ensureTargetResolver(const QString& action = QString());
 
    bool tryCrossDesktopMove(const QString& windowId, const QString& direction, const QString& screenId);
 
    bool tryCrossModeOutput(const QString& windowId, const QString& direction, const QString& screenId, bool swap);
 
    bool tryCrossDesktopFocus(const QString& focusedWindowId, const QString& direction, const QString& screenId);
 
    bool isWindowExcludedForAction(const QString& windowId, const QString& action, const QString& screenId);
 
    // `isAppIdExcluded` and `isWindowExcluded` are declared in the public
    // section above (so the unit tests can drive the wiring directly); full
    // docstrings live with those declarations.
 
    bool evaluateExcludeRules(const PhosphorWindowRules::WindowQuery& query) const;
 
    const PhosphorWindowRules::WindowRuleSet* m_excludeRuleSet = nullptr;
    mutable std::optional<PhosphorWindowRules::RuleEvaluator> m_excludeEvaluator;
 
    ExclusionQueryProvider m_exclusionQueryProvider{};
 
    // Persistence delegates (KConfig stays in adaptor layer)
    std::function<void()> m_saveFn;
    std::function<void()> m_loadFn;
 
    // Last-focused screen (updated by windowFocused)
    QString m_lastActiveScreenId;
 
    // Auto-snap entry gate. Empty until the daemon wires it; while empty
    // the engine treats every screen as active — preserving the
    // historical default that unit tests rely on. (The predicate's
    // signature is `bool(const QString& screenId)` — the desktop and
    // activity dimensions are resolved by the daemon-side closure at
    // call time, not passed in here; see ShouldRestorePredicate doc
    // above and discussion #461 item 7.)
    ShouldRestorePredicate m_shouldRestorePredicate{};
 
    // Unsnapped-position-restore gate. Empty until the daemon wires it; while
    // empty the engine marks floated windows floating but restores their position
    // only on the reopening screen — the historical behaviour unit tests rely on.
    // See RestorePositionPredicate doc above.
    RestorePositionPredicate m_restorePositionPredicate{};
 
    // Managed (snapped-to-zone) restore gate. Empty until the daemon wires it;
    // while empty the engine restores snapped records unconditionally — the
    // historical behaviour unit tests rely on. See ManagedRestorePredicate.
    ManagedRestorePredicate m_managedRestorePredicate{};
 
    // Rule-driven open-floating gate. Empty until the daemon wires it; while
    // empty no window is rule-floated. See FloatPredicate doc above.
    FloatPredicate m_floatPredicate{};
 
    // Rule-driven open-placement resolver (SnapToZone). Empty until the daemon
    // wires it; while empty no window is rule-snapped. See PlacementZonesResolver
    // doc above.
    PlacementZonesResolver m_placementZonesResolver{};
};
 
} // namespace PhosphorSnapEngine