SurfaceConfig.h

Go to the documentation of this file.

// SPDX-FileCopyrightText: 2026 fuddlesworth
// SPDX-License-Identifier: LGPL-2.1-or-later
 
#pragma once
 
#include <PhosphorLayer/Role.h>
#include <PhosphorLayer/phosphorlayer_export.h>
 
#include <QMargins>
#include <QSize>
#include <QString>
#include <QUrl>
#include <QVariantMap>
 
#include <memory>
#include <optional>
 
QT_BEGIN_NAMESPACE
class QQmlEngine;
class QQuickItem;
class QScreen;
QT_END_NAMESPACE
 
namespace PhosphorLayer {
 
struct PHOSPHORLAYER_EXPORT SurfaceConfig
{
    Role role;
 
    QUrl contentUrl;
 
    std::unique_ptr<QQuickItem> contentItem;
 
    QScreen* screen = nullptr;
 
    QVariantMap contextProperties;
 
    QVariantMap windowProperties;
 
    QQmlEngine* sharedEngine = nullptr;
 
    // ── Per-instance overrides ──────────────────────────────────────────
    // nullopt = use the role's default. All are applied at surface-creation
    // time; post-show mutation of these fields has no effect (SurfaceConfig
    // is stored const on the Surface).
 
    std::optional<Layer> layerOverride;
    std::optional<Anchors> anchorsOverride;
    std::optional<int> exclusiveZoneOverride;
    std::optional<KeyboardInteractivity> keyboardOverride;
    std::optional<QMargins> marginsOverride;
 
    // ── Lifecycle policy ────────────────────────────────────────────────
    bool keepMappedOnHide = false;
 
    QSize initialSize = {};
 
    QString debugName;
 
    // ── Resolution helpers ──────────────────────────────────────────────
 
    [[nodiscard]] Layer effectiveLayer() const noexcept
    {
        return layerOverride.value_or(role.layer);
    }
    [[nodiscard]] Anchors effectiveAnchors() const noexcept
    {
        return anchorsOverride.value_or(role.anchors);
    }
    [[nodiscard]] int effectiveExclusiveZone() const noexcept
    {
        return exclusiveZoneOverride.value_or(role.exclusiveZone);
    }
    [[nodiscard]] KeyboardInteractivity effectiveKeyboard() const noexcept
    {
        return keyboardOverride.value_or(role.keyboard);
    }
    [[nodiscard]] QMargins effectiveMargins() const noexcept
    {
        return marginsOverride.value_or(role.defaultMargins);
    }
    [[nodiscard]] QString effectiveDebugName() const
    {
        return debugName.isEmpty() ? role.scopePrefix : debugName;
    }
 
    // Special members defined out-of-line (in surface.cpp) so QQuickItem
    // need only be forward-declared here — the concrete ~unique_ptr<QQuickItem>
    // call sites live where QQuickItem is complete.
    SurfaceConfig();
    ~SurfaceConfig();
    SurfaceConfig(const SurfaceConfig&) = delete;
    SurfaceConfig& operator=(const SurfaceConfig&) = delete;
    SurfaceConfig(SurfaceConfig&&) noexcept;
    SurfaceConfig& operator=(SurfaceConfig&&) noexcept;
};
 
} // namespace PhosphorLayer