Metadata-Version: 1.0
Name: randrctl
Version: 1.1.1
Summary: Profile based screen manager for X
Home-page: http://github.com/edio/randrctl
Author: Dmytro Kostiuchenko
Author-email: edio@archlinux.us
License: GPLv3
Description: randrctl
        ========
        
        Minimalistic profile based screen manager for X. It allows to store current screen setup in a declarative configuration file (a profile) and apply stored settigns later with a simple command.
        
        Tool may be usefull to people who work on the same laptop at home, in the office (different external displays and different screen setup) and on the go (no external display).
        
        Currently randrctl can
        * handle *mode*, *position*, *rotation*, *panning* and *rate*
        * dump current screen setup to a profile
        * automatically (via udev) or manually switch between stored profiles
        * list all available profiles and show profile details
        * run custom commands before/after the switch or when it fails for some reason
        
        Usage is very simple:
        
        1. Setup your screen to suit your needs and dump settings to use them later
        
          ```randrctl dump home```
        
        2. After this you can reapply these settings whenever you need them
        
          ```randrctl switch-to home```
        
        3. ... or let randrctl to guess your settings automatically
        
          ```randrctl auto```
          
        4. You can list all available profiles
        
          ```randrctl list```
          
        5. And if you are interested in some particular profile
        
          ```randrctl show home```
        
        
        Profile format
        --------------
        
        Simple text file in JSON format, can be edited manually. All values are case-sensitive, white-spaces don't matter.
        
        ```
        {
          "match": {
            "LVDS1": {},
            "DP1": {
                "prefers": "1920x1080"
            }
          },
          "outputs": {
            "LVDS1": {
              "mode": "1366x768",
              "panning": "1366x1080
            },
            "DP1": {
              "mode": "1920x1080",
              "pos": "1366x0",
              "rotate": "inverted"
            }
          },
          "primary": "DP1"
        }
        ```
        
        Profile should contain 2 sections (```outputs``` and ```primary```) for manual switching. The ```match``` section is optional and is used for auto-switching.
        
        
        ### Outputs
        
        Each property of ```outputs``` section references output as seen in xrandr (i.e. *DP1*, *HDMI2*, etc.). Each output must contain ```mode``` property. Here is a list of output properties:
        
        * ```mode``` — output resolution. Value example: *"1920x1080"*
        
        * ```pos``` — output position. Value example: *"312x0"*
        
        * ```panning``` — output panning (it's fun http://crunchbang.org/forums/viewtopic.php?id=20634). Value example: *"1366x1080"*
        
        * ```rotate``` — output rotation. Possible values: *"normal"*, *"left"*, *"right"*, *"inverted"*
        
        * ```rate``` — output refresh rate. Optional field. If omitted xrandr will chose the best suitable rate. Values example: *60*
        
        
        ### Primary
        
        Just name of the primary output.
        
        
        ### Match
        
        See [auto-switching](auto) section.
        
        
        Auto-switching<a name="auto"></a>
        ---------------------------------------
        
        ```randrctl``` is able to associate profiles with your hardware configuration and switch between them automatically. To do so, ```match``` section should be declared in profile. As in ```outputs``` section, properties of this section are names of outputs to match.
        
        Profile is considered for matching if and only if all stated outputs are currently connected.
        
        Example:
        
        ```
        "match": {
          "LVDS1": {},
          "DP1": {}
        }
        ```
        This profile will be considered if *DP1* and *LVDS1* are connected. It won't be if *HDMI1* is additionally connected at the same time.
        
        Also each stated output can be matched by supported ```supports``` or preferred ```prefers``` modes or by connected display ```edid```.
        
        ```supports``` matches display if it supports specified mode.
        
        Example:
        
        ```
        "match": {
          "DP1": {
            "supports": "1920x1080"
          }
        }
        ```
        
        ```prefers``` matches display if its preferred mode (usually the most advanced one) matches
        
        Example:
        
        ```
        "match": {
          "DP1": {
            "prefers": "1920x1080"
          }
        }
        ```
        The examples above will match any display on *DP1* port that supports (in the first case) or prefers *1920x1080* resolution. This, for example, may be very useful if you want to create profile that is activated whenever full-HD display is connected to *HDMI* port of your laptop:
        
        ```
        {
          "match": {
            "LVDS1": {},
            "HDMI1": {
              "mode": "1920x1080"
            }
          },
          "outputs": {
            "LVDS1": {
              ...
            },
            "HDMI1": {
              ...
            }
          }
        }
        ```
        
        ```edid``` matching will look for specific display identified by edid.
        
        Example:
        
        ```
        "match": {
          "DP1": {
            "edid": "d8578edf8458ce06fbc5bb76a58c5ca4",
          }
        }
        ```
        will match display whichs EDID md5-sum is equal to the specified one (to generate profile with proper edid value use ```randrctl dump```)
        
        
        ### Order of matching
        
        The most specific profile is chosen among all that matched. So *edid* > *prefers* > *supports*. Naturally, *edid* is more specific than preferred or supported mode.
        
        
        Prior/Post hooks
        ------------------
        
        Some window managers (i.e. i3) are known to crash when screen setup is changed. Common workaround for this is:
        
        ```
        killall -SIGSTOP i3
        xrandr ...
        killall -SIGCONT i3
        ```
        
        randrctl handles this by allowing to declare hooks to be executed before and after call to xrandr. This is also useful if you want to show desktop notification on profile switch or failure. Declare them all in /etc/randrctl/config.ini
        
        ```
        [hooks]
        prior_switch = /usr/bin/killall -SIGSTOP i3
        post_switch = /usr/bin/killall -SIGCONT i3 && /usr/bin/notify-send -u low "randrctl" "switched to $randr_profile"
        post_fail = /usr/bin/killall -SIGCONT i3 && /usr/bin/notify-send -u critical "randrctl error" "$randr_error"
        ```
        
        
        Installation
        ------------
        
        
        ###Archlinux
        There is AUR package https://aur.archlinux.org/packages/randrctl-git/
        
        
        ###PyPi
        ```
        # pip install randrctl
        # randrctl-setup
        ```
        
        
        ###Manual from sources
        
        ```
        $ git clone https://github.com/edio/randrctl.git
        $ cd randrctl
        $ cp -r etc/randrctl ~/.config
        # python setup.py install
        # randrct-setup
        ```
        
        
        Feedback/contribution
        ---------------------
        
        This is my very first python project. Comments regarding code quality and suggestions are welcome. 
        
        
        License
        -------
        GPLv3
        
Platform: linux
