ScreenInfo.h

Go to the documentation of this file.

// SPDX-FileCopyrightText: 2026 fuddlesworth
// SPDX-License-Identifier: LGPL-2.1-or-later
#pragma once
 
// ScreenInfo — POD descriptor + QML-friendly serialiser.
//
// QML payload shape:
//   QML consumers binding individual keys via QVariantMap should be aware
//   that the variant map produced by screenInfoListToVariantList() emits
//   `width`, `height`, `resolution`, `x`, `y`, and `isVirtualScreen` with
//   the semantics documented in libs/phosphor-screens/CHANGES.md. In
//   particular, `isVirtualScreen` is ALWAYS present (was: only when
//   true); QML that uses `Object.keys(map).includes('isVirtualScreen')`
//   to disambiguate physical-vs-virtual must be audited. See the
//   screenInfoListToVariantList() docstring below for the full key list.
//
// Sentinel convention for width/height/virtualIndex (NOT x/y — see below):
//   - `width` / `height` use `0` (not -1) as "unknown / not yet reported".
//     The producer is expected to fill positive values when geometry is
//     known. `screenInfoListToVariantList()` skips emitting a dimension
//     when it's non-positive so a `0×0` tile doesn't render in pickers.
//   - `x` / `y` (screen-space position) have NO sentinel: 0 is a valid
//     origin and negatives are normal, so they are emitted unconditionally.
//   - `virtualIndex` uses `-1` as "not a virtual screen". `isVirtualScreen`
//     must be true and `virtualIndex >= 0` for a meaningful virtual id;
//     the serialiser warns when this invariant is violated.
//   Flipping these to negative-sentinel form would be API-breaking for
//   downstream producers, so the existing convention is locked in.
 
#include <QList>
#include <QString>
#include <QVariantList>
 
#include "phosphorscreenscore_export.h"
 
namespace PhosphorScreens {
 
struct PHOSPHORSCREENSCORE_EXPORT ScreenInfo
{
    QString name;
    bool isPrimary = false;
    QString manufacturer;
    QString model;
    int width = 0;
    int height = 0;
    int x = 0;
    int y = 0;
    QString screenId;
    bool isVirtualScreen = false;
    QString connectorName;
    int virtualIndex = -1;
    QString virtualDisplayName;
};
 
[[nodiscard]] PHOSPHORSCREENSCORE_EXPORT QVariantList screenInfoListToVariantList(const QList<ScreenInfo>& screens);
 
} // namespace PhosphorScreens