awesome/awesomerc.1.txt

awesomerc(1)
===========

NAME
----

awesomerc - Configuration file for the 'awesome window manager'

SYNOPSIS
--------

*awesome* reads *$HOME/.awesomerc* by default. You can choose another configuration
file with: awesome -c configuration

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).
*statusbar_set_position* top, bottom, left, right::
    Set the position of the statusbar.
*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_viewperv*::
    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.

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

FILES
-----
For an example of an awesomerc file, see the file provided with the sources.

EXAMPLES
--------

The general config and subconfig options for the awesomerc:

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


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