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

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

Methods

reloadSettings()

Reload settings from disk.

No arguments.

saveSettings()

Save current settings to disk.

No arguments.

resetToDefaults()

Reset all settings to their defaults.

No arguments.

getAllSettings()

Return all settings as a JSON object.

Arg Direction Type Description
settingsJson out s (string) All settings as JSON.

getSetting()

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

getSettings()

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.

setSetting()

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

setSettings()

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

getSettingKeys()

Return the list of all setting key names.

Arg Direction Type Description
keys out as (array<string>) All setting key names.

getSettingSchema()

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.

getAllSettingSchemas()

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}, ...}.

getPerScreenSettings()

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

setPerScreenSetting()

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

clearPerScreenSettings()

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

setPerScreenSettings()

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

requestRunningWindows()

Asynchronously request the running-windows list. The daemon emits runningWindowsRequested to the KWin effect; the reply is delivered via the runningWindowsAvailable signal.

No arguments.

provideRunningWindows()

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.

Signals

settingsChanged

Emitted when any setting is modified, except that a reload which moves only Editor.* settings emits editorSettingsChanged instead.

No payload.

editorSettingsChanged

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.

motionProfileTreeChanged

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.

sessionIdleChanged

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.

runningWindowsRequested

Daemon to KWin effect: please enumerate running windows. Emitted by requestRunningWindows; the effect answers via provideRunningWindows.

No payload.

runningWindowsAvailable

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.