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