org.plasmazones.LayoutRegistry

Layout management: CRUD, screen and virtual-desktop assignments, quick layout slots (1-9), KDE Activities, the scrolling-template store and template assignment, and editor launch.

Well-known name	org.plasmazones.LayoutRegistry
Source XML	org.plasmazones.LayoutRegistry.xml
Methods	71
Signals	16
Properties	0

Methods

<tt>getActiveLayout()</tt>

Returns the settings-based DEFAULT layout as JSON (id, name, zones, etc.). Note this is the persisted default, which may differ from the transient internal active layout — subscribe to activeLayoutIdChanged for the latter.

Arg	Direction	Type	Description
layoutJson	out	s *(string)*	Full layout as JSON (id, name, zones, etc.).

<tt>getLayoutList()</tt>

Returns an array of strings; each element is one JSON-serialized layout object (manual layouts enriched with origin/visibility/allow-lists, plus autotile algorithm entries). Never bare IDs and never a single JSON array. Scrolling-template entries are appended too, unconditionally — the list is not filtered by the caller's mode. A template entry carries isScrollingTemplate true, and its id is a plain braced UUID with no scheme prefix, so that flag is the only thing distinguishing it from a manual layout entry (autotile entries stay recognisable by their 'autotile:' prefix).

Arg	Direction	Type	Description
layouts	out	as *(array<string>)*	Array of JSON-serialized layout objects, one per string.

<tt>getLayoutPreviewList()</tt>

Source-agnostic list of renderer-ready previews across manual zone layouts, autotile algorithms, and scrolling templates. Each entry is a PhosphorLayout::LayoutPreview serialised to JSON (id, displayName, zones[]{x,y,width,height}, isAutotile, isScrollingTemplate, isSystem, category, optional algorithm{...} metadata for autotile entries). A template entry's id is a plain braced UUID with no scheme prefix — the isScrollingTemplate flag is the discriminator, as in getLayoutList. Renderers consume uniformly without branching on the underlying source. Returns '[]' when no source is wired (early startup).

Arg	Direction	Type	Description
previewListJson	out	s *(string)*	JSON array of LayoutPreview objects.

<tt>getLayoutPreview()</tt>

Source-agnostic preview for a single entry. id must match one returned by getLayoutPreviewList. windowCount is honoured by autotile sources (algorithm runs at that count); manual sources ignore it. Returns '{}' when id is unknown or no source is wired.

Arg	Direction	Type	Description
id	in	s *(string)*	Preview id (manual layout or scrolling-template UUID with braces, or 'autotile:<algorithmId>'). Layout and template ids share the bare braced-UUID form; the returned entry's isScrollingTemplate flag is the discriminator.
windowCount	in	i *(int32)*	Window count to render autotile algorithms with. Ignored by manual sources.
previewJson	out	s *(string)*	LayoutPreview serialised to JSON, or '{}' if not found.

<tt>getLayout()</tt>

Returns a specific layout by ID as JSON. Empty string if not found.

Arg	Direction	Type	Description
id	in	s *(string)*	Layout UUID.
layoutJson	out	s *(string)*	Full layout as JSON, or empty if not found.

<tt>setActiveLayout()</tt>

Switch to the layout with the given UUID.

Arg	Direction	Type	Description
id	in	s *(string)*	Layout UUID to activate.

<tt>applyQuickLayout()</tt>

Apply quick layout slot (1-9) for the given mode to the given screen.

Arg	Direction	Type	Description
mode	in	i *(int32)*	Tiling mode (0 = snapping, 1 = autotile, 2 = scrolling). Each mode owns a separate slot array. Scrolling slots hold native scrolling-template UUIDs (the ids getScrollingTemplates reports) and applying one swaps the context's template, so an id the template store does not know is refused.
number	in	i *(int32)*	Slot number (1-9).
screenId	in	s *(string)*	Target screen name (e.g. DP-1).

<tt>createLayout()</tt>

Create a new empty layout. Returns the new layout UUID.

Arg	Direction	Type	Description
name	in	s *(string)*	Display name for the layout. Names longer than 40 characters are shortened to fit.
type	in	s *(string)*	Layout type (e.g. custom).
layoutId	out	s *(string)*	UUID of the created layout.

<tt>deleteLayout()</tt>

Permanently delete the layout with the given ID. The deletion is REFUSED, and no layoutDeleted is emitted, when the registry cannot keep the layout, its file and its settings sidecar mutually consistent (an unwritable sidecar, an undeletable layout file) — the layout is then still registered, and since this method has no return value the absence of layoutDeleted is the only signal of that. A context whose assignment referenced the deleted layout is rewritten to the reserved word "none" (explicitly no layout) rather than cleared, wherever that slot is the one in force: an empty slot would inherit the configured default layout, silently reshaping a screen whose layout was just deleted. A dormant reference — a slot belonging to a mode the context is not in — is plainly cleared.

Arg	Direction	Type	Description
id	in	s *(string)*	Layout UUID to delete.

<tt>duplicateLayout()</tt>

Create a copy of an existing layout. Returns the new layout UUID. The copy's name is shortened to 40 characters if needed.

Arg	Direction	Type	Description
id	in	s *(string)*	Layout UUID to duplicate.
layoutId	out	s *(string)*	UUID of the new layout copy.

<tt>importLayout()</tt>

Import a layout from a JSON file. Returns the imported layout UUID. Layout and zone names longer than 40 characters are shortened to fit.

Arg	Direction	Type	Description
filePath	in	s *(string)*	Absolute path to the JSON file.
layoutId	out	s *(string)*	UUID of the imported layout.

<tt>getScrollingTemplates()</tt>

All scrolling templates as a JSON array (id, name, description, columns, defaults, preset lists, isSystem), name-sorted. The daemon-side template store is the authority; bundled templates carry isSystem true.

Arg	Direction	Type	Description
templatesJson	out	s *(string)*	JSON array of template objects.

<tt>saveScrollingTemplate()</tt>

Create or update a scrolling template from its JSON object. An empty or missing id creates a fresh template. Editing a bundled template writes a user copy that shadows it. Names longer than 40 characters and descriptions longer than 500 characters are shortened to fit. A save whose stored result is identical to the existing entry rewrites nothing and does not emit scrollingTemplatesChanged. Returns the stored template UUID, or empty when the template is invalid.

Arg	Direction	Type	Description
templateJson	in	s *(string)*	JSON object in the scrolling-template schema.
templateId	out	s *(string)*	UUID of the stored template, empty on refusal.

<tt>deleteScrollingTemplate()</tt>

Delete the user file of the scrolling template with the given id. Deleting a user copy that shadowed a bundled template resurfaces the bundled original, and a pure bundled template is refused. The id is scrubbed from every assignment rule and from every quick layout slot only when it no longer resolves to any template after the delete, so a resurfaced bundled original keeps its live assignments. The scrub reaches assignment rules and quick slots only. A context in SCROLLING mode is not merely scrubbed: its template slot is rewritten to the literal "none", so the screen ends up with no template rather than inheriting the configured default. That is what deleting the template a screen was actually using means, and an empty slot would have handed the screen to whatever other template happened to be the default. A context in another mode, where the slot is only a remembered value, keeps the plain clear. A deleted id still named by the Scrolling default-template SETTING is a different case and is deliberately left in place: it resolves to no template at read time and those contexts fall back to the engine's compiled defaults, so nothing has to rewrite the user's setting behind their back.

Arg	Direction	Type	Description
id	in	s *(string)*	Template UUID to delete.
deleted	out	b *(bool)*	True when the template's user file is gone after the call. False when the id is unknown, malformed, names a pure bundled template, or the file could not be removed.

<tt>duplicateScrollingTemplate()</tt>

Store a copy of the scrolling template under a fresh UUID. The copy's name is shortened to 40 characters if needed. Returns the new template UUID, empty when the source is unknown.

Arg	Direction	Type	Description
id	in	s *(string)*	Template UUID to duplicate.
templateId	out	s *(string)*	UUID of the new copy.

<tt>exportLayout()</tt>

Export a layout to a JSON file at the given path. Returns whether the export was written.

Arg	Direction	Type	Description
layoutId	in	s *(string)*	Layout UUID to export.
filePath	in	s *(string)*	Destination file path.
written	out	b *(bool)*	True when the layout reached the destination. False when it could not be opened, written or committed; the destination is left untouched in that case.

<tt>setLayoutHidden()</tt>

Set whether a layout is hidden from the zone selector.

Arg	Direction	Type	Description
layoutId	in	s *(string)*	Layout UUID.
hidden	in	b *(bool)*	True to hide from zone selector.

<tt>setLayoutAutoAssign()</tt>

Set whether a layout auto-assigns new windows to empty zones.

Arg	Direction	Type	Description
layoutId	in	s *(string)*	Layout UUID.
enabled	in	b *(bool)*	True to enable auto-assign.

<tt>setLayoutAspectRatioClass()</tt>

Set a layout's aspect-ratio class (which monitor shapes it targets).

Arg	Direction	Type	Description
layoutId	in	s *(string)*	Layout UUID.
aspectRatioClass	in	i *(int32)*	Aspect-ratio class enum value.

<tt>updateLayout()</tt>

Replace an existing layout with the supplied full layout JSON (editor save path). The layout's UUID is taken from the JSON. Layout and zone names longer than 40 characters are shortened to fit.

Arg	Direction	Type	Description
layoutJson	in	s *(string)*	Full layout as JSON.
success	out	b *(bool)*	True if the layout was updated.

<tt>createLayoutFromJson()</tt>

Create a new layout from the supplied full layout JSON (editor new-layout save, KZones import). Layout and zone names longer than 40 characters are shortened to fit.

Arg	Direction	Type	Description
layoutJson	in	s *(string)*	Full layout as JSON.
layoutId	out	s *(string)*	UUID of the created layout, or empty string on failure.

<tt>openEditor()</tt>

Launch the layout editor for the active layout. Returns false when the editor process could not be started.

Arg	Direction	Type	Description
launched	out	b *(bool)*	True when the editor process was spawned.

<tt>openEditorForScreen()</tt>

Launch the layout editor for the layout assigned to the given screen. Returns false when the editor process could not be started.

Arg	Direction	Type	Description
screenId	in	s *(string)*	Screen to edit layout for (e.g. DP-1).
launched	out	b *(bool)*	True when the editor process was spawned.

<tt>openEditorForLayoutOnScreen()</tt>

Launch the layout editor for a specific layout, optionally targeting a screen for geometry/name matching. Returns false when the id is malformed or the editor process could not be started.

Arg	Direction	Type	Description
layoutId	in	s *(string)*	Layout UUID to edit.
screenId	in	s *(string)*	Screen to open on (empty = editor default).
launched	out	b *(bool)*	True when the editor process was spawned.

<tt>openEditorForScrollingTemplate()</tt>

Launch the editor in scrolling-template mode. Opens on the screen under the cursor. Returns false when a malformed or unknown non-empty id is refused or the editor process could not be started.

Arg	Direction	Type	Description
templateId	in	s *(string)*	Template UUID to edit. Empty = create a new template.
launched	out	b *(bool)*	True when the editor process was spawned.

<tt>getScreenStates()</tt>

Return current mode, layout, algorithm, and scrolling template for all screens as a JSON array: one object per screen with screenId, virtualDesktop, activity, mode (0=Snapping, 1=Autotile, 2=Scrolling), layoutId, layoutName, layoutIdExplicit, snappingLayoutId, algorithmId, algorithmName, algorithmIdExplicit, scrollingTemplateId, scrollingTemplateName, scrollingTemplateExplicit. layoutId and algorithmId are the RESOLVED values (cascade and default fallbacks included; layoutId is empty for a Scrolling context); the *Explicit booleans say whether this exact screen/desktop/activity tuple pins the field itself, so a caller can tell an inherited value from an assigned one. scrollingTemplateId reads the stored entry field, so a template preserved across a mode toggle is reported even while another mode runs. That raw read also means it does NOT include the configured default-template fallback that getScrollingTemplateLayout applies, which is deliberate: this method reports what the context stores, not what the strip would resolve. snappingLayoutId is the same raw read for the snapping slot, carried because the resolved layoutId cannot distinguish the explicit no-layout opt-out (the reserved word "none", which resolves to no layout) from an unassigned context with no default in force. algorithmId can likewise carry the reserved word "none" (the explicit no-algorithm opt-out); algorithmName is empty for it.

Arg	Direction	Type	Description
statesJson	out	s *(string)*	JSON array of per-screen state objects.

<tt>getLayoutForScreen()</tt>

Get the layout currently in use on a screen (resolves with current virtual desktop and activity context). Falls through to the global default layout when the screen has no assignment, INCLUDING when the default is suppressed for that context — so it can report a layout where getActiveLayoutsForScreens omits the screen and getScreenStates reports none. Callers wanting the suppression-aware resolved value must use one of those instead. A Snapping context explicitly set to no layout (the reserved word "none" in its assignment) answers empty rather than the default: the opt-out beats the fallback.

Arg	Direction	Type	Description
screenId	in	s *(string)*	Stable screen id in manufacturer:model:serial form, as returned by getAvailableScreenIds. A connector name (e.g. DP-1) is also accepted and resolved to the stable id.
layoutId	out	s *(string)*	Layout UUID, autotile:<algorithmId> when the context resolves to autotile (including the literal "autotile:none" for an Autotile context explicitly set to no algorithm, where "none" is the reserved word, not an algorithm id), or empty string. Parsing this directly as a UUID yields a null UUID for an autotile screen.

<tt>getAssignedLayoutForScreen()</tt>

Get the layout assigned to a screen through the assignment cascade (resolves with current virtual desktop and activity context). Unlike getLayoutForScreen, returns an empty string when the screen has no assignment of its own instead of falling back to the global default layout.

Arg	Direction	Type	Description
screenId	in	s *(string)*	Stable screen id in manufacturer:model:serial form, as returned by getAvailableScreenIds. A connector name (e.g. DP-1) is also accepted and resolved to the stable id.
layoutId	out	s *(string)*	Layout UUID, autotile:<algorithmId>, the reserved word "none" for a Snapping context explicitly set to no layout, "autotile:none" for an Autotile context explicitly set to no algorithm, or empty string when unassigned. Parsing this directly as a UUID yields a null UUID for the reserved forms.

<tt>assignLayoutToScreen()</tt>

Assign a layout to a screen for all virtual desktops.

Arg	Direction	Type	Description
screenId	in	s *(string)*	Target screen name.
layoutId	in	s *(string)*	Layout UUID to assign, or the reserved word "none" to set the context to explicitly use no layout (the opt-out beats the configured default). Like a layout UUID, the reserved word also sets the context's mode to Snapping — it is the SNAPPING family's opt-out. To opt a context out within the other families use "autotile:none" here, or setScrollingTemplateLayout's own reserved word.

<tt>clearAssignment()</tt>

Remove the layout assignment from a screen.

Arg	Direction	Type	Description
screenId	in	s *(string)*	Screen to clear assignment for.

<tt>setAllScreenAssignments()</tt>

Batch set all base screen assignments (saves once). Clears existing assignments of this family first: a key absent from the map is DELETED, so a partial map silently drops every assignment it omits.

Arg	Direction	Type	Description
assignments	in	a{sv} *(dict<string,variant>)*	Map of screenId to a plain layoutId string (a Scrolling context stays the bare 'scrolling:' sentinel; the reserved words "none" and "autotile:none" are accepted and store the explicit opt-out, so the values the matching getter emits round-trip). Only that string is read here. The matching getter, getAllScreenAssignments, answers a wider and differently keyed shape (a JSON string of connector-keyed per-screen objects), so the two are not a round-trip pair. The scrolling template is written through setScrollingTemplateLayout, never through the batch setters.

<tt>getLayoutForScreenDesktop()</tt>

Get layout for a specific screen and virtual desktop (1-based). Falls through to the global default layout when that context has no assignment, INCLUDING when the default is suppressed for it, so it can report a layout where getActiveLayoutsForScreens omits the screen and getScreenStates reports none. Callers wanting the suppression-aware resolved value must use one of those instead. A Snapping context explicitly set to no layout (the reserved word "none" in its assignment) answers empty rather than the default: the opt-out beats the fallback.

Arg	Direction	Type	Description
screenId	in	s *(string)*	Stable screen id in manufacturer:model:serial form, as returned by getAvailableScreenIds. A connector name (e.g. DP-1) is also accepted and resolved to the stable id.
virtualDesktop	in	i *(int32)*	Virtual desktop index (1-based).
layoutId	out	s *(string)*	Layout UUID, autotile:<algorithmId> when the context resolves to autotile (including the literal "autotile:none" for an Autotile context explicitly set to no algorithm, where "none" is the reserved word, not an algorithm id), or empty string. Parsing this directly as a UUID yields a null UUID for an autotile screen.

<tt>assignLayoutToScreenDesktop()</tt>

Assign layout to a specific screen and virtual desktop.

Arg	Direction	Type	Description
screenId	in	s *(string)*	Target screen name.
virtualDesktop	in	i *(int32)*	Virtual desktop index (1-based).
layoutId	in	s *(string)*	Layout UUID to assign, or the reserved word "none" to set the context to explicitly use no layout (the opt-out beats the configured default). Like a layout UUID, the reserved word also sets the context's mode to Snapping — it is the SNAPPING family's opt-out. To opt a context out within the other families use "autotile:none" here, or setScrollingTemplateLayout's own reserved word.

<tt>clearAssignmentForScreenDesktop()</tt>

Clear layout assignment for a screen/desktop combination.

Arg	Direction	Type	Description
screenId	in	s *(string)*	Screen name.
virtualDesktop	in	i *(int32)*	Virtual desktop index (1-based).

<tt>hasExplicitAssignmentForScreenDesktop()</tt>

True if there is an explicit assignment (not inherited) for this screen/desktop.

Arg	Direction	Type	Description
screenId	in	s *(string)*	Screen name.
virtualDesktop	in	i *(int32)*	Virtual desktop index (1-based).
hasAssignment	out	b *(bool)*	True if explicit assignment exists.

<tt>getModeForScreenDesktop()</tt>

Get the current mode (0=Snapping, 1=Autotile, 2=Scrolling) for a screen/desktop.

Arg	Direction	Type	Description
screenId	in	s *(string)*
virtualDesktop	in	i *(int32)*
mode	out	i *(int32)*

<tt>getSnappingLayoutForScreenDesktop()</tt>

Get the snapping layout UUID for a screen/desktop (regardless of current mode). A raw slot read: a context explicitly set to no layout answers the reserved word "none", including when that opt-out is dormant, preserved across a mode toggle.

Arg	Direction	Type	Description
screenId	in	s *(string)*
virtualDesktop	in	i *(int32)*
layoutId	out	s *(string)*

<tt>getTilingAlgorithmForScreenDesktop()</tt>

Get the tiling algorithm ID for a screen/desktop (regardless of current mode). A raw slot read: a context explicitly set to no algorithm answers the reserved word "none", including when that opt-out is dormant, preserved across a mode toggle.

Arg	Direction	Type	Description
screenId	in	s *(string)*
virtualDesktop	in	i *(int32)*
algorithm	out	s *(string)*

<tt>setAllDesktopAssignments()</tt>

Batch set all per-desktop assignments (saves once). Canonical key format: 'screenId|desktopNumber' ('screenId:desktopNumber' is accepted as a legacy fallback but misparses virtual-screen ids — do not emit it). Clears existing assignments of this family first: a key absent from the map is DELETED, so a partial map silently drops every assignment it omits.

| Arg | Direction | Type | Description | |--—|--------—|---—|----------—| | assignments | in | a{sv} *(dict<string,variant>)* | Map of 'screenId|desktop' keys to a plain layoutId string (a Scrolling context stays the bare 'scrolling:' sentinel; the reserved words "none" and "autotile:none" are accepted and store the explicit opt-out, so the values the matching getter emits round-trip). Only that string is read here. The matching getter's value is a wider {layoutId, scrollingTemplate} map, and the scrolling template is written through setScrollingTemplateLayout, never through the batch setters. |

<tt>getAllDesktopAssignments()</tt>

Get all per-desktop assignments.

| Arg | Direction | Type | Description | |--—|--------—|---—|----------—| | assignments | out | a{sv} *(dict<string,variant>)* | Map of 'screenId|desktop' keys to a map {layoutId, scrollingTemplate}: layoutId is the assignment id the matching batch setter accepts (a Scrolling context stays the bare 'scrolling:' sentinel; a Snapping context that explicitly uses no layout carries the literal "none", and an Autotile context that explicitly uses no algorithm carries "autotile:none"), scrollingTemplate the context's scrolling-template UUID, or empty when the context pins none of its own, or the literal "none" when it explicitly uses no template at all. The getter value is deliberately wider than the setter's plain layoutId string; the template is written through setScrollingTemplateLayout, never through the batch setters. |

<tt>getVirtualDesktopCount()</tt>

Returns the number of virtual desktops.

Arg	Direction	Type	Description
count	out	i *(int32)*	Number of virtual desktops.

<tt>getVirtualDesktopNames()</tt>

Returns the names of all virtual desktops.

Arg	Direction	Type	Description
names	out	as *(array<string>)*	Array of desktop names.

<tt>getAvailableScreenIds()</tt>

Returns the daemon's effective screen ids — one entry per physical monitor PLUS any virtual-screen subdivisions configured on top. Use this for screen enumeration in UI / settings panels; getAllScreenAssignments is the assignment-state readback and emits only screens with stored entries.

Arg	Direction	Type	Description
screenIds	out	as *(array<string>)*	Stable screen ids in manufacturer:model:serial form (e.g. 'Dell:U2722D:115107' for physical, 'Dell:U2722D:115107/vs:0' for virtual subdivisions). Order follows the daemon's effective-screen iteration.

<tt>getAllScreenAssignments()</tt>

Returns all screen-to-layout assignments as JSON. This is a READBACK of stored assignment state, not a payload the batch setter accepts: setAllScreenAssignments takes a flat screenId-to-layoutId string map, while this answers a JSON string of connector-keyed per-screen objects, so the pair does not round-trip. Synthesized level-1 global-default fallbacks are deliberately NOT serialized, so callers that need the resolved mode for an unconfigured screen must use the per-context lookup methods instead. Only screens with at least one stored entry (base or per-desktop) appear; for screen enumeration use getAvailableScreenIds. Values come from the enabled-blind exact-context read, matching the explicit-vs-resolved discriminator getScreenStates uses, so a DISABLED pin reports its own stored payload rather than the default it currently resolves to. One shape is not representable: a per-desktop entry pinning only the MODE to Snapping carries no id (Snapping has no bare sentinel, unlike "autotile:" and "scrolling:"), so no desktop row is emitted for it, though the screen itself still appears.

Arg	Direction	Type	Description
assignmentsJson	out	s *(string)*	JSON object keyed by connector name, containing one entry per screen with stored assignments. Each entry includes {"screenId": <stable-id>}. Screens with an explicit base-level assignment additionally include "mode" — but ONLY when the stored rule actually declares an engine mode, so a missing "mode" means no mode was stated rather than Snapping (a layout-only pin, which carries an assignment slot and no engine mode, omits it) — plus whichever of {"default", "snappingLayout", "tilingAlgorithm", "scrollingTemplate"} the entry actually stores (an empty field is omitted, so a missing key means unset, not empty-string; the reserved opt-out words are stored values and so are NOT omitted — "scrollingTemplate" carries the literal "none" for a context that explicitly uses no template, "snappingLayout" carries "none" for an explicit no-layout opt-out, "tilingAlgorithm" carries "none" for an explicit no-algorithm opt-out, and "default" plus the numeric per-desktop keys carry "none" or "autotile:none" for such contexts); screens with explicit per-desktop assignments include numeric-string keys ("1", "2", …) mapping to the assigned layout id. Screens with no stored entries are omitted entirely — DO NOT use this method to enumerate available screens; call getAvailableScreenIds instead. Per-desktop keys are enumerated up to the compositor's CURRENT desktop count, so a stored entry for a desktop above that count (the user reduced their desktop count) is not serialized and the round trip is lossy for it. When the desktop count is unavailable the count falls back to 1, so desktop 1 is still serialized and only desktops 2 and up are dropped.

<tt>getActiveLayoutsForScreens()</tt>

Returns each effective screen's RESOLVED active layout id, as the daemon last computed it for that screen's current virtual desktop and activity. Unlike getAllScreenAssignments this is the resolved value (including synthesized global-default fallbacks), which is what the ActiveLayout rule field matches against. Pair with activeLayoutForScreenChanged: fetch once on daemon-ready, then track the signal.

Arg	Direction	Type	Description
activeLayouts	out	a{sv} *(dict<string,variant>)*	Map of stable screen id to active layout id (a layout UUID in braces, 'autotile:<algo>' for a tiling assignment, 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). A screen whose active id resolves EMPTY is omitted; the explicit opt-out is a stored value, resolves to no layout, and is still reported as the reserved word.

<tt>getQuickLayoutSlot()</tt>

Get the layout ID assigned to a quick slot (1-9) for the given mode.

Arg	Direction	Type	Description
mode	in	i *(int32)*	Tiling mode (0 = snapping, 1 = autotile, 2 = scrolling). Each mode owns a separate slot array. Scrolling slots hold native scrolling-template UUIDs (the ids getScrollingTemplates reports), never layout ids, and a template the store does not know is rejected on write.
slotNumber	in	i *(int32)*	Slot number (1-9).
layoutId	out	s *(string)*	The stored slot value, verbatim: a layout UUID for a snapping slot, autotile:<algorithmId> for an autotile slot, a scrolling-template UUID for a scrolling slot, or empty string when the slot is unset. No context resolution happens here.

<tt>setQuickLayoutSlot()</tt>

Assign a layout to a quick slot (1-9) for the given mode. The reserved opt-out id "autotile:none" is refused: a quick slot is an apply-this-layout binding, the opt-out has its own picker card, and a press on such a slot would resolve nothing. The snapping family's bare "none" is refused by the same UUID validation that rejects any non-layout string.

Arg	Direction	Type	Description
mode	in	i *(int32)*	Tiling mode (0 = snapping, 1 = autotile, 2 = scrolling). Each mode owns a separate slot array. Scrolling slots hold native scrolling-template UUIDs (the ids getScrollingTemplates reports), never layout ids, and a template the store does not know is rejected on write.
slotNumber	in	i *(int32)*	Slot number (1-9).
layoutId	in	s *(string)*	Layout UUID to assign (empty to clear).

<tt>setAllQuickLayoutSlots()</tt>

Batch set all quick layout slots for the given mode (saves once). Clears every existing slot for the mode first: a slot absent from the map is DELETED, so a partial map silently drops every slot it omits. Slots of the other modes are untouched. Like setQuickLayoutSlot, the reserved opt-out id "autotile:none" is refused: a quick slot is an apply-this-layout binding, and the opt-out resolves nothing on a press.

Arg	Direction	Type	Description
mode	in	i *(int32)*	Tiling mode (0 = snapping, 1 = autotile, 2 = scrolling). Each mode owns a separate slot array. Scrolling slots hold native scrolling-template UUIDs (the ids getScrollingTemplates reports), never layout ids, and a template the store does not know is rejected on write.
slots	in	a{sv} *(dict<string,variant>)*	Map of slot number (as string) to layoutId.

<tt>getAllQuickLayoutSlots()</tt>

Get all quick layout slot assignments for the given mode.

Arg	Direction	Type	Description
mode	in	i *(int32)*	Tiling mode (0 = snapping, 1 = autotile, 2 = scrolling). Each mode owns a separate slot array. Scrolling slots hold native scrolling-template UUIDs (the ids getScrollingTemplates reports), never layout ids, and a template the store does not know is rejected on write.
slots	out	a{sv} *(dict<string,variant>)*	Map of slot number (as string) to layoutId.

<tt>getCurrentVirtualDesktop()</tt>

Get the current virtual desktop number (1-indexed). Returns 0 if unavailable.

Arg	Direction	Type	Description
desktop	out	i *(int32)*	Current virtual desktop number (1-based), or 0 if unavailable.

<tt>isActivitiesAvailable()</tt>

True if KDE Activities are available.

Arg	Direction	Type	Description
available	out	b *(bool)*	True if Activities are available.

<tt>getActivities()</tt>

Returns the list of activity IDs.

Arg	Direction	Type	Description
activityIds	out	as *(array<string>)*	List of activity IDs.

<tt>getCurrentActivity()</tt>

Returns the current activity ID.

Arg	Direction	Type	Description
activityId	out	s *(string)*	Current activity ID.

<tt>getActivityInfo()</tt>

Returns activity metadata as JSON for the given activity ID.

Arg	Direction	Type	Description
activityId	in	s *(string)*	Activity ID to query.
activityJson	out	s *(string)*	Activity metadata as JSON.

<tt>getAllActivitiesInfo()</tt>

Returns metadata for all activities as JSON.

Arg	Direction	Type	Description
activitiesJson	out	s *(string)*	All activities metadata as JSON.

<tt>getLayoutForScreenActivity()</tt>

Get layout for a screen and activity (any desktop). Falls through to the global default layout when that context has no assignment, INCLUDING when the default is suppressed for it, so it can report a layout where getActiveLayoutsForScreens omits the screen and getScreenStates reports none. Callers wanting the suppression-aware resolved value must use one of those instead. A Snapping context explicitly set to no layout (the reserved word "none" in its assignment) answers empty rather than the default: the opt-out beats the fallback.

Arg	Direction	Type	Description
screenId	in	s *(string)*	Stable screen id in manufacturer:model:serial form, as returned by getAvailableScreenIds. A connector name (e.g. DP-1) is also accepted and resolved to the stable id.
activityId	in	s *(string)*	KDE Activity ID.
layoutId	out	s *(string)*	Layout UUID, autotile:<algorithmId> when the context resolves to autotile (including the literal "autotile:none" for an Autotile context explicitly set to no algorithm, where "none" is the reserved word, not an algorithm id), or empty string. Parsing this directly as a UUID yields a null UUID for an autotile screen.

<tt>assignLayoutToScreenActivity()</tt>

Assign layout to a screen and activity.

Arg	Direction	Type	Description
screenId	in	s *(string)*	Target screen name.
activityId	in	s *(string)*	KDE Activity ID.
layoutId	in	s *(string)*	Layout UUID to assign, or the reserved word "none" to set the context to explicitly use no layout (the opt-out beats the configured default). Like a layout UUID, the reserved word also sets the context's mode to Snapping — it is the SNAPPING family's opt-out. To opt a context out within the other families use "autotile:none" here, or setScrollingTemplateLayout's own reserved word.

<tt>clearAssignmentForScreenActivity()</tt>

Clear layout assignment for a screen/activity combination.

Arg	Direction	Type	Description
screenId	in	s *(string)*	Screen name.
activityId	in	s *(string)*	KDE Activity ID.

<tt>hasExplicitAssignmentForScreenActivity()</tt>

True if there is an explicit assignment for this screen/activity.

Arg	Direction	Type	Description
screenId	in	s *(string)*	Screen name.
activityId	in	s *(string)*	KDE Activity ID.
hasAssignment	out	b *(bool)*	True if explicit assignment exists.

<tt>setAllActivityAssignments()</tt>

Batch set all per-activity assignments (saves once). Key format: 'screenId|activityId' (legacy ':' fallback accepted). Clears existing assignments of this family first: a key absent from the map is DELETED, so a partial map silently drops every assignment it omits.

| Arg | Direction | Type | Description | |--—|--------—|---—|----------—| | assignments | in | a{sv} *(dict<string,variant>)* | Map of 'screenId|activityId' keys to a plain layoutId string (a Scrolling context stays the bare 'scrolling:' sentinel; the reserved words "none" and "autotile:none" are accepted and store the explicit opt-out, so the values the matching getter emits round-trip). Only that string is read here. The matching getter's value is a wider {layoutId, scrollingTemplate} map, and the scrolling template is written through setScrollingTemplateLayout, never through the batch setters. |

<tt>getAllActivityAssignments()</tt>

Get all per-activity assignments.

| Arg | Direction | Type | Description | |--—|--------—|---—|----------—| | assignments | out | a{sv} *(dict<string,variant>)* | Map of 'screenId|activityId' keys to a map {layoutId, scrollingTemplate}: layoutId is the assignment id the matching batch setter accepts (a Scrolling context stays the bare 'scrolling:' sentinel; a Snapping context that explicitly uses no layout carries the literal "none", and an Autotile context that explicitly uses no algorithm carries "autotile:none"), scrollingTemplate the context's scrolling-template UUID, or empty when the context pins none of its own, or the literal "none" when it explicitly uses no template at all. The getter value is deliberately wider than the setter's plain layoutId string; the template is written through setScrollingTemplateLayout, never through the batch setters. |

<tt>setAllCombinedAssignments()</tt>

Batch set all per-(screen,desktop,activity) Combined assignments (saves once). Key format: 'screenId|virtualDesktop|activityId'. Pure-Activity, pure-Desktop and Monitor-only rules are not touched. Clears existing assignments of this family first: a key absent from the map is DELETED, so a partial map silently drops every assignment it omits.

| Arg | Direction | Type | Description | |--—|--------—|---—|----------—| | assignments | in | a{sv} *(dict<string,variant>)* | Map of 'screen|desktop|activity' keys to a plain layoutId string (a Scrolling context stays the bare 'scrolling:' sentinel; the reserved words "none" and "autotile:none" are accepted and store the explicit opt-out, so the values the matching getter emits round-trip). Only that string is read here. The matching getter's value is a wider {layoutId, scrollingTemplate} map, and the scrolling template is written through setScrollingTemplateLayout, never through the batch setters. |

<tt>getAllCombinedAssignments()</tt>

Get all per-(screen,desktop,activity) Combined assignments. Returns ONLY rules with all three dimensions pinned.

| Arg | Direction | Type | Description | |--—|--------—|---—|----------—| | assignments | out | a{sv} *(dict<string,variant>)* | Map of 'screen|desktop|activity' keys to a map {layoutId, scrollingTemplate}: layoutId is the assignment id the matching batch setter accepts (a Scrolling context stays the bare 'scrolling:' sentinel; a Snapping context that explicitly uses no layout carries the literal "none", and an Autotile context that explicitly uses no algorithm carries "autotile:none"), scrollingTemplate the context's scrolling-template UUID, or empty when the context pins none of its own, or the literal "none" when it explicitly uses no template at all. The getter value is deliberately wider than the setter's plain layoutId string; the template is written through setScrollingTemplateLayout, never through the batch setters. |

<tt>getLayoutForScreenDesktopActivity()</tt>

Get layout for screen, virtual desktop, and activity. Falls through to the global default layout when that context has no assignment, INCLUDING when the default is suppressed for it, so it can report a layout where getActiveLayoutsForScreens omits the screen and getScreenStates reports none. Callers wanting the suppression-aware resolved value must use one of those instead. A Snapping context explicitly set to no layout (the reserved word "none" in its assignment) answers empty rather than the default: the opt-out beats the fallback.

Arg	Direction	Type	Description
screenId	in	s *(string)*	Stable screen id in manufacturer:model:serial form, as returned by getAvailableScreenIds. A connector name (e.g. DP-1) is also accepted and resolved to the stable id.
virtualDesktop	in	i *(int32)*	Virtual desktop index (1-based).
activityId	in	s *(string)*	KDE Activity ID.
layoutId	out	s *(string)*	Layout UUID, autotile:<algorithmId> when the context resolves to autotile (including the literal "autotile:none" for an Autotile context explicitly set to no algorithm, where "none" is the reserved word, not an algorithm id), or empty string. Parsing this directly as a UUID yields a null UUID for an autotile screen.

<tt>assignLayoutToScreenDesktopActivity()</tt>

Assign layout to screen, desktop, and activity.

Arg	Direction	Type	Description
screenId	in	s *(string)*	Target screen name.
virtualDesktop	in	i *(int32)*	Virtual desktop index (1-based).
activityId	in	s *(string)*	KDE Activity ID.
layoutId	in	s *(string)*	Layout UUID to assign, or the reserved word "none" to set the context to explicitly use no layout (the opt-out beats the configured default). Like a layout UUID, the reserved word also sets the context's mode to Snapping — it is the SNAPPING family's opt-out. To opt a context out within the other families use "autotile:none" here, or setScrollingTemplateLayout's own reserved word.

<tt>clearAssignmentForScreenDesktopActivity()</tt>

Clear layout assignment for screen/desktop/activity.

Arg	Direction	Type	Description
screenId	in	s *(string)*	Screen name.
virtualDesktop	in	i *(int32)*	Virtual desktop index (1-based).
activityId	in	s *(string)*	KDE Activity ID.

<tt>setScrollingTemplateLayout()</tt>

Assign a native scrolling template to the context and flip it to Scrolling mode. The value is a ScrollingTemplate UUID (one of the ids getScrollingTemplates reports), whose column blueprint seeds new columns and whose preset lists become the strip's vocabulary. Besides a UUID the field takes two reserved forms: the empty string, which clears the context's own choice so it inherits the configured default template, and the literal "none", which means the context explicitly uses NO template and is honoured over that default. Any other id the template store does not know, and any other non-UUID string, is rejected and nothing is written, so the context keeps its previous template. The existence half of that check needs the template store wired: an embedder running the daemon libraries without one (unit fixtures) gets the UUID-format check only, and a well-formed but unknown id is stored, then degrades to no template when the strip reads it. The mode flip applies to the empty-id clear form too, which is the one case where it is not implied by the argument: clearing the template still forces the context to Scrolling and materializes a stored entry for it if none existed. To remove the context's assignment outright, call clearAssignmentForScreenDesktopActivity, or clearAssignmentForScreenDesktop when the context names no activity — this setter accepts an empty activityId and the Combined clear does not, so the three-dimension clear refuses exactly the Desktop-family contexts this setter can create.

Arg	Direction	Type	Description
screenId	in	s *(string)*	Target screen name.
virtualDesktop	in	i *(int32)*	Virtual desktop index (1-based, 0 = screen-level).
activityId	in	s *(string)*	KDE Activity ID (empty = all activities).
layoutId	in	s *(string)*	Scrolling template UUID to assign (from getScrollingTemplates), or empty to clear the context's own choice so it inherits the configured default, or the literal "none" to use no template at all regardless of that default. All three forms force the context to Scrolling mode.

<tt>getScrollingTemplateLayout()</tt>

Resolved scrolling template for the context. A context that names no template of its own falls back to the configured default template, so the answer is empty only when the context is not Scrolling, or when neither the context nor the configured default names a template the store still holds. This is the RESOLVED answer, not the stored field, so it cannot distinguish a context that pins nothing from one set explicitly to "none" — both resolve to no template and both read back empty. Use getScreenStates, whose scrollingTemplateId carries the stored value verbatim, to tell those two apart.

Arg	Direction	Type	Description
screenId	in	s *(string)*	Target screen name.
virtualDesktop	in	i *(int32)*	Virtual desktop index (1-based, 0 = screen-level).
activityId	in	s *(string)*	KDE Activity ID (empty = all activities).
layoutId	out	s *(string)*	Scrolling template UUID or empty string.

<tt>setAssignmentEntry()</tt>

Set a complete assignment entry (mode + snapping layout + tiling algorithm) for a screen/desktop/activity context. Settings app sends one full entry per staged context during save. The entry is seeded from the context's stored one first, so a scrolling template already assigned there survives the call even though this signature does not carry it; setScrollingTemplateLayout remains the only way to change it.

Arg	Direction	Type	Description
screenId	in	s *(string)*	Screen ID.
virtualDesktop	in	i *(int32)*	Virtual desktop index (1-based, 0 = screen-level).
activity	in	s *(string)*	KDE Activity ID (empty = all activities).
mode	in	i *(int32)*	Mode (0=Snapping, 1=Autotile, 2=Scrolling). Out-of-range values are rejected, never clamped.
snappingLayout	in	s *(string)*	Snapping layout UUID, the reserved word "none" for the explicit no-layout opt-out (the context uses no layout at all, even while a default is configured), or empty = unset (the context inherits the default layout).
tilingAlgorithm	in	s *(string)*	Tiling algorithm ID, the reserved word "none" for the explicit no-algorithm opt-out (the context stays in autotile mode but nothing tiles there), or empty = unset (the context inherits the default algorithm).

<tt>setSaveBatchMode()</tt>

Suppress screenLayoutChanged signals while the settings app replays a batch of assignment mutations during save. Always paired: setSaveBatchMode(true) before the batch, setSaveBatchMode(false) after. applyAssignmentChanges also releases the suppression itself, before its empty-batch check, so a client that dies mid-batch cannot mute the signal for the rest of the daemon's life.

Arg	Direction	Type	Description
enabled	in	b *(bool)*	True to enter batch mode, false to leave it.

<tt>applyAssignmentChanges()</tt>

Trigger resnap/retile + OSD after a batch of assignment changes. Settings app calls this once after all setAssignmentEntry/clear calls complete. Releases the setSaveBatchMode suppression first, then returns without applying anything when the batch staged no screens, so a call with no preceding mutation is a no-op rather than a resnap of every window.

No arguments.

Signals

<tt>daemonReady</tt>

Emitted when the daemon has fully initialized and is ready. Clients (KCM, KWin effect) should wait for this before querying layouts.

No payload.

<tt>activeLayoutIdChanged</tt>

Emitted when the internal active layout changes. Carries the transient active-layout UUID, which may differ from getActiveLayout()'s settings-based default.

Arg	Direction	Type	Description
layoutId	out	s *(string)*	UUID of the newly active layout.

<tt>quickLayoutSlotsChanged</tt>

Refresh hint for subscribers holding quick layout slot state, such as the settings panel's slot cards. Emitted when the slots are modified directly, unconditionally when a layout is deleted, and when a scrolling template's deletion scrub changed a rule or swept a slot. Re-read the slots rather than assuming a specific slot changed.

No payload.

<tt>assignmentChangesApplied</tt>

Emitted after applyAssignmentChanges finishes a KCM save batch, listing the screens whose assignments changed. Skipped entirely for an empty batch. Also emitted by the daemon's own rule reconcile when a rule edit moves a screen's resolved assignment, so it is not exclusive to KCM saves.

Arg	Direction	Type	Description
changedScreenIds	out	as *(array<string>)*	Screen IDs whose assignments were modified in the batch.

<tt>currentActivityChanged</tt>

Emitted when the current KDE Activity changes.

Arg	Direction	Type	Description
activityId	out	s *(string)*	New current activity ID.

<tt>activitiesChanged</tt>

Emitted when the list of activities changes.

No payload.

<tt>virtualDesktopCountChanged</tt>

Emitted when the number of virtual desktops changes.

Arg	Direction	Type	Description
count	out	i *(int32)*	New virtual desktop count.

<tt>layoutChanged</tt>

Emitted on structural layout mutations (updateLayout, the editor's save path) and on every active-layout switch, alongside the cheaper activeLayoutChanged(id). Usually carries the full layout JSON payload; when the update targeted an AUTOTILE entry the payload is instead the caller's raw autotile-override object (id 'autotile:<algorithmId>', not a serialized layout), so subscribers must not blindly parse it as a layout. createLayoutFromJson does not emit this; a new layout announces itself with layoutCreated(id). Scalar property mutations (hidden, autoAssign, aspectRatioClass) emit layoutPropertyChanged instead to avoid the full serialization.

Arg	Direction	Type	Description
layoutJson	out	s *(string)*	Full layout as JSON.

<tt>activeLayoutChanged</tt>

Cheap context-switch notification: emitted alongside layoutChanged(json) on every active-layout switch, but carries only the layout UUID instead of the full JSON payload. Subscribers that re-load from disk (e.g. the editor) can bind to this signal and ignore the heavier layoutChanged emit.

Arg	Direction	Type	Description
layoutId	out	s *(string)*	UUID of the newly active layout.

<tt>layoutPropertyChanged</tt>

Compact per-property change notification. Replaces layoutChanged(json) for setLayoutHidden, setLayoutAutoAssign, and setLayoutAspectRatioClass. Subscribers that want the full shape should pull it via getLayout(layoutId) — the adaptor's cache is invalidated before the signal fires.

Arg	Direction	Type	Description
layoutId	out	s *(string)*	Layout UUID whose property changed.
property	out	s *(string)*	Property name: 'hidden', 'autoAssign', or 'aspectRatioClass'.
value	out	v *(variant)*	New value as a variant (bool or int).

<tt>layoutListChanged</tt>

Emitted when the list of layouts changes.

No payload.

<tt>scrollingTemplatesChanged</tt>

Emitted when the scrolling-template store's loaded set changes (save, delete, duplicate, rescan).

No payload.

<tt>layoutCreated</tt>

Emitted when a new layout is created (createLayout, createLayoutFromJson, duplicateLayout, importLayout). Carries the new layout's UUID.

Arg	Direction	Type	Description
layoutId	out	s *(string)*	UUID of the newly created layout.

<tt>layoutDeleted</tt>

Emitted when a layout is deleted. Carries the UUID of the deleted layout.

Arg	Direction	Type	Description
layoutId	out	s *(string)*	UUID of the deleted layout.

<tt>screenLayoutChanged</tt>

Emitted when a screen's layout assignment changes.

Arg	Direction	Type	Description
screenId	out	s *(string)*	Screen whose assignment changed.
layoutId	out	s *(string)*	The assignment id: a layout UUID, autotile:<algorithmId>, a scrolling id, or the reserved opt-out words "none" / "autotile:none" for a context explicitly set to use no layout or algorithm.
virtualDesktop	out	i *(int32)*	Virtual desktop number (0 = display default).

<tt>activeLayoutForScreenChanged</tt>

Emitted when a screen's RESOLVED active layout changes. The triggers are an assignment edit, a virtual-desktop or activity switch, a screen being added or removed, a virtual-screen reconfigure, a settings save that moves the global default, a rule edit that moves the assignment cascade, and a layout being deleted out from under a screen. This is the companion signal to getActiveLayoutsForScreens and the one to track for the ActiveLayout rule field. Unlike screenLayoutChanged, which reports assignment MUTATIONS and is suppressed during a KCM save batch, this reports every change to the value a rule would see.

Arg	Direction	Type	Description
screenId	out	s *(string)*	Stable screen id whose active layout changed.
layoutId	out	s *(string)*	The screen's new active layout id (a layout UUID in braces, 'autotile:<algo>', the reserved word 'none' for an explicit no-layout opt-out, or 'autotile:none' for an explicit no-algorithm opt-out). Empty when the screen no longer resolves to any layout; setting a screen to None emits the reserved word, not empty.