Centralised popout coordinator for Phosphor shells. Owns the single arbiter for popout lifetime, focus, and exclusivity policy across every transient surface in the shell.
A desktop shell has many transient surfaces. Examples include the control center, launcher, calendar, notification history, OSDs, and tray menus. Each one needs a Wayland layer-shell surface, keyboard- focus arbitration, screen affinity, exclusive-zone handling, a dismiss-on-focus-loss behaviour, and open/close animations. Letting each surface reinvent that machinery produces the "two popups fighting over a Wayland grab" bug class. phosphor-popout is the one place every popout request flows through so policy is resolved consistently.
| Type | Purpose |
|---|---|
| PhosphorPopout::PopoutRequest | Value type. Q_GADGET, registered as QML value type popoutRequest. Describes a popout to open: id, content, screen, anchor, exclusivity, scope, focus flags, props |
| PhosphorPopout::ExclusiveMode | Cooperative / Modal / Detached arbitration modes. Q_ENUM_NS, reachable from QML as ExclusiveMode.Cooperative etc. |
| PhosphorPopout::Anchor | Where on the screen the popout anchors. Values are BarLeft, BarCenter, BarRight, ScreenCenter, AtPointer, Custom. Q_ENUM_NS |
| PhosphorPopout::IPopoutService | Abstract service. Methods are open, close, toggle, isOpen, closeAll |
| PhosphorPopout::IPopoutTransport | Transport seam. Implementations create, tear down, and track layer-shell surfaces. Notifies the controller on self-dismiss |
| PhosphorPopout::PopoutController | Concrete IPopoutService. Owns the arbitration state machine and delegates surface creation to an injected transport. Registered as a QML element but marked uncreatable. Instantiate from C++ and publish via qmlRegisterSingletonInstance |
| Phosphor.Popout.PopoutHost (QML) | Transport-agnostic wrapper for popout content. Owns the open/close opacity-plus-scale animation, the backdrop dim, and the click-outside dismiss. Both transports instantiate this host wrapping the content delegate |
| Member | Direction | Purpose |
|---|---|---|
| contentComponent: Component | property | A QML Component the host instantiates inline via a Loader. Mutually exclusive with contentItem |
| contentItem: Item | property | A pre-built Item the host reparents under its content frame. Wins over contentComponent if both are set |
| open: bool | property | Drives the show/hide animation. The transport sets this true after the surface is parented and false to begin teardown |
| dismissOnClickOutside: bool | property | When true, a click on the backdrop sets open = false. The transport wires this from PopoutRequest.dismissOnFocusLoss |
| keyboardFocus: bool | property | Whether the popout takes the keyboard while open. The transport wires this from PopoutRequest.keyboardFocus. Separate from dismissOnClickOutside, since wanting the keyboard and being dismissible are different questions. A host with this false receives no key events at all, so Escape does not dismiss it either and click-outside is its only self-dismissal route |
| backdropColor: color | property | Background dim color. The transport binds a scrim for Modal, a lighter dim for Cooperative, transparent for Detached |
| dismiss() | function | Content delegates several levels deep can call this to close the popout without walking the parent chain. The transport injects a _popoutHost reference on the content, and the content calls _popoutHost.dismiss() |
| dismissed() | signal | Emitted after the close animation finishes. Fires once per open-then-close cycle, so transports that reuse a single host across many popouts get a fresh dismissed each time. Also fires once on Component.onDestruction if the host had ever been opened and is torn down before the close-animation timer emits dismissed itself, so transport bookkeeping never leaks a handle when a popout is destroyed mid-cycle. A host that is constructed and destroyed without ever having open driven true does NOT fire dismissed, so transports that pre-build and discard surfaces don't see a phantom dismissed in that case. The transport's dismissed callback fires through here so the bookkeeping lines up with the visual |
C++. Wire a controller to a transport and route a request.
#include <PhosphorPopout/PhosphorPopout.h>
#include <QObject>
using namespace PhosphorPopout;
MyPopoutTransport transport(...); // implements IPopoutTransport
PopoutController controller(&transport); // transport must outlive the controller
QObject::connect(&controller, &PopoutController::popoutOpened,
[](const QString& id, const QString& handle) {
qDebug() << "opened" << id << "->" << handle;
});
QQmlComponent* controlCenterComponent = ...; // caller owns; keep alive until popoutClosed
PopoutRequest req;
req.popoutId = QStringLiteral("control-center");
req.content = controlCenterComponent;
req.anchor = Anchor::BarRight; // BarLeft / BarCenter / BarRight / ScreenCenter
// / AtPointer / Custom. Custom uses req.customAnchor.
req.exclusive = ExclusiveMode::Cooperative;
const QString handle = controller.open(req); // empty if rejectedQML. Toggle from a button. Register the controller via qmlRegisterSingletonInstance in your engine setup so the whole UI sees the same arbiter. The example below assumes the singleton is registered as Popouts.
import QtQuick
import QtQuick.Controls
import Phosphor.Popout
ToolButton {
text: qsTr("Toggle calendar")
Component {
id: calendarComponent
Rectangle { implicitWidth: 320; implicitHeight: 220; color: "white" }
}
onClicked: Popouts.toggle({
"popoutId": "calendar",
"content": calendarComponent,
"anchor": PhosphorPopout.Anchor.BarCenter,
"exclusive": PhosphorPopout.ExclusiveMode.Cooperative
})
}Two things about that call are easy to get wrong, and both fail only at runtime.
The object literal converts to a popoutRequest because the value type is declared QML_STRUCTURED_VALUE. Without that macro QML has no conversion from a JS object to the gadget and the call raises TypeError: Passing incompatible arguments to C++ functions from JavaScript is not allowed.
Anchor and ExclusiveMode must be reached THROUGH PhosphorPopout. QML_ELEMENT on a Q_NAMESPACE publishes the namespace as the QML type name, so it does not put the enums in scope unqualified. A bare Anchor.BarCenter is a ReferenceError. Both rules are pinned by tests/test_popout_qml_enums.cpp.