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*::
    Hide or show statusbar.
*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.
*setborder* relative or absolute integer::
    Set default border size in pixels for new clients.

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

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

*mouse*::
    Set mouse bindings.

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

*mouse*::
    Set mouse bindings.

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

*mouse*::
    Set mouse bindings.

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.

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.

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.

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

*mouse*::
    Set mouse bindings.
*image*::
    Image file.
*resize*::
    Resize icon to fit into statusbar.

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

*mouse*::
    Set mouse bindings.
*width*::
    Set width.
*bar*::
    Draws a bar; Options: fg, bg, bcolor
*fg*::
    Foreground color.
*bg*::
    Background color.
*bcolor*::
    Border color.

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 are no whitespaces, quotes are optional.

<color>         -> #ff9933 (hexadecimal color notation: #red green blue)
<float>         -> 0.3, 0,8 (often values between 0 and 1 are useful)
<identifier>    -> foobar (choose a free name/string)
<image>         -> "/home/awesome/pics/icon.png" (path to image)
<integer>       -> 1, 10, -3 (positive numbers are required mostly)
<key>           -> a, 1, F10 (/usr/include/X11/keysymdef.h w/o XK_, 'xev')
<mod>           -> mod1, mod2,..., mod5
<uicb-cmd>      -> spawn, setborder (see UICB FUNCTIONS above)
<uicb-arg>      -> prog, 3 (argument to a uicb function, where required)
<string>        -> "foo bar"
<{.., ...}>     -> list of available options

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

screen <integer> [MULTI]
{
    colors
    {
        focus_bg=<color> 
        focus_border=<color>
        focus_fg=<color> 
        normal_bg=<color> 
        normal_border=<color> 
        normal_fg=<color>
        tab_border=<color> 
        urgent_bg=<color>
        urgent_fg=<color>
    }
    general
    {
        allow_lower_floats=<{true,false}>
        border=<integer> 
        focus_move_pointer=<{true,false}>
        font=<font> 
        opacity_unfocused=<integer>
        resize_hints=<{true,false}> 
        snap=<integer> 
    }
    layouts
    {
        layout <{dwindle,floating,max,
                 spiral,tile,tileleft}> { image=<image> } [MULTI]
            
    }
    padding 
    { 
        bottom=<integer> 
        left=<integer> 
        right=<integer> 
        top=<integer> 
    }
    statusbar <identifier> [MULTI]
    {
        position=<{bottom,top,left,right}>
        height=<integer>
        width=<integer>

        focustitle <identifier>
        {
            fg=<color>
            bg=<color>
            align=<{center,left,right}>
            font=<font>
            mouse [MULTI]
            {   
                modkey=<mod> 
                button=<integer>
                command=<uicb-cmd>
                arg=<uicb-arg>
            }
        }
        tasklist <identifier>
        {
            show_icons=<{true,false}>
            focus_fg=<color>
            focus_bg=<color>
            fg=<color>
            bg=<color>
            align=<{center,left,right}>
            font=<font>
            mouse [MULTI]
            {   
                modkey=<mod> 
                button=<integer>
                command=<uicb-cmd>
                arg=<uicb-arg>
            }
        }    
        iconbox <identifier> [MULTI]
        {
            image=<image>
            resize=<{true,false}>
            mouse [MULTI]
            {   
                modkey=<mod> 
                button=<integer>
                command=<uicb-cmd>
                arg=<uicb-arg>
            }
        }
        layoutinfo <identifier>
        {
            mouse [MULTI]
            {   
                modkey=<mod> 
                button=<integer>
                command=<uicb-cmd>
                arg=<uicb-arg>
            }
        }
        netwmicon <identifier>
        {
            mouse [MULTI]
            {   
                modkey=<mod> 
                button=<integer>
                command=<uicb-cmd>
                arg=<uicb-arg>
            }
        }
        progressbar <identifier> [MULTI]
        {
            bar { bcolor=<color> bg=<color> fg=<color> } [MULTI]
            gap=<integer> 
            width=<integer>
            height=<float> 
            lpadding=<integer>
            mouse [MULTI]
            {   
                button=<integer> modkey=<mod> 
                command=<uicb-cmd> arg=<uicb-arg>
            }
        }
        taglist <identifier> [MULTI]
        {
            mouse [MULTI]
            {   
                modkey=<mod> 
                button=<integer>
                command=<uicb-cmd>
            }
        }
        textbox <identifier> [MULTI]
        {
            bg=<color> 
            fg=<color> 
            font=<font>
            mouse [MULTI]
            {   
                modkey=<mod> 
                button=<integer>
                command=<uicb-cmd>
                arg=<uicb-arg>
            }
            text=<string>
            width=<integer>
            align=<{center,left,right}>
        }
    }
    tags
    { 
        tag <identifier> [MULTI]
        { 
            layout=<{dwindle,floating,max,
                     spiral,tile,tileleft}>
            mwfact=<float> 
            nmaster=<integer>
        }
    }
}
rules
{  
    rule [MULTI] 
    { 
        float=<{true,false}> 
        icon=<image> 
        name=<regex> 
        screen=<integer> 
        tags=<integer>,<integer>,...
        not_master=<{true,false}>
    }
}
keys
{
    key [MULTI]
    { 
        arg=<uicb-arg> 
        command=<uicb-cmd> 
        key=<key> 
        modkey=<mod> 
    }
    keylist [MULTI]
    { 
        arglist={<uicb-arg>, ...} 
        command=<uicb-cmd> 
        keylist={<key>, ...} 
        modkey=<mod> 
    }
}
mouse
{
    client [MULTI] 
    {
        arg=<uicb-arg> 
        button=<integer> 
        command=<uicb-cmd> 
        modkey=<mod> 
    }
    root [MULTI]
    {
        arg=<uicb-arg> 
        button=<integer> 
        command=<uicb-cmd> 
        modkey=<mod> 
    }
}
..............................................


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