No Description
Michał Góral 9e26ef695b Added --disable oputputs list and --force flag. 1 year ago
tools cfgrepo 1 year ago
LICENSE.txt license 1 year ago
README.adoc Docs update 1 year ago
config-example.yml Docs update 1 year ago
monconf Added --disable oputputs list and --force flag. 1 year ago

README.adoc

monconf
=======

monconf is utility for creating persistent xrandr configurations. It's
particularly useful when having different screen setups for a single machine:
e.g. for a laptop which can either use internal display or external monitors
when docked.

== Installation

monconf is a single script. Just drop it to your `$PATH`, e.g. to
`~/.local/bin`.

=== Dependencies

* Python 3.5+
* python3-yaml

== Configuration

monconf will search for configuration file under the following path:
`~/.config/monconf/config.yml`. You can also change configuration path with *-c
--conf-file* switch.

Configuration is a standard YAML file. You can find an example configuration in
this repository.

Configuration has 2 main sections:

* *outputs*: a section where xrandr-compatible outputs and their default options
are described
* *configurations*: a section where xrandr configurations are described

=== Outputs

Outputs section contains a list of xrandr outputs. Each of these might have one
of the following properties:

* *name*: same name of output as given by `xrandr`

* *mode*: (optional) mode which will be configured for xrandr. If omitted,
`auto` mode will be used, otherwise it should be any of the modes reported by
`xrandr`. It's disregarded (changed to *off*) when output is disabled for
current configuration.

* *options*: (optional) list of options which will be directly translated to
xrandr arguments. For example:
+
----
options:
- primary:
- crtc: 1
- right-of: VGA1
----
+
will be translated to: `--primary --crtc 1 --right-of VGA1`.

TIP: You don't have to specify _outputs_ section if you don't want to invoke
xrandr commands.

=== Configurations

Configurations section contains a list of options which will be translated to
xrandr invocations. Each configuration have the following properties:

* *name*: name under which configuration is known. This is the name passed as
monconf's argument

* *enable*: (optional) list of outputs which should be enabled by this
configuration. Can be a single output as well.

* *disable*: (optional) list of outputs which should be disabled by this
configuration. By default (if it's not specified), all outputs not listed in
*enable* field are disabled. If you don't want to disable any outputs, pass an
empty list:
+
----
disable: []
----

* *post_conf*: (optional) list of commands which will be executed after
*successfull* xrandr command (not running xrandr command at all e.g. because
there were no outputs to enable or disable is considered successfull as well).
Commands will stop on first failure. You can mark a command which can fail by
placing a leading *minus sign* `-`, similar to `make` recipes:
+
----
post_conf:
- echo "OK"
- -exit 1
- echo "I'm still OK"
----

* *on_error*: (optional) works the same way as *post_conf*, but commands will be
executed only after xrandr's failure.

* *standalone*: (optional) boolean (true/false) which, when set to true, removes
this configuration from a list which will be automatically cycled when
configuration name is not passed to monconf. By default all configurations
marked as not standalone (i.e. will be cycled through).

== Selecting a configuration

There are 3 ways to choose a configuration which will be used:

1. by passing it explicitly to monconf:
+
----
$ monconf configuration-name
----

2. by creating a temporary simple configuration from configured outputs:
+
----
$ monconf -e HDMI-1,VGA-2
----

3. by not telling monconf anything in which case it will cycle non-standalone
configurations.