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

Unified window-rule store: query and mutate the rule set that maps windows to zones. Rules cross the wire as JSON strings — a single rule serializes to { id, name, enabled, priority, match, actions } and the whole set is a JSON object { _version, rules }. This interface serves the daemon's authoritative in-memory view of the rules, which is not the same as being the only writer of rules.json: the settings app writes that file in its own process on a reset, on a per-mode engine disable and on a config import. The daemon watches rules.json and folds every such out-of-process write into its store once a short debounce fires, so reloadRules is needed only by a caller that must have the reload done before its very next call.

Well-known name org.phosphor_works.Placement.Rules
Source XML org.phosphor_works.Placement.Rules.xml
Methods 9
Signals 1
Properties 0

Methods

getAllRules()

Return the whole rule set as a JSON object string ({ _version, rules }). Empty string if the store is unavailable.

Arg Direction Type Description
rulesJson out s (string) JSON object string in the { _version, rules } shape.

setAllRules()

Replace the entire rule set. The payload is a JSON object string in the { _version, rules } shape (or a bare object whose rules array carries the list). Individually malformed entries are dropped and a warning logs the dropped/accepted/total counts. A _version that is present and disagrees with the schema the daemon reads is refused outright rather than re-persisted under the daemon's own stamp; an absent _version is tolerated, since the bare-array spelling is a documented caller shape.

Arg Direction Type Description
rulesJson in s (string) JSON object string carrying the rules array. Payloads above roughly a million characters are refused at the wire boundary.
ok out b (bool) True only when the accepted set was both committed and written to disk. False covers an oversize payload, malformed JSON or a non-object document, a mismatched _version, a missing rules array, a non-empty payload whose every rule was dropped (treated as a rejected payload rather than a clear, so the persisted set survives), and an in-memory replace whose file write failed. A payload identical to the persisted set is a no-op that still returns true.

addRule()

Append one rule from its JSON object string. Returns false if the payload is over the roughly million-character wire cap, the JSON is malformed, the rule fails validation, its id collides with an existing rule, or the rules.json write failed.

Arg Direction Type Description
ruleJson in s (string) JSON object string for a single rule ({ id, name, enabled, priority, match, actions }).
ok out b (bool) True if the rule was added and the set was written to disk.

updateRule()

Replace the rule with the same id from its JSON object string. Returns false if the payload is over the roughly million-character wire cap, the JSON is malformed, the rule fails validation, no rule with that id exists, or the rules.json write failed.

Arg Direction Type Description
ruleJson in s (string) JSON object string for a single rule ({ id, name, enabled, priority, match, actions }).
ok out b (bool) True if the rule was replaced and the set was written to disk.

removeRule()

Remove the rule with the given id. Returns false if the id is malformed, no rule with that id exists, or the rules.json write failed.

Arg Direction Type Description
ruleId in s (string) Rule UUID string.
ok out b (bool) True if a rule was removed and the set was written to disk.

setRuleEnabled()

Set the enabled flag of the rule with the given id. Returns false if the id is malformed, no rule with that id exists, or the rules.json write failed. Setting a rule to the flag it already carries is a no-op that still returns true.

Arg Direction Type Description
ruleId in s (string) Rule UUID string.
enabled in b (bool) True to enable the rule, false to disable it.
ok out b (bool) True if the rule now has the requested enabled state, whether or not this call is what put it there.

setRulePriority()

Set the priority of the rule with the given id. Higher priority wins when multiple rules match a window. Returns false if the id is malformed, no rule with that id exists, or the rules.json write failed. Setting a rule to the priority it already carries is a no-op that still returns true.

Arg Direction Type Description
ruleId in s (string) Rule UUID string.
priority in i (int32) New priority value.
ok out b (bool) True if the rule now carries the requested priority, whether or not this call is what put it there.

resetManagedDefaults()

Global Restore Defaults hook for the rule store. Window border, title bar and gap defaults live in the config store and the store holds no managed rules, so this creates and removes nothing. It reloads the store from disk to pick up an out-of-process write such as the settings app's own reset, which the daemon would otherwise write back on its next save. rulesChanged fires only when the on-disk set differs from the one in memory.

No arguments.

reloadRules()

Re-read rules.json from disk. The daemon already watches rules.json and folds an out-of-process rewrite (a settings import, for one) into its store once a short debounce fires, so this exists for a caller that rewrites the file and needs the reload to have happened before its very next call rather than on a later event-loop turn. Idempotent, and rulesChanged is emitted only when the on-disk content differs from what the store already holds.

No arguments.

Signals

rulesChanged

Emitted whenever the store's rule set changes (add, update, remove, enable, priority, or full replace).

Arg Direction Type Description
persisted out b (bool) True when the in-memory change was successfully written to disk. False signals an in-memory mutation whose persist failed — consumers can branch on this to differentiate 'saved' from 'edited but divergent from disk'.