Configuration: load/save/reset, get/set by key, and Zone Selector-specific settings.
| Well-known name | org.phosphor_works.Placement.Settings |
| Source XML | org.phosphor_works.Placement.Settings.xml |
| Methods | 17 |
| Signals | 6 |
| Properties | 0 |
Reload settings from disk.
No arguments.
Save current settings to disk.
No arguments.
Reset all settings to their defaults.
No arguments.
Return all settings as a JSON object.
| Arg | Direction | Type | Description |
|---|---|---|---|
| settingsJson | out | s (string) | All settings as JSON. |
Get a single setting value by key (variant type). An unknown or empty key answers with an org.freedesktop.DBus.Error.InvalidArgs error rather than a value, so a caller that fetches a key the daemon does not know keeps its own default instead of silently reading an empty one.
| Arg | Direction | Type | Description |
|---|---|---|---|
| key | in | s (string) | Setting key name. |
| value | out | v (variant) | Setting value (variant). |
Batch-get multiple settings in one call. Unknown keys are omitted from the result map.
| Arg | Direction | Type | Description |
|---|---|---|---|
| keys | in | as (array<string>) | List of setting key names to fetch. |
| values | out | a{sv} (dict<string,variant>) | Map of key → value for every key that was found. |
Set a single setting by key. Returns true if the setting now holds the supplied value — a same-value write is a no-op but still returns true (the value-equality guard suppresses the redundant write without reporting failure). One carve-out: the resolving color keys (the zone colors and the window border/tint colors) accept the empty string or the legacy accent token to put the color back on the color scheme; the write succeeds, but reading the key back returns the RESOLVED concrete color, never the sentinel — read the matching *Raw key for the stored follow-or-pinned state. The normalizing token-enum keys (renderingBackend, audioChannelMode, audioInputMethod) accept any case and surrounding whitespace their option set recognizes and store the canonical lowercase spelling; the window scope keys require their exact lowercase token. Range-clamped numeric keys are a second carve-out: an out-of-range value is clamped by the config schema on write and the call still returns true, so reading the key back may return the clamped bound rather than the supplied value.
| Arg | Direction | Type | Description |
|---|---|---|---|
| key | in | s (string) | Setting key name. |
| value | in | v (variant) | New value (variant). |
| success | out | b (bool) | True if the setting now holds the supplied value (including same-value no-op writes). |
Batch-set multiple settings in one call. Applies every key via the setter registry and saves once. Unknown keys are logged but do not abort the batch.
| Arg | Direction | Type | Description |
|---|---|---|---|
| settings | in | a{sv} (dict<string,variant>) | Map of setting key to value. |
| success | out | b (bool) | True if every key was known to the registry and every key that has a setter applied successfully. Read-only keys (motionProfileTree, animationShaderSearchPaths) are skipped without failing the batch. This is false when a key is unknown OR when a setter rejects its value (an out-of-range enum, an invalid blob). |
Return the list of all setting key names.
| Arg | Direction | Type | Description |
|---|---|---|---|
| keys | out | as (array<string>) | All setting key names. |
Get metadata for a single setting key. Returns JSON with key and type fields.
| Arg | Direction | Type | Description |
|---|---|---|---|
| key | in | s (string) | Setting key name. |
| schemaJson | out | s (string) | JSON: {key, type}. Type is bool, int, double, string, color, themeColor, stringlist, or map. A themeColor key stores a theme-fallback string: empty means the value follows the system color scheme, anything else is a pinned color. |
Get metadata for all settings. Returns JSON object mapping keys to type info (type is one of bool, int, double, string, color, themeColor, stringlist, map; themeColor marks a theme-fallback string whose empty value follows the system color scheme).
| Arg | Direction | Type | Description |
|---|---|---|---|
| schemasJson | out | s (string) | JSON object: {key: {type}, ...}. |
Get all per-screen settings for a screen and category.
| Arg | Direction | Type | Description |
|---|---|---|---|
| screenId | in | s (string) | Virtual or physical screen identifier. |
| category | in | s (string) | 'autotile' | 'scrolling' | 'snapping' | 'zoneSelector' | 'scrollingZoneSelector'. | | values | out | a{sv} (dict<string,variant>) | Map of per-screen setting key to value. |
Set a single per-screen setting and schedule a debounced save. Rejections are LOUD, not silent: an implausible screen id or setting key, an unknown category, the read-only 'snapping' category, or a missing settings backend answers with an org.freedesktop.DBus.Error.InvalidArgs error reply rather than a no-op.
| Arg | Direction | Type | Description |
|---|---|---|---|
| screenId | in | s (string) | Virtual or physical screen identifier. |
| category | in | s (string) | 'autotile' | 'scrolling' | 'snapping' | 'zoneSelector' | 'scrollingZoneSelector'. 'snapping' is READ-ONLY (a projection of the config per-monitor gaps): the two void methods reject a write to it with an InvalidArgs error reply, and the batch setter skips it returning false. | | key | in | s (string) | Per-screen setting key name. | | value | in | v (variant) | New value (variant). |
Clear all per-screen overrides for a screen and category, reverting to global defaults. Rejections are LOUD, like setPerScreenSetting's: an implausible screen id, an unknown category, the read-only 'snapping' category, or a missing settings backend answers with an org.freedesktop.DBus.Error.InvalidArgs error reply rather than a no-op.
| Arg | Direction | Type | Description |
|---|---|---|---|
| screenId | in | s (string) | Virtual or physical screen identifier. |
| category | in | s (string) | 'autotile' | 'scrolling' | 'snapping' | 'zoneSelector' | 'scrollingZoneSelector'. 'snapping' is READ-ONLY (a projection of the config per-monitor gaps): the two void methods reject a write to it with an InvalidArgs error reply, and the batch setter skips it returning false. |
Batch-set multiple per-screen keys in one D-Bus call. Applies every entry to the named category and schedules a single debounced save.
| Arg | Direction | Type | Description |
|---|---|---|---|
| screenId | in | s (string) | Virtual or physical screen identifier. |
| category | in | s (string) | 'autotile' | 'scrolling' | 'snapping' | 'zoneSelector' | 'scrollingZoneSelector'. 'snapping' is READ-ONLY (a projection of the config per-monitor gaps): the two void methods reject a write to it with an InvalidArgs error reply, and the batch setter skips it returning false. | | values | in | a{sv} (dict<string,variant>) | Map of per-screen setting key -> value. | | success | out | b (bool) | True if the category was recognized and writable and the batch ran (the dispatch runs against ISettings); false if the category was unknown or is the read-only 'snapping' projection. Individual per-key failures are logged by the underlying Settings implementation but cannot be surfaced here since the setter methods return void. |
Asynchronously request the running-windows list. The daemon emits runningWindowsRequested to the KWin effect; the reply is delivered via the runningWindowsAvailable signal.
No arguments.
KWin effect to daemon callback: deliver the enumerated running-windows list in response to requestRunningWindows. The daemon re-broadcasts it via runningWindowsAvailable. Only the registered compositor bridge may call it, and any other caller is answered with AccessDenied.
| Arg | Direction | Type | Description |
|---|---|---|---|
| json | in | s (string) | JSON array of window rows: [{windowClass, rawWindowClass, appName, caption, desktopFile}, ...]. windowClass is the canonical class token, rawWindowClass the "resourceName resourceClass" the WindowClass rule field compares, appName the short name of the window's app id. Any field may be empty, but every row carries a class, a caption or a desktop file: a window with no class is listed when it has a caption or a desktop file. At most 1 MiB (1048576 bytes) of UTF-8 (PhosphorProtocol::Service::MaxRunningWindowsPayloadBytes); the effect leaves rows out rather than exceed it. |
Emitted when any setting is modified, except that a reload which moves only Editor.* settings emits editorSettingsChanged instead.
No payload.
Daemon to the layout editor and the Settings app: a reload moved one or more Editor.* settings (shortcuts, snapping, fill on drop, canvas background). Kept separate from settingsChanged because no other consumer reads those keys, so a save from the editor does not make every settingsChanged subscriber re-fetch its state.
No payload.
Daemon to KWin effect: the per-event motion-profile tree changed. Since schema v8 that tree is the Animations/MotionProfileTree config key, so this fires on a write to it rather than on a file rescan. Kept separate from settingsChanged so the Settings app's value-change detection is not reset by its own timing writes. The KWin effect re-fetches motionProfileTree on this signal.
No payload.
Daemon to KWin effect: the session went idle (no input for the configured timeout) or became active again. The effect pauses decoration-chain animation while idle, which is what lets the GPU leave its top performance state — the per-frame work being cheap does not, since what costs is that there is work every frame at all. The daemon owns this because idleness is a Wayland CLIENT concern (ext-idle-notify-v1) and the effect lives inside the compositor, which serves that protocol rather than consuming it.
| Arg | Direction | Type | Description |
|---|---|---|---|
| idle | out | b (bool) | True when the session has been idle for the configured timeout. |
Daemon to KWin effect: please enumerate running windows. Emitted by requestRunningWindows; the effect answers via provideRunningWindows.
No payload.
Emitted when a fresh running-windows list has arrived from the KWin effect.
| Arg | Direction | Type | Description |
|---|---|---|---|
| json | out | s (string) | JSON array of window rows: [{windowClass, rawWindowClass, appName, caption, desktopFile}, ...]. windowClass is the canonical class token, rawWindowClass the "resourceName resourceClass" the WindowClass rule field compares, appName the short name of the window's app id. Any field may be empty, but every row carries a class, a caption or a desktop file: a window with no class is listed when it has a caption or a desktop file. At most 1 MiB (1048576 bytes) of UTF-8 (PhosphorProtocol::Service::MaxRunningWindowsPayloadBytes); the effect leaves rows out rather than exceed it. |