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

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

Methods

notifyDragOutUnsnap()

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.

getZoneForWindow()

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.

getMultiZoneForWindow()

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.

getWindowsInZone()

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.

getSnappedWindows()

Return all window IDs that are snapped to any zone.

Arg Direction Type Description
windowIds out as (array<string>) All snapped window IDs.

pruneStaleWindows()

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.

getEmptyZones()

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

getLastUsedZoneId()

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.

storePreTileGeometry()

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.

hasPreTileGeometry()

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.

getValidatedPreTileGeometry()

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

clearPreTileGeometry()

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.

setWindowFloating()

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.

isWindowFloating()

Return true if the window is floating.

Arg Direction Type Description
windowId in s (string) Window identifier.
floating out b (bool) True if floating.

getFloatingWindows()

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.

getPreFloatZone()

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

clearPreFloatZone()

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.

getZoneGeometry()

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

getZoneGeometryForScreen()

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

getUpdatedWindowGeometries()

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.

reportOutputSettle()

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.

getPendingRestoreGeometries()

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.

reportNavigationFeedback()

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

setWindowFloatingForScreen()

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.

cursorScreenChanged()

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

screenDesktopChanged()

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

reportPerOutputDesktopsMode()

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.

seedScreenDesktop()

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

setWindowMetadata()

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.

windowClosed()

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

windowActivated()

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.

activeWindowScreenChanged()

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.

setFrameGeometry()

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)

notifyWindowResized()

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)

setWindowSticky()

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.

windowScreenChanged()

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.

windowCrossedScreens()

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.

queryWindowFloating()

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.

getPreTileGeometries()

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

reapplyWindowAppearance()

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.

getWindowState()

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

getAllWindowStates()

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.

activateWindow()

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.

getWindowMetadata()

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.

moveWindowToDesktop()

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.

getUrgentWindows()

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.

getWindowStatesForDesktop()

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

findWindowByPid()

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.

Signals

windowZoneChanged

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

navigationFeedback

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

setScreenDesktopRequested

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.

pendingRestoresAvailable

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.

reapplyWindowGeometriesRequested

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.

windowFloatingChanged

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.

applyGeometryRequested

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.

fullscreenHandBackRequested

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.

activateWindowRequested

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.

windowDesktopMoveRequested

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

windowWorkspaceMoveRequested

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.

windowOutputMoveExpected

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.

applyGeometriesBatch

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.

raiseWindowsRequested

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

snapAllWindowsRequested

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.

moveSpecificWindowToZoneRequested

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)

windowStateChanged

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.

parkDropped

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.

parkReseated

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.

windowMetadataChanged

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.

windowUrgencyChanged

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.

pendingRestoresChanged

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.