Phosphor
Qt6 / Wayland library suite for window-management tools
Loading...
Searching...
No Matches
ShellEngine.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
6#include <PhosphorShell/phosphorshell_export.h>
7
8#include <QHash>
9#include <QMargins>
10#include <QObject>
11#include <QPointer>
12#include <QScreen>
13#include <QSize>
14#include <QString>
15#include <QUrl>
16#include <QVariantMap>
17
18#include <functional>
19#include <memory>
20#include <vector>
21
22QT_BEGIN_NAMESPACE
23class QFileSystemWatcher;
24class QQmlEngine;
25class QTimer;
26QT_END_NAMESPACE
27
28namespace PhosphorLayer {
29class IScreenProvider;
30class Surface;
31class SurfaceFactory;
32} // namespace PhosphorLayer
33
34namespace PhosphorShell {
35
36class PanelWindow;
38class ScreenModel;
39class ShellGlobal;
40
41class PHOSPHORSHELL_EXPORT ShellEngine : public QObject
42{
43 Q_OBJECT
44public:
54
55 explicit ShellEngine(Deps deps, QObject* parent = nullptr);
56 ~ShellEngine() override;
57
76 bool load(const QUrl& shellUrl);
77
85 [[nodiscard]] QQmlEngine* engine() const;
86
109 using EngineHook = std::function<void(QQmlEngine*)>;
111
122 [[nodiscard]] QMargins reservedMarginsFor(QScreen* screen) const;
123
124Q_SIGNALS:
142
147 void loaded();
150 void reloaded();
158 void failed(const QString& reason);
159
160public Q_SLOTS:
163
164private Q_SLOTS:
165 void onFileChanged();
166 void onScreensChanged();
167
168private:
173 [[nodiscard]] bool buildAndMaterialize();
180 [[nodiscard]] bool materializePanels(QString* failureReason);
184 static void installDynamicAutoFit(PanelWindow* panel, PhosphorLayer::Surface* surface, QSize screenSize);
190 static void installInputRegion(PanelWindow* panel, PhosphorLayer::Surface* surface);
191 void teardown();
192 void setupWatcher();
193 void savePersistentState();
194 void restorePersistentState();
204 [[nodiscard]] QList<PersistentProperties*> collectPersistentProperties() const;
205
206 QUrl m_shellUrl;
207 std::unique_ptr<QQmlEngine> m_engine;
208 std::unique_ptr<QObject> m_rootObject;
209 // Non-owning observer of the QML root. When the root is a PanelWindow,
210 // ownership transfers to a Surface and m_rootObject is released — but
211 // findChildren scans (PersistentProperties save/restore) still need a
212 // pointer to walk the tree. QPointer auto-clears when the wrapper
213 // window destroys the root.
214 QPointer<QObject> m_rootRef;
215 Deps m_deps;
216 std::vector<std::unique_ptr<PhosphorLayer::Surface>> m_surfaces;
217 // The panels materialized in this generation, in creation order. They
218 // are owned by their Surface's wrapper window, not by this, so these
219 // are QPointers: a surface torn down out of band leaves a null entry
220 // rather than a dangling one. Kept so the PersistentProperties scans
221 // can reach inside a panel that was detached from the QML root.
222 std::vector<QPointer<PanelWindow>> m_panels;
223 // What each materialized panel reserved, for reservedMarginsFor().
224 // Recorded beside the surface rather than re-derived from it: a
225 // Surface exposes its window, not the PanelWindow it adopted, and the
226 // zone actually sent to the compositor is the Role's, which is
227 // computed once at materialization and would otherwise be lost.
228 // Cleared with m_surfaces. QPointer: a screen can die before the
229 // reload that rebuilds this list, and a dead entry must read as "no
230 // screen", not as a match.
231 struct ReservedEdge
232 {
233 QPointer<QScreen> screen;
234 int edge = 0; // PanelWindow::Edge, kept as int to spare the header the include
235 int zone = 0;
236 };
237 std::vector<ReservedEdge> m_reserved;
238 QFileSystemWatcher* m_watcher = nullptr;
239 QTimer* m_reloadTimer = nullptr;
240 ScreenModel* m_screenModel = nullptr;
241 ShellGlobal* m_shellGlobal = nullptr;
242 QHash<QString, QVariantMap> m_persistentState;
243 std::vector<EngineHook> m_engineHooks;
244};
245
246} // namespace PhosphorShell
Source-of-truth interface for the available QScreen set.
Definition IScreenProvider.h:62
Stateless constructor for Surfaces.
Definition SurfaceFactory.h:35
One layer-shell surface with a managed lifecycle.
Definition Surface.h:105
Definition PanelWindow.h:23
Definition PersistentProperties.h:14
Definition ScreenModel.h:25
void requestReload()
Coalesced rebuild for configuration changes affecting surface geometry.
QMargins reservedMarginsFor(QScreen *screen) const
The space this shell's own panels reserve on screen, per edge: the largest exclusive zone advertised ...
void aboutToReload()
Emitted at the very top of a hot reload, BEFORE any teardown.
void reloaded()
A successful rebuild after a file or screen change, including the first successful build following a ...
void addEngineHook(EngineHook hook)
std::function< void(QQmlEngine *)> EngineHook
Register a callback that fires whenever a fresh QQmlEngine is created — at startup AND on hot-reload ...
Definition ShellEngine.h:109
bool load(const QUrl &shellUrl)
Build the shell from shellUrl.
QQmlEngine * engine() const
The current QML engine, or null before a successful load and after a failed one.
void loaded()
A successful load() call.
void failed(const QString &reason)
Something went wrong, with a human-readable reason.
ShellEngine(Deps deps, QObject *parent=nullptr)
Definition ShellGlobal.h:30
Definition SurfaceAnimator.h:26
Definition Environment.h:11
Definition ShellEngine.h:46
PhosphorLayer::IScreenProvider * screenProvider
Definition ShellEngine.h:48
QString shellName
The app's name, the one its ShellLoader takes: the layer-shell scope prefix of every panel and the di...
Definition ShellEngine.h:52
PhosphorLayer::SurfaceFactory * surfaceFactory
Definition ShellEngine.h:47