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 <PhosphorProtocol/NavigationTypes.h>
#include <PhosphorProtocol/WindowTypes.h>
#include <QObject>
#include <QPointer>
#include <QRect>
#include <QString>
#include <QStringList>
#include <functional>
#include <memory>
 
namespace PhosphorZones {
class IZoneDetector;
class LayoutRegistry;
}
 
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;
    QString currentActivity() 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);
    }
 
    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);
 
    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);
 
    // ═══════════════════════════════════════════════════════════════════════════
    // 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 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);
 
    void commitMultiZoneSnap(const QString& windowId, const QStringList& zoneIds, const QString& screenId,
                             PhosphorEngine::SnapIntent intent = PhosphorEngine::SnapIntent::UserInitiated);
 
    void uncommitSnap(const QString& windowId);
 
    PhosphorEngine::UnfloatResult resolveUnfloatGeometry(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 calculateSnapToAppRule(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;
    PhosphorEngine::SnapResult
    calculateRestoreFromSession(const QString& windowId, const QString& screenId, bool isSticky,
                                PhosphorEngine::WindowKind kind = PhosphorEngine::WindowKind::Unknown) 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;
    QVector<PhosphorEngine::ZoneAssignmentEntry> calculateSnapAllWindowEntries(const QStringList& windowIds,
                                                                               const QString& screenId) const;
    QVector<PhosphorEngine::ZoneAssignmentEntry> calculateRotation(bool clockwise,
                                                                   const QString& screenFilter = QString()) const;
 
    // ═══════════════════════════════════════════════════════════════════════════
    // Saved snap-floating windows (mode-transition bookkeeping)
    // ═══════════════════════════════════════════════════════════════════════════
 
    void saveSnapFloating(const QString& windowId);
    bool restoreSnapFloating(const QString& windowId);
    void clearSavedSnapFloating();
 
    // IPlacementEngine — generic mode-float overrides
    bool restoreSavedModeFloat(const QString& windowId) override
    {
        return restoreSnapFloating(windowId);
    }
    void clearSavedFloatingForWindows(const QStringList& windowIds) override
    {
        for (const QString& windowId : windowIds) {
            m_savedSnapFloatingWindows.remove(windowId);
        }
    }
    void saveModeFloat(const QString& windowId) override
    {
        saveSnapFloating(windowId);
    }
    void clearSavedModeFloating() override
    {
        clearSavedSnapFloating();
    }
 
    // ═══════════════════════════════════════════════════════════════════════════
    // 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;
    }
 
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);
 
protected:
    void onWindowClaimed(const QString& windowId) override;
    void onWindowReleased(const QString& windowId) override;
    void onWindowFloated(const QString& windowId) override;
    void onWindowUnfloated(const QString& windowId) override;
 
private:
    PhosphorEngine::ISnapSettings* snapSettings() const;
 
    struct GapParams
    {
        int zonePadding;
        ::PhosphorLayout::EdgeGaps outerGaps;
    };
    GapParams resolveGapParams() const;
 
    void commitSnapImpl(const QString& windowId, const QStringList& zoneIds, const QString& screenId,
                        PhosphorEngine::SnapIntent intent);
 
    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;
    // 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_savedSnapFloatingWindows;
    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 isWindowExcludedForAction(const QString& windowId, const QString& action, const QString& screenId);
 
    // 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, desktop) as active — preserving the
    // historical default that unit tests rely on. See ShouldRestorePredicate
    // doc above and discussion #461 item 7.
    ShouldRestorePredicate m_shouldRestorePredicate{};
};
 
} // namespace PhosphorSnapEngine