Phosphor
Qt6 / Wayland library suite for window-management tools
Loading...
Searching...
No Matches
IPopoutTransport.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
6#include <PhosphorPopout/phosphorpopout_export.h>
7
8#include <QString>
9#include <QtCore/qtclasshelpermacros.h> // Q_DISABLE_COPY_MOVE
10
11#include <functional>
12
13namespace PhosphorPopout {
14
15// Transport seam between the arbitration policy in PopoutController
16// and the actual layer-shell surface stack. Production uses a
17// transport backed by phosphor-layer's SurfaceFactory. Tests inject
18// a fake.
19//
20// The transport owns the lifetime of every surface it creates. The
21// controller hands it a PopoutRequest and gets back an opaque string
22// handle. Handles are globally unique within the transport instance.
23// closeSurface is idempotent. Calling it twice or on an already-
24// dismissed surface is a no-op.
25//
26// The dismissed callback notifies the controller when a surface goes
27// away on its own initiative. Possible triggers include focus loss,
28// a click outside the surface, the QML delegate calling close, or
29// compositor revocation. The controller uses that signal to update
30// its arbitration state without re-issuing closeSurface back to the
31// transport. Re-issuing would loop.
32class PHOSPHORPOPOUT_EXPORT IPopoutTransport
33{
34public:
35 IPopoutTransport() = default;
36 virtual ~IPopoutTransport() = default;
37 Q_DISABLE_COPY_MOVE(IPopoutTransport)
38
39 // Create and show a popout surface for the request. Returns an
40 // opaque handle the controller uses for later close and lookup.
41 // The empty string is a sentinel meaning the transport refused
42 // to open. Reasons include an invalid screen, missing content,
43 // or layer-shell being unavailable. The controller treats an
44 // empty return as "open failed" and does not update its
45 // arbitration tables.
46 [[nodiscard]] virtual QString openSurface(const PopoutRequest& request) = 0;
47
48 // Tear down the surface for handle. No-op if the handle is
49 // unknown or already closed. Must NOT invoke the dismissed
50 // callback for this handle. The callback is reserved for
51 // surfaces that close themselves. The controller may call
52 // closeSurface synchronously from inside the dismissed callback
53 // for OTHER handles (e.g., during arbitration-driven teardown);
54 // the controller's re-entrancy guard handles this case.
55 virtual void closeSurface(const QString& handle) = 0;
56
57 // Install a callback fired when a surface dismisses itself. The
58 // controller installs exactly one callback per transport during
59 // construction and detaches it via an empty std::function in its
60 // destructor. Implementations must replace any prior callback when
61 // called, so the controller's detach-on-destruction cannot leave
62 // a dangling lambda behind. The callback receives the handle of
63 // the dismissed surface. The transport must NOT call this for
64 // surfaces closed via closeSurface. Those are caller-initiated
65 // and the controller already knows. Transports also must NOT
66 // synchronously invoke this from inside openSurface or
67 // closeSurface; the controller has a re-entrancy guard for
68 // misbehaving transports but well-behaved transports defer
69 // dismiss events to the next event-loop tick.
70 //
71 // Thread affinity: the callback must be invoked on the same
72 // thread the PopoutController lives on (typically the GUI
73 // thread). The controller mutates internal tables synchronously
74 // from the callback and does not lock. Transports that observe
75 // surface-dismissed events on a Wayland reader or background
76 // thread must marshal via QMetaObject::invokeMethod or a queued
77 // signal-slot connection before firing the callback.
78 virtual void setSurfaceDismissedCallback(std::function<void(const QString&)> callback) = 0;
79};
80
81} // namespace PhosphorPopout
virtual ~IPopoutTransport()=default
virtual QString openSurface(const PopoutRequest &request)=0
virtual void setSurfaceDismissedCallback(std::function< void(const QString &)> callback)=0
virtual void closeSurface(const QString &handle)=0
Definition PopoutRequest.h:91
Definition IPopoutService.h:11