Phosphor
Qt6 / Wayland library suite for window-management tools
Loading...
Searching...
No Matches
Surface.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 <QObject>
10#include <QString>
11
12#include <memory>
13
14QT_BEGIN_NAMESPACE
15class QQuickWindow;
16QT_END_NAMESPACE
17
18namespace PhosphorLayer {
19
22class IScreenProvider;
25class SurfaceFactory;
26
42{
44 IQmlEngineProvider* engineProvider = nullptr; // Optional — nullptr = per-surface engine for contentUrl content
61};
62
104class PHOSPHORLAYER_EXPORT Surface : public QObject
105{
106 Q_OBJECT
107 Q_PROPERTY(State state READ state NOTIFY stateChanged FINAL)
108
109public:
110 enum class State {
111 Constructed,
112 Warming,
113 Shown,
114 Hidden,
115 Failed,
116 };
117
122 Q_ENUM(State)
123
124 ~Surface() override;
125
126 State state() const noexcept;
127 const SurfaceConfig& config() const noexcept;
147
167 [[nodiscard]] bool isLogicallyShown() const noexcept;
168
184public Q_SLOTS:
185 void show();
186 void hide();
190 void warmUp();
192
193public:
199 QQuickWindow* window() const noexcept;
200 ITransportHandle* transport() const noexcept;
202
203Q_SIGNALS:
207 void stateChanged(State newState);
208
220 void failed(const QString& reason);
221
237
238public:
256 class CtorToken
257 {
258 friend class SurfaceFactory;
259 CtorToken() = default;
260 };
261
262protected:
266 Surface(CtorToken, SurfaceConfig cfg, SurfaceDeps deps, QObject* parent);
267
268private:
269 Q_DISABLE_COPY_MOVE(Surface)
270
271 friend class SurfaceFactory;
272
273 class Impl;
274 std::unique_ptr<Impl> m_impl;
275};
276
277} // namespace PhosphorLayer
Abstracts the layer-shell protocol binding.
Definition ILayerShellTransport.h:111
Hook point for consumer-controlled QQmlEngine ownership policy.
Definition IQmlEngineProvider.h:40
Source-of-truth interface for the available QScreen set.
Definition IScreenProvider.h:62
Hook point for show/hide transitions on Surfaces.
Definition ISurfaceAnimator.h:51
Handle returned by attach(); lets the caller mutate post-show properties that the wlr-layer-shell pro...
Definition ILayerShellTransport.h:53
Stateless constructor for Surfaces.
Definition SurfaceFactory.h:35
Opaque construction token — only SurfaceFactory can create instances of it.
Definition Surface.h:257
friend class SurfaceFactory
Definition Surface.h:258
bool isLogicallyShown() const noexcept
Convenience: is the Surface in the logical "shown" state?
~Surface() override
Q_ENUM so QMetaEnum can stringify State values in log messages (State::Failed → "Failed") and so Q_PR...
friend class SurfaceFactory
Definition Surface.h:271
State state() const noexcept
void warmUp()
Create window + content (and, for contentUrl content, the engine that loads it), leave hidden.
State
Definition Surface.h:110
const SurfaceConfig & config() const noexcept
QQuickWindow * window() const noexcept
void stateChanged(State newState)
NOTIFY signal for the state Q_PROPERTY.
ITransportHandle * transport() const noexcept
Surface(CtorToken, SurfaceConfig cfg, SurfaceDeps deps, QObject *parent)
Protected so subclasses can forward a CtorToken through their own constructor.
void screenLost()
Emitted when the QScreen the Surface is bound to is removed from the IScreenProvider's list or destro...
void failed(const QString &reason)
Emitted once when transitioning to State::Failed.
void setKeyboardInteractivity(KeyboardInteractivity keyboard)
Change the surface's keyboard interactivity.
Definition SurfaceAnimator.h:26
KeyboardInteractivity
Keyboard focus policy (wlr-layer-shell v4 adds OnDemand).
Definition Role.h:51
Immutable per-surface configuration passed to SurfaceFactory::create().
Definition SurfaceConfig.h:47
Bundle of dependencies the Surface inherits from the factory.
Definition Surface.h:42
ILayerShellTransport * transport
Definition Surface.h:43
ISurfaceAnimator * animator
Phase-5 hook for show/hide visual transitions.
Definition Surface.h:60
IQmlEngineProvider * engineProvider
Definition Surface.h:44
IScreenProvider * screenProvider
Screen provider the Surface subscribes to for hot-unplug detection and its primary-screen fallback.
Definition Surface.h:49