PhosphorScreens::ScreenManager Class Reference

Centralized screen-topology service. More...

#include <phosphor-screens/include/PhosphorScreens/Manager.h>

Inheritance diagram for PhosphorScreens::ScreenManager:

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	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.

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*.
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.

Detailed Description

Centralized screen-topology service.

Owns: • physical screen monitoring (via an injected IScreenProvider — 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.

Member Typedef Documentation

Config

using PhosphorScreens::ScreenManager::Config = ScreenManagerConfig

Constructor & Destructor Documentation

ScreenManager()

PhosphorScreens::ScreenManager::ScreenManager ( ScreenManagerConfig  cfg = ScreenManagerConfig{}, QObject *  parent = nullptr  )

explicit

~ScreenManager()

PhosphorScreens::ScreenManager::~ScreenManager ( )

override

Member Function Documentation

actualAvailableGeometry() [1/2]

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.

actualAvailableGeometry() [2/2]

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.

availableGeometryChanged

void PhosphorScreens::ScreenManager::availableGeometryChanged ( const PhysicalScreen &  screen, const QRect &  availableGeometry  )

signal

delayedPanelRequeryCompleted

void PhosphorScreens::ScreenManager::delayedPanelRequeryCompleted ( )

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.

effectiveScreenAt()

QString PhosphorScreens::ScreenManager::effectiveScreenAt

(

const QPoint &

globalPos

)

const

effectiveScreenIds()

QStringList PhosphorScreens::ScreenManager::effectiveScreenIds

(

)

const

hasVirtualScreens()

bool PhosphorScreens::ScreenManager::hasVirtualScreens

(

const QString &

physicalScreenId

)

const

isPanelGeometryReady()

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").

maxVirtualScreensPerPhysical()

int PhosphorScreens::ScreenManager::maxVirtualScreensPerPhysical ( ) const

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.

panelGeometryReady

void PhosphorScreens::ScreenManager::panelGeometryReady ( )

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.

physicalEdgesFor()

VirtualScreenDef::PhysicalEdges PhosphorScreens::ScreenManager::physicalEdgesFor

(

const QString &

screenId

)

const

physicalScreenFor()

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.

primaryScreen()

PhysicalScreen PhosphorScreens::ScreenManager::primaryScreen

(

)

const

refreshVirtualConfigs()

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.

scheduleDelayedPanelRequery()

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.

screenAdded

void PhosphorScreens::ScreenManager::screenAdded ( const PhysicalScreen &  screen )

signal

screenAvailableGeometry()

QRect PhosphorScreens::ScreenManager::screenAvailableGeometry

(

const QString &

screenId

)

const

screenByName()

PhysicalScreen PhosphorScreens::ScreenManager::screenByName

(

const QString &

name

)

const

screenGeometry()

QRect PhosphorScreens::ScreenManager::screenGeometry

(

const QString &

screenId

)

const

screenGeometryChanged

void PhosphorScreens::ScreenManager::screenGeometryChanged ( const PhysicalScreen &  screen )

signal

screenIdentifierChanged

void PhosphorScreens::ScreenManager::screenIdentifierChanged ( const QString &  oldId, const QString &  newId  )

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 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).

screenRemoved

void PhosphorScreens::ScreenManager::screenRemoved ( const PhysicalScreen &  screen )

signal

screens()

QVector< PhysicalScreen > PhosphorScreens::ScreenManager::screens

(

)

const

setCompositorAvailableGeometry()

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.

setVirtualScreenConfig()

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.

start()

void PhosphorScreens::ScreenManager::start

(

)

Begin tracking screens.

Connects to the screen provider'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.

stop()

void PhosphorScreens::ScreenManager::stop

(

)

Tear down everything start() set up. Idempotent.

virtualScreenAt()

QString PhosphorScreens::ScreenManager::virtualScreenAt	(	const QPoint &	globalPos,
		const QString &	physicalScreenId
	)		const

virtualScreenConfig()

VirtualScreenConfig PhosphorScreens::ScreenManager::virtualScreenConfig

(

const QString &

physicalScreenId

)

const

virtualScreenIdsFor()

QStringList PhosphorScreens::ScreenManager::virtualScreenIdsFor

(

const QString &

physicalScreenId

)

const

virtualScreenRegionsChanged

void PhosphorScreens::ScreenManager::virtualScreenRegionsChanged ( const QString &  physicalScreenId )

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.

virtualScreensChanged

void PhosphorScreens::ScreenManager::virtualScreensChanged ( const QString &  physicalScreenId )

signal

VS topology changed (added, removed, renamed).

Handlers that depend on the VS ID set listen here.

---

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

• phosphor-screens/include/PhosphorScreens/Manager.h