From b5f99bd12ebc483e682e39c8126a1b51772bc67d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jonas=20=C3=85dahl?= Date: Fri, 1 Oct 2021 09:52:15 +0200 Subject: [PATCH] doc: Add monitor configuration documentation This describes how the `monitors.xml` file work, and how to override the newly introduced configurable policy. Part-of: --- doc/monitor-configuration.md | 105 +++++++++++++++++++++++++++++++++++ 1 file changed, 105 insertions(+) create mode 100644 doc/monitor-configuration.md diff --git a/doc/monitor-configuration.md b/doc/monitor-configuration.md new file mode 100644 index 000000000..46c107837 --- /dev/null +++ b/doc/monitor-configuration.md @@ -0,0 +1,105 @@ +Monitor configuration +===================== + +File locations +-------------- + +Monitor configurations are stored as XML files called `monitors.xml` on the file +system. There are two types of locations for the XML file: the system level and +the user level. + +The directories for system level configuration is defined in accordance to the +$XDG_CONFIG_DIRS environment variable defined in the XDG Base Directory +Specification. The default is `/etc/xdg/monitors.xml`. + +The directory for the user level configuration is defined in accordance to the +$XDG_CONFIG_HOME environment variable defined in the XDG Base Directory +Specification. The default is `~/.config/monitors.xml` + +File contents +------------- + +A configuration file consists of an XML document with the root element +``. In this document multiple configurations are stored as +individual `` elements containing all the details of the monitor +setup. The `version` attribute must be set to `"2"`. + +Each configuration corresponds to a specific hardware setup, where a given set +of monitors are connected to the computer. There can only be one configuration +per hardware setup. + +Writing configuration +--------------------- + +Monitor configurations are managed by Mutter via the Display panel in Settings, +which uses a D-Bus API to communicate with Mutter. Each time a new configuration +is applied and accepted, the user level configuration file is replaced with +updated content. + +Previously defined monitor configurations for hardware state other than the +current are left intact. + +Configuration policy +-------------------- + +The monitor configuration policy determines how Mutter configures monitors. This +can mean for example in what order configuration files should be preferred, or +whether configuration via Settings (i.e. D-Bus) should be allowed. + +The default policy is to prioritize configurations defined in the user level +configuration file, and to allow configuring via D-Bus. + +Changing the policy is possible by manually adding a `` element inside +the `` element in the `monitors.xml` file. Note that +there may only be one `` element in each configuration file. + +### Changing configuration file priority policy + +To change the order of configuration file priority, or to disable configuration +files completely, add a `` element inside the `` element +described above. + +In this element, the file policy is defined by a `` element, which +lists stores with the order according to prioritization. Each store is specified +using a `` element with either `system` or `user` as the content. + +#### Example of only reading monitor configuration from the system level file: + +```xml + + + + system + + + +``` + +#### Example of reversing the priority of monitor configuration: + +```xml + + + + user + system + + + +``` + +### Changing D-Bus configuration policy + +D-Bus configureability can be configured using a `` element in the +`` element. It's content should either be `yes` or `no` depending on +whether monitor configuration via D-Bus should be enabled or disable. + +#### Example of how to disable monitor configuration via D-Bus: + +```xml + + + no + + +```