AWESOMERC(1)

NAME
awesomerc - Configuration file for the 'awesome window manager'

SYNOPSIS
<item> [<argument>] { <option> = <value>
    <item> [<argument>] { <option> = <value>, ... }
    ....
}
<option> = <value>

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.

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.

  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_viewprev_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).

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

  netwmicon
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).

  focustitle
This widget shows the title of the focused window.

mouse
    Set mouse bindings.

font
    Font to use.

bg  Background color.

fg  Foreground color.

align
    Text alignement.

x   Horizontal offset (auto-alignment if not set).

y   Vertical offset (auto-alignment if not set).

  tasklist
This widget shows a list of running windows.

mouse
    Set mouse bindings.

font
    Font to use.

bg  Background color.

fg  Foreground color.

focus_bg
    Background color for focused window.

focus_fg
    Foreground color for focused window.

align
    Text alignement.

show_icons
    Show applications icons.

show_all
    Show all windows from all tags.

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.

bg  Background color.

fg  Foreground color.

width
    Set width.

text
    Text to change.

align
    Text alignement.

x   Horizontal offset (auto-alignment if not set).

y   Vertical offset (auto-alignment if not set).

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

  progressbar
This widget shows one or more progress-bars.

mouse
    Set mouse bindings.

width
    Set width.

height
    Set height (i.e. 0.9 = 90%)

padding_left
    Empty space on the left.

bar Draws a bar; Options: fg, bg, bordercolor.

fg  Foreground color.

bg  Background color.

bordercolor
    Border color.

x   Horizontal offset (auto-alignment if not set).

y   Vertical offset (auto-alignment if not set).

  graph
This widget shows a graph.

scale
    Re-scales when input > max (see below).

max This value prints a full graph.

mouse
    Set mouse bindings.

width
    Set width.

height
    Set height (i.e. 0.9 = 90%)

padding_left
    Empty space on the left.

fg  Foreground color.

bg  Background color.

bordercolor
    Border color.

x   Horizontal offset (auto-alignment if not set).

y   Vertical offset (auto-alignment if not set).

OPTIONS
Configuration 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')
<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
[MULTI] means, you can use an item multiple times.
screen <integer> [MULTI]
{
    general
    {
        allow_lower_floats = <boolean>
        border = <integer>
        focus_move_pointer = <boolean>
        font = <font>
        new_become_master = <boolean>
        new_get_focus = <boolean>
        opacity_unfocused = <integer>
        resize_hints = <boolean>
        sloppy_focus = <boolean>
        snap = <integer>
    }
    tags
    {
        tag <identifier> [MULTI]
        {
            layout = <{dwindle,floating,max,
                     spiral,tile,tileleft}>
            mwfact = <float>
            nmaster = <integer>
        }
    }
    layouts
    {
        layout <{dwindle,floating,max,
                 spiral,tile,tileleft}> { image = <image> } [MULTI]
    }
    colors
    {
        tab_border = <color>
        normal_fg = <color>
        normal_bg = <color>
        normal_border = <color>
        focus_fg = <color>
        focus_bg = <color>
        focus_border = <color>
        urgent_fg = <color>
        urgent_bg = <color>
    }
    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>
            mouse [MULTI]
            {
                button = <integer> modkey = {<mod>, ...}
                command = <uicb-cmd> arg = <uicb-arg>
            }
        }
        layoutinfo <identifier>
        {
            x = <integer> y = <integer>
            mouse [MULTI]
            {
                button = <integer> modkey = {<mod>, ...}
                command = <uicb-cmd> arg = <uicb-arg>
            }
        }
        netwmicon <identifier>
        {
            x = <integer> y = <integer>
            mouse [MULTI]
            {
                button = <integer> modkey = {<mod>, ...}
                command = <uicb-cmd> arg = <uicb-arg>
            }
        }
        focustitle <identifier>
        {
            fg = <color>
            bg = <color>
            font = <font>
            align = <{center,left,right}>
            x = <integer> y = <integer>
            mouse [MULTI]
            {
                button = <integer> modkey = {<mod>, ...}
                command = <uicb-cmd> arg = <uicb-arg>
            }
        }
        tasklist <identifier>
        {
            fg = <color>
            bg = <color>
            focus_fg = <color>
            focus_bg = <color>
            font = <font>
            show_icons = <boolean>
            show_all = <boolean>
            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>
            align = <{center,left,right}>
            x = <integer> y = <integer>
            mouse [MULTI]
            {
                button = <integer> modkey = {<mod>, ...}
                command = <uicb-cmd> arg = <uicb-arg>
            }
        }
        iconbox <identifier> [MULTI]
        {
            image = <image>
            resize = <boolean>
            x = <integer> y = <integer>
            mouse [MULTI]
            {
                button = <integer> modkey = {<mod>, ...}
                command = <uicb-cmd> arg = <uicb-arg>
            }
        }
        progressbar <identifier> [MULTI]
        {
            bar { fg = <color> bg = <color> bordercolor = <color> } [MULTI]
            gap = <integer>
            width = <integer>
            height = <float>
            padding_left = <integer>
            x = <integer> y = <integer>
            mouse [MULTI]
            {
                button = <integer> modkey = {<mod>, ...}
                command = <uicb-cmd> arg = <uicb-arg>
            }
        }
        graph <identifier> [MULTI]
        {
            scale = <boolean>
            max = <float>
            width = <integer>
            height = <float>
            padding_left = <integer>
            fg = <color>
            bg = <color>
            bordercolor = <color>
            x = <integer> y = <integer>
            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}>
        tags = <regex>
        screen = <integer>
        icon = <image>
        not_master = <boolean>
    }
}
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/

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

AUTHORS
This man page was written by Julien Danjou <julien@danjou.info> and Marco Candrian <mac@calmar.ws>.

WWW
http://awesome.naquadah.org