Phosphor
Qt6 / Wayland library suite for window-management tools
Loading...
Searching...
No Matches
PhosphorShell::Toplevels Class Reference

QML singleton exposing the live list of toplevel windows for taskbars. More...

#include <PhosphorShell/Toplevels.h>

Inheritance diagram for PhosphorShell::Toplevels:
[legend]

Signals

void toplevelsChanged ()
void activeToplevelChanged ()

Public Member Functions

 Toplevels (QObject *parent=nullptr)
 Snapshot list of currently-live toplevels.
 ~Toplevels () override
QList< PhosphorWayland::ForeignToplevel * > toplevels () const
QAbstractListModel * model () const
bool isSupported () const
PhosphorWayland::ForeignToplevel * activeToplevel () const

Static Public Member Functions

static Toplevels * create (QQmlEngine *engine, QJSEngine *scriptEngine)
 QML-singleton factory hook.

Detailed Description

QML singleton exposing the live list of toplevel windows for taskbars.

Wraps PhosphorWayland::ForeignToplevelManager and turns the imperative toplevelAdded/toplevelRemoved signals into a notifying toplevels Q_PROPERTY suitable for Repeater { model: Toplevels.toplevels }.

Usage from QML:

import Phosphor.Shell

Repeater {
    model: Toplevels.toplevels
    delegate: Rectangle {
        required property var modelData  // ForeignToplevel*
        Text { text: modelData.title }
        MouseArea {
            anchors.fill: parent
            onClicked: modelData.activate()
        }
    }
}

The supported property is false on compositors that don't advertise zwlr_foreign_toplevel_manager_v1; shells should hide their taskbar UI in that case rather than showing an empty placeholder. The wlroots family (sway, Hyprland, Niri, river, labwc) supports it. Mutter does not, and neither does KWin (6.8 offers org_kde_plasma_window_management instead), so on both supported stays false.

Constructor & Destructor Documentation

◆ Toplevels()

PhosphorShell::Toplevels::Toplevels ( QObject * parent = nullptr)
explicit

Snapshot list of currently-live toplevels.

Useful for one-shot reads (const list = Toplevels.toplevels). DO NOT bind a Repeater or ListView's model: to this property — every change re-evaluates the QList and resets every delegate, including hover state, scroll position, and any per-delegate state. Bind model: Toplevels.model for incremental add/remove updates. Incrementally-updating model — emits begin/endInsertRows and begin/endRemoveRows so consumers patch the delta instead of rebuilding. Bind Repeater { model: Toplevels.model }. The toplevel the compositor currently reports as activated, or null when nothing is (the bare desktop, or a compositor that does not advertise the protocol).

The protocol has no "which one is active" event — activation is a per-toplevel state flag — so anything that wants the focused window must watch every toplevel's stateChanged and re-scan. Doing that in QML costs a hidden delegate per window in every consuming widget; doing it once here costs one connection per toplevel for the whole process.

◆ ~Toplevels()

PhosphorShell::Toplevels::~Toplevels ( )
override

Member Function Documentation

◆ activeToplevel()

PhosphorWayland::ForeignToplevel * PhosphorShell::Toplevels::activeToplevel ( ) const
nodiscard

◆ activeToplevelChanged

void PhosphorShell::Toplevels::activeToplevelChanged ( )
signal

◆ create()

Toplevels * PhosphorShell::Toplevels::create ( QQmlEngine * engine,
QJSEngine * scriptEngine )
staticnodiscard

QML-singleton factory hook.

◆ isSupported()

bool PhosphorShell::Toplevels::isSupported ( ) const
nodiscard

◆ model()

QAbstractListModel * PhosphorShell::Toplevels::model ( ) const
nodiscard

◆ toplevels()

QList< PhosphorWayland::ForeignToplevel * > PhosphorShell::Toplevels::toplevels ( ) const
nodiscard

◆ toplevelsChanged

void PhosphorShell::Toplevels::toplevelsChanged ( )
signal

The documentation for this class was generated from the following file: