Centralized screen-topology service. More...
#include <PhosphorScreens/Manager.h>
Public Types | |
| using | Config = ScreenManagerConfig |
Signals | |
| void | screenAdded (const PhysicalScreen &screen) |
| void | screenRemoved (const PhysicalScreen &screen) |
| void | screenGeometryChanged (const PhysicalScreen &screen) |
| void | availableGeometryChanged (const PhysicalScreen &screen, const QRect &availableGeometry) |
| void | logicalScaleChanged (const PhysicalScreen &screen) |
logicalScale has a different answer for screen than it did. | |
| void | panelGeometryReady () |
| Fired once when isPanelGeometryReady transitions to true. | |
| void | delayedPanelRequeryCompleted () |
| Fired when a delayed panel re-query (scheduleDelayedPanelRequery) has settled. | |
| void | virtualScreensChanged (const QString &physicalScreenId) |
| VS topology changed (added, removed, renamed). | |
| void | virtualScreenRegionsChanged (const QString &physicalScreenId) |
| VS regions changed but the VS ID set is unchanged (swap, rotate, boundary resize). | |
| void | screenIdentifierChanged (const QString &oldId, const QString &newId) |
| Emitted when a connected screen's identifier flips — e.g. | |
| void | compositorPixelSizeChanged (const QString &connectorName) |
The report pending for connectorName was recorded, changed or cleared (setCompositorPixelSize), or a seed change altered what pixelSize answers for that connector's screen: either way a host that gates reports evaluates the connector again. | |
| void | acceptedPixelSizeChanged (const QString &connectorName) |
What pixelSize answers for connectorName's screen changed: an accept moved the accepted report (acceptCompositorPixelSize), or a seed change altered the answer for a screen with no accepted report. | |
| void | logicalScaleSensorMapped (const PhysicalScreen &screen) |
screen's geometry sensor mapped (isLogicalScaleSensorMapped): from now on logicalScale answers the compositor's scale for it. | |
Public Member Functions | |
| ScreenManager (ScreenManagerConfig cfg=ScreenManagerConfig{}, QObject *parent=nullptr) | |
| ~ScreenManager () override | |
| void | start () |
| Begin tracking screens. | |
| void | stop () |
| Tear down everything start() set up. Idempotent. | |
| QVector< PhysicalScreen > | screens () const |
| PhysicalScreen | primaryScreen () const |
| PhysicalScreen | screenByName (const QString &name) const |
| int | maxVirtualScreensPerPhysical () const |
| Maximum number of virtual screens per physical monitor this manager will admit. | |
| QRect | actualAvailableGeometry (const PhysicalScreen &screen) const |
| Per-screen panel-aware available geometry. | |
| QRect | actualAvailableGeometry (QScreen *screen) const |
Bridge overload for consumers that still hold a live QScreen*. | |
| qreal | logicalScale (const PhysicalScreen &screen) const |
The compositor's LOGICAL scale for screen (1.15, 1.5, 2.0…). | |
| qreal | logicalScale (QScreen *screen) const |
Bridge overload for consumers holding a live QScreen*. | |
| bool | isPanelGeometryReady () const |
| Has the panel source produced its first reading? | |
| bool | setVirtualScreenConfig (const QString &physicalScreenId, const VirtualScreenConfig &config) |
| Apply a single VS subdivision config. | |
| void | refreshVirtualConfigs (const QHash< QString, VirtualScreenConfig > &configs) |
Diff configs against the current cache and apply the delta. | |
| VirtualScreenConfig | virtualScreenConfig (const QString &physicalScreenId) const |
| bool | hasVirtualScreens (const QString &physicalScreenId) const |
| QStringList | effectiveScreenIds () const |
| QStringList | virtualScreenIdsFor (const QString &physicalScreenId) const |
| QRect | screenGeometry (const QString &screenId) const |
| QRect | screenAvailableGeometry (const QString &screenId) const |
| PhysicalScreen | physicalScreenFor (const QString &screenId) const |
| The physical output a (physical or virtual) screen ID resolves to. | |
| VirtualScreenDef::PhysicalEdges | physicalEdgesFor (const QString &screenId) const |
| QString | virtualScreenAt (const QPoint &globalPos, const QString &physicalScreenId) const |
| QString | effectiveScreenAt (const QPoint &globalPos) const |
| void | scheduleDelayedPanelRequery (int delayMs) |
Schedule a one-shot panel re-query after delayMs. | |
| void | setCompositorAvailableGeometry (const QString &screenName, const QRect &available) |
| Record the authoritative per-screen available geometry as reported by the compositor. | |
| void | setCompositorPixelSize (const QString &connectorName, const QSize &pixelSize) |
| Record an output's exact size in device pixels as reported by the compositor, PENDING until the host accepts it. | |
| void | seedPixelSize (const QString &physicalScreenId, const QSize &pixelSize) |
| Seed a monitor's size in device pixels from the host's own record, for use until a compositor report is accepted for it. | |
| std::optional< QSize > | pixelSize (const QString &screenId) const |
| A screen's size in device pixels, the one answer every reader uses. | |
| bool | isPixelSizeReported (const QString &screenId) const |
True only when pixelSize answers screenId from an accepted compositor report rather than from a seed or not at all. | |
| void | acceptCompositorPixelSize (const QString &connectorName) |
Promote connectorName's pending report to the accepted one. | |
| std::optional< QSize > | pendingPixelSize (const QString &connectorName) const |
The report pending for connectorName (setCompositorPixelSize), for a host deciding whether to accept it. | |
| bool | hasLogicalScaleSensor (const PhysicalScreen &screen) const |
Whether screen has a geometry sensor, so logicalScale answers the compositor's fractional scale, or will once the sensor maps. | |
| bool | isLogicalScaleSensorMapped (const PhysicalScreen &screen) const |
Whether screen's geometry sensor has mapped, so logicalScale answers the compositor's own scale for it. | |
Protected Member Functions | |
| bool | eventFilter (QObject *watched, QEvent *event) override |
Watches the geometry sensors for QEvent::DevicePixelRatioChange, which is the only notice Qt gives that a window's per-surface scale moved — QWindow has no changed signal for it. | |
Centralized screen-topology service.
Owns: • physical screen monitoring (via an injected IPhysicalScreenSource — add/remove/geometry lifecycle, decoupled from QGuiApplication) • virtual-screen subdivision cache (synced from an injected IConfigStore) • per-screen available-geometry computation (panel offsets via an injected IPanelSource + layer-shell sensor windows) • effective-screen resolution (the unified VS-or-physical view consumed by every PhosphorScreens client)
NOT a singleton — the lib never owns process-global state. Consumers that need a process-wide ScreenManager (the Phosphor daemon does) provide their own thin service-locator outside this class.
GUI THREAD ONLY. Every member, the const queries included, must be called on the thread that owns QGuiApplication: the queries fill lazy caches with no locking, and the sensor windows and QScreen reads behind them are GUI objects. Debug builds assert it on the hot accessors (PS_SCREEN_MANAGER_ASSERT_GUI_THREAD). ScreenIdentity carries the same constraint.
|
explicit |
|
override |
| void PhosphorScreens::ScreenManager::acceptCompositorPixelSize | ( | const QString & | connectorName | ) |
Promote connectorName's pending report to the accepted one.
The pending report becomes what pixelSize answers for the connector's screen, and a pending clear drops the accepted report, so the screen falls back to its seed. A no-op when the accepted state already matches the pending one. A real change emits acceptedPixelSizeChanged. Accepting a report that confirms the seed is a change too: pixelSize answers the same, but isPixelSizeReported flips. A no-op too for a connector the manager does not track: its report stays pending.
The accepted report is dropped, without a signal, when the manager's own QScreen for the connector goes away: it was accepted for the monitor that left, and nothing reads an untracked screen's size. The screen that next arrives on the connector answers its seed until the host accepts a report for it.
|
signal |
What pixelSize answers for connectorName's screen changed: an accept moved the accepted report (acceptCompositorPixelSize), or a seed change altered the answer for a screen with no accepted report.
An accept that confirms the seed fires it too, because isPixelSizeReported has flipped.
| QRect PhosphorScreens::ScreenManager::actualAvailableGeometry | ( | const PhysicalScreen & | screen | ) | const |
Per-screen panel-aware available geometry.
Reads from the live cache populated by sensor windows + panel-source data. Falls back to QScreen::availableGeometry() (or the full screen rect for a synthetic screen with no QScreen) when the cache has no entry for screen yet (e.g. before panelGeometryReady fires). Returns an invalid QRect on an invalid PhysicalScreen.
Was a static helper in the pre-extraction class; lives on the instance now so the cache no longer needs file-static storage.
| QRect PhosphorScreens::ScreenManager::actualAvailableGeometry | ( | QScreen * | screen | ) | const |
Bridge overload for consumers that still hold a live QScreen*.
Resolves screen to a tracked PhysicalScreen and delegates to the value-typed overload. Falls back to QScreen::availableGeometry() when the connector is not in the tracked set (e.g. a hotplug race), and to an invalid QRect when screen is null — so the caller never sees an empty rect for a screen Qt still considers live.
The single conversion point for the QScreen* → PhysicalScreen available-geometry path: prefer it over an ad-hoc actualAvailableGeometry(screenByName(...)) at the call site.
|
signal |
|
signal |
The report pending for connectorName was recorded, changed or cleared (setCompositorPixelSize), or a seed change altered what pixelSize answers for that connector's screen: either way a host that gates reports evaluates the connector again.
A pending change alone changes no pixelSize answer. connectorName may name an output the manager does not track yet.
|
signal |
Fired when a delayed panel re-query (scheduleDelayedPanelRequery) has settled.
The daemon uses this to trigger reapply of window geometries after a short delay.
| QString PhosphorScreens::ScreenManager::effectiveScreenAt | ( | const QPoint & | globalPos | ) | const |
| QStringList PhosphorScreens::ScreenManager::effectiveScreenIds | ( | ) | const |
|
overrideprotected |
Watches the geometry sensors for QEvent::DevicePixelRatioChange, which is the only notice Qt gives that a window's per-surface scale moved — QWindow has no changed signal for it.
Emits logicalScaleChanged for the sensor's screen. Also watches for the sensor's first expose, and emits logicalScaleSensorMapped then.
| bool PhosphorScreens::ScreenManager::hasLogicalScaleSensor | ( | const PhysicalScreen & | screen | ) | const |
Whether screen has a geometry sensor, so logicalScale answers the compositor's fractional scale, or will once the sensor maps.
Until the sensor maps, logicalScale answers the coarse QScreen fallback, and logicalScaleChanged announces the real number when it arrives. False for a screen with no sensor at all (a synthetic screen, a manager built without sensors, or one whose layer surface could not be created): its logicalScale stays the fallback for good, and no later signal improves it.
| bool PhosphorScreens::ScreenManager::hasVirtualScreens | ( | const QString & | physicalScreenId | ) | const |
| bool PhosphorScreens::ScreenManager::isLogicalScaleSensorMapped | ( | const PhysicalScreen & | screen | ) | const |
Whether screen's geometry sensor has mapped, so logicalScale answers the compositor's own scale for it.
True from the sensor's first expose, which follows the compositor's first configure of its layer surface. KWin settles a layer surface's preferred scale when it creates the surface's window, ahead of that configure, so by the expose the sensor carries the real scale, on an integer output as on a fractional one. Before it, logicalScale may still answer the coarse QScreen fallback, which a different monitor's mode can agree with. logicalScaleSensorMapped announces the change. False for a screen with no sensor (hasLogicalScaleSensor), and again once the sensor is destroyed.
| bool PhosphorScreens::ScreenManager::isPanelGeometryReady | ( | ) | const |
Has the panel source produced its first reading?
Components that compute initial zone geometry at startup gate on this so they don't lay out windows against the unreserved screen rect. Always true when no panel source is configured (zero offsets are trivially "ready").
| bool PhosphorScreens::ScreenManager::isPixelSizeReported | ( | const QString & | screenId | ) | const |
True only when pixelSize answers screenId from an accepted compositor report rather than from a seed or not at all.
| qreal PhosphorScreens::ScreenManager::logicalScale | ( | const PhysicalScreen & | screen | ) | const |
The compositor's LOGICAL scale for screen (1.15, 1.5, 2.0…).
Read from the screen's layer-shell geometry sensor window, because on Wayland that is the only place a client can see the real number. QScreen::devicePixelRatio() reports the wl_output INTEGER buffer scale, which a compositor advertises as the ceiling of the true scale for the benefit of clients that cannot scale fractionally — KWin says 2 for a 1.15 output. QWindow::devicePixelRatio() instead carries the per-surface value Qt derives from wp_fractional_scale_v1, which is the 1.15 itself.
Falls back to QScreen::devicePixelRatio() when the screen has no sensor (a synthetic test screen never gets one — see createGeometrySensor) or the sensor has not been mapped yet, and to 1.0 when there is no QScreen either. The fallback is the OLD, coarse answer, the integer ceiling on a fractional output. For a diagnostic reader that is only imprecise, but a reader that divides by the scale gets a wrong size from it (a device-pixel zone on a 1.15 output comes out at 1/2 of its pixels instead of 1/1.15). Such a reader must not cache a value read before the sensor maps. It must recompute on logicalScaleChanged, which fires when the real number arrives and on every later change; the daemon's layout recalculation does.
Placement works in logical coordinates throughout, and the compositor owns the conversion. The one placement reader is a layout that declares its fixed zone geometry in the OUTPUT's device pixels (PhosphorZones::Layout::fixedGeometryInDevicePixels), which divides by this to land in those logical coordinates. The getScreenInfo reply carries it too, as devicePixelRatio, and is no longer read for diagnostics only: the layout editor converts that unit with it, between the device pixels a layout stores and the logical ones it edits in. It also feeds the support report. Do not introduce another device-pixel calculation on the strength of this accessor without checking that the surface in question is actually scaled the same way.
| qreal PhosphorScreens::ScreenManager::logicalScale | ( | QScreen * | screen | ) | const |
Bridge overload for consumers holding a live QScreen*.
Mirrors the actualAvailableGeometry(QScreen*) convention: resolve through the tracked set so the sensor lookup is keyed the same way, and fall back to the QScreen's own (coarse, integer) ratio for a connector the manager does not track, which is a hotplug race. A null screen has no ratio to fall back to and answers 1.0.
|
signal |
logicalScale has a different answer for screen than it did.
Fires when the compositor tells the screen's sensor window its per-surface scale, which is both the first time the real number is knowable and every later change to it. It matters because the answer before that point is the coarse QScreen fallback, so anything that caches a scale read at startup is caching the wrong one until this says otherwise.
|
signal |
screen's geometry sensor mapped (isLogicalScaleSensorMapped): from now on logicalScale answers the compositor's scale for it.
Fires once per sensor, whether or not the scale differs from the fallback, so a host waiting on the real scale hears of an integer output too, where logicalScaleChanged may never fire. Appended last among the signals.
|
inline |
Maximum number of virtual screens per physical monitor this manager will admit.
Mirrors ScreenManagerConfig::maxVirtualScreensPerPhysical — exposed so callers (D-Bus adaptor, KCM validator) can pre-validate incoming configs before handing them to setVirtualScreenConfig and surface a specific rejection reason on cap overflow.
|
signal |
Fired once when isPanelGeometryReady transitions to true.
Components that need accurate panel geometry (window restoration, initial zone layout) should wait for this before performing geometry-dependent work.
| std::optional< QSize > PhosphorScreens::ScreenManager::pendingPixelSize | ( | const QString & | connectorName | ) | const |
The report pending for connectorName (setCompositorPixelSize), for a host deciding whether to accept it.
Nothing after a clear, and for a connector the compositor never reported. The connector need not be tracked.
| VirtualScreenDef::PhysicalEdges PhosphorScreens::ScreenManager::physicalEdgesFor | ( | const QString & | screenId | ) | const |
| PhysicalScreen PhosphorScreens::ScreenManager::physicalScreenFor | ( | const QString & | screenId | ) | const |
The physical output a (physical or virtual) screen ID resolves to.
Returns an invalid PhysicalScreen when nothing tracked matches.
| std::optional< QSize > PhosphorScreens::ScreenManager::pixelSize | ( | const QString & | screenId | ) | const |
A screen's size in device pixels, the one answer every reader uses.
screenId is a physical id (identifier or connector name) or a virtual one. A physical screen answers its connector's ACCEPTED compositor report (acceptCompositorPixelSize), else the seed for its identifier (seedPixelSize), else nothing. A report still pending is never the answer. A virtual screen answers its region's share of that size, computed as VirtualScreenDef::absoluteGeometry over the pixel rect, so its edges round exactly as the effect's own split of the same pixel rect does. An empty id, an untracked screen, and a virtual screen the manager does not know answer nothing.
| PhysicalScreen PhosphorScreens::ScreenManager::primaryScreen | ( | ) | const |
| void PhosphorScreens::ScreenManager::refreshVirtualConfigs | ( | const QHash< QString, VirtualScreenConfig > & | configs | ) |
Diff configs against the current cache and apply the delta.
Idempotent. Removals (entries in cache but absent from configs) are processed before additions/changes.
| void PhosphorScreens::ScreenManager::scheduleDelayedPanelRequery | ( | int | delayMs | ) |
Schedule a one-shot panel re-query after delayMs.
Forwards to the panel source's requestRequery. Useful after applying geometry updates so we pick up the settled panel state (e.g. after the KDE panel editor closes). If called again before the underlying timer fires, the timer restarts.
|
signal |
| QRect PhosphorScreens::ScreenManager::screenAvailableGeometry | ( | const QString & | screenId | ) | const |
| PhysicalScreen PhosphorScreens::ScreenManager::screenByName | ( | const QString & | name | ) | const |
| QRect PhosphorScreens::ScreenManager::screenGeometry | ( | const QString & | screenId | ) | const |
|
signal |
|
signal |
Emitted when a connected screen's identifier flips — e.g.
a bare EDID ID promotes to "base/CONNECTOR" form because a second same- model monitor joined, or vice versa on removal. The manager has already re-keyed its own internal m_virtualConfigs and its pixel-size seeds by the time this fires; external consumers (SettingsConfigStore-backed persistence) must re-key their own stores under newId so the next IConfigStore::loadAll agrees with the manager's cache. Both IDs are physical (no /vs:N suffix).
|
signal |
| QVector< PhysicalScreen > PhosphorScreens::ScreenManager::screens | ( | ) | const |
| void PhosphorScreens::ScreenManager::seedPixelSize | ( | const QString & | physicalScreenId, |
| const QSize & | pixelSize ) |
Seed a monitor's size in device pixels from the host's own record, for use until a compositor report is accepted for it.
Keyed by the physical screen's stable identifier, not the connector, because the host persists it across sessions and a connector name does not identify a monitor. Answers pixelSize only for a screen whose connector has no accepted report. A pending report does not shadow it. An invalid or empty size drops the seed. A redundant call is a no-op. A change that alters what pixelSize answers for a tracked screen emits acceptedPixelSizeChanged and then compositorPixelSizeChanged for its connector.
Seeds follow an identifier flip the way the virtual-screen configs do (see screenIdentifierChanged), and stop leaves them in place.
| void PhosphorScreens::ScreenManager::setCompositorAvailableGeometry | ( | const QString & | screenName, |
| const QRect & | available ) |
Record the authoritative per-screen available geometry as reported by the compositor.
The KWin effect queries KWin::clientArea(MaximizeArea) — the exact panel-excluded work area the compositor itself reserves for maximized windows, with correct per-edge strut attribution and correct auto-hide handling — and pushes it here over D-Bus.
This is the highest-priority source in calculateAvailableGeometry: when an entry exists for a screen it fully determines that screen's available rect, bypassing the layer-shell sensor + plasmashell D-Bus heuristic. That heuristic can only guess which edge a strut belongs to, and guesses wrong (attributes everything to the bottom edge) for top-panel layouts when the plasmashell D-Bus query returns no panels.
Pass an invalid or empty rect to clear the override for screenName and fall back to the heuristic. Keyed by connector name. A redundant call (same rect already recorded) is a no-op.
| void PhosphorScreens::ScreenManager::setCompositorPixelSize | ( | const QString & | connectorName, |
| const QSize & | pixelSize ) |
Record an output's exact size in device pixels as reported by the compositor, PENDING until the host accepts it.
A Wayland client cannot read an output's mode: wl_output's mode event stays inside the QPA plugin, and QScreen::geometry() is the logical rect. The KWin effect reads the output's current mode size (already rotated) and pushes it here over D-Bus, the same way it pushes the work area to setCompositorAvailableGeometry.
Keyed by connector name. An invalid or empty size clears the pending entry for connectorName, which is what the effect sends when the output goes away. A redundant call (same pending state) is a no-op. A real change emits compositorPixelSizeChanged.
A pending report is not what pixelSize answers. The report travels over D-Bus and the QScreen change it goes with over Wayland, in no fixed order, so it can describe a mode the tracked logical geometry does not show yet, or a monitor that replaced the tracked one on the same connector. The manager does not judge that. The host does, and calls acceptCompositorPixelSize once the report agrees with the screen it tracks, which makes it the accepted size every reader sees. A host that does not gate reports accepts each one from its compositorPixelSizeChanged handler.
Unlike the work-area override, the pending entry is NOT dropped when the manager's own QScreen for the connector goes away. The compositor and the daemon see an output come and go in no fixed order (a KVM switch presents as unplug and replug), so a report can land before the QScreen it describes, and dropping it on the manager's removal would lose the report that arrived first. The effect is the only writer and clears what it no longer has. A fresh effect re-sends every output it has when it registers, which overwrites each entry it still describes, and stop drops them all. An effect that goes away without its clears (unloaded, or the compositor restarted) leaves its entries behind, so until a fresh effect reports again, a different monitor plugged into the same connector finds the outgoing monitor's size pending there.
| bool PhosphorScreens::ScreenManager::setVirtualScreenConfig | ( | const QString & | physicalScreenId, |
| const VirtualScreenConfig & | config ) |
Apply a single VS subdivision config.
Use the IConfigStore for persistent writes; this method is for the refresh path only. Production code should mutate via the store and let refreshVirtualConfigs apply the delta.
| void PhosphorScreens::ScreenManager::start | ( | ) |
Begin tracking screens.
Connects to the screen source's add/remove/geometry signals, snapshots the current output set, attaches per-screen geometry sensors (when enabled), starts the panel source, and subscribes to the config store's changed signal for VS refresh.
| void PhosphorScreens::ScreenManager::stop | ( | ) |
Tear down everything start() set up. Idempotent.
| QString PhosphorScreens::ScreenManager::virtualScreenAt | ( | const QPoint & | globalPos, |
| const QString & | physicalScreenId ) const |
| VirtualScreenConfig PhosphorScreens::ScreenManager::virtualScreenConfig | ( | const QString & | physicalScreenId | ) | const |
| QStringList PhosphorScreens::ScreenManager::virtualScreenIdsFor | ( | const QString & | physicalScreenId | ) | const |
|
signal |
VS regions changed but the VS ID set is unchanged (swap, rotate, boundary resize).
Handlers that need to move windows to follow the new VS geometry listen here; topology-aware handlers stay on virtualScreensChanged.
|
signal |
VS topology changed (added, removed, renamed).
Handlers that depend on the VS ID set listen here.