awesome/awesomerc.5.txt

awesomerc(5)
===========

NAME
----

awesomerc - Configuration file for the 'awesome window manager'

SYNOPSIS
--------
..........................
<section> [title]
{
    <option> = <value>

    <section> [title]
    {
        <option> = <value>
         ...
    }
    ...
}

<option> = <value>

include(file.conf)
..........................

DESCRIPTION
-----------

The *awesomerc* file contains configuration informations for *awesome*. It can
be used to configure the behaviour and look of awesome in a variety of ways.

It is read at startup.

OPTIONS
--------
*awesomerc* contains 5 global sections: *screen*, *rules*, *keys*, *mouse* and *menu* which
are described here.

All these sections contain options which may be strings, integers, floats, or
even sections again.

include::optsdocgen.txt[]

UICB FUNCTIONS
--------------

In awesome, a lot of *functions* are available. These functions are called
uicb (User Interface Call Backs). Each function can be bound to a key shortcut
or a mouse button.

include::uicbdocgen.txt[]

EXAMPLES
--------

More examples are available on awesome's wiki:
http://awesome.naquadah.org/wiki/

Simple textbox example
~~~~~~~~~~~~~~~~~~~~~~
..............................................
1. Add an include directive into ~/.awesomerc

    screen 0 { include(~/.awesome/bottom-status-bar) }

2. Create ~/.awesome/bottom-status-bar

    statusbar "bottom"
    {
        position = "bottom"
        textbox "clock" { }
    }

3. Check the configuration file for errors

    $ awesome -k
    Configuration file OK.

    Note: If you see anything other than "Configuration file OK." you have a
    typo somewhere.

4. Create ~/bin/awesome-clock

    #!/bin/sh
    while true
    do
        # if you start this from .xinitrc, the script will start before
        # awesome, and will fail.
        if [ -S ~/.awesome_ctl.0 ]; then
            while true
            do
              echo "0 widget_tell bottom clock text `date`"
              echo "" # an empty line flushes data inside awesome
              sleep 1
            done | awesome-client
        else
            sleep 1
        fi
    done

    Note: What we are saying is "awesome-client, tell the bottom status bar's
    widget named 'clock' to set it's 'text' property to date's output".

5. Make your ~/bin/awesome-clock executable

   $ chmod a+x ~/bin/awesome-clock

6. Modify ~/.xinitrc

    ~/bin/awesome-clock &
    exec awesome

7. Restart awesome

8. If you did not get what you were expecting, take a look at
   ~/.xsession-errors or the terminal where X got started.
..............................................

Simple progressbar example
~~~~~~~~~~~~~~~~~~~~~~~~~~
..............................................

1. Add an include directive into ~/.awesomerc

    screen 0 { include(~/.awesome/bottom-status-bar) }

2. Create ~/.awesome/bottom-status-bar

    statusbar "bottom"
    {
        position = "bottom"
        progressbar "diskusage"
        {
            data "disk"
            {
                bordercolor = "#006e96"
                bg          = "#000000"
                fg          = "#ff0000"
                fg_center   = "#daaf0a"
                fg_end      = "#00ff00"
            }
            width = 100
            align = "left"
        }
    }

3. Check the configuration file for errors

    $ awesome -k
    Configuration file OK.

    Note: If you see anything other than "Configuration file OK," you have a
    typo somewhere.

4. Create ~/bin/awesome-diskusage

    #!/bin/sh
    while true
    do
        # if you start this from .xinitrc, the script will start before
        # awesome, and will fail.
        if [ -S ~/.awesome_ctl.0 ]; then
            while true; do
                usage = `df /dev/sda5 | awk '/\/dev\/sda5/ { print 100-$5 }'`
                echo "0 widget_tell bottom diskusage data disk ${usage}"
                echo "" # an empty line flushes data inside awesome
                sleep 600;
            done | awesome-client
        else
            sleep 1
        fi
    done


    Note: What we are saying is "awesome-client, tell the bottom status bar's
    widget named 'diskusage' to set it's 'data' property named 'disk' to
    ${usage}."

5. Make ~/bin/awesome-diskusage executable

$ chmod a+x ~/bin/awesome-diskusage

6. Modify ~/.xinitrc

    ~/bin/awesome-diskusage &
    exec awesome

7. Restart awesome

8. If you did not get what you were expecting, take a look at
   ~/.xsession-errors or the terminal where X got started.
..............................................

AWESOMERC SKELETON
------------------
The following skeleton lists all available configuration options in *awesomerc*.

..........................
include::rcskeletongen.txt[]
..........................

SEE ALSO
--------
awesome(1) awesome-client(1) awesome-menu(1) awesome-message(1)

AUTHORS
-------
This man page was written by Julien Danjou <julien@danjou.info>, Marco Candrian <mac@calmar.ws>
and Chris Ciulla <chris.ciulla@gmail.com> (Simple Examples).

WWW
---
http://awesome.naquadah.org