Shared tiling-family transport: the engine-managed screen set, window lifecycle notifications from the KWin effect, and geometry/focus/float requests to it. Engine-specific control lives on org.phosphor_works.Placement.Autotile and org.phosphor_works.Placement.Scrolling.
| Well-known name | org.phosphor_works.Placement.Tiling |
| Source XML | org.phosphor_works.Placement.Tiling.xml |
| Methods | 14 |
| Signals | 12 |
| Properties | 3 |
Force retiling of windows on a screen, or all screens if empty.
| Arg | Direction | Type | Description |
|---|---|---|---|
| screenId | in | s (string) | Screen to retile, or empty for all screens. |
Force retiling of all engine-managed screens. Convenience method equivalent to retile with an empty screen ID.
No arguments.
Notify the daemon that a window has been focused (called from KWin effect). Updates the owning engine's focus tracking and window-to-screen mapping. The screenId must name a screen the compositor currently reports for that window: a screen no engine knows is ignored rather than treated as a move, because reading an unknown screen as a genuine cross-screen move would untrack the window with no repair path on this channel. 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 that gained focus. |
| screenId | in | s (string) | Screen where the window is located (for window-to-screen mapping update). |
Notify the daemon that a window genuinely opened (called from KWin effect). The only announce that may take focus under Focus new windows. 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 KWin. |
| screenId | in | s (string) | Screen where the window appeared. |
| minWidth | in | i (int32) | Window minimum width in pixels (0 if unconstrained). |
| minHeight | in | i (int32) | Window minimum height in pixels (0 if unconstrained). |
Hand an already-shown window (back) to the tiling engines without it counting as an open: a desktop-switch catch-scan, a cross-output re-add, an unminimize. Placed exactly like windowOpened, but never takes focus. Added in API v10. 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 KWin. |
| screenId | in | s (string) | Screen the window is on. |
| minWidth | in | i (int32) | Window minimum width in pixels (0 if unconstrained). |
| minHeight | in | i (int32) | Window minimum height in pixels (0 if unconstrained). |
Batch re-announce: process multiple windows in one D-Bus call. Used on daemon startup/restart and mode toggle-on, so its entries are re-placements and never take focus. Array of (windowId, screenId, minWidth, minHeight). Only the registered compositor bridge may call it, and any other caller is answered with AccessDenied.
| Arg | Direction | Type | Description |
|---|---|---|---|
| entries | in | a(ssii) (array<struct(string,string,int32,int32)>) | Array of window-opened entry structs. |
Update a window's minimum size at runtime. Called by KWin effect when a window's minimum size changes after initial windowOpened. Triggers retiling if the value differs. 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 KWin. |
| minWidth | in | i (int32) | New minimum width in pixels (0 if unconstrained). |
| minHeight | in | i (int32) | New minimum height in pixels (0 if unconstrained). |
Notify the daemon that a window was closed (called from KWin effect). 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 KWin. |
Drop a LIVE window from engine tracking without a close, such as one crossing to another output or desktop or no longer tileable. Unlike windowClosed, no placement capture runs: the window is not dying and its current frame is transient state, not a placement. 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 KWin. |
Every screen's current tab-indicator model, as a map of effective screen id to the JSON string described on scrollTabStripsChanged. The replay half of that signal, for an effect that loads (or reloads) after the strips were last laid out and would otherwise paint nothing until the next relayout. Screens with no tabbed column are absent from the map rather than present with an empty array.
| Arg | Direction | Type | Description |
|---|---|---|---|
| strips | out | a{sv} (dict<string,variant>) | Map of effective screen id to tab-strip JSON string. |
Every screen's current tab-indicator paint overrides resolved from context rules (a Set tab style / gaps / corner radius / colour / label-font rule scoped to a screen, desktop or activity), as a map of effective screen id to a map of paint key to value. Keys are tabStyle, gapsBetweenTabs, cornerRadius, activeColor, inactiveColor, urgentColor, fontFamily, fontWeight, fontItalic, fontUnderline and fontStrikeout. An empty fontFamily is a set value meaning the system font, not an absent override. Only the keys a rule actually set are present, and each layers over the matching global Scrolling.TabIndicator setting for that screen alone. The replay half of scrollTabPaintOverridesChanged. Screens with no override are absent.
| Arg | Direction | Type | Description |
|---|---|---|---|
| overrides | out | a{sv} (dict<string,variant>) | Map of effective screen id to a paint-key map. |
Per-window tab colours resolved from the window rules, keyed activeColor / inactiveColor / urgentColor with colour strings as values. An EMPTY map means no rule sets a tab colour for this window and the painter must use its own defaults. Only the keys a rule actually sets are present, so a caller reads each key independently. Rules that pair a tab colour with a ScreenId or Mode condition are inert on this path, because the query carries no screen or mode stamp.
| Arg | Direction | Type | Description |
|---|---|---|---|
| windowId | in | s (string) | Window ID to resolve colours for. |
| colors | out | a{sv} (dict<string,variant>) | Colour key to colour string, empty when no rule applies. |
The last geometry batch this interface emitted for a screen, replayed as JSON so a client that attaches after the batch went out can rebuild the screen's tiles without asking for a retile. A JSON array with one object per entry of the last windowsTileRequested batch that named this screen, restricted to that screen's entries, carrying the keys the daemon's own batch parser reads (windowId, x, y, width, height, screenId, monocle and floating) and zoneId, which that parser does not read. x, y, width and height are the committed rect in absolute logical pixels and are all 0 on a floating entry, which carries no rect. zoneId is reserved and always empty, as on the signal. The daemon keeps ONE batch per screen, replaced whenever a newer batch names the screen, and prunes an entry the moment its window is closed or released from tracking, so a replay never resurrects a window that has already gone. A screen that leaves the engine-managed set has its batch dropped with the announce that removes it, and a daemon restart starts with nothing. The array is empty (the two characters []) for a screen no batch has named, for an empty screenId, and after the screen's batch was dropped. This is a replay of what was SENT, not a fresh resolve: the paint hints the signal carries beside the rect (scrollEdge, viewDelta, the visual position, tabFrom, viewImmediate) are deliberately absent, because they described a transition rather than a state.
| Arg | Direction | Type | Description |
|---|---|---|---|
| screenId | in | s (string) | Screen whose last batch to replay. An empty string yields an empty array. |
| tilesJson | out | s (string) | JSON array string. |
The window the engine owning a screen considers focused there, or an empty string. Answered by whichever tiling-family engine currently claims the screen (the scroll engine's active tile of the active column, autotile's tracked focus), so the answer follows the screen's mode rather than a caller having to know it. Empty for a screen no tiling-family engine owns, which includes every snapping screen: that mode's placement runs outside this interface's pipeline and has no arm here. Empty also for an empty screenId and while the pipeline is torn down. Changes are announced on focusedWindowChanged below.
| Arg | Direction | Type | Description |
|---|---|---|---|
| screenId | in | s (string) | Screen to ask about. An empty string yields an empty string. |
| windowId | out | s (string) | Window id, or empty when no engine-managed window holds focus there. |
Emitted when the pipeline enabled state changes (any engine active/inactive).
| Arg | Direction | Type | Description |
|---|---|---|---|
| enabled | out | b (bool) | New enabled state. |
Emitted when the set of engine-managed screens changes. Also RE-EMITTED with an unchanged set on a desktop/activity switch between contexts with identical NON-EMPTY managed sets (isDesktopSwitch=true) so the effect's catch-scan can re-add windows moved here while the user was away — an empty identical set skips the re-emit, and receivers must be idempotent for the same-set case.
| Arg | Direction | Type | Description |
|---|---|---|---|
| screenIds | out | as (array<string>) | List of screen IDs currently engine-managed. |
| isDesktopSwitch | out | b (bool) | True if the change is due to desktop/activity switch (effect should skip geometry restore/re-notification). |
| screenDesktops | out | a{sv} (dict<string,variant>) | screenId to virtual desktop (int) the announced set was RESOLVED AGAINST. This signal is asynchronous while the compositor's own desktopChanged is not, so an announce can arrive after the user has switched again, describing a desktop that is no longer current. Without this stamp the receiver cannot tell such an announce from a fresh one — its own last-reported desktop already equals the live one — and would install a managed set for one desktop while filtering windows by another. Receivers compare against what they last reported per screen and DROP a mismatch, relying on the next announce rather than queuing the dropped one for replay. |
Emitted when any screen's rules-visible active layout changes (see the activeLayouts property for the value vocabulary). Deduplicated: the daemon pushes on every screen-set recompute and only actual map changes reach the wire.
| Arg | Direction | Type | Description |
|---|---|---|---|
| activeLayouts | out | a{sv} (dict<string,variant>) | Full screenId to rules-visible layout id map after the change. |
Emitted when tiling layout changes for a screen.
| Arg | Direction | Type | Description |
|---|---|---|---|
| screenId | out | s (string) | Screen that was retiled. |
Emitted when windows should be moved to new geometries (batch).
| Arg | Direction | Type | Description |
|---|---|---|---|
| tileRequests | out | a(siiiissbbbbssiiibsb) (array<struct(string,int32,int32,int32,int32,string,string,bool,bool,bool,bool,string,string,int32,int32,int32,bool,string,bool)>) | Array of (windowId, x, y, width, height, zoneId, screenId, monocle, floating, windowedFullscreen, maximizedToEdges, stacking, scrollEdge, viewDelta, visualX, visualY, hasVisualPos, tabFrom, viewImmediate). zoneId is reserved and currently always empty on this signal. windowedFullscreen means the effect flips KWin fullscreen state on the client while committing the column rect (scrolling windowed fullscreen). maximizedToEdges means this window's scrolling column is maximized to the screen edges (it fills the available area on both axes with no gaps while staying tiled), and the effect mirrors that onto KWin's maximize bit so the titlebar button agrees with the engine however the maximize was reached. It is declared engine state driven by the Scrolling toggleMaximizeToEdges verb, never inferred from the rect, and it carries no geometry: the committed rect already has the full placement. scrollEdge is the side a parked scrolling column departs towards, one of {left, right, top, bottom}, and empty for any placement that is not a scrolling park. viewDelta is how far a scrolling strip's view slid since the last batch, in logical pixels, for this entry's screen. It is a signed scalar along THAT screen's own strip axis, so it reads as a horizontal slide on a horizontal strip and a vertical one on a vertical strip, and a consumer must take the axis from the screen rather than assuming x. Zero for every other placement and for a window the view does not carry. visualX/visualY, valid only when hasVisualPos is true, are where a PARKED scrolling column really sits on the strip: the committed rect stays the safe off-monitor park while this is the position to paint at, so the column is seen travelling with the rest of the strip. tabFrom, set only on a tab being activated in a tabbed column, names the tab it is replacing: the outgoing tab parks and this one takes the rect it vacated, and the pair is not recoverable from the rects alone, so the compositor cross-fades the two instead of hard-cutting between them. viewImmediate marks a batch whose view travel is user-driven continuous motion (the drag edge auto-scroll heartbeat): the compositor applies viewDelta outright instead of animating it, because the per-tick commits are the motion. |
Emitted when a window should be focused by the KWin effect.
| Arg | Direction | Type | Description |
|---|---|---|---|
| windowId | out | s (string) | Window ID to focus. |
Emitted when windows are released from engine management (e.g., screen left an engine-managed mode). External contract surface only: the PlasmaZones KWin effect does not subscribe, because the restore runs through the daemon-internal windowsReleased wiring and the resnap path.
| Arg | Direction | Type | Description |
|---|---|---|---|
| windowIds | out | as (array<string>) | Window IDs no longer under engine control. |
The daemon's notion of the engine-managed focused window on a screen changed. Emitted once per actual change and never for a repeat: the daemon re-reads the owning engine's answer after every focus report from the compositor (notifyWindowFocused), after every engine-driven activation (a focus verb, a window open that takes focus), after every relayout it announces on tilingChanged, after a window closes, and after each coalesced managed-screens announce, and compares against the last value it broadcast for that screen. The payload carries the whole answer, so a receiver replaces rather than merges. An empty windowId means no engine-managed window holds focus there any more, which is also what a screen leaving the engine-managed set announces. NOT seeded at bring-up: a consumer that attaches later reads managedFocusedWindow for the screens it cares about and then follows this signal.
| Arg | Direction | Type | Description |
|---|---|---|---|
| screenId | out | s (string) | Screen whose focused window changed. |
| windowId | out | s (string) | The window now focused there, or empty. |
Emitted when a window's floating state changes.
| Arg | Direction | Type | Description |
|---|---|---|---|
| windowId | out | s (string) | Window ID whose floating state changed. |
| isFloating | out | b (bool) | Whether the window is now floating. |
| screenId | out | s (string) | Screen where the window is located. |
A screen's tab-indicator model changed. stripsJson is a JSON array with one object per VISIBLE tabbed column: x, y, width and height give the indicator bar's rect on that column in absolute logical coordinates (the rect the engine resolved for the pills, not the column rect), position is where the indicator sits on that column (0 Left, 1 Right, 2 Top, 3 Bottom), activeIndex is the zero-based index of the tab currently showing, and tabs is the column's window IDs in strip order. The array is empty (the two characters []) when the screen has no tabbed column, which is how a screen's indicators are retracted. Emitted after every strip relayout that changes the model, so a receiver may treat each payload as the complete state for that screen.
| Arg | Direction | Type | Description |
|---|---|---|---|
| screenId | out | s (string) | Effective screen id the model belongs to. |
| stripsJson | out | s (string) | JSON array of tabbed-column entries, or [] when the screen has none. |
A screen's context-rule tab-indicator paint overrides changed. Same eleven-key set as scrollTabPaintOverrides (tabStyle, gapsBetweenTabs, cornerRadius, activeColor, inactiveColor, urgentColor, fontFamily, fontWeight, fontItalic, fontUnderline, fontStrikeout). An empty map means the screen has no override and the global settings apply to it again.
| Arg | Direction | Type | Description |
|---|---|---|---|
| screenId | out | s (string) | Effective screen id. |
| overrides | out | a{sv} (dict<string,variant>) | Paint key to value, empty to clear. |
Tab colours resolved from window rules changed. Two shapes. The BROADCAST has an empty windowId and an empty colors map and means every cached scrollTabColors answer is stale and must be re-queried for the windows the receiver is painting. It is sent when a rules save or a colour-scheme flip moves the verdict for every window at once. The TARGETED form names one window and carries its resolved colour map, and is sent when that window's metadata record changes (its title, state, desktop or another field the compositor reports) or its first record lands while it is a tab. An unchanged map is not re-sent. The map may itself be empty, meaning the window has no tab-colour rule, so windowId alone tells the two shapes apart.
| Arg | Direction | Type | Description |
|---|---|---|---|
| windowId | out | s (string) | Window whose colours changed. Empty for the all-windows broadcast. |
| colors | out | a{sv} (dict<string,variant>) | Resolved colours for the named window, keyed activeColor, inactiveColor and urgentColor. Empty for the broadcast, and empty when the named window has no tab-colour rule. |
| Property | Access | Type | Description |
|---|---|---|---|
| enabled | read | b (bool) | Whether any tiling-family engine is active on any screen (read-only, derived from assignments). Changes are announced on the enabledChanged signal below, not through org.freedesktop.DBus.Properties.PropertiesChanged, which this property does not emit. |
| managedScreens | read | as (array<string>) | UNION of every tiling-family engine's screens. org.phosphor_works.Placement.Scrolling names the scrolling subset. Changes are announced on the managedScreensChanged signal below, which carries an extra isDesktopSwitch flag the property itself cannot express, not through org.freedesktop.DBus.Properties.PropertiesChanged, which this property does not emit. |
| activeLayouts | read | a{sv} (dict<string,variant>) | Per-screen RULES-VISIBLE active layout id (screenId to string): a snapping layout UUID, autotile:<algorithmId>, scrolling:<templateUuid> for a templated scrolling context, the bare scrolling: sentinel when no template resolves, the reserved word "none" for a Snapping context explicitly set to no layout, or "autotile:none" for an Autotile context explicitly set to no algorithm. Pushed by the daemon so effect-evaluated window rules see the same ActiveLayout vocabulary as daemon-evaluated context rules. Covers EVERY effective screen, not just engine-managed ones. Changes are announced on the activeLayoutsChanged signal below, not through org.freedesktop.DBus.Properties.PropertiesChanged, which this property does not emit. |