AssignmentEntry.h

Go to the documentation of this file.

// SPDX-FileCopyrightText: 2026 fuddlesworth
// SPDX-License-Identifier: LGPL-2.1-or-later
 
#pragma once
 
#include <PhosphorLayoutApi/LayoutId.h>
 
#include <QColor>
#include <QHash>
#include <QList>
#include <QString>
#include <QUuid>
#include <QVariantMap>
#include <QtGlobal>
 
#include <optional>
 
namespace PhosphorZones {
 
struct LayoutAssignmentKey
{
    QString screenId; // Stable EDID-based identifier (or connector name fallback)
    int virtualDesktop = 0; // 0 = all desktops
    QString activity; // Empty = all activities
 
    bool operator==(const LayoutAssignmentKey& other) const
    {
        return screenId == other.screenId && virtualDesktop == other.virtualDesktop && activity == other.activity;
    }
 
    static LayoutAssignmentKey fromGroupName(const QString& groupName, const QString& prefix)
    {
        LayoutAssignmentKey result;
        if (!groupName.startsWith(prefix))
            return result;
        QString remainder = groupName.mid(prefix.size());
        if (remainder.isEmpty())
            return result;
 
        constexpr QLatin1String kActivityTag(":Activity:");
        constexpr QLatin1String kDesktopTag(":Desktop:");
        int actIdx = remainder.indexOf(kActivityTag);
        if (actIdx >= 0) {
            const QString activity = remainder.mid(actIdx + kActivityTag.size());
            if (!activity.isEmpty())
                result.activity = activity;
            remainder = remainder.left(actIdx);
        }
        int deskIdx = remainder.indexOf(kDesktopTag);
        if (deskIdx >= 0) {
            bool ok = false;
            int desktop = remainder.mid(deskIdx + kDesktopTag.size()).toInt(&ok);
            if (ok && desktop > 0)
                result.virtualDesktop = desktop;
            remainder = remainder.left(deskIdx);
        }
        result.screenId = remainder;
        return result;
    }
};
 
inline size_t qHash(const LayoutAssignmentKey& key, size_t seed = 0)
{
    seed = ::qHash(key.screenId, seed);
    seed = ::qHash(key.virtualDesktop, seed);
    seed = ::qHash(key.activity, seed);
    return seed;
}
 
inline constexpr QLatin1String NoScrollingTemplate{"none"};
 
inline constexpr QLatin1String NoSnappingLayout{"none"};
 
inline constexpr QLatin1String NoTilingAlgorithm{"none"};
 
struct AssignmentEntry
{
    enum Mode {
        Snapping = 0,
        Autotile = 1,
        Scrolling = 2
    };
    Mode mode = Snapping;
    QString snappingLayout; // UUID string of manual layout
    QString tilingAlgorithm; // e.g. "dwindle", "wide", "tall"
    QString scrollingTemplateLayout;
 
    QString activeLayoutId() const
    {
        // Scrolling has no layout entity, so the id is the bare sentinel
        // "scrolling:". This is LOAD-BEARING: the assignment cascade's
        // visitors reject entries with an empty activeLayoutId(), and a
        // fresh mode-only Scrolling entry (empty preserved snappingLayout)
        // would otherwise silently fail to assign. The gap / lock /
        // overlay / tiling-param / scrolling-param resolvers stamp this
        // sentinel into query.activeLayout, so `ActiveLayout Equals
        // "scrolling:"` matches THERE (the assignment and context-default
        // resolvers deliberately leave activeLayout unstamped — recursion).
        // There is no per-layout identity to distinguish beyond the mode.
        if (mode == Scrolling) {
            return QString(PhosphorLayout::LayoutId::ScrollingId);
        }
        if (mode == Autotile) {
            // Autotile mode always produces a non-empty id so the cascade
            // visitors in LayoutRegistry accept it (they reject on
            // activeLayoutId().isEmpty()). For a mode-only entry (empty
            // tilingAlgorithm — what the KCM writes for "autotile, use
            // default algorithm"), makeAutotileId returns the bare
            // prefix @c "autotile:"; downstream callers use
            // @ref PhosphorLayout::LayoutId::isAutotile to detect mode
            // and @ref PhosphorLayout::LayoutId::extractAlgorithmId to
            // get the algorithm (empty = engine default).
            return PhosphorLayout::LayoutId::makeAutotileId(tilingAlgorithm);
        }
        return snappingLayout;
    }
    bool isValid() const
    {
        return !snappingLayout.isEmpty() || !tilingAlgorithm.isEmpty();
    }
    bool operator==(const AssignmentEntry& other) const
    {
        return mode == other.mode && snappingLayout == other.snappingLayout && tilingAlgorithm == other.tilingAlgorithm
            && scrollingTemplateLayout == other.scrollingTemplateLayout;
    }
 
    static AssignmentEntry fromLayoutId(const QString& layoutId, const AssignmentEntry& existing)
    {
        AssignmentEntry entry = existing;
        if (PhosphorLayout::LayoutId::isAutotile(layoutId)) {
            entry.mode = Autotile;
            entry.tilingAlgorithm = PhosphorLayout::LayoutId::extractAlgorithmId(layoutId);
        } else if (PhosphorLayout::LayoutId::isScrolling(layoutId)) {
            // The "scrolling:" sentinel carries no layout entity — flip the
            // mode and preserve all three layout fields (the lossless-toggle
            // contract), so a get→set round-trip cannot degrade a Scrolling
            // assignment into Snapping-pointing-at-a-bogus-id.
            entry.mode = Scrolling;
        } else {
            entry.mode = Snapping;
            // Normalize a UUID-shaped id to its canonical braced spelling at
            // this ONE classification choke point, so every caller (the D-Bus
            // setAssignmentEntry and the four setAll*Assignments verbs, the
            // batch rebuilds, the controllers) stores one spelling. A braceless
            // or upper-case bus-supplied uuid stored verbatim defeats the
            // exact-string compare that purgeLayoutIdFromAssignments does on
            // layout delete, and the byte-wise action compare in
            // upsertAssignmentRule's no-op guard. Anything that is not a UUID
            // passes through untouched — the snapping slot is not required to
            // hold one, and @ref NoSnappingLayout DEPENDS on this arm staying
            // verbatim: parsing the reserved word yields a null QUuid, and
            // storing that null's toString would silently turn "explicitly
            // none" into a dangling id.
            const QUuid parsed = QUuid::fromString(layoutId);
            entry.snappingLayout = parsed.isNull() ? layoutId : parsed.toString();
        }
        return entry;
    }
    static AssignmentEntry fromLayoutId(const QString& layoutId)
    {
        return fromLayoutId(layoutId, AssignmentEntry{});
    }
};
 
struct ContextGapOverride
{
    std::optional<int> innerGap;
    std::optional<int> outerGap;
    std::optional<bool> usePerSideOuterGap;
    std::optional<int> outerGapTop;
    std::optional<int> outerGapBottom;
    std::optional<int> outerGapLeft;
    std::optional<int> outerGapRight;
 
    bool isEmpty() const
    {
        return !innerGap && !outerGap && !usePerSideOuterGap && !outerGapTop && !outerGapBottom && !outerGapLeft
            && !outerGapRight;
    }
};
 
struct ContextOverlayOverride
{
    std::optional<QString> shaderId;
    QVariantMap shaderParams;
    std::optional<int> style;
    std::optional<QColor> highlightColor;
    std::optional<QColor> inactiveColor;
    std::optional<QColor> borderColor;
    std::optional<double> activeOpacity;
    std::optional<double> inactiveOpacity;
    std::optional<int> borderWidth;
    std::optional<int> borderRadius;
    std::optional<bool> showZoneNumbers;
 
    bool isEmpty() const
    {
        // shaderParams is only ever populated alongside shaderId, but check it too so
        // isEmpty() stays honest if a future writer sets the map without the gate.
        return !shaderId && shaderParams.isEmpty() && !style && !highlightColor && !inactiveColor && !borderColor
            && !activeOpacity && !inactiveOpacity && !borderWidth && !borderRadius && !showZoneNumbers;
    }
};
 
struct ContextTilingParams
{
    std::optional<int> maxWindows;
    std::optional<double> splitRatio;
    std::optional<int> masterCount;
    std::optional<int> insertPosition;
    std::optional<int> overflowBehavior;
    std::optional<int> dragBehavior;
    QString algorithmParamTarget;
    QVariantMap algorithmParams;
 
    bool isEmpty() const
    {
        // algorithmParams is only ever populated alongside algorithmParamTarget, but
        // check it too so isEmpty() stays honest if a future writer sets it without the
        // target.
        return !maxWindows && !splitRatio && !masterCount && !insertPosition && !overflowBehavior && !dragBehavior
            && algorithmParamTarget.isEmpty() && algorithmParams.isEmpty();
    }
};
 
struct ContextScrollingParams
{
    std::optional<double> defaultColumnWidth;
    std::optional<int> centerFocusedColumn;
    std::optional<int> defaultColumnDisplay;
    std::optional<int> insertPosition;
    std::optional<double> defaultWindowHeight;
 
    std::optional<bool> alwaysCenterSingleColumn;
    std::optional<bool> respectMinimumSize;
    std::optional<bool> cropStraddlers;
    std::optional<bool> focusNewWindows;
    std::optional<bool> smartGaps;
    std::optional<bool> focusFollowsMouse;
    std::optional<double> focusFollowsMouseMaxScroll;
    std::optional<int> stickyWindowHandling;
    std::optional<int> stripAxis;
 
    std::optional<bool> tabIndicatorEnabled;
    std::optional<bool> tabIndicatorHideWhenSingleTab;
    std::optional<bool> tabIndicatorPlaceWithinColumn;
    std::optional<int> tabIndicatorGap; 
    std::optional<int> tabIndicatorWidth; 
    std::optional<double> tabIndicatorLength; 
    std::optional<int> tabIndicatorPosition; 
    std::optional<int> tabIndicatorStyle; 
    std::optional<int> tabIndicatorGapsBetweenTabs; 
    std::optional<int> tabIndicatorCornerRadius; 
    std::optional<QString> tabIndicatorActiveColor;
    std::optional<QString> tabIndicatorInactiveColor;
    std::optional<QString> tabIndicatorUrgentColor;
    std::optional<QString> tabIndicatorFontFamily;
    std::optional<int> tabIndicatorFontWeight; 
    std::optional<bool> tabIndicatorFontItalic;
    std::optional<bool> tabIndicatorFontUnderline;
    std::optional<bool> tabIndicatorFontStrikeout;
 
    std::optional<bool> dropIndicatorEnabled;
    std::optional<QString> dropIndicatorColor;
    std::optional<QString> dropIndicatorBorderColor;
    std::optional<double> dropIndicatorOpacity; 
    std::optional<int> dropIndicatorBorderWidth; 
    std::optional<int> dropIndicatorBorderRadius; 
 
    // The three block-level aggregates below exist for isEmpty() — their
    // ONLY caller. Earlier docs claimed the daemon consulted them to skip
    // whole override blocks; it never did (it tests each optional it
    // consumes directly), so do not add such a gate on the strength of a
    // predicate existing here.
 
    bool hasDropIndicatorOverrides() const
    {
        return dropIndicatorEnabled || dropIndicatorColor || dropIndicatorBorderColor || dropIndicatorOpacity
            || dropIndicatorBorderWidth || dropIndicatorBorderRadius;
    }
 
    bool hasTabIndicatorOverrides() const
    {
        return tabIndicatorEnabled || tabIndicatorHideWhenSingleTab || tabIndicatorPlaceWithinColumn || tabIndicatorGap
            || tabIndicatorWidth || tabIndicatorLength || tabIndicatorPosition || tabIndicatorStyle
            || tabIndicatorGapsBetweenTabs || tabIndicatorCornerRadius || tabIndicatorActiveColor
            || tabIndicatorInactiveColor || tabIndicatorUrgentColor || tabIndicatorFontFamily || tabIndicatorFontWeight
            || tabIndicatorFontItalic || tabIndicatorFontUnderline || tabIndicatorFontStrikeout;
    }
 
    bool hasBehaviourOverrides() const
    {
        return alwaysCenterSingleColumn || respectMinimumSize || cropStraddlers || focusNewWindows || smartGaps
            || stickyWindowHandling || focusFollowsMouse || focusFollowsMouseMaxScroll;
    }
 
    bool isEmpty() const
    {
        return !defaultColumnWidth && !centerFocusedColumn && !defaultColumnDisplay && !insertPosition
            && !defaultWindowHeight && !stripAxis && !hasTabIndicatorOverrides() && !hasDropIndicatorOverrides()
            && !hasBehaviourOverrides();
    }
};
 
inline QString modeToWireString(AssignmentEntry::Mode mode)
{
    switch (mode) {
    case AssignmentEntry::Snapping:
        return QStringLiteral("snapping");
    case AssignmentEntry::Autotile:
        return QStringLiteral("autotile");
    case AssignmentEntry::Scrolling:
        return QStringLiteral("scrolling");
    }
    // Switch is exhaustive over `Mode`. A `static_cast<Mode>(99)` reaching
    // this line means either (a) a future Mode enum value was added without
    // a case here — the real guard against that is Qt's -Wswitch diagnostic
    // at the missing-case site (NOTE: this project's CMake does NOT
    // promote it to -Werror, so it's a warning at build time, not an
    // error), or (b) callers fabricated an out-of-range value via cast.
    // `Q_UNREACHABLE_RETURN` expands to `[[unreachable]] + return`
    // on modern compilers, so the sentinel below carries through release
    // builds even when the optimizer assumes the function never reaches
    // here.
    //
    // The sentinel `"invalid"` is rejected by the `DisableEngine`
    // descriptor's closed-vocabulary validator
    // (`engineModeOptions().contains(...)`), so a malformed disable rule
    // fails load loudly. NOTE: `SetEngineMode`'s validator only checks
    // `hasNonEmptyString` (open-vocabulary by design — see its descriptor
    // validator in `libs/phosphor-rules/src/ruleaction_builtins_engine.cpp`), so a
    // malformed assignment rule survives load but is silently coerced
    // back to Snapping at consumption via
    // `entryFromRuleMatchActions → modeFromWireString → nullopt`. The
    // sentinel makes the corruption visible to operators inspecting
    // rules.json by eye, but is not a load-time gate for the
    // assignment path.
    Q_UNREACHABLE_RETURN(QStringLiteral("invalid"));
}
 
inline std::optional<AssignmentEntry::Mode> modeFromWireString(const QString& wire)
{
    if (wire == QLatin1String("snapping")) {
        return AssignmentEntry::Snapping;
    }
    if (wire == QLatin1String("autotile")) {
        return AssignmentEntry::Autotile;
    }
    if (wire == QLatin1String("scrolling")) {
        return AssignmentEntry::Scrolling;
    }
    return std::nullopt;
}
 
inline QList<AssignmentEntry::Mode> allModes()
{
    return {AssignmentEntry::Snapping, AssignmentEntry::Autotile, AssignmentEntry::Scrolling};
}
 
} // namespace PhosphorZones