Phosphor
Qt6 / Wayland library suite for window-management tools
Loading...
Searching...
No Matches
PopoutRequest.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
5#include <PhosphorPopout/phosphorpopout_export.h>
6
7#include <QObject>
8#include <QPointF>
9#include <QQmlComponent>
10#include <QScreen>
11#include <QString>
12#include <QVariantMap>
13#include <QtQmlIntegration/qqmlintegration.h>
14
15namespace PhosphorPopout {
16
17// Namespace metaobject so QML can see the Anchor and ExclusiveMode
18// enums. QML_ELEMENT on a Q_NAMESPACE publishes the NAMESPACE as the
19// QML type name, so after `import Phosphor.Popout` consumers reach the
20// values through it: `PhosphorPopout.Anchor.BarCenter` and
21// `PhosphorPopout.ExclusiveMode.Cooperative`. The enums are not in
22// scope unqualified — a bare `Anchor.BarCenter` is a ReferenceError.
23Q_NAMESPACE_EXPORT(PHOSPHORPOPOUT_EXPORT)
24QML_ELEMENT
25
26// Anchor on the host screen where the popout should appear. BarLeft,
27// BarCenter, and BarRight are convenience names tied to the bar
28// geometry the shell has chosen. The transport resolves them to
29// actual coordinates. ScreenCenter and AtPointer ignore the bar.
30// Custom forwards customAnchor verbatim.
31//
32// BarItem is the one anchor that depends on a value only the caller has:
33// it hangs below the bar like the other bar anchors, but centres on a
34// specific widget rather than on a fixed edge, reading customAnchor.x() as
35// that widget's horizontal centre in screen-local pixels. It is what a
36// popout summoned by one bar widget uses, so the panel opens under the
37// thing that was clicked. customAnchor.y() is ignored; the reserved band
38// decides the vertical, exactly as it does for BarLeft/Center/Right.
39// BarItemRight uses the same reserved band but aligns the panel's right
40// edge to customAnchor.x(), the invoking widget's right edge.
52Q_ENUM_NS(Anchor)
53
54// Exclusivity model. Driven by the arbitration policy in
55// PopoutController.
56//
57// Cooperative one per scope. Opening another Cooperative request
58// with the same scope closes the prior one. The
59// default for control center, launcher, calendar.
60//
61// Modal suppresses every Cooperative across every scope
62// while it's open. New Cooperative requests are
63// rejected with an empty handle. Used for OSDs and
64// confirm dialogs.
65//
66// Detached floats independent of the above. Ignored by scope
67// arbitration. Stays open when modals open and close.
68// Used for pinned overlays.
74Q_ENUM_NS(ExclusiveMode)
75
76// A popout open request. Stable id, content delegate, screen, anchor,
77// exclusivity, and forwarded props. Q_GADGET + QML_VALUE_TYPE so QML
78// callers can build one declaratively as `PopoutRequest { ... }`.
79//
80// One-shot value type. Mutating fields after passing to
81// IPopoutService::open has no effect on the live popout; rebuild and
82// re-open if the popout state needs to change. Fields use MEMBER
83// Q_PROPERTY without NOTIFY because the request is read once at open
84// time and never re-read.
85//
86// Lifetime of `content`. The caller retains ownership of the
87// QQmlComponent. The caller must keep it alive until the corresponding
88// popoutClosed signal fires for the handle that open() returned.
89// Deleting the component earlier will dangle inside the transport.
90class PHOSPHORPOPOUT_EXPORT PopoutRequest
91{
92 Q_GADGET
93 QML_VALUE_TYPE(popoutRequest)
94 // STRUCTURED_VALUE is what lets QML build one from an object literal,
95 // which is how every caller actually passes a request:
96 // `Popouts.toggle({ "popoutId": "power", ... })`. Without it QML has no
97 // conversion from a JS object to this gadget and the call fails with
98 // "Passing incompatible arguments to C++ functions from JavaScript is
99 // not allowed" — a TypeError at the call site, not a compile error.
100 QML_STRUCTURED_VALUE
101
102 Q_PROPERTY(QString popoutId MEMBER popoutId)
103 Q_PROPERTY(QQmlComponent* content MEMBER content)
104 Q_PROPERTY(QScreen* targetScreen MEMBER targetScreen)
105 Q_PROPERTY(PhosphorPopout::Anchor anchor MEMBER anchor)
106 Q_PROPERTY(QPointF customAnchor MEMBER customAnchor)
108 Q_PROPERTY(QString scope MEMBER scope)
109 Q_PROPERTY(bool keyboardFocus MEMBER keyboardFocus)
110 Q_PROPERTY(bool exclusiveKeyboard MEMBER exclusiveKeyboard)
111 Q_PROPERTY(bool dismissOnFocusLoss MEMBER dismissOnFocusLoss)
112 Q_PROPERTY(QVariantMap props MEMBER props)
113
114public:
115 // Default cooperative-scope identifier. Single shared instance so
116 // every default-constructed PopoutRequest reuses one refcounted
117 // QString rather than allocating a fresh "default" per construction.
118 // Shells issuing popouts on every focus change benefit from this.
119 // A function-local static, not a header-scope inline QString: the
120 // inline form gains a static initializer plus exit-time destructor in
121 // every linking binary and sits in SIOF territory; the local static
122 // initializes on first use instead.
123 static const QString& defaultScope()
124 {
125 static const QString scope = QStringLiteral("default");
126 return scope;
127 }
128
129 // Stable identifier for this popout. Examples are "control-center"
130 // or "launcher". Used by isOpen, toggle, and closeAll. Two requests
131 // with the same id are treated as the same logical popout. Toggle
132 // toggles the existing instance rather than opening a second.
133 QString popoutId;
134
135 // QML component that renders the popout content. Owned by the
136 // caller. The popout service does not take ownership. May be null
137 // only when the caller has wired a custom transport that doesn't
138 // need a QML delegate. Examples are tests and native-rendered
139 // overlays. The caller must keep the component alive until
140 // popoutClosed fires for the returned handle.
141 QQmlComponent* content = nullptr;
142
143 // Screen to open on. Null means "pick the active screen". The
144 // transport defines that meaning. Examples are the focused output
145 // or the last-used output.
146 QScreen* targetScreen = nullptr;
147
148 // Where the popout sits. The default is BarCenter, which used to be a
149 // harmless synonym for "centred" because every anchor centred; it now
150 // routes to the bar-hang branch, so a caller that expresses no opinion
151 // gets a popout hanging below the bar rather than in the middle of the
152 // screen. That IS the right default for this shell, where every popout
153 // is triggered from the bar, but it is no longer a neutral value: a
154 // caller that wants the middle of the screen must ask for ScreenCenter.
156
157 // Used when anchor == Custom (both coordinates, screen-local) and when
158 // anchor == BarItem (x only, the anchoring widget's horizontal centre).
159 // Interpreted by the transport
160 // in screen-local coordinates. A default-constructed QPointF
161 // (0, 0) is a valid screen-origin anchor and the transport will
162 // place the popout there; callers using Anchor::Custom must
163 // populate this explicitly or accept origin placement.
165
167
168 // Cooperative-mode grouping. Two Cooperative popouts in different
169 // scopes can be open at the same time. Defaults to "default" so
170 // callers that don't care all share one scope. Common patterns
171 // are "default" for one popout per process, or "screen-DP-1"
172 // when the shell wants one cooperative popout per output.
173 QString scope = defaultScope();
174
175 // Whether the popout should request keyboard focus on open.
176 // Modals typically yes. Cooperatives sometimes no. The bar's
177 // calendar popout does not need keyboard while it's just showing
178 // dates.
179 bool keyboardFocus = true;
180
181 // Whether the popout must hold the keyboard EXCLUSIVELY while open,
182 // without being Modal: no scrim, other popouts stay allowed, but the
183 // compositor routes every key here until the surface goes away. The
184 // case is a credential prompt (polkit) that cannot lose focus to a
185 // click on another window. Ignored when keyboardFocus is false.
186 bool exclusiveKeyboard = false;
187
188 // Whether the popout should close when focus moves away from it.
189 // Toggleable so plugins can pin a popout open. Examples are the
190 // user dragging a value or focus moving to a dialog the popout
191 // spawned.
193
194 // Arbitrary props forwarded to the QML delegate via the transport.
195 // The transport plumbs these into the delegate's properties before
196 // showing the surface.
197 QVariantMap props;
198};
199
200} // namespace PhosphorPopout
Definition PopoutRequest.h:91
bool dismissOnFocusLoss
Definition PopoutRequest.h:192
ExclusiveMode exclusive
Definition PopoutRequest.h:166
QScreen * targetScreen
Definition PopoutRequest.h:146
Anchor anchor
Definition PopoutRequest.h:155
bool keyboardFocus
Definition PopoutRequest.h:179
QString popoutId
Definition PopoutRequest.h:133
QPointF customAnchor
Definition PopoutRequest.h:164
bool exclusiveKeyboard
Definition PopoutRequest.h:186
QQmlComponent * content
Definition PopoutRequest.h:141
static const QString & defaultScope()
Definition PopoutRequest.h:123
QVariantMap props
Definition PopoutRequest.h:197
QString scope
Definition PopoutRequest.h:173
Definition IPopoutService.h:11
ExclusiveMode
Definition PopoutRequest.h:69
@ Detached
Definition PopoutRequest.h:72
@ Cooperative
Definition PopoutRequest.h:70
@ Modal
Definition PopoutRequest.h:71
Anchor
Definition PopoutRequest.h:41
@ BarLeft
Definition PopoutRequest.h:42
@ BarItem
Definition PopoutRequest.h:45
@ BarCenter
Definition PopoutRequest.h:43
@ AtPointer
Definition PopoutRequest.h:47
@ Custom
Definition PopoutRequest.h:48
@ BarItemRight
Definition PopoutRequest.h:50
@ BarRight
Definition PopoutRequest.h:44
@ BottomCenter
Definition PopoutRequest.h:49
@ ScreenCenter
Definition PopoutRequest.h:46