IZoneLayoutRegistry.h

Go to the documentation of this file.

// SPDX-FileCopyrightText: 2026 fuddlesworth
// SPDX-License-Identifier: LGPL-2.1-or-later
 
#pragma once
 
// IZoneLayoutRegistry - enumeration + mutation of the catalog of
// manual zone layouts.
//
// Split out of ILayoutManager so callers that need the layout set
// (editor save path, layout-import flow, settings create-layout
// button, read-only preview renderers) can depend on one contract
// instead of the full manager. "Active layout" selection lives here
// because it mutates the manager's active-layout slot.
//
// Inherits PhosphorLayout::ILayoutSourceRegistry so concrete registries
// (LayoutManager) carry the unified `contentsChanged` signal that
// ZonesLayoutSource subscribes to - matching the pattern every other
// provider library (phosphor-tiles, phosphor-scroll-engine, …)
// follows. Inheriting QObject via the unified base rather than
// directly keeps ILayoutManager's non-virtual multi-inheritance safe:
// every path through ILayoutManager reaches QObject exactly once, so
// LayoutManager has a single QObject subobject.
 
#include <phosphorzones_export.h>
 
#include <PhosphorLayoutApi/ILayoutSourceRegistry.h>
#include <PhosphorLayoutApi/LayoutId.h>
#include <PhosphorZones/AssignmentEntry.h>
#include <PhosphorZones/Layout.h>
#include <PhosphorZones/ScrollingTemplate.h>
 
#include <QJsonObject>
#include <QString>
#include <QUuid>
#include <QVector>
 
#include <optional>
 
namespace PhosphorZones {
 
class ScrollingTemplateStore;
 
class PHOSPHORZONES_EXPORT IZoneLayoutRegistry : public PhosphorLayout::ILayoutSourceRegistry
{
    Q_OBJECT
 
    // Live in the interface so QML-bound consumers can target the contract
    // without depending on the concrete @ref LayoutRegistry. moc's NOTIFY
    // check resolves the signal in the same class scope it sees the READ
    // method, so the property + the signal must travel together.
    Q_PROPERTY(Layout* activeLayout READ activeLayout NOTIFY activeLayoutChanged)
 
public:
    explicit IZoneLayoutRegistry(QObject* parent = nullptr);
    ~IZoneLayoutRegistry() override;
 
    virtual QVector<Layout*> layouts() const = 0;
 
    virtual int layoutCount() const = 0;
    virtual Layout* layout(int index) const = 0;
    virtual Layout* layoutByName(const QString& name) const = 0;
 
    virtual Layout* layoutById(const QUuid& id) const = 0;
 
    virtual void addLayout(Layout* layout) = 0;
    virtual bool removeLayout(Layout* layout) = 0;
    virtual bool removeLayoutById(const QUuid& id) = 0;
    virtual Layout* duplicateLayout(Layout* source) = 0;
 
    // Active layout (internal - used for resnap / geometry / overlay
    // machinery). Borrowed pointer owned by the registry.
    virtual Layout* activeLayout() const = 0;
    virtual void setActiveLayout(Layout* layout) = 0;
    virtual void setActiveLayoutById(const QUuid& id) = 0;
 
    // ─── Per-screen layout resolution (cascade-aware) ─────────────────────
    //
    // These queries resolve a layout for a (screen, desktop, activity)
    // context by walking the assignment cascade and falling back to the
    // global default. Overlay/geometry/animation consumers depend on this
    // shape, so it lives on the interface - callers can target the
    // contract without depending on the concrete @c LayoutRegistry.
 
    virtual Layout* layoutForScreen(const QString& screenId, int virtualDesktop = 0,
                                    const QString& activity = QString()) const = 0;
 
    virtual Layout* resolveLayoutForScreen(const QString& screenId) const = 0;
 
    virtual QString assignmentIdForScreen(const QString& screenId, int virtualDesktop = 0,
                                          const QString& activity = QString()) const = 0;
 
    virtual ScrollingTemplateStore* scrollingTemplateStore() const
    {
        return nullptr;
    }
 
    virtual ScrollingTemplate scrollingTemplateForContext(const QString& screenId, int virtualDesktop,
                                                          const QString& activity) const
    {
        Q_UNUSED(screenId)
        Q_UNUSED(virtualDesktop)
        Q_UNUSED(activity)
        return {};
    }
 
    // scrollingTemplateExplicitlyNone, the other half of the pair the next
    // function reads, is declared at the END of the virtuals (see its own doc
    // there for both what it answers and why it sits last).
 
    QString scrollingDisplayIdForContext(const QString& screenId, int virtualDesktop, const QString& activity) const
    {
        const ScrollingTemplate templ = scrollingTemplateForContext(screenId, virtualDesktop, activity);
        if (templ.isValid()) {
            return templ.id.toString();
        }
        // Tested only once the resolver has come back empty: a context cannot
        // both name a template and be opted out. That ordering costs a second
        // resolve on a screen with no template and no configured default,
        // which is not rare — the memoized context cache makes it a lookup
        // rather than a second priority walk.
        if (scrollingTemplateExplicitlyNone(screenId, virtualDesktop, activity)) {
            return QString(NoScrollingTemplate);
        }
        return QString(PhosphorLayout::LayoutId::ScrollingId);
    }
 
    virtual Layout* defaultLayout() const = 0;
 
    // ─── Session context (current desktop / activity) ─────────────────────
    //
    // The registry holds session-context state because per-context
    // assignment resolution needs it. Consumers that drive context-aware
    // queries (overlay re-layout on desktop switch, autotile re-run on
    // activity change) read it through the interface.
 
    virtual int currentVirtualDesktop() const = 0;
    virtual int currentVirtualDesktopForScreen(const QString& screenId) const
    {
        Q_UNUSED(screenId)
        return currentVirtualDesktop();
    }
    virtual QString currentActivity() const = 0;
 
    virtual QJsonObject loadAutotileOverrides(const QString& algorithmId) const
    {
        Q_UNUSED(algorithmId)
        return {};
    }
 
    virtual QString tilingAlgorithmForScreen(const QString& screenId, int virtualDesktop = 0,
                                             const QString& activity = QString()) const
    {
        Q_UNUSED(screenId)
        Q_UNUSED(virtualDesktop)
        Q_UNUSED(activity)
        return {};
    }
 
    virtual ContextGapOverride resolveContextGaps(const QString& screenId, int virtualDesktop, const QString& activity,
                                                  const QString& mode = QString()) const
    {
        Q_UNUSED(screenId);
        Q_UNUSED(virtualDesktop);
        Q_UNUSED(activity);
        Q_UNUSED(mode);
        return {};
    }
 
    virtual bool resolveContextLocked(const QString& screenId, int virtualDesktop, const QString& activity) const
    {
        Q_UNUSED(screenId);
        Q_UNUSED(virtualDesktop);
        Q_UNUSED(activity);
        return false;
    }
 
    virtual std::optional<bool> resolveContextDragSelectorEnabled(const QString& screenId, int virtualDesktop,
                                                                  const QString& activity) const
    {
        Q_UNUSED(screenId);
        Q_UNUSED(virtualDesktop);
        Q_UNUSED(activity);
        return std::nullopt;
    }
 
    virtual bool isContextActiveLayoutSuppressed(const QString& screenId, int virtualDesktop,
                                                 const QString& activity) const
    {
        Q_UNUSED(screenId);
        Q_UNUSED(virtualDesktop);
        Q_UNUSED(activity);
        return false;
    }
 
    virtual ContextOverlayOverride resolveContextOverlay(const QString& screenId, int virtualDesktop,
                                                         const QString& activity) const
    {
        Q_UNUSED(screenId);
        Q_UNUSED(virtualDesktop);
        Q_UNUSED(activity);
        return {};
    }
 
    virtual bool scrollingTemplateExplicitlyNone(const QString& screenId, int virtualDesktop,
                                                 const QString& activity) const
    {
        Q_UNUSED(screenId)
        Q_UNUSED(virtualDesktop)
        Q_UNUSED(activity)
        return false;
    }
 
Q_SIGNALS:
    // Catalog mutation. @c addLayout / @c duplicateLayout fire `layoutAdded`;
    // @c removeLayout / @c removeLayoutById fire `layoutRemoved` on success;
    // a refused removal (see their @return) fires nothing.
    void layoutAdded(Layout* layout);
    void layoutRemoved(Layout* layout);
 
    // Active-layout selection. Fires from @c setActiveLayout /
    // @c setActiveLayoutById only when the active-layout pointer actually
    // changes (concrete implementer guards with an equality check -
    // matches the project rule "only emit signals when value actually
    // changes").
    void activeLayoutChanged(Layout* layout);
 
    // Assignment churn. Fires when a (screenId, virtualDesktop) assignment
    // is WRITTEN; activity context is intentionally omitted from the signal -
    // consumers that care about activity-keyed assignments re-query via
    // @c layoutForScreen with their current activity. Deliberately NOT an
    // emit-on-change signal: the emitters fire unconditionally on every
    // assignment write, because consumers use it as a re-derive trigger
    // (engine screen sets, layout filters, template vocabulary pushes) whose
    // inputs go beyond the (screen, desktop, layout) payload - an identical
    // payload can still mean a changed template or activity-keyed entry.
    void layoutAssigned(const QString& screenId, int virtualDesktop, Layout* layout);
};
 
} // namespace PhosphorZones