Window-to-zone tracking: pre-snap geometry for restore, floating state, zone geometry, drag-out unsnap, resolution-change handling, keyboard-navigation feedback, window-metadata registration, and the Phosphor shell surface (activateWindow, getWindowMetadata, moveWindowToDesktop, getUrgentWindows, getWindowStatesForDesktop, findWindowByPid with the windowMetadataChanged and windowUrgencyChanged announcements). Snap commits, snap-restore fallback chains, and daemon-driven navigation targets live on the org.phosphor_works.Placement.Snap adaptor.
| Well-known name | org.phosphor_works.Placement.WindowTracking |
| Source XML | org.phosphor_works.Placement.WindowTracking.xml |
| Methods | 48 |
| Signals | 22 |
| Properties | 0 |
Notify that a snapped window was dragged without the activation trigger and dropped on the screen it is snapped on. Saves pre-float zone, marks floating, and clears zone assignment so the window does not auto-restore to the zone on close/reopen. A drag that ends on another screen is resolved by the drag adaptor at the end of the drag. Only the registered compositor bridge may call it, and any other caller is answered with AccessDenied.
| Arg | Direction | Type | Description |
|---|---|---|---|
| windowId | in | s (string) | Window ID from the effect. |
Return the zone UUID a window is snapped to, or empty string.
| Arg | Direction | Type | Description |
|---|---|---|---|
| windowId | in | s (string) | Window identifier. |
| zoneId | out | s (string) | Zone UUID or empty string. |
Return all zone UUIDs a window spans (multi-zone snap).
| Arg | Direction | Type | Description |
|---|---|---|---|
| windowId | in | s (string) | Window identifier. |
| zoneIds | out | as (array<string>) | Zone UUIDs the window spans. |
Return window IDs currently snapped to the given zone.
| Arg | Direction | Type | Description |
|---|---|---|---|
| zoneId | in | s (string) | Zone UUID. |
| windowIds | out | as (array<string>) | Window IDs snapped to the zone. |
Return all window IDs that are snapped to any zone.
| Arg | Direction | Type | Description |
|---|---|---|---|
| windowIds | out | as (array<string>) | All snapped window IDs. |
Drop the windows not in the alive set: capture the final placement of each one the daemon holds a frame for, then release it from every engine, the window registry and the daemon's per-window shadows. An empty set is refused. Called by the KWin effect after the daemon is ready. Only the registered compositor bridge may call it, and any other caller is answered with AccessDenied.
| Arg | Direction | Type | Description |
|---|---|---|---|
| aliveWindowIds | in | as (array<string>) | Window IDs currently known to KWin. |
Return typed list of empty zones for Snap Assist continuation. Same EmptyZoneEntry format as the WindowDrag interface's snapAssistReady signal.
| Arg | Direction | Type | Description |
|---|---|---|---|
| screenId | in | s (string) | Screen identifier (e.g. Dell:U2722D:115107 or Dell:U2722D:115107/vs:0). |
| emptyZones | out | a(siiiiiibsssdd) (array<struct(string,int32,int32,int32,int32,int32,int32,bool,string,string,string,double,double)>) | Array of EmptyZoneEntry structs: (zoneId, x, y, width, height, borderWidth, borderRadius, useCustomColors, highlightColor, inactiveColor, borderColor, activeOpacity, inactiveOpacity). |
Return the last zone a window was snapped to (for auto-snap).
| Arg | Direction | Type | Description |
|---|---|---|---|
| zoneId | out | s (string) | Last used zone UUID or empty string. |
Store window geometry before tiling (snap or autotile). With overwrite false an existing entry is kept. Only the registered compositor bridge may call it, and any other caller is answered with AccessDenied.
| Arg | Direction | Type | Description |
|---|---|---|---|
| windowId | in | s (string) | Window identifier. |
| x | in | i (int32) | Window X position. |
| y | in | i (int32) | Window Y position. |
| width | in | i (int32) | Window width. |
| height | in | i (int32) | Window height. |
| screenId | in | s (string) | Screen id where the window is located (for cross-screen restore). |
| overwrite | in | b (bool) | True when the frame is a known-fresh free position, which is always written. False keeps an existing entry. |
Return true if pre-tile geometry is stored for the window.
| Arg | Direction | Type | Description |
|---|---|---|---|
| windowId | in | s (string) | Window identifier. |
| hasGeometry | out | b (bool) | True if pre-tile geometry exists. |
Return the window's own free geometry on the screen it is tracked on. A rect that does not lie on that screen is not returned. Returns found, x, y, width, height.
| Arg | Direction | Type | Description |
|---|---|---|---|
| windowId | in | s (string) | Window identifier. |
| found | out | b (bool) | True if geometry was found and validated. |
| x | out | i (int32) | X position (if found). |
| y | out | i (int32) | Y position (if found). |
| width | out | i (int32) | Width (if found). |
| height | out | i (int32) | Height (if found). |
Clear stored pre-tile geometry for a window. Only the registered compositor bridge may call it, and any other caller is answered with AccessDenied.
| Arg | Direction | Type | Description |
|---|---|---|---|
| windowId | in | s (string) | Window identifier. |
Float or unfloat a window through the engine that runs the screen it is on, the path the compositor's minimize and drag floats take. A tile floats on a tiling or scrolling screen and a snapped window leaves its zone on a snapping one. Silent for a window the daemon has no record of, one with no screen, one not on the desktop and activity its screen shows, or one whose screen is disabled there.
| Arg | Direction | Type | Description |
|---|---|---|---|
| windowId | in | s (string) | Window identifier. |
| floating | in | b (bool) | True to float. |
Return true if the window is floating.
| Arg | Direction | Type | Description |
|---|---|---|---|
| windowId | in | s (string) | Window identifier. |
| floating | out | b (bool) | True if floating. |
Return the window IDs that are floating, excluding suspension (minimize-as-float) entries: a minimized window's float is daemon-side occupancy bookkeeping, and the effect's own minimize-float claim paths own it. Consumers re-seeding float state from this list therefore never adopt a suspension float.
| Arg | Direction | Type | Description |
|---|---|---|---|
| windowIds | out | as (array<string>) | Floating window IDs. |
Return the zone to restore to when unfloating (if any).
| Arg | Direction | Type | Description |
|---|---|---|---|
| windowId | in | s (string) | Window identifier. |
| found | out | b (bool) | True if a pre-float zone was stored. |
| zoneId | out | s (string) | Zone to restore to (if found). |
Clear saved pre-float zone for the window. Only the registered compositor bridge may call it, and any other caller is answered with AccessDenied.
| Arg | Direction | Type | Description |
|---|---|---|---|
| windowId | in | s (string) | Window identifier. |
Return zone geometry for the given zone (primary screen).
| Arg | Direction | Type | Description |
|---|---|---|---|
| zoneId | in | s (string) | Zone UUID. |
| geometry | out | (iiii) (struct(int32,int32,int32,int32)) | ZoneGeometryRect: (x, y, width, height). |
Return zone geometry for the given zone on the given screen.
| Arg | Direction | Type | Description |
|---|---|---|---|
| zoneId | in | s (string) | Zone UUID. |
| screenId | in | s (string) | Screen identifier (e.g. Dell:U2722D:115107 or Dell:U2722D:115107/vs:0). |
| geometry | out | (iiii) (struct(int32,int32,int32,int32)) | ZoneGeometryRect: (x, y, width, height). |
Return the zone rect each snapped window holds in the context in view (its primary context when none is in view), one entry per window, for the re-apply after a work-area settle or a resolution or virtual-screen change. Empty while keepWindowsInZonesOnResolutionChange is off or snapping is switched off; windows on a context where snapping is disabled are left out.
| Arg | Direction | Type | Description |
|---|---|---|---|
| geometries | out | a(siiiis) (array<struct(string,int32,int32,int32,int32,string)>) | Array of (windowId, x, y, width, height, screenId). Matches the marshalling format in libs/phosphor-protocol/src/marshalling.cpp — the trailing screenId field was added alongside applyGeometriesBatch's (siiiis) signature so the effect can route the geometry to the correct screen on multi-monitor setups. |
Report the windows a screen-change settle moved. Sent when a settle added or removed an output, or held back a crossing during the debounce. The daemon compares each window with the state it had before its output went away and answers with one verdict per window. A window KWin returned untouched is re-seated in its old zone, tile or column. An evacuee floats where KWin put it. A placement KWin moved is re-asserted, and anything else is the user's move. Only the registered compositor bridge may call it, and any other caller is answered with AccessDenied.
| Arg | Direction | Type | Description |
|---|---|---|---|
| rows | in | a(ssssbiiiiiiiiiiibbbbssiiibiiii) (array<struct(string,string,string,string,bool,int32,int32,int32,int32,int32,int32,int32,int32,int32,int32,int32,bool,bool,bool,bool,string,string,int32,int32,int32,bool,int32,int32,int32,int32)>) | Array of (windowId, outputUuid, screenId, sourceScreenId, sourceConnected, x, y, width, height, baseX, baseY, baseWidth, baseHeight, moveResizeCount, maximizeMode, quickTileMode, fullscreen, kwinOnly, placeableNow, hasS0, s0Uuid, s0ScreenId, s0MoveResizeCount, s0MaximizeMode, s0QuickTileMode, s0Fullscreen, s0X, s0Y, s0Width, s0Height). |
| verdicts | out | a(sis) (array<struct(string,int32,string)>) | Array of (windowId, verdict, screenId). verdict: 0 none, 1 re-seated, 2 evacuee floating, 3 re-asserted, 4 the user's move. screenId names the screen the verdict placed the window on. |
Pre-computed zone geometries for pending restore entries. The effect caches these for instant window teleport on open (no D-Bus round-trip flash). Empty while snapping or the zone restore is off, or while an enabled rule can turn that restore off for a window.
| Arg | Direction | Type | Description |
|---|---|---|---|
| geometriesJson | out | s (string) | JSON object: { appId: [ {x, y, width, height, screenId, windowId}, ... ], ... }, newest record first. windowId is the record's; the effect applies the newest entry on the opener's output whose window it cannot still see. |
Report keyboard-navigation result from KWin effect, which the daemon emits as navigationFeedback for OSD. Only the registered compositor bridge may call it, and any other caller is answered with AccessDenied.
| Arg | Direction | Type | Description |
|---|---|---|---|
| success | in | b (bool) | True if navigation succeeded. |
| action | in | s (string) | Action name (e.g. move, focus). |
| reason | in | s (string) | Reason string (e.g. no adjacent zone). |
| sourceZoneId | in | s (string) | Source zone ID for OSD highlighting (optional). |
| targetZoneId | in | s (string) | Target zone ID for OSD highlighting (optional). |
| screenId | in | s (string) | Screen identifier where navigation occurred (for OSD placement). |
Set a window's floating state explicitly (directional, not toggle) on the engine that runs the screen: autotile, scrolling or snapping. Used by minimize and unminimize, drag-to-float, the monocle unmaximize and the Phosphor shell placement map. A tiling engine floats or tiles the window where it is, with no float-back geometry and no OSD. A caller other than the registered compositor bridge is refused, with a log line, when it names a screen the window is not on, and for a window off the desktop or activity the screen shows or in a disabled context, as setWindowFloating is.
| Arg | Direction | Type | Description |
|---|---|---|---|
| windowId | in | s (string) | Window identifier (from KWin). |
| screenId | in | s (string) | Screen where the window is located. Empty uses the screen the daemon tracks it on. From a caller other than the compositor bridge, a split monitor's physical id names the virtual screen the window is on. |
| floating | in | b (bool) | True to float, false to unfloat. |
Report that the cursor has moved to a different screen: across monitors, across the virtual screens of one, or a re-send when the daemon starts. A screen the daemon does not know yet is held and applied when it appears. Shortcuts use this screen when no window has focus. Only the registered compositor bridge may call it, and any other caller is answered with AccessDenied.
| Arg | Direction | Type | Description |
|---|---|---|---|
| screenId | in | s (string) | Screen identifier the cursor is now on (e.g. Dell:U2722D:115107 or Dell:U2722D:115107/vs:0). |
Report a screen's current virtual desktop (Plasma 6.7 per-output virtual desktops). Called by the KWin effect on KWin::EffectsHandler::desktopChanged, on a window activation, in its bring-up re-sync, and as the answer to a setScreenDesktopRequested. That answer is forced past the effect's own dedup when the request switched nothing, so it may repeat the value the daemon already holds. KWin's placeholder output is never reported. KWin's own D-Bus interface only exposes the global current desktop, so per-screen data arrives this way. Only the registered compositor bridge may call it, and any other caller is answered with AccessDenied.
| Arg | Direction | Type | Description |
|---|---|---|---|
| screenId | in | s (string) | Physical screen identifier whose desktop changed (NOT virtual-screen-suffixed; per-output desktops belong to the physical output). |
| desktop | in | i (int32) | The screen's current virtual desktop, 1-based (x11DesktopNumber). |
Report the compositor's actual per-output-virtual-desktops mode. The KWin effect reports it at bring-up and again whenever KWin's mode changes at runtime. It is the authoritative arm of the dynamic-workspaces feature gate, since a kwinrc read can disagree with the running compositor. Only the registered compositor bridge may call it, and any other caller is answered with AccessDenied.
| Arg | Direction | Type | Description |
|---|---|---|---|
| enabled | in | b (bool) | True when KWin runs with PerOutputVirtualDesktops on. |
Report the virtual desktop an output shows as it is connected or comes back. KWin picks it without a desktop change, so this is a seed, not a switch: the engines take the desktop and the managed screens are recomputed, with no desktop-switch OSD and no switch announce. Only the registered compositor bridge may call it, and any other caller is answered with AccessDenied.
| Arg | Direction | Type | Description |
|---|---|---|---|
| screenId | in | s (string) | Physical screen identifier of the output that was added. |
| desktop | in | i (int32) | The desktop it shows, 1-based (x11DesktopNumber). |
Register or update metadata for a live window. Called by the compositor bridge on window-added and on every mutation of the window's app class, desktop file, caption, virtual desktop, activity or role, and on its minimize, urgency, maximize and fullscreen edges, a maximize on one axis included. Idempotent, so it is safe to call on every observation and a no-op if metadata is unchanged. Only the registered compositor bridge may call it, and any other caller is answered with AccessDenied.
| Arg | Direction | Type | Description |
|---|---|---|---|
| instanceId | in | s (string) | Opaque compositor handle, stable for the window lifetime (KWin internalId). |
| appId | in | s (string) | Current app class (mutable). |
| desktopFile | in | s (string) | Current desktop file name (mutable, may be empty). |
| title | in | s (string) | Current caption (mutable, may be empty). |
| windowRole | in | s (string) | X11 WM_WINDOW_ROLE (empty for Wayland-native windows). |
| pid | in | i (int32) | Process id (0 = unknown). |
| virtualDesktop | in | i (int32) | 1-based x11 desktop number (0 = all desktops / unknown). |
| activity | in | s (string) | Activity UUID (empty = all activities / unknown). |
| windowType | in | i (int32) | PhosphorProtocol::WindowType underlying value; out-of-range values are clamped to Unknown. |
| extended | in | a{sv} (dict<string,variant>) | Extended window-property snapshot (state flags, geometry, accessory flags, captionNormal, multi-desktop span list) keyed by PhosphorProtocol::Service::WindowMetadataKey. A key is present only when the value is known, so absent keys leave the derived window-rule field disengaged. Caption-only refresh protocol: an EMPTY map, or a map whose sole key is CaptionNormal, carries the daemon's existing extended snapshot forward (updating only the caption when supplied) rather than clearing it — a sender meaning 'nothing is known' must not use those shapes. Lets the daemon's Float/RestorePosition resolvers match the same KWin-property fields the effect path resolves live. |
Notify daemon that a window was closed (cleanup). Only the registered compositor bridge may call it, and any other caller is answered with AccessDenied.
| Arg | Direction | Type | Description |
|---|---|---|---|
| windowId | in | s (string) | Window identifier. |
| windowKind | in | i (int32) | Structural kind of the closing window (0=Unknown, 1=Normal, 2=Transient). Unused: it gated the pending-restore queue, which was removed. Kept so the signature does not change. |
| screenId | in | s (string) | The window's authoritative current screen at close (the effect's getWindowScreenId). Used by the final placement capture to record the float-back on the screen the window actually closed on, even when a cross-screen move has torn down every engine's tracking. Empty opts out (legacy callers). |
Notify daemon that a window was activated/focused. Only the registered compositor bridge may call it, and any other caller is answered with AccessDenied.
| Arg | Direction | Type | Description |
|---|---|---|---|
| windowId | in | s (string) | Window identifier. |
| screenId | in | s (string) | Screen where window is located. |
Notify daemon that the focused window moved to another screen without a new activation, whether a user, KWin or daemon move did it. Window shortcuts act on the focused window's screen, which windowActivated otherwise sets, so a key pressed after such a move acted on the screen the window had left. Updates only that record, and only when windowId is the focused window. Only the registered compositor bridge may call it, and any other caller is answered with AccessDenied.
| Arg | Direction | Type | Description |
|---|---|---|---|
| windowId | in | s (string) | Window identifier. |
| screenId | in | s (string) | Screen the window is now on. |
Push current frame geometry for a window into the daemon's shadow. Called by the compositor plugin on windowFrameGeometryChanged, throttled to one push per window every 50 ms. Sent for every window the plugin manages, including ones kept above others, and not for a window an exclusion rule matches. Enables daemon-local shortcut handlers (e.g. float toggle) to read fresh geometry without a cross-process round-trip. Only the registered compositor bridge may call it, and any other caller is answered with AccessDenied.
| Arg | Direction | Type | Description |
|---|---|---|---|
| windowId | in | s (string) | Window identifier. |
| x | in | i (int32) | |
| y | in | i (int32) | |
| width | in | i (int32) | |
| height | in | i (int32) |
Notify the daemon that a tiled window finished an interactive edge/border resize. The scrolling engine fits the column to the new size, or the autotile engine reflows neighbouring windows to fill the gap (GitHub #652). Fire-and-forget, since the resize is already committed in the compositor. The old/new frames are the window's geometry before and after the resize, supplied by the compositor plugin (the daemon's throttled frame shadow is unreliable as a baseline because it updates during the drag). Floating, untracked and snap-mode windows are ignored daemon-side, and the autotile engine also ignores a resize that carried the window's centre off its screen. Only the registered compositor bridge may call it, and any other caller is answered with AccessDenied.
| Arg | Direction | Type | Description |
|---|---|---|---|
| windowId | in | s (string) | Window identifier. |
| oldX | in | i (int32) | |
| oldY | in | i (int32) | |
| oldWidth | in | i (int32) | |
| oldHeight | in | i (int32) | |
| newX | in | i (int32) | |
| newY | in | i (int32) | |
| newWidth | in | i (int32) | |
| newHeight | in | i (int32) |
Set whether a window is sticky (visible on all virtual desktops). Only the registered compositor bridge may call it, and any other caller is answered with AccessDenied.
| Arg | Direction | Type | Description |
|---|---|---|---|
| windowId | in | s (string) | Window identifier. |
| sticky | in | b (bool) | True if window is on all desktops. |
Record that a window moved to a different screen. The daemon releases the window's snap memory off the new screen. A snapped window loses its zone unless the daemon put it on that screen itself (a restore, resnap or snap assist assigns the zone first), and a floating window forgets the zone it floated from. Only the registered compositor bridge may call it, and any other caller is answered with AccessDenied.
| Arg | Direction | Type | Description |
|---|---|---|---|
| windowId | in | s (string) | Window identifier. |
| newScreenId | in | s (string) | Identifier of the screen the window moved to. |
Record that KWin moved a window between screens where a tiling engine runs on either end (the effect hands the window to the tiling engines itself). The daemon releases what every engine still holds of the window off the new screen: snap zones and floats, another tiling engine's background hold, and the record's slots naming the old monitor, keeping the engine that took the window there. Only the registered compositor bridge may call it, and any other caller is answered with AccessDenied.
| Arg | Direction | Type | Description |
|---|---|---|---|
| windowId | in | s (string) | Window identifier. |
| fromScreenId | in | s (string) | Identifier of the screen the window left. |
| toScreenId | in | s (string) | Identifier of the screen the window moved to. |
Query the daemon's floating state for one window. The effect asks when a window opens, to seed its float cache for that window, and around an unminimize unfloat. Its bring-up re-seed reads getFloatingWindows.
| Arg | Direction | Type | Description |
|---|---|---|---|
| windowId | in | s (string) | Window identifier. |
| floating | out | b (bool) | True if the daemon currently has the window marked as floating. |
Return the pre-tile geometry of every window the daemon currently holds a LIVE record for (appId → rect + screen). The effect pre-populates its local cache from this on bringup so it can teleport restoring windows to their pre-tile geometry without a round-trip on every restore. Each entry carries the appId, the geometry rect (x,y,w,h), and the screen the geometry was captured on. Each entry names the window whose record it is (windowId, the registry's canonical composite), and the compositor applies it to that window only.
| Arg | Direction | Type | Description |
|---|---|---|---|
| geometries | out | a(siiiiss) (array<struct(string,int32,int32,int32,int32,string,string)>) | Array of (appId, x, y, width, height, screenId, windowId). |
Re-drive each placement engine's per-window decoration inputs (snap border / hidden title bar, autotile border, while the scrolling engine has none of its own) for every window it manages. Snap re-states the zone only of a window it holds on the desktop shown on a screen it runs, so no window is moved into a zone it is not in. The compositor effect calls this after (re)registering its bridge so a freshly-(re)started effect converges on the daemon's authoritative appearance without waiting for the next natural change. Window-rule decoration overrides flow separately via the Rules rulesChanged broadcast. Only the registered compositor bridge may call it, and any other caller is answered with AccessDenied.
No arguments.
Get comprehensive state for a single window.
| Arg | Direction | Type | Description |
|---|---|---|---|
| windowId | in | s (string) | Window identifier. |
| state | out | (sssbsasb) (struct(string,string,string,bool,string,array<string>,bool)) | WindowStateEntry: (windowId, zoneId, screenId, isFloating, changeType, zoneIds, isSticky). |
Get the state of every window an engine holds, in any context, tiled ones included (TUI dashboard, shell maps). A tiled window reads as its tiling engine has it, so a snap zone kept for a return to snapping is not reported as a placement.
| Arg | Direction | Type | Description |
|---|---|---|---|
| states | out | a(sssbsasb) (array<struct(string,string,string,bool,string,array<string>,bool)>) | Array of WindowStateEntry structs. |
Ask the compositor to activate (focus) a tracked window. The verb behind a click on a Phosphor shell placement-map cell. The daemon emits activateWindowRequested for the id, the same signal its own focus and cycle verbs use, and the KWin effect turns that into activateWindow. A window the daemon does not track (no setWindowMetadata registration, or already closed) is a silent no-op with no error reply.
| Arg | Direction | Type | Description |
|---|---|---|---|
| windowId | in | s (string) | Window identifier, as the placement models carry it. |
A tracked window's identity as the compositor last reported it through setWindowMetadata: app id, caption, and desktop file name. All three are empty for a window the daemon does not track; title and desktopFile are also empty when the compositor reported them so (a window with no caption yet, or no matching desktop entry). Changes are announced by windowMetadataChanged.
| Arg | Direction | Type | Description |
|---|---|---|---|
| windowId | in | s (string) | Window identifier. |
| appId | out | s (string) | Current app class. |
| title | out | s (string) | Current caption, as the compositor sends it (the KWin effect pushes every caption change). |
| desktopFile | out | s (string) | Desktop file name, without directory, for icon and display-name lookup. |
Ask the compositor to move a tracked window to a virtual desktop. The verb behind dragging a placement-map cell onto another desktop's pane. The daemon emits windowDesktopMoveRequested, which the KWin effect already consumes for the cross-desktop directional move (windowToDesktops); the daemon's own tracking follows through the compositor's resulting desktop report, the same way it does for that move. Silent no-op with no error reply for an untracked window or a desktop below 1 or past the last one.
| Arg | Direction | Type | Description |
|---|---|---|---|
| windowId | in | s (string) | Window identifier. |
| desktop | in | i (int32) | Target virtual desktop, 1-based. |
Every tracked window currently demanding attention (KWin's demandsAttention). The daemon keeps the set from the isDemandingAttention field of the compositor's metadata pushes, which the KWin effect re-sends on every demandsAttentionChanged edge, and drops a window on close. Sorted, so two reads of an unchanged set compare equal. Edges are announced by windowUrgencyChanged.
| Arg | Direction | Type | Description |
|---|---|---|---|
| windowIds | out | as (array<string>) | Window identifiers, sorted. |
getAllWindowStates filtered to one screen and one virtual desktop, for the Phosphor shell dashboard's per-desktop placement maps. A window is on the desktop when its last setWindowMetadata push named it (virtualDesktop, or any entry of the multi-desktop span list), or when it is sticky (the push's IsSticky flag, a virtualDesktop of 0, or the service's setWindowSticky record), which puts it on every desktop. Windows the compositor never registered through setWindowMetadata are left out, since there is no desktop to compare against. Same WindowStateEntry struct and the same rows as getAllWindowStates, tiled windows on a desktop out of view included, with nothing added or re-shaped.
| Arg | Direction | Type | Description |
|---|---|---|---|
| screenId | in | s (string) | Screen identifier the rows must be on (the entry's screenId). Empty means any screen, except that a virtualDesktop of 0 then has no screen to resolve against and answers nothing. |
| virtualDesktop | in | i (int32) | Virtual desktop, 1-based. 0 means the screen's current desktop (per-output on Plasma 6.7, as screenDesktopChanged reported it). Negative answers nothing. |
| states | out | a(sssbsasb) (array<struct(string,string,string,bool,string,array<string>,bool)>) | Array of WindowStateEntry structs: (windowId, zoneId, screenId, isFloating, changeType, zoneIds, isSticky). |
The tracked window whose last setWindowMetadata push carried this process id, for attaching the Phosphor shell's polkit prompt to the window that asked. When several windows share the pid (a multi-window application) the one whose registered record changed most recently wins (a push that repeats a window's record does not count). Empty when no registered window matches, or when pid is not positive.
| Arg | Direction | Type | Description |
|---|---|---|---|
| pid | in | i (int32) | Process id, as setWindowMetadata received it. |
| windowId | out | s (string) | Window identifier, as the placement models carry it, or empty. |
Emitted when a window's zone assignment changes.
| Arg | Direction | Type | Description |
|---|---|---|---|
| windowId | out | s (string) | Window identifier. |
| zoneId | out | s (string) | Zone UUID (or empty if unsnapped). |
A navigation result for the OSD: a daemon verb's own outcome (the snap, autotile and scrolling engines and the Snap adaptor's bus verbs), or one the effect reports through reportNavigationFeedback.
| Arg | Direction | Type | Description |
|---|---|---|---|
| success | out | b (bool) | True if navigation succeeded. |
| action | out | s (string) | Action name (e.g. move, focus). |
| reason | out | s (string) | Reason string (e.g. no adjacent zone). |
| sourceZoneId | out | s (string) | Source zone ID for OSD highlighting. |
| targetZoneId | out | s (string) | Target zone ID for OSD highlighting. |
| screenId | out | s (string) | Screen identifier where navigation occurred (for OSD placement). |
Ask the KWin effect to switch one output's current virtual desktop (per-output virtual desktops). KWin's D-Bus VirtualDesktopManager only exposes the global current, so the dynamic-workspaces focus verbs and the owner-wins snap-back ride this command. The effect answers every request for an output it knows exactly once with a screenDesktopChanged for that output carrying the desktop it shows afterwards: the switch's own report when it switched, otherwise a forced report, as when the id names no desktop, KWin refuses the switch (global virtual desktops), a correction waits out Show Desktop, or the output already showed the desktop. That report is what the daemon's SetCurrent ledger reads. An unknown output gets no answer.
| Arg | Direction | Type | Description |
|---|---|---|---|
| screenId | out | s (string) | Physical screen identifier to switch. |
| desktopId | out | s (string) | Target desktop's stable id (VirtualDesktop::id()). An id rather than a number, so a renumber landing between the emit and the effect's handling cannot point the switch at another desktop. |
| purpose | out | i (int32) | ScreenDesktopSwitchPurpose. 0 is a user focus verb, shown like any switch the user makes. 1 is a correction the daemon makes on its own (the owner-wins return), carried out without the effect's desktop-switch transition. Unknown values are read as 0. |
Emitted at most once per session, once the placement store held records at load or at a layout change and panel geometry is known. The KWin effect should retry restoring untracked windows when receiving this signal.
No payload.
Emitted after a work-area settle (a panel edit, for one) or a resolution or virtual-screen change, so the KWin effect calls getUpdatedWindowGeometries and applies those geometries to snapped windows.
No payload.
Emitted when a window's floating state changes (e.g., when a floating window is drag-snapped). The KWin effect should listen to this to keep its local floating cache in sync.
| Arg | Direction | Type | Description |
|---|---|---|---|
| windowId | out | s (string) | Window identifier. |
| isFloating | out | b (bool) | New floating state. |
| screenId | out | s (string) | Screen where the window is located. |
Daemon requests compositor to apply geometry. The daemon has already committed the placement: zoneId names the zone it committed (empty for a free placement), and screenId is the screen the effect pre-seeds as tracked.
| Arg | Direction | Type | Description |
|---|---|---|---|
| windowId | out | s (string) | Window to apply to, resolved by instance (the exact id, or the same window under a drifted app prefix). A window that closed inside the round trip is not replaced by a same-app window. |
| x | out | i (int32) | Frame x in compositor coordinates. Ignored when sizeOnly is true. |
| y | out | i (int32) | Frame y in compositor coordinates. Ignored when sizeOnly is true. |
| width | out | i (int32) | Frame width. |
| height | out | i (int32) | Frame height. |
| zoneId | out | s (string) | Zone the window is snapped into, empty for a free placement. |
| screenId | out | s (string) | Screen the geometry belongs to. |
| sizeOnly | out | b (bool) | True to resize the window where it stands, keeping the position the compositor chooses (the drag-out unsnap keeps the top-left, a free-size restore at open keeps the centre). |
| purpose | out | i (int32) | PlacementPurpose. 0 places the window a user action is about, so its maximize and fullscreen end. 1 re-states a placement it already has, so a maximized or fullscreen window keeps that state. Unknown values are read as 0. |
A user action on the window that places no geometry for it (a float with no remembered spot, a move to a tiling monitor). The compositor ends the window's own fullscreen where it stands.
| Arg | Direction | Type | Description |
|---|---|---|---|
| windowId | out | s (string) | Window whose fullscreen ends. |
Daemon requests KWin to activate (focus) a window. For the snap engine's focus, cycle and layer-switch verbs and its Focus new windows activation after a restore, the cross-mode focus crossing, and activateWindow.
| Arg | Direction | Type | Description |
|---|---|---|---|
| windowId | out | s (string) | Window to activate. |
Daemon requests KWin to move a window to a virtual desktop by number, on the output it is on: the desktop move shortcut, a RouteToDesktop rule, an engine's cross-desktop crossing and moveWindowToDesktop. The dynamic-workspaces verbs use windowWorkspaceMoveRequested instead. The effect calls windowToDesktops, and a target desktop not in view parks the window for its placement when that desktop is shown.
| Arg | Direction | Type | Description |
|---|---|---|---|
| windowId | out | s (string) | Window to move. |
| desktop | out | i (int32) | Target virtual desktop (1-based). |
Daemon requests KWin to move a window to a desktop and another monitor as ONE step, or to either alone. Sent for every workspace verb's window (the move-window, move-column and move-to-slot verbs, the riders of a workspace moved to another monitor, a RouteToWorkspace rule and the daemon's reunion and removal re-routes), whether or not an engine tracks it, and for an engine's crossing that has to carry the window to another monitor itself: a monitor crossing into a snap layout with no zone to land in, and a cross-desktop crossing onto another monitor's tiled desktop. With an empty desktopId and a desktop below 1 the move has no desktop leg: the window goes to targetScreenId only and joins the desktop that output shows, as KWin's Move to Screen does. The effect judges whether the window lands out of view, and where focus goes when the active window leaves, on the DESTINATION output. A window already on the target output takes no output leg. A window on all desktops takes neither leg of a move that has a desktop leg and is not placed again, since it is already on every desktop.
| Arg | Direction | Type | Description |
|---|---|---|---|
| windowId | out | s (string) | Window to move. |
| desktopId | out | s (string) | Target desktop's stable id (VirtualDesktop::id()). It survives the renumbering the workspace feature does alongside its own moves, where a number resolved before the hop can name another desktop by the time it arrives. Empty to name the desktop by number instead. An id naming no desktop (one removed since) runs neither leg: the window stays on its desktop and output, and the effect places it again where it is (a window on all desktops is left alone, see the signal). |
| desktop | out | i (int32) | Target desktop, 1-based (x11DesktopNumber), read only when desktopId is empty. Below 1 with an empty desktopId, the move has no desktop leg (see the signal). A number naming no desktop runs neither leg, like an unknown desktopId. |
| targetScreenId | out | s (string) | Destination output's screen id. Empty keeps the window on the output it is on. An unknown screen moves the desktop only, and in the output-only form, with no desktop leg, it moves nothing. |
Daemon-initiated cross-output move: the daemon is moving the window onto targetScreenId, and its placement follows on this connection or already ran for a cross-mode move. The window's resulting outputChanged is expected; the effect updates bookkeeping and decoration only, without re-issuing windowClosed/windowOpened. User-drag cross-output moves carry no marker.
| Arg | Direction | Type | Description |
|---|---|---|---|
| windowId | out | s (string) | Window the daemon moved across outputs. |
| targetScreenId | out | s (string) | Destination screen the daemon is moving the window onto. |
| sourceScreenId | out | s (string) | Screen the window is leaving: the spawn screen for open-time routing, the left screen for a cross-mode move. Empty for an engine move, armed before the engine re-keys the window, where the compositor may take its own notified-screen record as the source. |
Daemon requests compositor to apply geometries for a batch of windows.
| Arg | Direction | Type | Description |
|---|---|---|---|
| geometries | out | a(siiiis) (array<struct(string,int32,int32,int32,int32,string)>) | Array of (windowId, x, y, width, height, screenId). A non-empty screenId is the zone's screen for a snap placement, and the compositor seeds its tracked-screen cache from it. An empty screenId marks a float or restore entry: the compositor clears the window's snapped mark, judges the rect on the screen it lies on, and skips a minimized window. |
| action | out | s (string) | rotate, resnap, restate or vs_reconfigure. It picks the compositor's animation profile, and only resnap offers Snap Assist afterwards. |
Reserved: the daemon does not emit it. It stays on the interface because shipped compositor bridges subscribe to it.
| Arg | Direction | Type | Description |
|---|---|---|---|
| windowIds | out | as (array<string>) | Ordered list of window IDs (bottom-to-top). |
Emitted when snap-all-windows shortcut is triggered. KWin effect should collect unsnapped windows and call calculateSnapAllWindows (on org.phosphor_works.Placement.Snap).
| Arg | Direction | Type | Description |
|---|---|---|---|
| screenId | out | s (string) | Screen to operate on. |
Emitted when a specific window (e.g. from Snap Assist) should be moved to a zone.
| Arg | Direction | Type | Description |
|---|---|---|---|
| windowId | out | s (string) | |
| zoneId | out | s (string) | |
| x | out | i (int32) | |
| y | out | i (int32) | |
| width | out | i (int32) | |
| height | out | i (int32) |
Unified window state change stream. Emitted on snap, unsnap, float, unfloat, and screen change events. A screen change carries isFloating true for a floating window and false for a snapped one, which has lost its zone.
| Arg | Direction | Type | Description |
|---|---|---|---|
| windowId | out | s (string) | Window whose state changed. |
| state | out | (sssbsasb) (struct(string,string,string,bool,string,array<string>,bool)) | WindowStateEntry: (windowId, zoneId, screenId, isFloating, changeType, zoneIds, isSticky). changeType: snapped, unsnapped, floated, unfloated, screen_changed. |
The daemon no longer keeps a window parked for the return of an output that went away: it was re-seated, touched, closed, or moved off every desktop the park held it on. The effect forgets its record of the window's state on that output.
| Arg | Direction | Type | Description |
|---|---|---|---|
| windowId | out | s (string) | The window. |
| outputUuid | out | s (string) | KWin's uuid of the output the window was parked for. Empty when no settle report row the daemon has read carried that output as the window's state before the output went away (its S0), so the daemon never learned its uuid. The drop still names one output, and the effect forgets only the records it never sent as that state. |
The window was put back into its parked place on an output that returned. When nothing else stays parked for it there, parkDropped for the same window and output follows at once. Sent alone, the window is still parked there for another desktop or activity. A parkDropped with no parkReseated just ahead of it put nothing back, for example when the window's desktop was given another mode while the output was away, and the window is then placed as any opening window is.
| Arg | Direction | Type | Description |
|---|---|---|---|
| windowId | out | s (string) | The window. |
| outputUuid | out | s (string) | KWin's uuid of the output, as parkDropped carries it. Empty when the daemon never learned it. |
A tracked window's app id or caption changed, or the window was just registered. Emitted only when one of the two carried fields differs from the previous push, so a geometry or state edge that leaves them equal is silent. A consumer that also wants the desktop file reads getWindowMetadata.
| Arg | Direction | Type | Description |
|---|---|---|---|
| windowId | out | s (string) | Window identifier. |
| appId | out | s (string) | Current app class. |
| title | out | s (string) | Current caption. |
A tracked window started or stopped demanding attention. Emitted once per edge, never for a push that repeats the current state, and once with urgent false when a window closes while urgent so a consumer's own set never keeps a dead entry.
| Arg | Direction | Type | Description |
|---|---|---|---|
| windowId | out | s (string) | Window identifier. |
| urgent | out | b (bool) | True when the window now demands attention. |
getPendingRestoreGeometries may answer differently now, because a layout was assigned or switched, a desktop or activity was switched, a context was disabled, or an output was added, removed or moved. Emitted once per burst however many of those happened in it, after a short quiet interval. The KWin effect fetches its instant-restore cache again.
No payload.