==========================
ARandR: Another XRandR GUI
==========================


ARandR is designed to provide a simple visual front end for XRandR_. Relative monitor positions are shown graphically and can be changed in a drag-and-drop way.



Features
--------

* Full control over output positioning (instead of plain "left of") with edge snapping
* Saving configurations as executable shell scripts (configurations can be loaded without using this program)
* Configuration files can be edited to include additional payload (like xsetwacom_ commands tablet PC users need when rotating), which is preserved when editing
* Metacity key binding integration:
    * Saved configurations can be bound to arbitrary keys via metacity's custom commands.
    * Several layouts can be bound to one key; they are cycled through. (Useful for "rotate" buttons on tablet PCs.)
* Main widget separated from packaged application (to facilitate integration with existing solutions)



Installation
------------

* Using your distribution's installer:

    * Debian_ / Ubuntu_::

        aptitude install arandr

    * archlinux_::

        pacman -S arandr

    * Slackware using a `slackbuild by PhantomX`_::

        wget http://cloud.github.com/downloads/PhantomX/slackbuilds/arandr-0.1.4.tar.bz2
        tar xjf arandr-0.1.4.tar.bz2
        cd arandr
        ./arandr.SlackBuild 2>&1 | tee build.log

    * Gentoo_::

        emerge arandr

    * Fedora_::

        yum install arandr

* From source:

    * Fetch either

        * the `latest release`_::

            wget http://christian.amsuess.com/tools/arandr/files/arandr-0.1.7.1.tar.gz
            tar xzf arandr-0.1.7.1.tar.gz
            cd arandr-0.1.7.1

        * or get it directly from GIT (`hosted on gitorious`_)::

            git clone git://gitorious.org/arandr/arandr.git
            cd arandr

    * and start it using::

        ./arandr

    * or install it::

        sudo ./setup.py install



Dependencies
------------

 * python_
 * PyGTK_
 * xrandr_
 * docutils_ (>=0.6; for building the man page)



Bugs / Caveats
--------------

 * Changes while running are not caught.
 * Versions before 0.1.7 depended on all modes to have a <width>x<height> name (see `debian bug #507521`_); if ARandR does not start up, please install the latest version. (On different bugtrackers, this is called the ValueError / "1080p" / "1024x768i" problem).
 * See TODO_ for planned features.


Similar projects
----------------

A number of other programs exist that cover similar functionality, often
bundled with a particular desktop environment. Those I know of are, in
alphabetical order:

* Gnome's ``gnome-control-center display``, notable for its ``~/.config/monitors.xml`` `persistence <https://live.gnome.org/RandR#Storage_of_RANDR_configurations>`_
* `grandr <ftp://ftp.freedesktop.org/pub/individual/app/>`_
* `grandr-applet <http://dekorte.homeip.net/download/grandr-applet/>`_ (which seems not to be related to grandr)
* KDE's RandR tool ``krandrtray``, notable for being the only listed program to be Qt based
* LXDE's `LXRandR <http://wiki.lxde.org/en/LXRandR>`_, notable for storing configuration in ``~/.config/autostart/lxrandr-autostart``
* LXQt's `lxqt-config-monitor <https://github.com/lxde/lxqt-config`_, for lxqt based on Qt5.
* `urandr <http://www.albertomilone.com/urandr.html>`_
* `zarfy <http://sourceforge.net/projects/zarfy/>`_, notable for its nice use of a current screenshot
* cglita wrote a patch that solved the ValueError / "1080p" problem. His patches went a little further and include more precise mode line selection; I keep it around, and you can try it like this::

    git clone git://gitorious.org/arandr/arandr.git -b cglita
    cd arandr
    ./arandr



Contributing
------------

If you are fluent with languages not yet supported, you can add translations to ARandR using gettext_. An easy way to do this is `ARandR's page on hosted Weblate`_. (Transifex and Launchpad translations were discontinued for lack of SCM integration and associated problems with attributing contributions).

Please send bug reports, suggestions, patches and git pull requests to me_.


About
-----

Copyright © chrysn_ <chrysn@fsfe.org> 2008–2013, Себастьян Gli ţa Κατινα 2011, published under GPLv3_ or any later version.

Inspired by the `dual head sketch`_ in the ThinkWiki_.

Translations by

* Quizzlo (Italian)
* Phantom X (Brazilian)
* Joe Hansen (Danish)
* gundachandru (Kannada)
* HsH (Russian)
* Clément Démoulins, Bruno Patri (French)
* RooTer (Polish)
* Mohammad Alhargan, aboodilankaboot (Arabic)
* Mehmet Gülmen (Turkish)
* Ricardo A. Hermosilla Carrillo (Spanish)
* el_libre (Catalan)
* Carezero (Chinese)
* wimfeijen (Dutch)
* Себастьян Gli ţa Κατινα (Romanian)
* Slavko (Slovak)
* Alireza Savand (Persian)
* Belvar (Breton)
* Algimantas Margevičius (Lithuanian)
* Miguel Anxo Bouzada (Galician, Spanish)
* o-157 (Japanese)
* Ingemar Karlsson (Swedish)
* Semsudin Abdic (Bosnian)
* Rax Garfield (Ukrainian)
* Tamás Nagy (Hungarian)
* Mantas Kriaučiūnas (Lithuanian)
* Dimitris Giouroukis (Greek)
* ParkJS (Korean)
* chrysn (German, English)


 .. _XRandR: http://www.x.org/wiki/Projects/XRandR
 .. _xsetwacom: http://linuxwacom.sourceforge.net/index.php/howto/xsetwacom
 .. _TODO: ./TODO
 .. _`latest release`: http://christian.amsuess.com/tools/arandr/files/arandr-0.1.7.1.tar.gz
 .. _archlinux: http://www.archlinux.org/packages/community/any/arandr/
 .. _chrysn: http://christian.amsuess.com
 .. _GPLv3: http://www.gnu.org/licenses/gpl-3.0.txt
 .. _`dual head sketch`: http://www.thinkwiki.org/wiki/Image:Intel-DualHead.png
 .. _ThinkWiki: http://thinkwiki.org/
 .. _`hosted on gitorious`: http://gitorious.org/arandr/arandr
 .. _Debian: http://packages.debian.org/arandr
 .. _Ubuntu: http://packages.ubuntu.com/arandr
 .. _gettext: http://www.gnu.org/software/gettext/
 .. _`ARandR's page on hosted Weblate`: http://hosted.weblate.org/projects/arandr/translations/
 .. _me: mailto:chrysn@fsfe.org
 .. _python: http://www.python.org/
 .. _PyGTK: http://www.pygtk.org/
 .. _`slackbuild by PhantomX`: http://github.com/PhantomX/slackbuilds/tree/master/arandr/
 .. _Gentoo: http://packages.gentoo.org/package/x11-misc/arandr
 .. _Fedora: https://admin.fedoraproject.org/pkgdb/applications/Arandr
 .. _docutils: http://docutils.sourceforge.net/
 .. _`debian bug #507521`: http://bugs.debian.org/507521