Phosphor
Qt6 / Wayland library suite for window-management tools
Loading...
Searching...
No Matches
ShellHost.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// ShellHost - owns the per-screen layer-shell shell-state map and the
7// lifecycle bookkeeping (create / destroy / rekey / sync) that any
8// multi-slot overlay consumer needs.
9//
10// Phase 2 foundation: the type holds a `QHash<QString, ShellState>`
11// keyed by effective screen id plus a sticky creation-failure set
12// (spam-guard for compositors that refuse a shell on a given screen).
13// Method moves from OverlayService land in subsequent Phase 2 commits;
14// this commit pins the shape of the public type and its accessors so
15// the daemon can construct a ShellHost as a member alongside its
16// existing per-screen state.
17
19#include <PhosphorOverlay/phosphoroverlay_export.h>
20
22#include <PhosphorLayer/Role.h>
23
24#include <QHash>
25#include <QObject>
26#include <QSet>
27#include <QString>
28#include <QStringList>
29#include <QStringView>
30
31#include <functional>
32
33class QScreen;
34
35namespace PhosphorLayer {
36class Surface;
37} // namespace PhosphorLayer
38
39namespace PhosphorOverlay {
40
58[[nodiscard]] PHOSPHOROVERLAY_EXPORT PhosphorLayer::Role makePerInstanceRole(const PhosphorLayer::Role& base,
59 QStringView screenId, quint64 generation);
60
61class PHOSPHOROVERLAY_EXPORT ShellHost : public QObject
62{
63 Q_OBJECT
64
65public:
69 {
70 bool visible = false;
71 bool inputGrabbing = false;
72 bool keyboardGrabbing = false;
73 };
74
79 using SurfaceFactory = std::function<PhosphorLayer::Surface*(const QString& screenId, QScreen* physScreen)>;
80
86 using PostCreateCallback = std::function<void(const QString& screenId, ShellState& state)>;
87
99 using PreDestroyCallback = std::function<void(const QString& screenId)>;
100
101 explicit ShellHost(QObject* parent = nullptr);
102 ~ShellHost() override;
103
108
111
114
120
154 ShellState* ensureShell(const QString& screenId, QScreen* physScreen);
155
161 void destroyShell(const QString& screenId);
162
244 void syncSurfaceState(const QString& screenId, const SurfaceStateWants& wants);
245
277 bool rekey(const QString& oldKey, const QString& newKey);
278
285
310 void hideSlot(const QString& screenId, const QString& slotKey, std::function<void()> completion = {});
311
320 ShellState& getOrCreateStateFor(const QString& screenId);
321
325 const ShellState* stateFor(const QString& screenId) const;
326
328 bool hasState(const QString& screenId) const;
329
333 void removeState(const QString& screenId);
334
337 QStringList screenIds() const;
338
343 void markFailure(const QString& screenId);
344 void clearFailure(const QString& screenId);
345 bool hasFailure(const QString& screenId) const;
346
352 QStringList failureScreenIds() const;
353
354private:
371 QHash<QString, ShellState*> m_states;
372 QSet<QString> m_creationFailed;
373 SurfaceFactory m_surfaceFactory;
374 PostCreateCallback m_postCreateCallback;
375 PreDestroyCallback m_preDestroyCallback;
376 PhosphorAnimationLayer::SurfaceAnimator* m_surfaceAnimator = nullptr;
377};
378
379} // namespace PhosphorOverlay
Concrete PhosphorLayer::ISurfaceAnimator driving show/hide via phosphor-animation Profiles.
Definition SurfaceAnimator.h:121
One layer-shell surface with a managed lifecycle.
Definition Surface.h:105
std::function< void(const QString &screenId)> PreDestroyCallback
Hook fired before the library deletes the shell surface.
Definition ShellHost.h:99
QStringList failureScreenIds() const
Snapshot of every screen id currently flagged as failed.
const ShellState * stateFor(const QString &screenId) const
Read-only accessor.
void markFailure(const QString &screenId)
Sticky per-screen creation-failure flag.
ShellHost(QObject *parent=nullptr)
void hideSlot(const QString &screenId, const QString &slotKey, std::function< void()> completion={})
Animator-driven slot hide for the slot keyed by slotKey on the shell for screenId.
void destroyShell(const QString &screenId)
Tear down the shell for screenId.
void registerConfigForRole(const PhosphorLayer::Role &role, PhosphorAnimationLayer::SurfaceAnimator::Config config)
Register an animator config under role.
std::function< PhosphorLayer::Surface *(const QString &screenId, QScreen *physScreen)> SurfaceFactory
Consumer-provided factory for the per-screen layer-shell surface.
Definition ShellHost.h:79
bool hasFailure(const QString &screenId) const
void syncSurfaceState(const QString &screenId, const SurfaceStateWants &wants)
Reconcile the shell's mapped state + pointer-input region with the consumer's view of what's live on ...
void setPostCreateCallback(PostCreateCallback callback)
Inject the post-create hook (optional but typically used).
void removeState(const QString &screenId)
Remove the ShellState for screenId entirely.
ShellState * ensureShell(const QString &screenId, QScreen *physScreen)
All methods on this class must be called on the GUI thread.
bool hasState(const QString &screenId) const
True if a ShellState exists (live or zeroed) for screenId.
QStringList screenIds() const
Enumerate every screen id with a ShellState entry (in arbitrary QHash iteration order).
void setSurfaceFactory(SurfaceFactory factory)
Inject the per-screen surface factory.
void setPreDestroyCallback(PreDestroyCallback callback)
Inject the pre-destroy hook (optional).
bool rekey(const QString &oldKey, const QString &newKey)
Move the ShellState entry from oldKey to newKey, preserving the underlying heap-allocated state objec...
std::function< void(const QString &screenId, ShellState &state)> PostCreateCallback
Hook fired after a fresh shell surface + window are recorded in the ShellState.
Definition ShellHost.h:86
ShellState & getOrCreateStateFor(const QString &screenId)
Read-write accessor.
void clearFailure(const QString &screenId)
void setSurfaceAnimator(PhosphorAnimationLayer::SurfaceAnimator *animator)
Inject the SurfaceAnimator that drives every slot's show/hide leg.
Definition ShellState.h:41
Definition SurfaceAnimator.h:26
Definition ShellHost.h:39
PHOSPHOROVERLAY_EXPORT PhosphorLayer::Role makePerInstanceRole(const PhosphorLayer::Role &base, QStringView screenId, quint64 generation)
Build a per-instance PhosphorLayer::Role by appending -{screenId}-{generation} to base's scope prefix...
Per-role profile + scale tuning bundle.
Definition SurfaceAnimator.h:156
Value type describing a surface's protocol-level configuration.
Definition Role.h:77
What the consumer's live content wants from the shell surface on one screen.
Definition ShellHost.h:69
bool keyboardGrabbing
Definition ShellHost.h:72
bool inputGrabbing
Definition ShellHost.h:71
bool visible
Definition ShellHost.h:70