LayoutRegistry.h

Go to the documentation of this file.

// SPDX-FileCopyrightText: 2026 fuddlesworth
// SPDX-License-Identifier: LGPL-2.1-or-later
 
// FILE-SIZE EXCEPTION (sanctioned): LayoutRegistry is the single owner of
// layout storage, per-context assignments, quick slots, and the context
// resolve cascade, and this is an INSTALLED public header — carving the
// class in two would be an API break for third-party consumers the library
// exists to serve. The implementation is already split by concern across
// src/layoutregistry_*.cpp, and the member ordering here encodes which
// state each of those files owns.
 
#pragma once
 
#include <PhosphorZones/AssignmentEntry.h>
#include <PhosphorZones/ContextResolveKey.h>
#include <PhosphorZones/IZoneLayoutRegistry.h>
#include <PhosphorZones/Layout.h>
#include <PhosphorZones/LayoutSettingsStore.h>
 
#include <PhosphorRules/RuleEvaluator.h>
#include <PhosphorRules/RuleStore.h>
 
#include <QHash>
#include <QPair>
#include <QString>
#include <QUuid>
#include <functional>
#include <memory>
#include <optional>
 
namespace PhosphorZones {
 
class ScrollingTemplateStore;
 
struct CombinedAssignmentKey
{
    QString screenId;
    int virtualDesktop = 0;
    QString activity;
 
    bool operator==(const CombinedAssignmentKey& other) const
    {
        return screenId == other.screenId && virtualDesktop == other.virtualDesktop && activity == other.activity;
    }
};
 
inline size_t qHash(const CombinedAssignmentKey& key, size_t seed = 0) noexcept
{
    return qHashMulti(seed, key.screenId, key.virtualDesktop, key.activity);
}
 
class PHOSPHORZONES_EXPORT LayoutRegistry : public IZoneLayoutRegistry
{
    Q_OBJECT
 
    Q_PROPERTY(int layoutCount READ layoutCount NOTIFY layoutsChanged)
    // `activeLayout` Q_PROPERTY moved to IZoneLayoutRegistry alongside its
    // NOTIFY signal so the contract is visible to interface consumers.
    Q_PROPERTY(QString layoutDirectory READ layoutDirectory WRITE setLayoutDirectory NOTIFY layoutDirectoryChanged)
 
public:
    LayoutRegistry(PhosphorRules::RuleStore* ruleStore, QString layoutSubdirectory, QObject* parent = nullptr);
    ~LayoutRegistry() override;
 
    // ─── IZoneLayoutRegistry ──────────────────────────────────────────────
 
    int layoutCount() const override
    {
        return m_layouts.size();
    }
    QVector<Layout*> layouts() const override
    {
        return m_layouts;
    }
    Layout* layout(int index) const override;
    Layout* layoutById(const QUuid& id) const override;
    Layout* layoutByName(const QString& name) const override;
 
    Q_INVOKABLE void addLayout(Layout* layout) override;
    Q_INVOKABLE bool removeLayout(Layout* layout) override;
    Q_INVOKABLE bool removeLayoutById(const QUuid& id) override;
    Q_INVOKABLE Layout* duplicateLayout(Layout* source) override;
 
    static QString duplicateNameSuffix()
    {
        return QStringLiteral(" (Copy)");
    }
 
    Layout* activeLayout() const override
    {
        return m_activeLayout;
    }
    Q_INVOKABLE void setActiveLayout(Layout* layout) override;
    Q_INVOKABLE void setActiveLayoutById(const QUuid& id) override;
 
    // ─── Layout persistence (disk JSON) ───────────────────────────────────
 
    QString layoutDirectory() const
    {
        return m_layoutDirectory;
    }
    void setLayoutDirectory(const QString& directory);
 
    Q_INVOKABLE void loadLayouts();
    Q_INVOKABLE void saveLayouts();
    void saveLayout(Layout* layout);
 
    Q_INVOKABLE Layout* importLayout(const QString& filePath);
 
    static bool isLayoutJsonValid(const QJsonObject& json, const QString& context);
 
    Q_INVOKABLE bool exportLayout(Layout* layout, const QString& filePath);
 
    // ─── Assignment persistence (via config backend) ──────────────────────
 
    Q_INVOKABLE void loadAssignments();
    Q_INVOKABLE void saveAssignments();
 
    // ─── Default-layout resolution ────────────────────────────────────────
 
    Q_INVOKABLE Layout* defaultLayout() const override;
 
    void setDefaultLayoutIdProvider(std::function<QString()> provider);
 
    void setDefaultAutotileAlgorithmProvider(std::function<QString()> provider);
 
    void setTiledWindowCountProvider(
        std::function<std::optional<int>(const QString& screenId, int virtualDesktop, const QString& activity)>
            provider);
 
    void setScreenOrientationProvider(std::function<std::optional<QString>(const QString& screenId)> provider);
 
    void setColorSchemeProvider(std::function<std::optional<QString>()> provider);
 
    void setSnappingPreferredProvider(std::function<bool()> provider);
 
    void setDefaultAssignmentSuppressedProvider(std::function<bool()> provider);
 
    bool snappingPreferred() const;
 
    // ─── Assignments (per-context routing) ────────────────────────────────
 
    Layout* previousLayout() const
    {
        return m_previousLayout;
    }
 
    Q_INVOKABLE void assignLayout(const QString& screenId, int virtualDesktop, const QString& activity, Layout* layout);
    Q_INVOKABLE void assignLayoutById(const QString& screenId, int virtualDesktop, const QString& activity,
                                      const QString& layoutId);
 
    void setAssignmentEntryDirect(const QString& screenId, int virtualDesktop, const QString& activity,
                                  const AssignmentEntry& entry);
 
    void assignScrollingTemplate(const QString& screenId, int virtualDesktop, const QString& activity,
                                 const QString& templateId);
    ScrollingTemplate scrollingTemplateForContext(const QString& screenId, int virtualDesktop,
                                                  const QString& activity) const override;
 
    void setScrollingTemplateStore(ScrollingTemplateStore* store)
    {
        m_scrollingTemplateStore = store;
    }
    ScrollingTemplateStore* scrollingTemplateStore() const override
    {
        return m_scrollingTemplateStore;
    }
 
    void setDefaultScrollingTemplateProvider(std::function<QString()> provider)
    {
        m_defaultScrollingTemplateProvider = std::move(provider);
    }
 
    QString rulesVisibleActiveLayoutId(const QString& screenId, int virtualDesktop, const QString& activity) const;
 
    Q_INVOKABLE Layout* layoutForScreen(const QString& screenId, int virtualDesktop = 0,
                                        const QString& activity = QString()) const override;
 
    Q_INVOKABLE Layout* resolveLayoutForScreen(const QString& screenId) const override
    {
        // Resolve against THIS screen's current virtual desktop (Plasma 6.7
        // per-output virtual desktops, #648). Falls back to the global desktop
        // when the screen has no per-output value, so every caller (all of which
        // already pass a screenId) gets per-screen resolution with no edits.
        return layoutForScreen(screenId, currentVirtualDesktopForScreen(screenId), m_currentActivity);
    }
 
    ContextGapOverride resolveContextGaps(const QString& screenId, int virtualDesktop, const QString& activity,
                                          const QString& mode = QString()) const override;
 
    bool resolveContextLocked(const QString& screenId, int virtualDesktop, const QString& activity) const override;
 
    std::optional<bool> resolveContextDefaultAssignment(const QString& screenId, int virtualDesktop,
                                                        const QString& activity) const;
 
    std::optional<bool> resolveContextOsdEnabled(const QString& screenId, int virtualDesktop,
                                                 const QString& activity) const;
 
    std::optional<bool> resolveContextDragSelectorEnabled(const QString& screenId, int virtualDesktop,
                                                          const QString& activity) const override;
 
    ContextOverlayOverride resolveContextOverlay(const QString& screenId, int virtualDesktop,
                                                 const QString& activity) const override;
 
    ContextTilingParams resolveContextTilingParams(const QString& screenId, int virtualDesktop,
                                                   const QString& activity) const;
 
    ContextScrollingParams resolveContextScrollingParams(const QString& screenId, int virtualDesktop,
                                                         const QString& activity) const;
 
    QString screenOrientationToken(const QString& screenId) const
    {
        if (m_screenOrientationProvider) {
            if (const auto token = m_screenOrientationProvider(screenId)) {
                return *token;
            }
        }
        return QString();
    }
 
    void stampScreenOrientation(PhosphorRules::WindowQuery& query, const QString& screenId) const
    {
        query.screenOrientation = screenOrientationToken(screenId);
    }
 
    QString colorSchemeToken() const
    {
        if (m_colorSchemeProvider) {
            if (const auto token = m_colorSchemeProvider()) {
                return *token;
            }
        }
        return QString();
    }
 
    void stampColorScheme(PhosphorRules::WindowQuery& query) const
    {
        query.colorScheme = colorSchemeToken();
    }
 
    static QString contextCacheKeyToken(const QString& modeToken, const QString& activeLayoutId,
                                        const QString& orientationToken, const QString& colorSchemeToken)
    {
        return escapeKeyComponent(modeToken) + QLatin1String("|al:") + escapeKeyComponent(activeLayoutId)
            + QLatin1String("|or:") + escapeKeyComponent(orientationToken) + QLatin1String("|cs:")
            + escapeKeyComponent(colorSchemeToken);
    }
 
    static QString assignmentCacheKeyToken(const std::optional<int>& tiledCount, const QString& orientationToken,
                                           const QString& colorSchemeToken)
    {
        return (tiledCount ? (QLatin1String("twc:") + QString::number(*tiledCount)) : QString()) + QLatin1String("|or:")
            + escapeKeyComponent(orientationToken) + QLatin1String("|cs:") + escapeKeyComponent(colorSchemeToken);
    }
 
    static QString escapeKeyComponent(const QString& component)
    {
        QString escaped = component;
        escaped.replace(QLatin1Char('%'), QLatin1String("%25"));
        escaped.replace(QLatin1Char('|'), QLatin1String("%7C"));
        return escaped;
    }
 
    Q_INVOKABLE void clearAssignment(const QString& screenId, int virtualDesktop = 0,
                                     const QString& activity = QString());
    Q_INVOKABLE bool hasExplicitAssignment(const QString& screenId, int virtualDesktop = 0,
                                           const QString& activity = QString()) const;
 
    AssignmentEntry exactContextEntry(const QString& screenId, int virtualDesktop, const QString& activity) const;
 
    bool exactContextDeclaresEngineMode(const QString& screenId, int virtualDesktop, const QString& activity) const;
 
    Q_INVOKABLE QString assignmentIdForScreen(const QString& screenId, int virtualDesktop = 0,
                                              const QString& activity = QString()) const override;
 
    Q_INVOKABLE QString storedAssignmentIdForScreen(const QString& screenId, int virtualDesktop = 0,
                                                    const QString& activity = QString()) const;
 
    AssignmentEntry assignmentEntryForScreen(const QString& screenId, int virtualDesktop = 0,
                                             const QString& activity = QString()) const;
 
    AssignmentEntry::Mode modeForScreen(const QString& screenId, int virtualDesktop = 0,
                                        const QString& activity = QString()) const;
 
    bool isContextActiveLayoutSuppressed(const QString& screenId, int virtualDesktop = 0,
                                         const QString& activity = QString()) const override;
 
    bool isDefaultAssignmentSuppressedForContext(const QString& screenId, int virtualDesktop = 0,
                                                 const QString& activity = QString()) const;
 
    QString snappingLayoutForScreen(const QString& screenId, int virtualDesktop = 0,
                                    const QString& activity = QString()) const;
    QString tilingAlgorithmForScreen(const QString& screenId, int virtualDesktop = 0,
                                     const QString& activity = QString()) const override;
    QString scrollingTemplateLayoutForScreen(const QString& screenId, int virtualDesktop = 0,
                                             const QString& activity = QString()) const;
    bool scrollingTemplateExplicitlyNone(const QString& screenId, int virtualDesktop,
                                         const QString& activity) const override;
 
    void clearAutotileAssignments();
 
    int restoreAutotileAssignments();
 
    void setAllScreenAssignments(const QHash<QString, QString>& assignments);
    void setAllDesktopAssignments(const QHash<QPair<QString, int>, QString>& assignments);
    void setAllActivityAssignments(const QHash<QPair<QString, QString>, QString>& assignments);
    void setAllCombinedAssignments(const QHash<CombinedAssignmentKey, QString>& assignments);
 
    QHash<QPair<QString, int>, AssignmentEntry> desktopAssignments() const;
    QHash<QPair<QString, QString>, AssignmentEntry> activityAssignments() const;
    QHash<CombinedAssignmentKey, AssignmentEntry> combinedAssignments() const;
 
    // ─── Quick-layout slots (1..9) ────────────────────────────────────────
    //
    // Quick slots are keyed by tiling mode, one INDEPENDENT array per mode
    // (see @ref slotIndexFor: Snapping 0, Autotile 1, Scrolling 2). Snapping
    // slots hold manual-layout UUIDs, Autotile slots hold autotile algorithm
    // IDs, and Scrolling slots hold native ScrollingTemplate UUIDs. The three
    // sets are independent so the same Meta+Alt+N can map to a zone layout in
    // snapping mode, an algorithm in autotile mode, and a template in
    // scrolling mode. applyQuickLayout's scrolling arm routes its slot id to
    // applyScrollingTemplateToScreen — the press changes the screen's
    // template, never the engine.
 
    static constexpr QLatin1String QuickSlotsSnappingKey{"snapping"};
    static constexpr QLatin1String QuickSlotsAutotileKey{"autotile"};
    static constexpr QLatin1String QuickSlotsScrollingKey{"scrolling"};
 
    Q_INVOKABLE Layout* layoutForShortcut(AssignmentEntry::Mode mode, int number) const;
    Q_INVOKABLE void applyQuickLayout(AssignmentEntry::Mode mode, int number, const QString& screenId);
    void setQuickLayoutSlot(AssignmentEntry::Mode mode, int number, const QString& layoutId);
    void setAllQuickLayoutSlots(AssignmentEntry::Mode mode, const QHash<int, QString>& slots);
    QHash<int, QString> quickLayoutSlots(AssignmentEntry::Mode mode) const
    {
        return m_quickLayoutSlots[slotIndexFor(mode)];
    }
 
    // ─── Layout cycling ───────────────────────────────────────────────────
 
    Q_INVOKABLE void cycleToPreviousLayout(const QString& screenId);
    Q_INVOKABLE void cycleToNextLayout(const QString& screenId);
 
    bool applyScrollingTemplateToScreen(const QString& screenId, const QString& templateId);
 
    bool purgeLayoutIdFromAssignments(const QString& layoutId);
 
    // ─── Built-in layouts ─────────────────────────────────────────────────
 
    Q_INVOKABLE void createBuiltInLayouts();
    QVector<Layout*> builtInLayouts() const;
 
    // ─── Context (desktop / activity) ─────────────────────────────────────
 
    Q_INVOKABLE int currentVirtualDesktop() const override
    {
        return m_currentVirtualDesktop;
    }
    Q_INVOKABLE QString currentActivity() const override
    {
        return m_currentActivity;
    }
    void setCurrentVirtualDesktop(int desktop)
    {
        m_currentVirtualDesktop = desktop;
    }
    int currentVirtualDesktopForScreen(const QString& screenId) const override
    {
        if (m_currentVirtualDesktopProvider) {
            if (const auto desktop = m_currentVirtualDesktopProvider(screenId); desktop && *desktop >= 1) {
                return *desktop;
            }
        }
        return m_currentVirtualDesktop;
    }
    void setCurrentVirtualDesktopProvider(std::function<std::optional<int>(const QString& screenId)> provider)
    {
        m_currentVirtualDesktopProvider = std::move(provider);
    }
    void setCurrentActivity(const QString& activity)
    {
        m_currentActivity = activity;
    }
 
    // ─── Autotile layout overrides (per-algorithm user overrides) ─────────
 
    void saveAutotileOverrides(const QString& algorithmId, const QJsonObject& overrides);
    QJsonObject loadAutotileOverrides(const QString& algorithmId) const override;
 
    void seedDefaultLayoutSettingsIfFresh(const QJsonObject& defaults);
 
    [[nodiscard]] int contextResolveCacheSize() const
    {
        return static_cast<int>(m_contextResolveCache.size());
    }
 
Q_SIGNALS:
    // layoutAdded / layoutRemoved / activeLayoutChanged / layoutAssigned are
    // inherited from IZoneLayoutRegistry - declared on the interface so
    // consumers that target the contract can connect without depending on
    // the concrete class. Emit sites still live in this TU and reach the
    // inherited signal via Q_OBJECT's metaobject chain.
    void layoutsChanged();
    void layoutDirectoryChanged();
    void layoutsLoaded();
    void layoutsSaved();
 
private:
    void initCommon();
 
    void ensureLayoutDirectory();
    void loadLayoutsFromDirectory(const QString& directory);
    Layout* restoreSystemLayout(const QUuid& id, const QString& systemPath);
    QString layoutFilePath(const QUuid& id) const;
    QString quickLayoutsFilePath() const;
    QString layoutSettingsFilePath() const;
    void readQuickLayouts();
    void writeQuickLayouts();
    static constexpr int QuickSlotCount = 9;
    static constexpr int slotIndexFor(AssignmentEntry::Mode mode)
    {
        if (mode == AssignmentEntry::Autotile) {
            return 1;
        }
        return mode == AssignmentEntry::Scrolling ? 2 : 0;
    }
    Layout* cycleLayoutImpl(const QString& screenId, int direction);
    bool shouldSkipLayoutAssignment(const QString& layoutId, const QString& context) const;
    void emitLayoutAssigned(const QString& screenId, int virtualDesktop, const QString& layoutId);
    bool applyLayoutToScreen(const QString& screenId, Layout* layout);
    void migrateLegacyAutotileOverrides();
 
    // ─── Rule-backed assignment resolution ────────────────────────────────
    // The unified RuleStore is the single source of truth for every
    // per-context assignment. These helpers translate the legacy
    // AssignmentEntry API onto the rule store + evaluator.
 
    std::optional<AssignmentEntry> resolveAssignmentEntry(const QString& screenId, int virtualDesktop,
                                                          const QString& activity) const;
 
    bool hasExactContextRule(const QString& screenId, int virtualDesktop, const QString& activity) const;
 
    const PhosphorRules::Rule* findExactContextRule(const QString& screenId, int virtualDesktop,
                                                    const QString& activity) const;
 
    bool hasExplicitSnappingModePin(const QString& screenId, int virtualDesktop, const QString& activity,
                                    const AssignmentEntry& entry) const;
 
    std::optional<QString> resolveStoredAssignmentId(const QString& screenId, int virtualDesktop,
                                                     const QString& activity) const;
 
    QUuid exactContextRuleId(const QString& screenId, int virtualDesktop, const QString& activity) const;
 
    bool upsertAssignmentRule(const QString& screenId, int virtualDesktop, const QString& activity,
                              const AssignmentEntry& entry);
 
    bool removeAssignmentRule(const QString& screenId, int virtualDesktop, const QString& activity);
 
    template<typename KeyT, typename DecodeFn, typename ValidFn, typename FamilyFn>
    void applyBatchAssignments(const QHash<KeyT, QString>& assignments, DecodeFn decode, ValidFn valid,
                               FamilyFn familyMatches, int emitDesktop, const char* label);
 
    AssignmentEntry resolveDefaultAssignmentEntryRaw() const;
 
    AssignmentEntry resolveDefaultAssignmentEntry() const;
 
    AssignmentEntry resolveDefaultAssignmentEntryForContext(const QString& screenId, int virtualDesktop,
                                                            const QString& activity) const;
 
    bool hasMatchingAssignmentRule(const QString& screenId, int virtualDesktop, const QString& activity) const;
 
    using ContextResolveKey = PhosphorZones::ContextResolveKey;
 
    template<typename V, typename ComputeFn>
    V resolveCachedContext(QHash<ContextResolveKey, V>& cache, quint64& cacheRevision, const QString& screenId,
                           int virtualDesktop, const QString& activity, const QString& mode, ComputeFn&& compute) const
    {
        const quint64 revision = m_ruleStore->ruleSet().revision();
        if (revision != cacheRevision) {
            cache.clear();
            cacheRevision = revision;
        }
        const ContextResolveKey key{screenId, virtualDesktop, activity, mode};
        const auto cached = cache.constFind(key);
        if (cached != cache.constEnd()) {
            return cached.value();
        }
        V value = compute();
        constexpr qsizetype kMaxEntries = 256;
        if (cache.size() >= kMaxEntries) {
            cache.clear();
        }
        cache.insert(key, value);
        return value;
    }
 
    struct RuleSlotResolution
    {
        std::optional<AssignmentEntry> modeEntry;
        std::optional<QString> snappingLayout;
        std::optional<QString> tilingAlgorithm;
        std::optional<QString> scrollingTemplate;
    };
 
    mutable QHash<ContextResolveKey, std::optional<RuleSlotResolution>> m_contextResolveCache;
    mutable quint64 m_contextResolveCacheRevision = 0;
 
    mutable QHash<ContextResolveKey, ContextGapOverride> m_contextGapCache;
    mutable quint64 m_contextGapCacheRevision = 0;
 
    mutable QHash<ContextResolveKey, bool> m_contextLockCache;
    mutable quint64 m_contextLockCacheRevision = 0;
 
    mutable QHash<ContextResolveKey, std::optional<bool>> m_contextDefaultAssignmentCache;
    mutable quint64 m_contextDefaultAssignmentCacheRevision = 0;
 
    std::optional<bool> resolveContextBoolSlot(QHash<ContextResolveKey, std::optional<bool>>& cache,
                                               quint64& cacheRevision, QLatin1StringView actionType,
                                               const QString& screenId, int virtualDesktop,
                                               const QString& activity) const;
 
    mutable QHash<ContextResolveKey, std::optional<bool>> m_contextOsdCache;
    mutable quint64 m_contextOsdCacheRevision = 0;
 
    mutable QHash<ContextResolveKey, std::optional<bool>> m_contextDragSelectorCache;
    mutable quint64 m_contextDragSelectorCacheRevision = 0;
 
    mutable QHash<ContextResolveKey, ContextOverlayOverride> m_contextOverlayCache;
    mutable quint64 m_contextOverlayCacheRevision = 0;
 
    std::function<QString()> m_defaultLayoutIdProvider; 
    std::function<QString()> m_defaultAutotileAlgorithmProvider;
    std::function<std::optional<int>(const QString& screenId, int virtualDesktop, const QString& activity)>
        m_tiledWindowCountProvider;
    std::function<std::optional<QString>(const QString& screenId)> m_screenOrientationProvider;
    std::function<std::optional<QString>()> m_colorSchemeProvider;
    ScrollingTemplateStore* m_scrollingTemplateStore = nullptr;
    std::function<QString()> m_defaultScrollingTemplateProvider;
    std::function<bool()> m_snappingPreferredProvider;
    std::function<bool()> m_defaultAssignmentSuppressedProvider;
    PhosphorRules::RuleStore* m_ruleStore = nullptr;
    std::unique_ptr<PhosphorRules::RuleEvaluator> m_evaluator;
    QString m_layoutSubdirectory; 
    QString m_layoutDirectory; 
    QVector<Layout*> m_layouts;
    Layout* m_activeLayout = nullptr;
    Layout* m_previousLayout = nullptr; 
    QHash<int, QString> m_quickLayoutSlots[3];
    LayoutSettingsStore m_layoutSettings;
    int m_currentVirtualDesktop = 1;
    std::function<std::optional<int>(const QString&)> m_currentVirtualDesktopProvider;
    QString m_currentActivity;
};
 
} // namespace PhosphorZones