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
--------
Global sections
~~~~~~~~~~~~~~~
awesomerc contains 4 global sections: *screen*, *rules*, *keys* and *mouse*.

screen section
~~~~~~~~~~~~~~
general
^^^^^^^
General is a section containing some general option for this screen.
It must have a title with screen number, starting at 0.

border::
    This defines the windows 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 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 require 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 tag section, which defines tags.

layouts
^^^^^^^
    Layouts is a section containing the layouts list.

colors
^^^^^^
    Colors is a section containing the colors parameters.

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

statusbar
^^^^^^^^^
   Statusbar are sections containing statusbars parameters.

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.
*fg*::
    Foreground color.
*focus_bg*::
    Background color for focused window.
*focus_fg*::
    Foreground color for focused window.
*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.
*bg*::
    Background color.
*fg*::
    Foreground color.
*width*::
    Set width.
*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.

*bar*::
    Draws a bar; Options: fg, bg, bordercolor.
*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.
*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 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).
*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

[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}>
    }
    tags
    {
        tag <identifier> [MULTI]
        {
            layout = <{dwindle,floating,max,
                     spiral,tile,tileleft,tilebottom,tiletop}>
            mwfact = <float>
            nmaster = <integer>
        }
    }
    layouts
    {
        layout <{dwindle,floating,max,
                 spiral,tile,tileleft,
		 tilebottom,tiletop}> { 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>
            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>
        {
            fg = <color>
            bg = <color>
            focus_fg = <color>
            focus_bg = <color>
            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]
        {
            bar [MULTI]
            {
                fg = <color> fg_center = <color> fg_end = <color>
                bg = <color> bordercolor = <color>
            }
            gap = <integer>
            width = <integer>
            height = <float>
            padding = <integer>
            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>
            }
            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/


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