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 :)