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

Scroll-engine-specific surface. Window lifecycle and tile-request traffic for scrolling screens rides org.phosphor_works.Placement.Tiling (the shared tiling-family pipeline, which routes per screen). This interface carries the scrolling screen set, the strip snapshot the settings app renders as its preview surface (plus the preset vocabulary beside it), the wheel-driven focusColumn and scrollView verbs, their placement-map twins focusColumnAt, moveColumnTo and scrollViewByPx beside the stripModelJson whole-strip read they act on, the four absolute width/height setters for external scripting, the toggleMaximizeColumn width verb, the toggleMaximizeToEdges verb the KWin effect sends when a scroll-managed window is asked to maximize, the clearWindowedFullscreen reconciliation call the KWin effect sends when a client leaves fullscreen on its own, the reapplyWindowGeometry repair call it sends on a fullscreen exit whose strip rects never moved, the reportCommittedSize call it sends when a client, Wayland or XWayland, settles on a size other than the rect the strip offered it (or, for a parked tile, on that rect itself), the blueprintProgressJson template-seed report, the stripChanged wake-up that tells a renderer its strip is worth re-reading, the focus-follows-mouse scroll cap's blocked-window list, the stripContextChanged announcement of which strip a screen is currently showing, the setWindowFullscreenFloat hold the KWin effect sends when a strip tile enters or leaves its own fullscreen, and the scrollingScreensChanged / scrollEffectBehaviourChanged / scrollFocusScrollBlockedWindowsChanged change announcements for the three properties.

Well-known name org.phosphor_works.Placement.Scrolling
Source XML org.phosphor_works.Placement.Scrolling.xml
Methods 19
Signals 5
Properties 3

Methods

focusColumn()

Focus the adjacent column on a scrolling screen. Called by the KWin effect's Meta+wheel axis shortcut with the cursor's screen. A press at the strip's edge CROSSES to the adjacent output when one exists — including a neighbour running a different mode, where the daemon activates that engine's entry-edge window — and a press on an EMPTY scrolling screen crosses the same way instead of dead-ending, so a wheel notch can move focus to another monitor. Every rejected call is a silent no-op with no error reply: an empty screenId, a screen the scrolling engine does not own, a screen whose current scrolling context is disabled (the same per-context gate the keyboard verbs pass through), and any delta other than -1 or +1 are all ignored, so a caller cannot tell a refusal from a call that landed on an empty strip.

Arg Direction Type Description
screenId in s (string) Screen whose strip should move (the cursor's screen). An empty string is ignored.
delta in i (int32) -1 focuses the previous column along the strip, +1 the next one (left/right on a horizontal strip, up/down on a vertical one). Any other value is ignored.

scrollView()

Scroll the view along a scrolling screen's strip by one configured step WITHOUT moving focus. Called by the KWin effect's Meta+Shift+wheel axis shortcut with the cursor's screen, one call per wheel notch, the pointer-gesture twin of focusColumn. The view stays where the scroll leaves it until the next focus change or centering verb, and a notch at the strip's end never crosses to another output, unlike focusColumn: it answers with the no-target navigation OSD (when that OSD is on) like the sibling verbs, and no error reply. A step that rounds to zero pixels answers the same way under its own no_movement reason. Same silent ownership and per-context gates as focusColumn: an empty screenId, a screen the scrolling engine does not own, a screen whose current scrolling context is disabled, and any delta other than -1 or +1 are ignored.

Arg Direction Type Description
screenId in s (string) Screen whose strip should move (the cursor's screen). An empty string is ignored.
delta in i (int32) -1 scrolls the view one step toward the strip's start, +1 one step toward its end. The step is the Scrolling view scroll step setting. Any other value is ignored.

focusColumnAt()

Focus the column at a strip index on a scrolling screen. The placement-map twin of focusColumn: a map that draws the whole strip lets the user click a column directly, and this is the verb behind that click. It has an engine entry of its own but shares the keyboard and wheel focus verbs' re-anchor policy, so the view re-anchors under the same centering policy (the Never fit, OnOverflow, Always, and the lone-column rule) and the column's active window is activated afterwards. A call that moves focus raises the navigation OSD (when that OSD is on), like the sibling focus verbs. A press on the column that is already active answers with the no-target navigation OSD, an owned screen whose strip holds no windows answers with the no_windows one, and an index past the last column lands on the last column, which is the strip's own clamp. Every other rejected call is a silent no-op with no error reply: an empty screenId, a screen the scrolling engine does not own, a screen whose current scrolling context is disabled (the same per-context gate focusColumn passes through), and a negative index are all ignored.

Arg Direction Type Description
screenId in s (string) Screen whose strip should move. An empty string is ignored.
index in i (int32) Strip index of the column to focus, as stripModelJson numbers them. A negative value is ignored; a value past the last column clamps to it.

moveColumnTo()

Move a column from one strip index to another on a scrolling screen. The structural twin of focusColumnAt: a placement map that draws the whole strip lets the user drag a column past its neighbours, and this is the verb behind the drop. The moved column becomes the active column and the view re-anchors under the same centering policy the keyboard move verbs use, then the column's active window is activated and the move raises the navigation OSD (when that OSD is on). A from index past the last column, or a from equal to to, names no move and answers with the no-target navigation OSD rather than clamping, because the map numbers its columns from stripModelJson and an out-of-range index means a stale model. An owned screen whose strip holds no windows answers with the no_windows navigation OSD. Every other rejected call is a silent no-op with no error reply: an empty screenId, a screen the scrolling engine does not own, a screen whose current scrolling context is disabled, and a negative index in either argument are all ignored.

Arg Direction Type Description
screenId in s (string) Screen whose strip should change. An empty string is ignored.
from in i (int32) Strip index of the column to move, as stripModelJson numbers them. A negative value is ignored; a value past the last column answers no-target.
to in i (int32) Strip index the column should occupy afterwards. A negative value is ignored; a value past the last column answers no-target.

scrollViewByPx()

Scroll the view along a scrolling screen's strip by a pixel distance WITHOUT moving focus. The pixel twin of scrollView, for a caller that already holds a distance along the strip: the placement map pans by however far it was dragged, and one call per configured step would make that drag land on step boundaries. The view stays where the pan leaves it until the next focus change or centering verb, clamped at the strip's ends. A pan raises no navigation OSD, unlike scrollView, because the map calls this once per frame of a drag. That holds for a pan that moves the view and for a pan already pinned at the strip end it is asked to move toward. Only an owned screen whose strip holds no windows answers, with the no_windows navigation OSD (when that OSD is on) and no error reply. A distance of zero is a silent no-op at this boundary, never reaching the engine, and a distance past a million pixels either way is clamped to that bound here, the same band the engine bounds the verb to. Same silent ownership and per-context gates as focusColumn: an empty screenId, a screen the scrolling engine does not own, and a screen whose current scrolling context is disabled are ignored.

Arg Direction Type Description
screenId in s (string) Screen whose strip should move. An empty string is ignored.
px in i (int32) Signed distance in logical pixels along the strip's own axis: positive moves the view toward the strip's end (rightward on a horizontal strip, downward on a vertical one), negative toward its start. Zero is ignored.

setColumnWidthProportion()

Set the focused column's extent along the strip (its width on a horizontal strip, its height on a vertical one) to a fraction of the work area's extent along the strip (niri set-column-width with an absolute value; the shortcut surface carries no value argument, so the absolute setters live here). Same silent ownership and per-context gates as focusColumn, and the value is refused silently outside the proportion range the settings UI enforces (0.05 to 1.0). A value equal to the current intent answers with a no-target OSD rather than acting, like the step verbs, except on a column maximized to its edges, where the write takes the column out of that state and counts as a change. A successful call also raises the navigation OSD — every one of the four setters reports through it when that setting is on, so a scripted caller should expect on-screen feedback per call.

Arg Direction Type Description
screenId in s (string) Screen whose focused column to resize. An empty string is ignored.
proportion in d (double) Work-area fraction, 0.05 to 1.0.

setColumnWidthPixels()

Set the focused column's extent along the strip to a fixed value in logical pixels. Same gates, equal-value no-target answer and OSD feedback as setColumnWidthProportion. The value is refused silently outside the fixed range the settings UI enforces (100 to 10000). The value is stored as given, and the relayout still caps a rendered column at the work area's extent along the strip. While minimum sizes are respected it also holds the column at least at its windows' declared minimums and at any floor reportCommittedSize learned, so a smaller value takes effect once that floor drops.

Arg Direction Type Description
screenId in s (string) Screen whose focused column to resize. An empty string is ignored.
px in i (int32) Width in logical pixels, 100 to 10000.

setWindowHeightProportion()

Set the focused window's height intent to a fraction of the work area ACROSS the strip (niri set-window-height with an absolute value; on a vertical strip that extent is the work area's width). Same gates, proportion range, equal-value no-target answer and OSD feedback as setColumnWidthProportion. Heights have no exact-proportion kind in the strip model: the value is stored as a fraction anchor that snaps to the NEAREST entry of the screen's effective height preset list at relayout, the same value-anchored contract the cycle-height shortcut walks. For an exact height use setWindowHeightPixels. The relayout renormalizes heights into the column budget, so an oversized value degrades rather than overflowing.

Arg Direction Type Description
screenId in s (string) Screen whose focused window to resize. An empty string is ignored.
proportion in d (double) Fraction of the work area's extent across the strip, 0.05 to 1.0.

setWindowHeightPixels()

Set the focused window's extent across the strip (its height on a horizontal strip, its width on a vertical one) to a fixed value in logical pixels. Same gates, equal-value no-target answer and OSD feedback as setWindowHeightProportion. The value is refused silently outside the fixed range the settings UI enforces (100 to 10000).

Arg Direction Type Description
screenId in s (string) Screen whose focused window to resize. An empty string is ignored.
px in i (int32) Height in logical pixels, 100 to 10000.

toggleMaximizeColumn()

Toggles a column between the work area's full extent along the strip and its previous width (niri maximize-column), the same verb the Scrolling maximize column shortcut drives. A pure width verb: it does not touch KWin's maximize bit or the maximizedToEdges state, matching niri, where maximize-column is only a sizing mode. Same silent ownership and per-context gates as focusColumn. A call naming a window is silent, because that spelling exists for requests about a window the user may not be looking at; the empty (focused-column) spelling raises the navigation OSD like the other resize verbs.

Arg Direction Type Description
screenId in s (string) Screen whose column to toggle. An empty string is ignored.
windowId in s (string) Window naming the column to toggle. An empty string targets the focused column. A named window targets the column holding it and is ignored when the strip does not hold that window, so a request arriving for a window that never took focus cannot resize somebody else's column. The Phosphor shell's placement map sends the named form from its column menu, naming the focused window, so that click raises no OSD. The map sends nothing when the daemon reports no focused window for that screen, or when the map is showing a pinned desktop rather than the current one. The keyboard shortcut reaches the engine in-process and never crosses this interface, and the compositor's maximize interception goes to toggleMaximizeToEdges instead. The empty form is accepted so a script can address the focused column without first resolving its window id.
changed out b (bool) True when the strip actually changed. False covers both kinds of refusal and deliberately does not distinguish them: refused at the boundary (no engine, empty screen id, the engine is not active on that screen, or the per-context gate is closed), and accepted but acted on by nothing (no state for that context, an empty strip, a window no column holds, or a column the toggle itself refuses). Reported here to keep the wire shape identical to toggleMaximizeToEdges, which is the verb whose caller steers on it, and the placement map discards it. Note the gate reads the screenId passed in, while the engine acts on a named window's own tracked screen.

toggleMaximizeToEdges()

Toggles a column's maximize-to-edges state (niri maximize-window-to-edges, generalized to the column): the column takes the available screen area on both axes with no gaps while staying tiled, and the state is what the KWin effect mirrors onto the client's maximize bit. Called by the KWin effect when a scroll-managed window is asked to maximize, so the titlebar button, Meta+PgUp and a client-side maximize request all reach the engine's own maximize instead of KWin's. A named window that is the active tile of the active, not yet maximized shared column (tabbed or stacked) is first expelled into a column of its own and that column is maximized, because the request is about the window and not the column it shares; a background tile and the empty spelling toggle the column whole. Otherwise the same window addressing, silent ownership and per-context gates as toggleMaximizeColumn, and a successful call raises the navigation OSD only for the empty (focused-column) spelling.

Arg Direction Type Description
screenId in s (string) Screen whose column to toggle. An empty string is ignored.
windowId in s (string) Window naming the column to toggle. An empty string targets the focused column. A named window targets the column holding it (after the active-tab expel described on the method, that is the window's own new column) and is ignored when the strip does not hold that window, so a maximize request arriving for a window that never took focus cannot maximize somebody else's column. The KWin effect's maximize interception always names the requesting window; the empty form is accepted so an external script can address the focused column without first resolving its window id. For a named window the gates above are still evaluated against the screenId passed in, while the engine resolves and acts on the window's own tracked screen.
changed out b (bool) True when the strip actually changed. False covers both kinds of refusal and deliberately does not distinguish them: refused at the boundary (no engine, empty screen id, the engine is not active on that screen, or the per-context gate is closed), and accepted but acted on by nothing (no state for that context, an empty strip, a window no column holds, or a column the toggle itself refuses). The KWin effect leaves KWin's maximize bit exactly where the user's click put it and dispatches, so false is its only cue to put the bit back where the engine has it. Nothing else corrects it on a refusal, because a call that changes nothing emits no tile batch.

clearWindowedFullscreen()

Drops a window's windowed-fullscreen flag. Called by the KWin effect when a windowed-fullscreen client leaves fullscreen on its own, so the strip's flag follows reality. Silent no-op for an unknown window or one whose flag is not set. 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 whose flag to clear. An empty string is ignored.

reapplyWindowGeometry()

Re-emits a window's true strip rect. Called by the KWin effect when the compositor moved the window behind the engine's back (KWin restores a fullscreen-exiting window to its pre-fullscreen rect one client round-trip after the strip already placed it, and the engine's emit-on-change gate would otherwise stay silent forever). The engine evicts the window's emit-gate memory and, when the window's strip is the one its screen shows now, relayouts that screen so the next batch re-carries the rect. A window on a desktop or activity not in view only has the memory evicted, and its rect is re-carried when that context is shown again. Silent no-op for an unknown 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 to re-emit. An empty string is ignored.

reportCommittedSize()

Reports the frame size a strip window's client settled on when it differs from the rect the strip offered it, which is the window's own tile in its column. Called by the KWin effect for Wayland and XWayland windows alike, and only once the client has settled with no geometry configure in flight, so the commit is the answer to that offer rather than to an older one. The effect reports once per batch that sent the client a new size, and once more for each size the client later settles on by itself. It sends a difference along the strip of more than one pixel either way, or an answer more than one pixel longer across the strip, and never one that is only shorter across it. For a tile parked off screen it also sends an answer that equals the offer along the strip. An XWayland window's answer is judged against its size hints' answer to the column rather than the column itself, so a window narrowed to its size increments sends nothing, and a size the window takes by itself is reported only once it keeps it after the strip put it back. A client that commits longer than its tile along the strip (wider on a horizontal strip, taller on a vertical one) gives the column a floor at that extent, so the next column is laid out beside the window instead of under it. When that floor, with any tab indicator the column draws along the strip, is longer than the work area's extent along the strip, or the answer is longer across the strip than the work area, the window floats instead, the way a window whose declared minimum size outgrows the work area floats. An answer longer across the strip that still fits the work area holds the tile at that share of its column, so the stack shrinks the tiles beside it instead of laying them under the window, and the window floats when the column cannot give it that share beside the minimums of its other tiles. That hold ends on the same events as the floor along the strip, with the user's resize and a lowered declared minimum read across the strip instead, and also when a change to the column leaves it unable to hold that share or offers the tile another extent along the strip. A column whose window committed wider than it once is remembered at that width, so it parks off screen rather than peeking when it straddles the screen edge. An answer that equals a whole offer narrower than that memory, a park included, ends the memory and lets the column peek again. A later answer shorter than a floored column gives the floor back, down to that answer or entirely once the column offers the window enough without it, except that a floor taught again after a give-back is kept. The floor also ends when the window closes or moves to another monitor or desktop, when the user resizes the window along the strip, when the window lowers its declared minimum along the strip, when every column the window holds offers it the floor without it, and when the work area shrinks below it. It survives floating, fullscreen, a drag within the strip and Retile. A floor is learned only while minimum sizes are respected, turning them on makes the strip offer its columns again so the answer can be learned then, and it is runtime state that is never saved. A difference of one pixel along the strip or across it counts as the offer. Refused silently for a non-positive size, while the window is under an interactive move, for an unknown, floating or maximized-to-edges window, while minimum sizes are not respected, and when the offered size is not the tile's whole current rect (a newer batch has replaced it, the column was clamped at the screen edge, or a stack tile was clamped to the work area). A reconciliation call reporting what the client has already done, so neither ownership- nor context-gated, but only the registered compositor bridge may make it, and any other caller is answered with AccessDenied.

Arg Direction Type Description
windowId in s (string) Window whose commit to report. An empty string is ignored.
offeredWidth in i (int32) Width of the rect the strip offered the window, in logical pixels.
offeredHeight in i (int32) Height of the rect the strip offered the window, in logical pixels.
committedWidth in i (int32) Width of the frame the client committed, in logical pixels.
committedHeight in i (int32) Height of the frame the client committed, in logical pixels.

setWindowFullscreenFloat()

Holds a strip tile out of the strip for its OWN fullscreen, or returns it. Called by the KWin effect with floating=true when a tiled window goes fullscreen by itself (a client F11, a video going fullscreen, NOT the windowed-fullscreen feature) and with floating=false when it leaves fullscreen. The engine floats the window with the same slot memory a user float keeps, so the return lands in the same column at the same width, but announces the change on its passive channel: no float notification is shown and no free geometry is restored. A return of a window that no longer fits the work area (its declared minimum, or a floor reportCommittedSize learned, outgrows it) still answers true and is then floated again with the ordinary float announcement, the policy for any window that outgrows the work area. A hold of a window that already floats under another owner, and a return of a window this call did not hold, both answer false, so a user float is never taken over or undone. A repeat hold of this call's own float answers true. A reconciliation call reporting what the compositor has already done, so neither ownership- nor context-gated, but only the registered compositor bridge may make it, and any other caller is answered with AccessDenied.

Arg Direction Type Description
windowId in s (string) Window to hold out or return. An empty string answers false.
screenId in s (string) Ignored. The engine acts on, and announces, the window's own tracked screen.
floating in b (bool) true to hold the window out of the strip, false to return it.
changed out b (bool) True when the engine holds, or has returned, this call's own float: a first hold of a strip tile, a repeat hold of a tile this call already holds, or a return of a tile this call held. False for an empty or untracked window, a window that floats under another owner, and a return of a window this call did not hold.

visibleStripJson()

The strip as it currently looks on a screen: a JSON array of visible tile rects plus zoneNumber, the tile's 1-based visible slot in strip order. Each rect is {x, y, width, height}, 0.0 to 1.0 per axis, normalized against the screen's FULL geometry. The tiles themselves are clipped to the work area after the outer gaps are subtracted (a column maximized to its edges covers those gaps too), so the fractions show the panel gap and a consumer maps back to pixels by scaling against the screen rectangle. Same basis as the daemon's own OSD strip card. Only what is on screen is listed. Hidden tabs of a tabbed column, minimized tiles, and tiles whose intersection with the work area is empty (a stack whose minimum sizes overflow the work area resolves its tail past the work area's far edge across the strip) are all left out and carry no number. A partially visible column is clipped to the work area rather than dropped, with no minimum-visibility threshold: an arbitrarily thin sliver still gets its own number, and a barely-visible column sitting parked below its peek floor keeps its number too, which is what lets a digit press scroll it back into view. zoneNumber is the scroll zone number, and the Snap-to-Zone shortcuts cover 1 to 9, so a strip showing more than nine tiles numbers them all but only the first nine have a digit that reaches them. The settings app renders the array where the other modes show a layout thumbnail. A tile whose column draws a tab indicator carries four more keys describing it, and a tile whose column draws none carries no tab key at all: tabCount, how many tabs the indicator shows; activeTab, this tile's own 0-based tab within them; tabPosition, the edge the indicator runs along (0 left, 1 right, 2 top, 3 bottom); and tabLength, how much of that edge it covers as a 0.0 to 1.0 proportion, centered on it. Only the shown tab of a tabbed column is listed at all, so those keys are the only thing telling a reader that the tile stands for a stack rather than a single window. No thickness rides along: the configured width is a few pixels, which is sub-pixel in any thumbnail of a whole screen, so a renderer floors it at whatever it can draw. Empty array when the screen has no strip or is not scrolling.

Arg Direction Type Description
screenId in s (string) Screen whose strip to describe. An empty string yields an empty array.
stripJson out s (string) JSON array string.

stripModelJson()

The whole strip of a scrolling screen, columns on and off screen alike, as the Phosphor shell's placement map draws it. Where visibleStripJson describes only what is on screen as screen-normalized rects for a thumbnail, this is the strip MODEL in pixels along the strip's own axis, so a consumer can draw every column, place the viewport over them, and pan. A JSON object {axis, viewOffsetPx, viewportPx, stripExtentPx, activeColumn, columns}. axis is 0 for a horizontal strip and 1 for a vertical one, and every other pixel value runs along that axis (main) or across it (cross). viewOffsetPx is the viewport's leading edge in strip coordinates, where the first column's leading edge is 0; it can overhang either end of the strip, because the centering policy centres a short strip on purpose. viewportPx is the viewport's extent along the strip (the work area's main extent) and stripExtentPx the strip's total extent, every non-minimized column plus the gaps between them. activeColumn is the strip index of the active column, -1 on an empty strip. columns is an array in strip order of {index, stripPosPx, extentPx, display, activeTile, maximized, tiles}: index is the column's strip index and the value focusColumnAt takes, stripPosPx its leading edge in strip coordinates, extentPx its resolved extent along the strip (0 for a fully minimized column, which takes no strip position), display 0 for a normal stack and 1 for a tabbed column, activeTile the index into tiles of its active tile (the shown tab when tabbed) as the strip stores it, so on a column whose active tile is minimized it names that tile while the relayout shows the column's first tile that is not minimized, and maximized the column's declared maximize-to-edges state, the one toggleMaximizeToEdges drives and the compositor mirrors onto the maximize bit. The width-only maximize of toggleMaximizeColumn is not a flag on the model and is not reported. tiles is the column's stack in order, minimized tiles included, each {windowId, crossPx, minimized}: crossPx is the tile's resolved extent across the strip, 0 for a minimized tile, and a hidden tab of a tabbed column carries the shown tab's extent since every tab is committed at the column's one rect. The daemon resolves the screen's layout parameters once and runs one relayout per call, the same cost as visibleStripJson. Same ownership gate as focusColumn (reads are not context-gated): an empty object when the screen is not scrolling. A scrolling screen with no strip yet answers a valid object with an empty columns array and its axis and viewport filled in, so a consumer can draw the empty strip. Changes are announced by the stripChanged wake-up, whose coalescing advice applies here too.

Arg Direction Type Description
screenId in s (string) Screen whose strip to describe. An empty string yields an empty object.
modelJson out s (string) JSON object string.

presetVocabularyJson()

The screen's effective preset vocabulary as a JSON object {"columnWidths": [...], "windowHeights": [...]} of 0.0 to 1.0 fractions. Each list resolves independently: a list the context's resolved scrolling template supplies comes from that template's own preset list, and a list it does not supply falls back to the configured preset list, so a template that defines widths but no heights yields template widths beside the configured heights. This is the vocabulary the cycle-preset-width and cycle-preset-height shortcuts walk on that screen. Same ownership gate as focusColumn (reads are not context-gated): an empty object when the screen is not scrolling.

Arg Direction Type Description
screenId in s (string) Screen whose vocabulary to describe. An empty string yields an empty object.
vocabularyJson out s (string) JSON object string.

blueprintProgressJson()

How far the screen has worked through its scrolling template's seed blueprint, as a JSON object {"total": n, "used": n}. total is how many starting columns the context's resolved template declares, and used is how many of them the strip has already taken. An entry is spent once a column has taken it, so closing a column does not return its entry to the pool, and used == total means further columns open at the template's ordinary width and display instead. The count restarts when the strip empties while it holds no floating window and no drag is holding a window out of it, or when the screen is given a different template. used never reads below the strip's current column count, since columns that arrived without taking an entry (a restored strip, say) still stand for the entries their positions cover. Reports the current desktop and activity context, matching visibleStripJson. Same ownership gate as focusColumn (reads are not context-gated): an empty object when the screen is not scrolling.

Arg Direction Type Description
screenId in s (string) Screen whose progress to describe. An empty string yields an empty object.
progressJson out s (string) JSON object string.

Signals

scrollingScreensChanged

Emitted when the set of screens using the scrolling engine changes.

Arg Direction Type Description
screenIds out as (array<string>) List of screen IDs currently using the scrolling engine.
isContextSwitch out b (bool) True when a desktop or activity switch changed the set. Such a change is never an engine flip: the engines already hold the context entered.
leavingToAutotile out as (array<string>) Screens that left the set in this change and run autotile now, so they are still in the engine-managed union.

stripContextChanged

Emitted when the identity of the strip a screen is showing changes, which happens on a virtual-desktop switch, an activity switch, a sticky-pin release, the screen joining or rejoining the scrolling set, and a desktop being removed so that the desktops after it are renumbered. A pin ACQUIRE does not announce, and does not need to: it pins the screen to the desktop its key already resolves to, so the strip under it does not change until a later switch. NOT SEEDED AT BRING-UP: there is no property to read the current epochs from, so a consumer that connects after a screen was announced holds nothing for it, and its first announcement for that screen is a bare record rather than a comparison. Such a consumer does not retire on the first switch it sees. epoch is OPAQUE: it is derived from the same context key that keys strip storage in the engine, and a consumer may only compare it for equality with the last epoch it saw for that screen. It must never be parsed, ordered, or reconciled against the compositor's own current desktop or activity — a screen under a sticky pin resolves to the PINNED desktop rather than the live one, so anything re-derived compositor-side disagrees with the engine permanently on exactly those screens. debugLabel is for logging only and branching on it is the same mistake as parsing the epoch. This is announced independently of any geometry batch on purpose: windowsTileRequested is emitted only when some rect actually changed, so a switch onto a strip nobody touched produces no batch at all, and identity carried as a batch field would be silent in exactly the case a consumer most needs it. A consumer holding per-window strip state that is not keyed by desktop should retire that state for the named screen when the epoch changes.

Arg Direction Type Description
screenId out s (string) Screen whose strip identity changed.
epoch out s (string) Opaque strip identity. Compare for equality only.
debugLabel out s (string) Human-readable context for logs. Never a branch input.

scrollEffectBehaviourChanged

Emitted when the resolved per-screen behaviour the compositor owns changes. The payload is the WHOLE map, never a delta, so a receiver that missed an earlier emission never has to merge against a stale copy.

Arg Direction Type Description
behaviour out a{sv} (dict<string,variant>) Same shape as the scrollEffectBehaviour property.

scrollFocusScrollBlockedWindowsChanged

Emitted when the set of windows the focus-follows-mouse scroll cap refuses changes. The payload is the WHOLE list, so a receiver never merges a delta against a copy it may have missed an update to. Separate from scrollEffectBehaviourChanged because it fires on every relayout that moves the answer, while that one fires when settings or rules change.

Arg Direction Type Description
windowIds out as (array<string>) Same shape as the scrollFocusScrollBlockedWindows property.

stripChanged

A screen's strip changed shape. This is a wake-up for anyone rendering the strip, not a payload: re-read visibleStripJson or stripModelJson to find out what it looks like now. It relays the engine's own placement-change signal, so it fires on a placement or focus change, a column reportCommittedSize resized included, rather than on every relayout, but it is NOT gated against the strip payload — payload-gating would cost a full relayout on every placement change, paid whether or not anything is listening, to suppress wake-ups whose only cost to a receiver is one read it discards as identical. Treat it as 're-read soon', never as 'the strip differs': a placement change that moves a floating window, or one on a context the screen is not currently showing, fires it without changing a single visible tile. The gate also runs one way only: a settings, rule or template push re-resolves the strip through applyLayout and emits this only if the view anchor moved or a floor reportCommittedSize learned was dropped, so a relayout that changes column widths while the anchor stays put changes the strip without waking anyone. Keep a periodic re-read as the backstop; this signal only makes the common cases prompt. Coalesce it, since a drag or a burst of window opens emits per step. Never emitted for a screen the scrolling engine does not currently own, since visibleStripJson and stripModelJson answer empty for those anyway.

Arg Direction Type Description
screenId out s (string) Screen whose strip to re-read.

Properties

Property Access Type Description
scrollingScreens read as (array<string>) List of screen IDs currently using the scrolling engine, sorted, matching the ordering of the scrollingScreensChanged payload so a consumer can compare the two for the same set. The KWin effect uses it as the discriminator that stamps Mode 'scrolling' rather than 'tiling' in window rule queries, but it does not answer from this raw set: it intersects it at read time with the engine-managed union published on org.phosphor_works.Placement.Tiling, because the two sets arrive as independent signals with no ordering guarantee and this one can transiently name a screen the union has already dropped. Changes are announced on the scrollingScreensChanged signal below, not through org.freedesktop.DBus.Properties.PropertiesChanged, which this property does not emit.
scrollEffectBehaviour read a{sv} (dict<string,variant>) The scrolling facts the COMPOSITOR owns, already resolved as three screen-id lists, {'focusFollowsMouse': as, 'cropStraddlers': as, 'verticalAxis': as}. The first two are per-context rule slots (SetScrollFocusFollowsMouse / SetScrollCropStraddlers) with a consumer in the KWin effect. focusFollowsMouse has no other consumer, so it cannot ride the engine's per-screen override map. cropStraddlers rides that map as well, because the engine's own straddler clamp reads it, and both consumers resolve it from the same rule slot and setting, so they cannot disagree. verticalAxis is the resolved face of the SetScrollStripAxis rule slot and the per-screen/global StripAxis settings: the daemon reads the verdict back from the scroll engine's merged per-screen map (rule over per-screen setting over global, with Auto resolved by the engine from the screen's work area), so this list can never disagree with the axis the strip is actually laid out on. It is membership rather than a per-screen value: a screen IN that list runs its strip VERTICALLY, and absence means horizontal, so an absent key and an empty list mean the same safe thing and a compositor that predates the axis reads the whole desktop as horizontal. The daemon resolves rule-then-config per scrolling screen and publishes the RESOLVED membership, which keeps the effect free of any config knowledge: it answers each question with a set lookup and holds no fallback of its own. A screen absent from a list has that behaviour off (or, for verticalAxis, a horizontal strip); a screen that is not scrolling appears in none of the three. The focus-follows-mouse scroll cap's blocked-window list is NOT on this map: it rides scrollFocusScrollBlockedWindows below, because it changes on every relayout while these three change only when settings or rules do. All three lists are sorted, matching the scrollEffectBehaviourChanged payload. One map rather than three list properties so the compositor pays a single bring-up query and a single subscription for what is really one push. Changes are announced on scrollEffectBehaviourChanged below, not through org.freedesktop.DBus.Properties.PropertiesChanged, which this property does not emit.
scrollFocusScrollBlockedWindows read as (array<string>) The windows focus-follows-mouse must REFUSE to focus, as WINDOW ids rather than screen ids: activating one would scroll the strip further than the per-context cap allows (the SetScrollFocusFollowsMouseMaxScroll rule slot over the Scrolling.Behavior FocusFollowsMouseMaxScroll setting). The daemon resolves the cap and asks the scroll engine which windows exceed it, because the answer depends on the strip's layout and where its view sits and the compositor cannot recompute that per pointer event; it is republished on every strip layout change of a capped screen. Its own property rather than a fourth key on scrollEffectBehaviour for exactly that reason: sharing one property made a strip that merely scrolled re-publish the three screen lists too, and the reader re-parse them to discover they had not moved. An absent property, an empty list and an absent window all mean the same thing, that nothing is refused, which is what the default cap of 100 percent resolves to, so a reader that misses this update fails OPEN with focus following the pointer as it did before the setting existed. The list is sorted, matching the scrollFocusScrollBlockedWindowsChanged payload. Changes are announced on that signal, not through org.freedesktop.DBus.Properties.PropertiesChanged, which this property does not emit.