Phosphor
Qt6 / Wayland library suite for window-management tools
Loading...
Searching...
No Matches
IPopoutService.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
11namespace PhosphorPopout {
12
13// Service contract for centralized popout coordination.
14//
15// A shell instantiates exactly one IPopoutService and exposes it to
16// QML and to any C++ caller that wants to open a transient surface.
17// The default concrete implementation is PopoutController. Alternate
18// implementations plug in by satisfying this interface.
19//
20// The service is the single arbiter for popout lifetime, focus, and
21// exclusivity policy. The transport seam handles the actual surface
22// creation. Arbitration lives here. This split is what avoids the
23// "two popups fighting over a Wayland grab" bug class. Every
24// transient surface in the shell routes through the same arbiter,
25// so conflicting open requests are resolved consistently.
26//
27// The interface stays pure-virtual to keep tests cheap. No QObject
28// base. No signal/slot machinery exposed at the abstract layer.
29// Concrete implementations bring their own QObject when notifications
30// are needed.
31//
32// Alternate implementations must re-mark their overrides as Q_INVOKABLE
33// (the macro can only attach to a Q_OBJECT or Q_GADGET, neither of
34// which this interface uses) if QML callers are to reach them through
35// a context-property or singleton handle. The default concrete
36// implementation, PopoutController, does this.
37class PHOSPHORPOPOUT_EXPORT IPopoutService
38{
39public:
40 IPopoutService() = default;
41 virtual ~IPopoutService() = default;
42 Q_DISABLE_COPY_MOVE(IPopoutService)
43
44 // Open a popout per the request. Returns an opaque handle on
45 // success. Returns an empty string when the request was rejected
46 // by arbitration policy or by the transport. An arbitration
47 // rejection happens when a Cooperative request is issued while
48 // a Modal popout is open. A transport rejection happens on an
49 // invalid screen or missing content. Callers should not assume
50 // an empty handle means an error. It can also mean policy says
51 // no right now.
52 [[nodiscard]] virtual QString open(const PopoutRequest& request) = 0;
53
54 // Close the popout with handle. No-op if the handle is unknown,
55 // already closed, or never opened in the first place.
56 virtual void close(const QString& handle) = 0;
57
58 // Toggle a popout by its stable popoutId. If a popout with the
59 // request's popoutId is currently open, close it. Otherwise open
60 // it per the request. Returns the handle of the newly opened
61 // popout. Returns empty string if the call closed an existing
62 // popout, or if the open was rejected by policy.
63 [[nodiscard]] virtual QString toggle(const PopoutRequest& request) = 0;
64
65 // True if any popout with this popoutId is currently open. Note
66 // that "open" is independent of "visible to the user". A
67 // Cooperative popout in scope A is open even if a Modal is
68 // currently suppressing its successors elsewhere.
69 [[nodiscard]] virtual bool isOpen(const QString& popoutId) const = 0;
70
71 // Close every popout the service is currently tracking. Useful
72 // on shell teardown and for plugins that want to enforce a clean
73 // slate. One use case is before showing a session-lock surface.
74 virtual void closeAll() = 0;
75};
76
77} // namespace PhosphorPopout
virtual QString open(const PopoutRequest &request)=0
virtual ~IPopoutService()=default
virtual void close(const QString &handle)=0
virtual QString toggle(const PopoutRequest &request)=0
virtual bool isOpen(const QString &popoutId) const =0
Definition PopoutRequest.h:91
Definition IPopoutService.h:11