awesome/awesomerc.5.txt

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

NAME
----

awesomerc - Configuration file for the 'awesome window manager'

SYNOPSIS
--------

<item> [<argument>]
{
    <option> = <value>

    <item> [<argument>] { <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 4 global sections: *screen*, *rules*, *keys* and *mouse* which
are described here.

screen
~~~~~~
This is the global section for a physical screen. It must have a title with screen number,
starting at 0. It contains several subsections, which are *general*, *tags*, *layouts*, *colors*,
*padding* and *statusbar*.

general
^^^^^^^
General is a section containing some general options for this screen.

border::
    This defines the window borders size in pixel.
font::
    This defines the general font used in awesome.
new_become_master::
    If this is set to true, new windows will become the master window.
new_get_focus::
    If this is set to true, new windows will get focus.
opacity_unfocused::
    If this is set to true, non-focused windows will have this opacity.
    This requires an external XComposite manager.
resize_hints::
    If this is set to true, resize hints given by the window will be respected.
    If this is set to false, window size will be forced.
    If you dislike gaps between windows, you should try to set it to false.
sloppy_focus::
    If this is set to true, focus will be set to the window under the mouse. If not,
    you will have to click on a window to set it focused.
sloppy_focus_raise::
    If this is set to true with sloppy_focus, when a window is focused with the mouse
    it will be raised on top of the windows stack.
snap::
    Snap windows to the screen border when it is this pixel away only from the border.
floating_placement::
    Select the floating placement algorithm to use when placing window.
    
tags
^^^^
Tags is a section containing one or more tag sections, which defines a tag.

tag
+++
Tag is a section which contains several options defining a tag.

layout::
    Layout is a name of an available layout which will be set by default on this tag.
mwfact::
    Set the default master width factor for this tag.
ncol::
    Set the default number of columns for non-master windows for this tag.
nmaster::
    Set the default number of windows which will be treated as master for this tag.

layouts
^^^^^^^
Layouts is a section containing a layout list, where each layout is a layout section.

layout
++++++
Layout is a section which define a layout. It has a title which is the algorithm to use.

image::
    Set the image path used to describe this layouts, useful in layoutinfo widget.

colors
^^^^^^
Colors is a section containing the colors parameters which is composed of a normal, focus and urgent
subsection each ones containing:

fg::
    Set the foreground color.
bg::
    Set the background color.
border::
    Set the window's border color.
shadow::
    Set the shadow color.
shadow_offset::
    Set the shadow offset in pixel.

padding
^^^^^^^
Padding is a section containing screen padding parameters.

top::
    Set the top padding in pixel.
bottom::
    Set the bottom padding in pixel.
left::
    Set the left padding in pixel.
right::
    Set the right padding in pixel.

statusbar
^^^^^^^^^
Statusbar are sections containing statusbars parameters. Each statusbar section
must have a title which is the statusbar name. Each statusbar can have none or
several widgets (see WIDGETS section for more details) each one identified by its
name.

position::
    Default statusbar position.
height::
    Statusbar height. By default, is auto computed with font size.
width::
    Statusbar width. By default, it will be whole screen.

rules
~~~~~
Rules is a section containing a rule list to automatically configure windows.

rule
^^^^
Rule are sections containing the auto-configuration options for one window.

name::
    Set the window name for name matching as a regular expression.
xproperty_name::
    Set the name of the XProperty for XProperty matching.
xproperty_value::
    Set the regular expression to match against the named XProperty's value.
float::
    Set the window to be floating. One of auto, true or false. Defaults to auto.
master::
    Set the window to be the master. One of auto, true or false. Defaults to
    auto.
tags::
    Set the tags to be assigned to the window as a regular expression.
screen::
    Set the screen the window should show up on.
icon::
    Set the window's icon.
opacity::
    Set the window's opacity.

keys
~~~~
Keys is the section to define your keybindings in. It may consist of multiple
key and keylist entries.

key
^^^
In a key section you define a single keybinding.

key::
    The keysym you want to bind.
mod::
    Modifiers that need to be pressed for this binding.
command::
    The *uicb function* to call.
arg::
    The argument to the *uicb function*, if needed.

keylist
^^^^^^^
In a keylist you can define multiple very similar keybindings at once. For
example you can define <Mod1>-{1..9} to switch the view to tag 1..9
respectively.

keylist::
    The list of keysyms to bind.
modkey::
    Modifiers that need to be pressed for these bindings.
command::
    The *uicb function* to call.
arglist::
    The list of arguments to the *uicb function*, if needed. *Must* match the
    length of *keylist*.

mouse
~~~~~
In the mouse section you may define mouse button bindings for the root and
client windows.

client
^^^^^^
Defines a mouse button binding for events on clients.

button::
    The mouse button you want to bind.
modkey::
    Modifiers that need to be pressed for this binding.
command::
    The *uicb function* to call.
arg::
    The argument to the *uicb function*, if needed.

root
^^^^
Defines a mouse button binding for events on the root window.

button::
    The mouse button you want to bind.
modkey::
    Modifiers that need to be pressed for this binding.
command::
    The *uicb function* to call.
arg::
    The argument to the *uicb function*, if needed.

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.

General
~~~~~~~
*quit*::
    This function quits awesome.
*statusbar_toggle* statusbar-identifier::
    Hide or show statusbar (with no argument, toggle all).
*spawn* client::
    Execute an external program.
*exec* program::
    Replace awesome with another window manager (or itself; i.e. reload config).
*widget_tell* widget-identifier data::
    Feed information to your widgets.

Client
~~~~~~
*client_kill*::
    Closes the focused client.
*client_moveresize* x y width height::
    Dynamically move and resize floating windows.
    Coordinates can be relative or absolute. Relative values must begin with + or -.
    E.g: to move a window 10 pixels up: "+0 \+10 +0 +0" To move a window
    in the upper left corner and increase its width by 10px: "0 0 \+0 +10"
*client_settrans* float::
    Set client transparency, number can be a relative or absolute floating number in percentage.
*client_swapnext*::
    Swap window placement with the next displayed window.
*client_swapprev*::
    Swap window placement with the previous displayed window.
*client_focusnext*::
    Focus next window.
*client_focusprev*::
    Focus previous window.
*client_togglemax*::
    Set window fullscreen. Calling this function another time will reset the window to its previous state.
*client_togglehorizontalmax*::
    Set window's horizontal size to display width. Calling another time will reset the window to its previous state.
*client_toggleverticalmax*::
    Set window's vertical size to display height. Calling another time will reset the window to its previous state.
*client_togglefloating*::
    Set window floating or tiled.
*client_zoom*::
    Set window as master window.
*client_movetoscreen* relative or absolute integer::
    Move focused window to the nth screen, or next (+1) or previous (-1). If no screen_number is set, move to the next screen.
*client_tag* tag number::
    Tag focused window with this tag.
*client_toggletag*::
    Add or remove tag to focused window.
*client_movemouse*::
    Move client window with mouse.
*client_resizemouse*::
    Resize client window with mouse.
*client_setscratch*::
    Set or unset client as being the scratch window.
*client_togglescratch*::
    Toggle scratch window.

Tag
~~~
*tag_setlayout* relative or absolute integer::
    Set layout number; or just switch to the next layout for current tag.
*tag_toggleview* tag::
    Add windows tagged with tag number to current display.
*tag_view* tag number::
    View windows tagged with tag number.
*tag_viewnext*::
    Show windows tagged with next tag in list.
*tag_viewprev*::
    Show windows tagged with previous tag in list.
*tag_prev_selected*::
    Switch back to the previously displayed set of tags.
*tag_setmwfact* relative or absolute float::
    Set master width factor.
*tag_setncol* relative or absolute integer::
    Set number of columns for non-master windows.
*tag_setnmaster* relative or absolute integer::
    Set number of master windows.
*tag_create* name::
    Create a new tag with that name.

Focus
~~~~~
*focus_client_byname* string::
    Give client focus by its name.
*focus_history* negative number::
    Focus the client that had focused nth focus switch earlier.

Screen
~~~~~~
*screen_focus* relative or absolute integer::
    Select Screen and focus first window and move mouse.

WIDGETS
-------
Statusbars can be customized by modifying widgets names, order and options.

taglist
~~~~~~~
This widget shows the tag list.

*mouse*::
    Set mouse bindings.
*x*::
    Horizontal offset (auto-alignment if not set).
*y*::
    Vertical offset (auto-alignment if not set).
*align*::
    Widget alignment.

layoutinfo
~~~~~~~~~~
This widget shows a icon for the selected layout.

*mouse*::
    Set mouse bindings.
*x*::
    Horizontal offset (auto-alignment if not set).
*y*::
    Vertical offset (auto-alignment if not set).
*align*::
    Widget alignment.

focusicon
~~~~~~~~~
This widget shows a icon for the focused window  using NET_WM_ICON or icon file set in rule.

*mouse*::
    Set mouse bindings.
*x*::
    Horizontal offset (auto-alignment if not set).
*y*::
    Vertical offset (auto-alignment if not set).
*align*::
    Widget alignment.

tasklist
~~~~~~~~
This widget shows a list of running windows.

*mouse*::
    Set mouse bindings.
*font*::
    Font to use.
*bg*::
    Background color.
*colors*::
    Colors section with a focus and normal subsection.
*text_align*::
    Text alignement.
*show_icons*::
    Show applications icons.
*show*::
    Show all windows from all tags, tags clients only or focused client.
*x*::
    Horizontal offset (auto-alignment if not set).
*y*::
    Vertical offset (auto-alignment if not set).

textbox
~~~~~~~
This widget shows a text.

*mouse*::
    Set mouse bindings.
*font*::
    Font to use.
*width*::
    Set width.
*colors*::
    Colors section with a focus and normal subsection.
*text*::
    Text to change.
*text_align*::
    Text alignement.
*x*::
    Horizontal offset (auto-alignment if not set).
*y*::
    Vertical offset (auto-alignment if not set).
*align*::
    Widget alignment.

iconbox
~~~~~~~
This widget shows an icon.

*mouse*::
    Set mouse bindings.
*image*::
    Image file.
*resize*::
    Resize icon to fit into statusbar.
*x*::
    Horizontal offset (auto-alignment if not set).
*y*::
    Vertical offset (auto-alignment if not set).
*align*::
    Widget alignment.

progressbar
~~~~~~~~~~~
This widget shows one or more progress-bars.

*data*::
    Draws a bar for each data section;
    Options: reverse, fg, fg_center, fg_end, bg, bordercolor.
*reverse*::
    Reverse/mirror the bar.
*fg*::
    Foreground color.
*fg_center*::
    Foreground color in the center of the bar (as gradient).
*fg_end*::
    Foreground color at the end of a bar (as gradient).
*bg*::
    Background color.
*bordercolor*::
    Border color.
*mouse*::
    Set mouse bindings.
*width*::
    Set width.
*height*::
    Set height (i.e. 0.9 = 90%)
*padding*::
    Empty space on both sides.
*vertical*::
    Draw the bar(s) vertically/standing up.
*x*::
    Horizontal offset (auto-alignment if not set).
*y*::
    Vertical offset (auto-alignment if not set).
*align*::
    Widget alignment.

graph
~~~~~
This widget shows a graph.

*data*::
    Defines a data-stream section;
    Options: max, scale, fg, fg_center, fg_end and style.
*max*::
    This value prints a full graph (default = 100)
*scale*::
    Re-scales when input > max (see below).
*fg*::
    Foreground color.
*fg_center*::
    Foreground color in the center of the bar (as gradient).
*fg_end*::
    Foreground color at the end of a bar (as gradient).
*vertical_gradient*
    If true, create a gradient from 0 > full instead of new > old values
*style*::
    bottom (fills to bottom with fg), top, or line.
*mouse*::
    Set mouse bindings.
*width*::
    Set width.
*height*::
    Set height (i.e. 0.9 = 90%)
*padding_left*::
    Empty space on the left.
*bg*::
    Background color.
*bordercolor*::
    Border color.
*x*::
    Horizontal offset (auto-alignment if not set).
*y*::
    Vertical offset (auto-alignment if not set).
*align*::
    Widget alignment.

FORMAT
------
Here is the global configuration file format, with a list of options
and possible values.

..............................................
Note: when there is no whitespace, quotes are optional.

<boolean>       -> "true" or "false"
<color>         -> #ff9933 (hexadecimal color notation: #red green blue)
<float>         -> 0.3, 0,8 (often values between 0 and 1 are useful)
<font>          -> Xft font: mono-10, fixed-12, sans-8, ...
<identifier>    -> foobar (choose a name/string)
<image>         -> "/home/awesome/pics/icon.png" (path to image)
<integer>       -> 1, 10, -3 (positive numbers are required mostly)
<key>           -> a, 1, F10 (see /usr/include/X11/keysymdef.h w/o XK_ or 'xev')
                   or a keycode beginning with #
<mod>           -> "Mod1", "Mod4", "Control" (modifiers)
<regex>         -> regular expression
<string>        -> "foo bar"
<uicb-arg>      -> prog, 3... (argument to a uicb function, where required)
<uicb-cmd>      -> spawn, exec, client_tag... (see UICB FUNCTIONS above)
<{.., ...}>     -> list of available options
<color section> -> a section with fg, bg, border, shadow and shadow_offset options.

[MULTI] means, you can use an item multiple times.


screen <integer> [MULTI]
{
    general
    {
        border = <integer>
        font = <font>
        new_become_master = <boolean>
        new_get_focus = <boolean>
        opacity_unfocused = <integer>
        resize_hints = <boolean>
        sloppy_focus = <boolean>
        sloppy_focus_raise = <boolean>
        snap = <integer>
        floating_placement = <{smart,under_mouse}>
        mwfact_lower_limit = <float>
        mwfact_upper_limit = <float>
    }
    tags
    {
        tag <identifier> [MULTI]
        {
            layout = <{dwindle,floating,max,
                     spiral,tile,tileleft,tilebottom,tiletop}>
            mwfact = <float>
            nmaster = <integer>
            ncol = <integer>
        }
    }
    layouts
    {
        layout <{dwindle,floating,max,
                 spiral,tile,tileleft,
		 tilebottom,tiletop}> { image = <image> } [MULTI]
    }
    colors
    {
        normal { <color section> }
        focus { <color section> }
        urgent { <color section> }
    }
    padding
    {
        top = <integer>
        bottom = <integer>
        left = <integer>
        right = <integer>
    }
    statusbar <identifier> [MULTI]
    {
        position = <{top,bottom,left,right}>
        height = <integer>
        width = <integer>

        taglist <identifier> [MULTI]
        {
            x = <integer> y = <integer>
            align = <{auto,right,left}>
            mouse [MULTI]
            {
                button = <integer> modkey = {<mod>, ...}
                command = <uicb-cmd> arg = <uicb-arg>
            }
        }
        layoutinfo <identifier>
        {
            x = <integer> y = <integer>
            align = <{auto,right,left}>
            mouse [MULTI]
            {
                button = <integer> modkey = {<mod>, ...}
                command = <uicb-cmd> arg = <uicb-arg>
            }
        }
        focusicon <identifier>
        {
            x = <integer> y = <integer>
            align = <{auto,right,left}>
            mouse [MULTI]
            {
                button = <integer> modkey = {<mod>, ...}
                command = <uicb-cmd> arg = <uicb-arg>
            }
        }
        tasklist <identifier>
        {
            colors
            {
                normal { <color section> }
                focus { <color section> }
            }
            font = <font>
            show_icons = <boolean>
            show = <{all,tags,focus}>
            text_align = <{center,left,right}>
            x = <integer> y = <integer>
            mouse [MULTI]
            {
                command = <uicb-cmd> arg = <uicb-arg>
                button = <integer> modkey = {<mod>, ...}
            }
        }
        textbox <identifier> [MULTI]
        {
            text = <string>
            bg = <color>
            fg = <color>
            font = <font>
            width = <integer>
            text_align = <{center,left,right}>
            x = <integer> y = <integer>
            align = <{auto,right,left}>
            mouse [MULTI]
            {
                button = <integer> modkey = {<mod>, ...}
                command = <uicb-cmd> arg = <uicb-arg>
            }
        }
        iconbox <identifier> [MULTI]
        {
            image = <image>
            resize = <boolean>
            x = <integer> y = <integer>
            align = <{auto,right,left}>
            mouse [MULTI]
            {
                button = <integer> modkey = {<mod>, ...}
                command = <uicb-cmd> arg = <uicb-arg>
            }
        }
        progressbar <identifier> [MULTI]
        {
            data [MULTI]
            {
                reverse = <boolean> bg = <color> bordercolor = <color>
                fg = <color> fg_center = <color> fg_end = <color>
            }
            gap = <integer>
            width = <integer>
            height = <float>
            padding = <integer>
            vertical = <boolean>
            x = <integer> y = <integer>
            align = <{auto,right,left}>
            mouse [MULTI]
            {
                button = <integer> modkey = {<mod>, ...}
                command = <uicb-cmd> arg = <uicb-arg>
            }
        }
        graph <identifier> [MULTI]
        {
            data [MULTI]
            {
                scale = <boolean> max = <float> style = <{bottom, top, line}>
                fg = <color> fg_center = <color> fg_end = <color>
                vertical_gradient = <boolean>
            }
            width = <integer>
            height = <float>
            padding_left = <integer>
            bg = <color>
            bordercolor = <color>
            x = <integer> y = <integer>
            align = <{auto,right,left}>
            mouse [MULTI]
            {
                button = <integer> modkey = {<mod>, ...}
                command = <uicb-cmd> arg = <uicb-arg>
            }
        }
    }
}
rules
{
    rule [MULTI]
    {
        name = <regex>
        xproperty_name = <string>
        xproperty_value = <regex>
        float = <{auto,true,false}>
        master = <{auto,true,false}>
        tags = <regex>
        screen = <integer>
        icon = <image>
        opacity = <float>
    }
}
keys
{
    key [MULTI]
    {
        key = <key> modkey = {<mod>, ...}
        command = <uicb-cmd> arg = <uicb-arg>
    }
    keylist [MULTI]
    {
        keylist = {<key>, ...}
        modkey = {<mod>, ...}
        command = <uicb-cmd>
        arglist = {<uicb-arg>, ...}
    }
}
mouse
{
    client [MULTI]
    {
        button = <integer> modkey = {<mod>, ...}
        command = <uicb-cmd> arg = <uicb-arg>
    }
    root [MULTI]
    {
        button = <integer> modkey = {<mod>, ...}
        command = <uicb-cmd> arg = <uicb-arg>
    }
}
..............................................

EXAMPLES
--------

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


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