Phosphor
Qt6 / Wayland library suite for window-management tools
Loading...
Searching...
No Matches
SurfaceConfig.h
Go to the documentation of this file.
1// SPDX-FileCopyrightText: 2026 fuddlesworth
2// SPDX-License-Identifier: LGPL-2.1-or-later
3
4#pragma once
5
7#include <PhosphorLayer/phosphorlayer_export.h>
8
9#include <QMargins>
10#include <QSize>
11#include <QString>
12#include <QUrl>
13#include <QVariantMap>
14
15#include <memory>
16#include <optional>
17
18QT_BEGIN_NAMESPACE
19class QQmlEngine;
20class QQuickItem;
21class QScreen;
22QT_END_NAMESPACE
23
24namespace PhosphorLayer {
25
46struct PHOSPHORLAYER_EXPORT SurfaceConfig
47{
50
54
59 std::unique_ptr<QQuickItem> contentItem;
60
64 QScreen* screen = nullptr;
65
71 QVariantMap contextProperties;
72
86 QVariantMap windowProperties;
87
95 QQmlEngine* sharedEngine = nullptr;
96
97 // ── Per-instance overrides ──────────────────────────────────────────
98 // nullopt = use the role's default. All are applied at surface-creation
99 // time; post-show mutation of these fields has no effect (the Surface
100 // holds its own copy privately and exposes it only through
101 // Surface::config() const). keyboardOverride is the one exception:
102 // Surface::setKeyboardInteractivity updates the Surface's copy and the
103 // live transport handle.
104
105 std::optional<Layer> layerOverride;
106 std::optional<Anchors> anchorsOverride;
107 std::optional<int> exclusiveZoneOverride;
108 std::optional<KeyboardInteractivity> keyboardOverride;
109 std::optional<QMargins> marginsOverride;
110
111 // ── Lifecycle policy ────────────────────────────────────────────────
139 bool keepMappedOnHide = false;
140
162 QSize initialSize = {};
163
165 QString debugName;
166
184 bool animateRoot = true;
185
186 // ── Resolution helpers ──────────────────────────────────────────────
187
188 [[nodiscard]] Layer effectiveLayer() const noexcept
189 {
190 return layerOverride.value_or(role.layer);
191 }
192 [[nodiscard]] Anchors effectiveAnchors() const noexcept
193 {
194 return anchorsOverride.value_or(role.anchors);
195 }
196 [[nodiscard]] int effectiveExclusiveZone() const noexcept
197 {
198 return exclusiveZoneOverride.value_or(role.exclusiveZone);
199 }
200 [[nodiscard]] KeyboardInteractivity effectiveKeyboard() const noexcept
201 {
202 return keyboardOverride.value_or(role.keyboard);
203 }
204 [[nodiscard]] QMargins effectiveMargins() const noexcept
205 {
206 return marginsOverride.value_or(role.defaultMargins);
207 }
208 [[nodiscard]] QString effectiveDebugName() const
209 {
210 return debugName.isEmpty() ? role.scopePrefix : debugName;
211 }
212
213 // Special members defined out-of-line (in surface.cpp) so QQuickItem
214 // need only be forward-declared here — the concrete ~unique_ptr<QQuickItem>
215 // call sites live where QQuickItem is complete.
218 SurfaceConfig(const SurfaceConfig&) = delete;
221 SurfaceConfig& operator=(SurfaceConfig&&) noexcept;
222};
223
224} // namespace PhosphorLayer
Definition SurfaceAnimator.h:26
KeyboardInteractivity
Keyboard focus policy (wlr-layer-shell v4 adds OnDemand).
Definition Role.h:51
Layer
Meta-object context for namespace-level enums so QML and QMetaEnum can stringify them.
Definition Role.h:24
Value type describing a surface's protocol-level configuration.
Definition Role.h:77
Layer effectiveLayer() const noexcept
Definition SurfaceConfig.h:188
QUrl contentUrl
QML root component URL, a qrc: or file: URL.
Definition SurfaceConfig.h:53
SurfaceConfig & operator=(const SurfaceConfig &)=delete
QSize initialSize
Initial size committed to the wl_surface during warm-up.
Definition SurfaceConfig.h:162
std::optional< int > exclusiveZoneOverride
Definition SurfaceConfig.h:107
SurfaceConfig(SurfaceConfig &&) noexcept
SurfaceConfig(const SurfaceConfig &)=delete
std::optional< QMargins > marginsOverride
Definition SurfaceConfig.h:109
QVariantMap windowProperties
Applied to the QQuickWindow before the QML content completes.
Definition SurfaceConfig.h:86
QMargins effectiveMargins() const noexcept
Definition SurfaceConfig.h:204
std::optional< KeyboardInteractivity > keyboardOverride
Definition SurfaceConfig.h:108
std::optional< Anchors > anchorsOverride
Definition SurfaceConfig.h:106
bool animateRoot
When false, the surface's own show/hide never dispatches ISurfaceAnimator::beginShow / beginHide on i...
Definition SurfaceConfig.h:184
QString effectiveDebugName() const
Definition SurfaceConfig.h:208
QScreen * screen
Target screen.
Definition SurfaceConfig.h:64
KeyboardInteractivity effectiveKeyboard() const noexcept
Definition SurfaceConfig.h:200
QVariantMap contextProperties
Injected into the surface's QML root context.
Definition SurfaceConfig.h:71
int effectiveExclusiveZone() const noexcept
Definition SurfaceConfig.h:196
QQmlEngine * sharedEngine
Opt-in shared QQmlEngine for contentUrl content.
Definition SurfaceConfig.h:95
std::unique_ptr< QQuickItem > contentItem
Pre-built QQuickItem.
Definition SurfaceConfig.h:59
QString debugName
Logged in state transitions. Defaults to Role::scopePrefix when empty.
Definition SurfaceConfig.h:165
Role role
Protocol-level defaults. Required.
Definition SurfaceConfig.h:49
Anchors effectiveAnchors() const noexcept
Definition SurfaceConfig.h:192
bool keepMappedOnHide
When true, Surface::hide() does NOT call QQuickWindow::hide(); the surface stays Qt-visible and the v...
Definition SurfaceConfig.h:139
std::optional< Layer > layerOverride
Definition SurfaceConfig.h:105