monitor_layout/README.md

# monitor\_layout

A tool for specifying monitor layout on Linux.


## Installation

### Pre-requisites

 * PHP 7.2+

### Setup

 * Extract the tool.


## Usage

### layout

    monitor_layout layout <config_file.yaml>

Will load `config_file.yaml` and attempt to lay out all attached screens
following the layout rules.

### monitor

	monitor_layout monitor <config_file.yaml> [--interval=5]

Will load `config_file.yaml` and attempt to lay out all attached screens
following the layout rules.

The program will stay running and attempt to perform layout again every
`interval` seconds in order to respond to screens being attached/unattached.


## Configuration

### Screens

```
screens:
	internal:
		output: eDP-1-1
	hdmi:
		output:
			- HDMI-1-1
			- HDMI-1-2
	usb:
		output: DVI-I-2-1
```

Each screen provides a single logical resource for dealing with your display in
various configurations. The program will enumerate the outputs specified until
it finds one that is connected, and that screen will refer to that output. This
allows for, example, allowing connecting a display to *any* of a variety of
outputs and having it treated as a single logical screen.

### Layouts

```
layouts:
	all_screens:
		screens:
			internal: null
			hdmi: null
			usb:
				width: 1920
				height: 1080
		links:
			- display: hdmi
			  right_of: internal
			- display: usb
			  above: hdmi
	hdmi_only:
		screens:
			internal: null
			hdmi: null
		links:
			- display: hdmi
			  right_of: internal
```

Layouts are evaluated in the order listed. The first layout found where all the
listed `screens` are available (that is, xrandr shows them as connected) will be
used.

The selected layout can specify additional parameters (e.g., width and height)
for the screen.

The `links` will be used to calculate the offsets of all the displays relative
to whichever screen is considered `primary` by xrandr. Valid relations are:

 * `above` - above the referenced display, centered horizontally
 * `below` - below the referenced display, centered horizontally
 * `left_of` - to the left of the referenced display, with the tops aligned
 * `right_of` - to the right of the referenced display, with the tops aligned

### Sample

```
screens:
  hdmi:
    output: HDMI-1-2
  touchpad:
    output: HDMI-1-1
  internal:
    output: eDP-1-1
  usb:
    output:
      - DVI-I-2-1
      - DVI-I-2-2
      - DVI-I-2-3
      - DVI-I-2-4
      - DVI-I-2-5
      - DVI-I-2-6

layouts:
  all_screens:
    screens:
      hdmi: null
      touchpad: null
      internal: null
      usb:
        width: 1920
        height: 1080
    links:
      - display: usb
        right_of: internal
      - display: hdmi
        above: usb
      - display: touchpad
        below: internal
  no_usb:
    screens:
      hdmi: null
      touchpad: null
      internal: null
    links:
      - display: hdmi
        right_of: internal
      - display: touchpad
        below: internal
```

## Building

`php monitor_layout app:build`

 * This will occassionally fail due to the system's limit on open file
   descriptors. The most straightforward (if slightly gross) solution is
   simply: `sudo -- sh -c 'ulimit -n 65535 && ./monitor_layout app:build'`