b5f99bd12e
This describes how the `monitors.xml` file work, and how to override the newly introduced configurable policy. Part-of: <https://gitlab.gnome.org/GNOME/mutter/-/merge_requests/2030>
106 lines
3.4 KiB
Markdown
106 lines
3.4 KiB
Markdown
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
|
|
`<monitors version="2">`. In this document multiple configurations are stored as
|
|
individual `<configuration/>` 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 `<policy/>` element inside
|
|
the `<monitors version="2"/>` element in the `monitors.xml` file. Note that
|
|
there may only be one `<policy/>` 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 `<stores/>` element inside the `<policy/>` element
|
|
described above.
|
|
|
|
In this element, the file policy is defined by a `<stores/>` element, which
|
|
lists stores with the order according to prioritization. Each store is specified
|
|
using a `<store/>` element with either `system` or `user` as the content.
|
|
|
|
#### Example of only reading monitor configuration from the system level file:
|
|
|
|
```xml
|
|
<monitors version="2">
|
|
<policy>
|
|
<stores>
|
|
<store>system</store>
|
|
</stores>
|
|
</policy>
|
|
</monitors>
|
|
```
|
|
|
|
#### Example of reversing the priority of monitor configuration:
|
|
|
|
```xml
|
|
<monitors version="2">
|
|
<policy>
|
|
<stores>
|
|
<store>user</store>
|
|
<store>system</store>
|
|
</stores>
|
|
</policy>
|
|
</monitors>
|
|
```
|
|
|
|
### Changing D-Bus configuration policy
|
|
|
|
D-Bus configureability can be configured using a `<dbus/>` element in the
|
|
`<policy/>` 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
|
|
<monitors version="2">
|
|
<policy>
|
|
<dbus>no</dbus>
|
|
</policy>
|
|
</monitors>
|
|
```
|