org.plasmazones.WindowTracking

Window-to-zone tracking: pre-snap geometry for restore, floating state, zone geometry, drag-out unsnap, resolution-change handling, keyboard-navigation feedback, and window-metadata registration. Snap commits, snap-restore fallback chains, and daemon-driven navigation targets live on the org.plasmazones.Snap adaptor.

Well-known name	org.plasmazones.WindowTracking
Source XML	org.plasmazones.WindowTracking.xml
Methods	37
Signals	14
Properties	0

Methods

<tt>notifyDragOutUnsnap()</tt>

Notify that a snapped window was dragged without the activation trigger. Saves pre-float zone, marks floating, and clears zone assignment so the window does not auto-restore to the zone on close/reopen.

Arg	Direction	Type	Description
windowId	in	s *(string)*	Window ID from the effect.

<tt>getZoneForWindow()</tt>

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.

<tt>getMultiZoneForWindow()</tt>

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.

<tt>getWindowsInZone()</tt>

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.

<tt>getSnappedWindows()</tt>

Return all window IDs that are snapped to any zone.

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

<tt>pruneStaleWindows()</tt>

Remove zone assignments for windows not in the alive set. Called by KWin effect after daemon ready to clean up stale KConfig entries.

Arg	Direction	Type	Description
aliveWindowIds	in	as *(array<string>)*	Window IDs currently known to KWin.

<tt>getEmptyZones()</tt>

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

<tt>getLastUsedZoneId()</tt>

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.

<tt>storePreTileGeometry()</tt>

Store window geometry before tiling (snap or autotile). If overwrite is false (snap mode), skips if entry exists.

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 connector name where window is located (for cross-screen restore).
overwrite	in	b *(bool)*	If false, skip if entry exists (snap). If true, always overwrite (autotile).

<tt>hasPreTileGeometry()</tt>

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.

<tt>getValidatedPreTileGeometry()</tt>

Return pre-tile geometry (pre-snap or pre-autotile) validated against current screen bounds (adjusts off-screen). 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).

<tt>clearPreTileGeometry()</tt>

Clear stored pre-tile geometry for a window.

Arg	Direction	Type	Description
windowId	in	s *(string)*	Window identifier.

<tt>setWindowFloating()</tt>

Set whether a window is floating (not snapped).

Arg	Direction	Type	Description
windowId	in	s *(string)*	Window identifier.
floating	in	b *(bool)*	True to float.

<tt>isWindowFloating()</tt>

Return true if the window is floating.

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

<tt>getFloatingWindows()</tt>

Return all window IDs that are floating.

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

<tt>getPreFloatZone()</tt>

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

<tt>clearPreFloatZone()</tt>

Clear saved pre-float zone for the window.

Arg	Direction	Type	Description
windowId	in	s *(string)*	Window identifier.

<tt>getZoneGeometry()</tt>

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

<tt>getZoneGeometryForScreen()</tt>

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

<tt>getUpdatedWindowGeometries()</tt>

Return updated window geometries after resolution change.

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.

<tt>getPendingRestoreGeometries()</tt>

Pre-computed zone geometries for pending restore entries. The effect caches these for instant window teleport on open (no D-Bus round-trip flash).

Arg	Direction	Type	Description
geometriesJson	out	s *(string)*	JSON object: { appId: {x, y, width, height}, ... }

<tt>reportNavigationFeedback()</tt>

Report keyboard-navigation result from KWin effect; daemon emits navigationFeedback for OSD.

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

<tt>setWindowFloatingForScreen()</tt>

Set a window's floating state explicitly (directional, not toggle). Routes to autotile engine for autotile screens, handles snap mode locally. Used by minimize/unminimize, drag-to-float, and monocle unmaximize.

Arg	Direction	Type	Description
windowId	in	s *(string)*	Window identifier (from KWin).
screenId	in	s *(string)*	Screen where window is located.
floating	in	b *(bool)*	True to float, false to unfloat.

<tt>cursorScreenChanged()</tt>

Report that the cursor has moved to a different screen. Called by KWin effect when cursor crosses monitor boundaries.

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

<tt>screenDesktopChanged()</tt>

Report a screen's current virtual desktop (Plasma 6.7 per-output virtual desktops). Called by the KWin effect on KWin::EffectsHandler::desktopChanged with the per-output desktop. KWin's own D-Bus interface only exposes the global current desktop, so per-screen data arrives this way.

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

<tt>setWindowMetadata()</tt>

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. Idempotent — safe to call on every observation; a no-op if metadata is unchanged.

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) 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. Lets the daemon's Float/RestorePosition resolvers match the same KWin-property fields the effect path resolves live.

<tt>windowClosed()</tt>

Notify daemon that a window was closed (cleanup). The window's structural kind is captured into the PendingRestore entry if one is recorded, so the consume path can refuse to assign that entry to a window of a different kind on reopen.

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). Recorded on the PendingRestore entry if one is enqueued. Pass 0 to opt out of the gate (legacy callers).
screenId	in	s *(string)*	The window's authoritative current screen at close (KWin'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 both engines' tracking. Empty opts out (legacy callers).

<tt>windowActivated()</tt>

Notify daemon that a window was activated/focused.

Arg	Direction	Type	Description
windowId	in	s *(string)*	Window identifier.
screenId	in	s *(string)*	Screen where window is located.

<tt>setFrameGeometry()</tt>

Push current frame geometry for a window into the daemon's shadow. Called by the compositor plugin on windowFrameGeometryChanged (debounced). Enables daemon-local shortcut handlers (e.g. float toggle) to read fresh geometry without a cross-process round-trip.

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

<tt>notifyWindowResized()</tt>

Notify the daemon that a tiled window finished an interactive edge/border resize. The autotile engine reflows neighbouring windows to fill the gap (GitHub #652). Fire-and-forget; 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 debounced frame shadow is unreliable as a baseline because it updates during the drag). Floating, untracked, snap-mode, and cross-output windows are ignored daemon-side.

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

<tt>setWindowSticky()</tt>

Set whether a window is sticky (visible on all virtual desktops).

Arg	Direction	Type	Description
windowId	in	s *(string)*	Window identifier.
sticky	in	b *(bool)*	True if window is on all desktops.

<tt>windowScreenChanged()</tt>

Record that a window moved to a different screen. The daemon compares the new screen against the window's stored snap assignment and unsnaps if they differ — heuristic for distinguishing a user-initiated cross-screen drag from a programmatic resnap (programmatic moves assign the zone first, so the stored screen matches and no unsnap occurs).

Arg	Direction	Type	Description
windowId	in	s *(string)*	Window identifier.
newScreenId	in	s *(string)*	Identifier of the screen the window moved to.

<tt>queryWindowFloating()</tt>

Query the daemon's authoritative floating state for a window. The effect uses this on bringup to reconcile its local cache against persisted state across daemon restarts.

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.

<tt>getPreTileGeometries()</tt>

Return every persisted pre-tile geometry (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 (entries persist across window close/reopen for session restore, so the per-instance windowId is not the key), the geometry rect (x,y,w,h), and the screen the geometry was captured on.

Arg	Direction	Type	Description
geometries	out	a(siiiis) *(array<struct(string,int32,int32,int32,int32,string)>)*	Array of (appId, x, y, width, height, screenId) — the same marshalling shape as applyGeometriesBatch and getUpdatedWindowGeometries.

<tt>reapplyWindowAppearance()</tt>

Re-drive each placement engine's per-window decoration inputs (snap border / hidden title bar, autotile border) for every window it manages. 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 WindowRules rulesChanged broadcast.

No arguments.

<tt>getWindowState()</tt>

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

<tt>getAllWindowStates()</tt>

Get state for all tracked windows (TUI dashboard).

Arg	Direction	Type	Description
states	out	a(sssbsasb) *(array<struct(string,string,string,bool,string,array<string>,bool)>)*	Array of WindowStateEntry structs.

Signals

<tt>windowZoneChanged</tt>

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

<tt>navigationFeedback</tt>

Emitted when KWin effect reports navigation result via reportNavigationFeedback (for OSD).

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

<tt>pendingRestoresAvailable</tt>

Emitted when the daemon's layout becomes available and there are pending zone restores. The KWin effect should retry restoring untracked windows when receiving this signal.

No payload.

<tt>reapplyWindowGeometriesRequested</tt>

Emitted after panel geometry has settled so the KWin effect should call getUpdatedWindowGeometries and apply those geometries to snapped windows. Fixes shifted windows after closing the KDE panel editor.

No payload.

<tt>windowFloatingChanged</tt>

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.

<tt>applyGeometryRequested</tt>

Daemon requests compositor to apply geometry. zoneId empty = float restore only; zoneId set = apply and call windowSnapped.

Arg	Direction	Type	Description
windowId	out	s *(string)*
x	out	i *(int32)*
y	out	i *(int32)*
width	out	i *(int32)*
height	out	i *(int32)*
zoneId	out	s *(string)*
screenId	out	s *(string)*
sizeOnly	out	b *(bool)*

<tt>activateWindowRequested</tt>

Daemon requests KWin to activate (focus) a window. Used by daemon-driven focus/cycle navigation.

Arg	Direction	Type	Description
windowId	out	s *(string)*	Window to activate.

<tt>windowDesktopMoveRequested</tt>

Daemon requests KWin to move a window to a virtual desktop. Used by cross-desktop directional move; the effect calls windowToDesktops.

Arg	Direction	Type	Description
windowId	out	s *(string)*	Window to move.
desktop	out	i *(int32)*	Target virtual desktop (1-based).

<tt>windowOutputMoveExpected</tt>

Daemon-initiated cross-output move: the daemon already migrated its tiling state for the window onto targetScreenId and reflowed both outputs. 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 migrated the window onto.

<tt>applyGeometriesBatch</tt>

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). screenId is the daemon-authoritative target screen — compositor uses it to seed its tracked-screen cache without re-deriving from geometry. Empty screenId means no authoritative answer (fall back to geometry-based resolution).
action	out	s *(string)*	Navigation action type (rotate, resnap, vs_reconfigure) for feedback.

<tt>raiseWindowsRequested</tt>

Daemon requests KWin to raise windows in order (z-order restoration).

Arg	Direction	Type	Description
windowIds	out	as *(array<string>)*	Ordered list of window IDs (bottom-to-top).

<tt>snapAllWindowsRequested</tt>

Emitted when snap-all-windows shortcut is triggered. KWin effect should collect unsnapped windows and call calculateSnapAllWindows (on org.plasmazones.Snap).

Arg	Direction	Type	Description
screenId	out	s *(string)*	Screen to operate on.

<tt>moveSpecificWindowToZoneRequested</tt>

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

<tt>windowStateChanged</tt>

Unified window state change stream. Emitted on snap, unsnap, float, unfloat, and screen change events.

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.