Phosphor
Qt6 / Wayland library suite for window-management tools
Loading...
Searching...
No Matches
org.phosphor_works.Placement.Screen

Screen enumeration and metadata (geometry, scale, refresh). Notifications when screens are added, removed, or geometry changes.

Well-known name org.phosphor_works.Placement.Screen
Source XML org.phosphor_works.Placement.Screen.xml
Methods 15
Signals 5
Properties 0

Methods

getScreens()

Return the list of effective screen identifiers (EDID-based physical IDs like Dell:U2722D:115107, or virtual screen IDs like Dell:U2722D:115107/vs:0 when subdivided).

Arg Direction Type Description
screens out as (array<string>) List of effective screen identifiers.

getScreenInfo()

Return detailed info for a screen as JSON (geometry, scale, refresh rate, etc.). It includes pixelSize, the screen's size in device pixels as {width, height}, which for a virtual screen covers its own region. That is the output's mode as the compositor reported it through setPixelSizeFromKWin, once the daemon has found the report agrees with the screen's logical geometry and scale, or at once on a screen whose scale the daemon cannot measure. Until then it is the size last accepted for that monitor, in this session or an earlier one. With neither it is estimated as the logical size times the scale, rounded, which lands on the mode or within a pixel of it. pixelSizeSource names which of the three it is (reported, seeded or estimated), and is absent when there is no size at all. The daemon's rules never read the estimate. An empty id, or one that does not resolve, an unknown virtual screen included, answers an empty string.

Arg Direction Type Description
screenId in s (string) Screen identifier (EDID-based like Dell:U2722D:115107, or virtual like Dell:U2722D:115107/vs:0).
screenJson out s (string) Screen info as JSON.

getScreenId()

Return the stable EDID-based screen identifier for a connector name. Format: manufacturer:model:serial (or connector name fallback for virtual displays).

Arg Direction Type Description
connectorName in s (string) Connector name (e.g. DP-1).
screenId out s (string) Stable EDID-based screen identifier.

getPrimaryScreen()

Return the EDID-based identifier of the primary screen. Prefers KWin output order over QGuiApplication::primaryScreen().

Arg Direction Type Description
screenId out s (string) Primary screen identifier (e.g. Dell:U2722D:115107).

setPrimaryScreenFromKWin()

Override the primary screen with the KWin compositor's output order primary. Called by the KWin effect on daemon ready. Only the registered compositor bridge may call it, and any other caller is answered with AccessDenied.

Arg Direction Type Description
connectorName in s (string) Connector name from Workspace::outputOrder().first() (e.g. DP-1). Resolved to EDID-based identifier internally.

setAvailableGeometryFromKWin()

Record the authoritative per-screen available geometry (panel-excluded work area) as reported by the KWin effect's clientArea(MaximizeArea) query. Overrides the layer-shell sensor + plasmashell D-Bus panel-strut heuristic, which mis-attributes per-edge struts for top-panel layouts. The effect always reports a valid work area (the full screen rect when no panels reserve space). A zero-size rect is accepted defensively to clear the override and revert to the heuristic. Called by the KWin effect. Only the registered compositor bridge may call it, and any other caller is answered with AccessDenied.

Arg Direction Type Description
screenName in s (string) Connector name (e.g. DP-1).
x in i (int32) Work-area X origin.
y in i (int32) Work-area Y origin.
width in i (int32) Work-area width.
height in i (int32) Work-area height.

setPixelSizeFromKWin()

Record an output's exact size in device pixels as reported by the KWin effect, which reads the output's current mode with rotation already applied. A Wayland client cannot read an output's mode, so this is where the pixelSize getScreenInfo reports comes from. The report and the screen's own geometry change arrive in no fixed order, so the daemon holds a report back, and getScreenInfo keeps answering the previous size, until it agrees with the screen's logical geometry and scale. A screen whose scale the daemon cannot measure takes the report at once. A 0x0 size clears the record, which the effect sends when the output goes away. A negative size, a size with only one side zero, or one larger than 65535 on either side is ignored and leaves the record as it was. Called by the KWin effect. Only the registered compositor bridge may call it, and any other caller is answered with AccessDenied.

Arg Direction Type Description
screenName in s (string) Connector name (e.g. DP-1).
width in i (int32) Output width in device pixels.
height in i (int32) Output height in device pixels.

getAvailableGeometry()

Return the available geometry (excluding panels/taskbars) for a screen. Handles virtual screen IDs (e.g. physId/vs:0). Uses layer-shell sensor data when available, falls back to Qt's availableGeometry. An empty id answers for the primary screen. An id that does not resolve, an unknown virtual screen included, answers an empty rect.

Arg Direction Type Description
screenId in s (string) Screen identifier (EDID-based, connector name, or virtual screen ID).
geometry out (iiii) (struct(int32,int32,int32,int32)) Available geometry as (x, y, width, height).

getScreenGeometry()

Return the full geometry for a screen. Handles virtual screen IDs. Used by the editor to determine drawing area dimensions for VS-aware zone editing. An empty id answers for the primary screen. An id that does not resolve, an unknown virtual screen included, answers an empty rect.

Arg Direction Type Description
screenId in s (string) Screen identifier (EDID-based, connector name, or virtual screen ID).
geometry out (iiii) (struct(int32,int32,int32,int32)) Full screen geometry as (x, y, width, height).

getVirtualScreenConfig()

Get the virtual screen subdivision configuration for a physical screen as JSON.

Arg Direction Type Description
physicalScreenId in s (string) Stable EDID-based physical screen identifier.
config out s (string) Virtual screen config as JSON.

setVirtualScreenConfig()

Set the virtual screen subdivision configuration for a physical screen from JSON. Returns an empty string on success or a stable error token (e.g. parse_error, missing_screens, bad_index, store_rejected) on failure.

Arg Direction Type Description
physicalScreenId in s (string) Stable EDID-based physical screen identifier.
configJson in s (string) Virtual screen config as JSON.
reason out s (string) Empty on success; rejection token on failure.

getPhysicalScreens()

Return the list of physical screen identifiers (stable EDID-based IDs).

Arg Direction Type Description
screens out as (array<string>) List of physical screen identifiers.

getEffectiveScreenAt()

Return the effective screen ID (virtual or physical) containing the given global coordinates.

Arg Direction Type Description
x in i (int32) Global X coordinate.
y in i (int32) Global Y coordinate.
screenId out s (string) Effective screen ID at the given point, or empty if none.

swapVirtualScreenInDirection()

Swap the region of the given virtual screen with its adjacent sibling VS in the requested direction within the same physical monitor. VS IDs, display names, and indices are preserved — only the region fields are exchanged — so all per-VS state (windows, layouts, autotile) follows the new geometry via Settings::virtualScreenConfigsChanged propagation. Returns an empty string on success, otherwise a stable token: not_virtual, no_subdivision, unknown_vs, no_sibling, invalid_direction, settings_rejected.

Arg Direction Type Description
currentVirtualScreenId in s (string) Full virtual screen ID (e.g. Dell:U2722D:115107/vs:0).
direction in s (string) One of left, right, up, down.
reason out s (string) Empty on success, otherwise a stable rejection token.

rotateVirtualScreens()

Rotate every virtual screen region on a physical monitor through a spatial clockwise ring order. VS IDs are preserved — only the region fields are cycled. Returns an empty string on success, otherwise a stable token: not_virtual, no_subdivision, settings_rejected.

Arg Direction Type Description
physicalScreenId in s (string) Stable EDID-based physical screen identifier.
clockwise in b (bool) True to rotate clockwise (each VS inherits its ring successor's region), false for counter-clockwise.
reason out s (string) Empty on success, otherwise a stable rejection token.

Signals

screenAdded

Emitted when a new screen is connected. For subdivided screens, emits once per virtual screen.

Arg Direction Type Description
screenId out s (string) Effective screen identifier (e.g. Dell:U2722D:115107 or Dell:U2722D:115107/vs:0).

screenRemoved

Emitted when a screen is disconnected. For subdivided screens, emits once per virtual screen.

Arg Direction Type Description
screenId out s (string) Effective screen identifier (e.g. Dell:U2722D:115107 or Dell:U2722D:115107/vs:0).

screenGeometryChanged

Emitted when a screen's resolution, position or scale changes, or when the size in device pixels that getScreenInfo reports for it does.

Arg Direction Type Description
screenId out s (string) Effective screen identifier whose geometry changed.

virtualScreensChanged

Emitted when virtual screen subdivisions change for a physical screen.

Arg Direction Type Description
physicalScreenId out s (string) Physical screen whose virtual screen configuration changed.

availableGeometryChanged

Emitted when a screen's available area (the space panels leave) changes, including when its full geometry does not.

Arg Direction Type Description
screenId out s (string) Effective screen identifier whose available area changed.