Phosphor
Qt6 / Wayland library suite for window-management tools
Loading...
Searching...
No Matches
PopoutController.h
Go to the documentation of this file.
1// SPDX-FileCopyrightText: 2026 fuddlesworth
2// SPDX-License-Identifier: LGPL-2.1-or-later
3#pragma once
4
7#include <PhosphorPopout/phosphorpopout_export.h>
8
9#include <QObject>
10#include <QString>
11#include <QtQmlIntegration/qqmlintegration.h>
12
13#include <memory>
14
15namespace PhosphorPopout {
16
18
19// Concrete IPopoutService. Owns the arbitration state machine and
20// delegates surface creation to an injected IPopoutTransport. One
21// instance per shell process. Registered as a QML singleton so QML
22// callers reach the same arbiter as C++ callers. A separate instance
23// per engine would defeat the single-arbiter guarantee. Consumers that
24// want a shared instance across engines must use
25// qmlRegisterSingletonInstance to pin the same C++ pointer in each.
26//
27// Arbitration rules.
28//
29// Cooperative At most one Cooperative popout per scope. Opening a
30// new Cooperative request in the same scope closes the
31// prior one before opening the new one. Different
32// scopes are independent. A second open with a
33// popoutId that is already open is rejected with an
34// empty handle regardless of scope. Callers that want
35// to reopen by id must close first or use toggle.
36//
37// Modal While ANY Modal is open, every new Cooperative
38// request is rejected. open returns an empty string.
39// Existing Cooperative popouts are closed when the
40// first Modal opens. They are NOT restored when the
41// modal closes. The user explicitly demanded the
42// modal. Restoring would clobber whatever they focus
43// next. Modal-on-Modal stacks, but a second Modal
44// with the same popoutId is rejected like any other
45// same-id collision.
46//
47// Detached Ignored by scope arbitration. Detached popouts open,
48// stay open across cooperative-swap and modal-open
49// events, and only close when explicitly closed or
50// when their underlying surface dismisses itself.
51class PHOSPHORPOPOUT_EXPORT PopoutController : public QObject, public IPopoutService
52{
53 Q_OBJECT
54 // QML-bindable mirror of isModalActive(). UIs binding a "disable
55 // popout-trigger buttons while a modal is up" rule reach this
56 // directly via `Popouts.modalActive` instead of wiring an
57 // imperative onModalActiveChanged handler.
58 Q_PROPERTY(bool modalActive READ isModalActive NOTIFY modalActiveChanged)
59 QML_ELEMENT
60 // PopoutController requires a transport injected at construction.
61 // QML cannot default-construct it. The type is registered for
62 // type-annotation visibility only. Production wiring uses
63 // qmlRegisterSingletonInstance from C++ to publish a pre-built
64 // instance to QML. The demo uses a context property.
65 QML_UNCREATABLE(
66 "Construct PopoutController in C++ with an IPopoutTransport, then expose via qmlRegisterSingletonInstance")
67
68public:
69 // transport must be non-null. The controller does not own the
70 // transport. The caller must keep the transport alive at least as
71 // long as the controller. Null transport aborts via qFatal in both
72 // debug and release builds; a silent crash on the first transport
73 // method call would be harder to diagnose than the explicit abort.
74 explicit PopoutController(IPopoutTransport* transport, QObject* parent = nullptr);
75 ~PopoutController() override;
76
77 // QObject blocks copy via Q_OBJECT but leaves move ill-formed
78 // rather than deleted. Make the intent explicit so static
79 // analyzers and readers see both copy and move are forbidden,
80 // matching the disable-copy-move pattern on IPopoutService /
81 // IPopoutTransport.
82 Q_DISABLE_COPY_MOVE(PopoutController)
83
84 // IPopoutService. Re-declared as Q_INVOKABLE so QML callers reach
85 // them through this concrete type. The base interface has no
86 // Q_OBJECT/Q_GADGET so it cannot carry Q_INVOKABLE itself.
87 [[nodiscard]] Q_INVOKABLE QString open(const PopoutRequest& request) override;
88 Q_INVOKABLE void close(const QString& handle) override;
89 [[nodiscard]] Q_INVOKABLE QString toggle(const PopoutRequest& request) override;
90 [[nodiscard]] Q_INVOKABLE bool isOpen(const QString& popoutId) const override;
91 Q_INVOKABLE void closeAll() override;
92
93 // Diagnostic accessor. Returns the handle for a known popoutId, or
94 // empty string if the popoutId isn't currently open. Useful from
95 // QML for binding visible-state badges to a specific popout.
96 [[nodiscard]] Q_INVOKABLE QString handleFor(const QString& popoutId) const;
97
98 // True if any Modal popout is currently open. Cooperative requests
99 // issued while this is true are rejected.
100 [[nodiscard]] Q_INVOKABLE bool isModalActive() const;
101
102Q_SIGNALS:
103 // Fired after a popout is opened. popoutId is the request's
104 // popoutId. handle is the transport-assigned identifier. Use
105 // handle for subsequent close calls.
106 void popoutOpened(const QString& popoutId, const QString& handle);
107
108 // Fired after a popout closes. Fires regardless of who initiated
109 // the close. The initiator may be the caller, arbitration policy,
110 // or a transport-driven dismiss.
111 void popoutClosed(const QString& popoutId, const QString& handle);
112
113 // Fired when modal-active state changes. UIs that want to disable
114 // their popout-trigger buttons while a modal is up can bind here.
116
117private:
118 struct Impl;
119 std::unique_ptr<Impl> d;
120};
121
122} // namespace PhosphorPopout
Definition IPopoutTransport.h:33
Definition PopoutController.h:52
void popoutClosed(const QString &popoutId, const QString &handle)
void popoutOpened(const QString &popoutId, const QString &handle)
Definition PopoutRequest.h:91
Definition IPopoutService.h:11