xi-desktop-portals

commit

0d5e4bfae635735d6fb0b4dea13c90471fba6c53

parent

c96dc742d78baf34600f10679d5fc647d78cced5

Author

Tobias Bengfort <tobias.bengfort@posteo.de>

Date

2026-03-14 10:45

[Settings] spec

Diffstat

1 files changed, 58 insertions, 0 deletions

diff --git a/Settings/README.md b/Settings/README.md

@@ -0,0 +1,58 @@
   -1     1 # Settings Portal
   -1     2 
   -1     3 This interface provides access to settings. It describes both a general purpose
   -1     4 mechanism for making settings available to applications as well as defining a
   -1     5 small number of standardized host settings required for toolkits.
   -1     6 
   -1     7 ## General Purpose Mechanism
   -1     8 
   -1     9 -   Settings are stored in files inside
   -1    10     [`$XDG_CONFIG_HOME`](https://specifications.freedesktop.org/basedir/latest/).
   -1    11 -   Sandboxes can give read-write, read-only, or no access to a given settings
   -1    12     file.
   -1    13 -   Sandboxes may also present different settings than what is used on the host
   -1    14     system.
   -1    15 -   Applications can watch settings using `inotify(7)`
   -1    16 
   -1    17 ## Standardized Settings
   -1    18 
   -1    19 -   `$XDG_CONFIG_HOME/org.freedesktop.appearance/color-scheme` (`''`, `'dark'`,
   -1    20     `'light'`)
   -1    21 -   `$XDG_CONFIG_HOME/org.freedesktop.appearance/accent-color` (`''`,
   -1    22     `#rrggbb`)
   -1    23 -   `$XDG_CONFIG_HOME/org.freedesktop.appearance/contrast` (`''`, `'high'`)
   -1    24 -   `$XDG_CONFIG_HOME/org.freedesktop.appearance/reduced-motion` (`''`,
   -1    25     `'reduced'`)
   -1    26 
   -1    27 ## Open Questions
   -1    28 
   -1    29 -   Should `inotify` be used to watch directories or files? That makes a
   -1    30     difference when files are not only modified, but also deleted, created, or
   -1    31     moved.
   -1    32 -   Should there be one setting per file (`/proc/`-style) or multiple settings
   -1    33     in a single file?
   -1    34 -   Should sandboxes be allowed to bind individual files? (can mess with
   -1    35     inotify)
   -1    36 
   -1    37 ## Compatibility Considerations
   -1    38 
   -1    39 Legacy applications may either use `org.freedesktop.portal.Settings` or
   -1    40 `gsettings`.
   -1    41 
   -1    42 It should be easily possible to implement a service that watches the relevant
   -1    43 settings and syncs them to gsettings. This service could also implement the
   -1    44 relevant xdg portal backend or rely on `xdg-desktop-portal-gtk`.
   -1    45 
   -1    46 ## Security Considerations
   -1    47 
   -1    48 -   The available set of settings should be limited, well-structured, and
   -1    49     clearly labelled so that users understand which settings they should expose
   -1    50     to sandboxed applications.
   -1    51 -   Sandboxes should usually expose settings read-only.
   -1    52 -   Confidential data (e.g. passwords) should not be stored in settings.
   -1    53 -   Settings that belong to different security domains should be stored in
   -1    54     different files.
   -1    55 
   -1    56 ## Related Links
   -1    57 
   -1    58 -   [org.freedesktop.portal.Settings](https://flatpak.github.io/xdg-desktop-portal/docs/doc-org.freedesktop.portal.Settings.html)