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 this sections contain options which may be string, integer, float, 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
      echo "0 widget_tell clock text `date`"
      echo "" # an empty line flushes data inside awesome
      sleep 1
    done | awesome-client

    Note: What we're saying is "awesome-client, tell widget '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 your didn't 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

    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
        usage = `df /dev/sda5 | awk '/\/dev\/sda5/ { print 100-$5 }'`
        echo "0 widget_tell diskusage data disk ${usage}"
        echo "" # an empty line flushes data inside awesome
        sleep 600;
    done | awesome-client


    Note: What we're saying is "awesome-client, tell widget '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 your didn't get what you were expecting, take a look at
   ~/.xsession-errors or the terminal where X got started.
..............................................


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