Role.h

Go to the documentation of this file.

// SPDX-FileCopyrightText: 2026 fuddlesworth
// SPDX-License-Identifier: LGPL-2.1-or-later
 
#pragma once
 
#include <PhosphorLayer/phosphorlayer_export.h>
 
#include <QFlags>
#include <QMargins>
#include <QObject>
#include <QString>
 
#include <cstdint>
 
namespace PhosphorLayer {
 
Q_NAMESPACE_EXPORT(PHOSPHORLAYER_EXPORT)
 
// ── Protocol-level enums (match zwlr_layer_shell_v1 values) ────────────
 
 
enum class Layer : int {
    Background = 0, 
    Bottom = 1, 
    Top = 2, 
    Overlay = 3, 
};
Q_ENUM_NS(Layer)
 
 
enum class Anchor : std::uint32_t {
    None = 0,
    Top = 1U << 0,
    Bottom = 1U << 1,
    Left = 1U << 2,
    Right = 1U << 3,
};
Q_DECLARE_FLAGS(Anchors, Anchor)
Q_FLAG_NS(Anchors)
 
// Constructed via QFlags' initializer_list ctor so these expressions don't
// depend on the global-scope operator| from Q_DECLARE_OPERATORS_FOR_FLAGS,
// which is only declared at the bottom of this header.
inline constexpr Anchors AnchorNone = Anchors();
inline constexpr Anchors AnchorAll{Anchor::Top, Anchor::Bottom, Anchor::Left, Anchor::Right};
 
enum class KeyboardInteractivity : int {
    None = 0, 
    Exclusive = 1, 
    OnDemand = 2, 
};
Q_ENUM_NS(KeyboardInteractivity)
 
// ── Role: protocol-level configuration bundle ──────────────────────────
 
 
struct PHOSPHORLAYER_EXPORT Role
{
    Layer layer = Layer::Overlay;
    Anchors anchors = AnchorNone;
    int exclusiveZone = -1; 
    KeyboardInteractivity keyboard = KeyboardInteractivity::None;
    QMargins defaultMargins;
    QString scopePrefix; 
 
    [[nodiscard]] Role withLayer(Layer l) const;
    [[nodiscard]] Role withAnchors(Anchors a) const;
    [[nodiscard]] Role withExclusiveZone(int z) const;
    [[nodiscard]] Role withKeyboard(KeyboardInteractivity k) const;
    [[nodiscard]] Role withMargins(QMargins m) const;
    [[nodiscard]] Role withScopePrefix(QString prefix) const;
 
    [[nodiscard]] bool isValid() const;
 
    friend bool operator==(const Role& a, const Role& b) = default;
};
 
// The legacy `Roles` namespace was removed in phase 1 of the surface
// taxonomy refactor, and the axis-2 Patterns vocabulary was lifted into
// its own sibling library `phosphor-shell-patterns` in phase 3. New
// consumers should depend on PhosphorShellPatterns and use
// `PhosphorShellPatterns::{Hud, Modal, Wallpaper, Floating, Panel(Edge),
// Toast(Corner)}` rather than re-deriving Role values inline. See
// `docs/surface-taxonomy-refactor-plan.md` for the migration map.
 
} // namespace PhosphorLayer
 
Q_DECLARE_OPERATORS_FOR_FLAGS(PhosphorLayer::Anchors)