edfd1880c9
Let's try to consolidate our documentation in doc/ in the repo. This includes some documentation from README.md, the HACKING.md coding style and the gitlab wiki. The README.md file now links to all top-level topics (i.e. not reachable via other topics). This also includes a few small changes to make things more consistent. Part-of: <https://gitlab.gnome.org/GNOME/mutter/-/merge_requests/3465>
101 lines
3.3 KiB
Markdown
101 lines
3.3 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>
|
|
```
|