mutter/doc/monitor-configuration.md

# 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>
```