01ca101164e803ebd640f6ce47b9cd19535cb59d
[lilass.git] / README.md
1 # LiLaSS: Linux Laptop Screen Setup
2
3 ## Introduction
4
5 This is the documentation of [LiLaSS]( https://www.ralfj.de/projects/lilass), a 
6 tool to setup screens on a Linux-powered Laptop.
7
8 LiLaSS is targeted for a specific use-case: The laptop is used both with the
9 internal screen only, and in combination with a single external screen.
10 [xrandr](http://www.x.org/wiki/Projects/XRandR) is used to detect whether an
11 external screen is plugged in, and to change the configuration according to the
12 user's specification.  Furthermore, LiLaSS remembers the configuration used for
13 any particular screen, so that it can offer the same configuration next time.
14 You can even make it apply that configuration automatically.
15
16 ## Usage
17
18 LiLaSS features an interactive and a batched mode of use.  Either way, if LiLaSS
19 is started while no external screen is connected, it enables the internal
20 screen.
21
22 It is in the case that an external screen is plugged in that the two modes
23 differ.
24
25 Simply run `lilass` to start the interactive mode.  A window will pop up,
26 allowing you to select which screens are enabled, their resolution, and how they
27 are positioned relatively to each other.  The option `--frontend` (or `-f`) can
28 be used to choose the frontend which opens the window. Currently, the frontends
29 `qt` (using Qt5), `zenity` and `cli` are available.  LiLaSS attempts to choose
30 an adequate frontend automatically.
31
32 If a screen is connected that was already configured with LiLaSS before, the
33 previously selected configuration will be offered per default.  You can pass
34 `--silent` (`-s`) to instead suppress the UI altogether, and just apply the
35 previous configuration.  You can disable the use of the stored screen
36 configurations by passing `--no-db`.
37
38 Furthermore, you can also suppress the UI in case LiLaSS sees a new screen by
39 telling LiLaSS directly what to do with that screen: With the flags
40 `--internal-only` (`-i`) and `--external-only` (`-e`), one of the two screens is
41 picked and the other one disabled.  With `--relative-position` (`-r`), the
42 relative position of the two screens can be set (`left`, `right`, `above`,
43 `below` or `mirror`). In either case, the preferred possible resolution(s) of
44 the screen(s) will be picked if applicable. (In `mirror` mode, LiLaSS instead
45 picks the largest resolution that both screens have in common.)
46
47 If the internal screen ends up being the only one that is used, LiLaSS attempts 
48 to turn on your backlight if it was disabled.
49
50 ## Automatic Configuration
51
52 In combination with [x-on-resize](http://keithp.com/blogs/x-on-resize/) by Keith
53 Peckard, LiLaSS can be run automatically when a screen is plugged in, and
54 automatically re-enable the internal screen the external one is plugged off.  As
55 LiLaSS remembers the screen configuration that was used last time, this
56 automatic mode will use the previous configuration if the same screen is
57 connected again.
58
59 All this is achieved by running the following on log-in:
60
61     x-on-resize --config "lilass -s -r mirror" --start
62
63 Of course, instead of `-r mirror`, you can pick a different default
64 configuration applied to screens that have not been seen previously. By dropping
65 this option altogether, LiLaSS will instead pop up and ask what to do when a new
66 screen is connected.
67
68 ## Configuration File
69
70 You can use `~/.config/lilass.conf` to tell LiLaSS which are the names of your
71 internal and external connectors.  These are the names as used by `xrandr`.  The
72 option `internalConnector` gives the name of the xrandr connector corresponding
73 to your internal laptop screen.  All the others will be considered external
74 screens, unless you use the option `externalConnectors` to provide a
75 (space-separated) list of connectors to be considered external by LiLaSS.  Any
76 connector not mentioned in either option will be completely ignored.
77
78 ## Source, License
79
80 You can find the sources in the
81 [git repository](http://www.ralfj.de/git/lilass.git) (also available
82 [on GitHub](https://github.com/RalfJung/lilass)). They are provided under the
83 [GPLv2](https://www.gnu.org/licenses/old-licenses/gpl-2.0.html) or (at your
84 option) any later version of the GPL.  See the file `LICENSE-GPL2` for more
85 details.
86
87 ## Contact
88
89 If you found a bug, or want to leave a comment, please
90 [send me a mail](mailto:post-AT-ralfj-DOT-de).  I'm also happy about pull
91 requests :)