<section> [title]
{
<option> = <value>
<section> [title]
{
<option> = <value>
...
}
...
}
<option> = <value>
include(file.conf)
awesomerc - Configuration file for the awesome window manager
<section> [title]
{
<option> = <value>
<section> [title]
{
<option> = <value>
...
}
...
}
<option> = <value>
include(file.conf)
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.
awesomerc contains 5 global sections: screen, rules, keys, mouse and menu which are described here.
All these sections contain options which may be strings, integers, floats, or even sections again.
This section defines global awesome options.
The rules section. This allows specific options for specific windows. This option must be a section `rules'.
Menu options. This option must be a section `menu', can be specified multiple times, must have a unique title.
The screens section. Make one for each of your screens. This option must be a section `screen', can be specified multiple times, must have a unique title.
Key bindings. This option must be a section `keys'.
Mouse bindings. This option must be a section `mouse'.
This section defines general options.
New windows get focus. This option must be a boolean value.
How to dispose floating windows. Can be smart or under_mouse. This option must be string value.
New windows become master windows. This option must be a boolean value.
Raise the window if it is given focus with the mouse. This option must be a boolean value.
Enable sloppy focus, also known as focus follows mouse. This option must be a boolean value.
Lower limit for the master window size factor. This option must be a float value.
Use resize hints when resizing tiled windows. Can produce gaps between windows. This option must be a boolean value.
The number of pixels to snap when moving floating windows. This option must be an integer value.
The border size of windows in pixels. This option must be an integer value.
Upper limit for the master window size factor. This option must be a float value.
Opacity of windows when focused. This option must be a float value.
Opacity of windows when unfocused. This option must be a float value.
This section defines a global key binding.
Argument to use for command. This option must be string value.
Uicb command to run. This option must be string value.
Key to press. This option must be string value.
Modifier keys. This option must be string list.
This section defines keylist options.
List of keys, order matters. This option must be string list.
List of arguments for command, order matters. This option must be string list.
Uicb command to run. This option must be string value.
Modifier keys. This option must be string list.
This section defines keys options.
A list of key bindings. This option must be a section `keylist', can be specified multiple times.
A key binding. This option must be a section `key', can be specified multiple times.
This section defines layout options.
Image to represent layout in layoutinfo widget. This option must be string value.
This section defines layouts options.
Available layout(s). This option must be a section `layout', can be specified multiple times, must have a title.
This section defines menu options.
Styles to use for this menu. This option must be a section `styles'.
Height of the menu. Set to 0 for auto. This option must be an integer value.
Width of the menu. Set to 0 for auto. This option must be an integer value.
Y coordinate, do not set for auto. This option must be an integer value.
X coordinate, do not set for auto. This option must be an integer value.
This section defines mouse options.
Mouse bindings for the clients' window. This option must be a section `mouse_generic', can be specified multiple times.
Mouse bindings for the root window. This option must be a section `mouse_generic', can be specified multiple times.
Mouse bindings for the clients' titlebar. This option must be a section `mouse_generic', can be specified multiple times.
This section defines generic mouse bindings.
Mouse button. This option must be string value.
Argument to use for command. This option must be string value.
Uicb command to run. This option must be string value.
Modifier keys. This option must be string list.
This section defines mouse bindings or the taglist widget.
Mouse button. This option must be string value.
Uicb command to run. This option must be string value.
Modifier keys. This option must be string list.
This section defines padding options.
Top padding in pixels. This option must be an integer value.
Right padding in pixels. This option must be an integer value.
Left padding in pixels. This option must be an integer value.
Bottom padding in pixels. This option must be an integer value.
This section defines rule options.
Opacity for this window. This option must be a float value.
Name of the window. This option must be string value.
Tags matching that regexp to put windows in. This option must be string value.
Screen to start this window on. This option must be an integer value.
Set this window floating. This option must be string value.
Set this window as master. This option must be string value.
Name of the xproperty to match. This option must be string value.
Titlebar for this window. This option must be a section `titlebar'.
Value of the xproperty above to match. This option must be string value.
Icon to use for that window. This option must be string value.
This section defines rules options.
A rule. A window can match one rule. This option must be a section `rule', can be specified multiple times.
This section defines screen options.
Styles definitions. This option must be a section `styles'.
Tags definitions. This option must be a section `tags'.
Statubar(s) definitions. This option must be a section `statusbar', can be specified multiple times, must have a unique title.
General options. This option must be a section `general'.
Paddings definitions. This option must be a section `padding'.
Layouts definitions. This option must be a section `layouts'.
Titlebar definitions. This option must be a section `titlebar'.
This section defines statusbar options.
Tasklist(s) widget(s). This option must be a section `widget_tasklist', can be specified multiple times, must have a unique title.
Layoutinfo widget(s). This option must be a section `widget', can be specified multiple times, must have a unique title.
Graph(s) widget(s). This option must be a section `widget_graph', can be specified multiple times, must have a unique title.
Statusbar height. Set to 0 for auto. This option must be an integer value.
Statusbar width. Set to 0 for auto. This option must be an integer value.
Emptybox widget(s). This option must be a section `widget_emptybox', can be specified multiple times, must have a unique title.
Progressbar widget(s). This option must be a section `widget_progressbar', can be specified multiple times, must have a unique title.
Statusbar position. This option must be a position value.
Focusicon widget(s). This option must be a section `widget', can be specified multiple times, must have a unique title.
Taglist widget(s). This option must be a section `widget_taglist', can be specified multiple times, must have a unique title.
Iconbox widget(s). This option must be a section `widget_iconbox', can be specified multiple times, must have a unique title.
Textbox widget(s). This option must be a section `widget_textbox', can be specified multiple times, must have a unique title.
This section defines a style.
Background color. This option must be string value.
Foreground color. This option must be string value.
Shadow offset in pixels. This option must be an integer value.
Shadow color. This option must be string value.
Font to use. This option must be string value.
Windows border color. This option must be string value.
This section defines several styles in a row.
Style used for windows with urgency hint. This option must be a section `style'.
Style used for the focused window. This option must be a section `style'.
Normal style. This option must be a section `style'.
This section defines tag options.
Default master width factor for this tag. This option must be a float value.
Default number of window columns for this tag. This option must be an integer value.
Default layout for this tag. This option must be string value.
Default number of master windows for this tag. This option must be an integer value.
This section defines tags options.
Available tag(s). This option must be a section `tag', can be specified multiple times, must have a unique title.
This section defines a titlebar.
Titlebar styles. This option must be a section `styles'.
Titlebar alignment around window. This option must be an alignment value.
Text alignment. This option must be an alignment value.
Titlebar height. Set to 0 for auto. This option must be an integer value.
Titlebar width. Set to 0 for auto. This option must be an integer value.
Titlebar position. This option must be a position value.
This section defines common widgets options.
Y coordinate, do not set for auto. This option must be an integer value.
X coordinate, do not set for auto. This option must be an integer value.
Widget alignment. This option must be an alignment value.
Mouse bindings. This option must be a section `mouse_generic', can be specified multiple times.
This section defines emptybox widget options.
Style to use for drawing. This option must be a section `style'.
Widget alignment. This option must be an alignment value.
Widget width. Set to 0 for auto. This option must be an integer value.
Y coordinate, do not set for auto. This option must be an integer value.
X coordinate, do not set for auto. This option must be an integer value.
Mouse bindings. This option must be a section `mouse_generic', can be specified multiple times.
This section defines graph widget options.
Border color. This option must be string value.
Background color. This option must be string value.
Data stream. This option must be a section `widget_graph_data', can be specified multiple times, must have a unique title.
Widget alignment. This option must be an alignment value.
Set height (i.e. 0.9 = 90%). This option must be a float value.
Widget width. Set to 0 for auto. This option must be an integer value.
Y coordinate, do not set for auto. This option must be an integer value.
X coordinate, do not set for auto. This option must be an integer value.
Mouse bindings. This option must be a section `mouse_generic', can be specified multiple times.
Put new values onto the left or right. This option must be a position value.
This section defines graph data widget options.
fg, fg_center and fg_end define a vertical gradient. This option must be a boolean value.
Foreground color at the end of a bar (as gradient). This option must be string value.
Draw style. This option must be string value.
Scale graph when values are bigger than max. This option must be a boolean value.
Value of a full graph. This option must be a float value.
Foreground color in the center of the bar (as gradient). This option must be string value.
Foreground color. This option must be string value.
This section defines iconbox widget options.
Widget alignment. This option must be an alignment value.
Y coordinate, do not set for auto. This option must be an integer value.
X coordinate, do not set for auto. This option must be an integer value.
Mouse bindings. This option must be a section `mouse_generic', can be specified multiple times.
Image to draw. This option must be string value.
Enable automatic resize of the image. This option must be a boolean value.
This section defines progressbar widget options.
Distance between the ticks. This option must be an integer value.
Draw the bar(s) vertically. This option must be a boolean value.
Padding between border and ticks/bar. This option must be an integer value.
Draws a bar for each data section. This option must be a section `widget_progressbar_data', can be specified multiple times, must have a unique title.
Widget alignment. This option must be an alignment value.
Distance between individual bars. This option must be an integer value.
Set height (i.e. 0.9 = 90%). This option must be a float value.
Widget width. This option must be an integer value.
Number of ticks to draw. This option must be an integer value.
Y coordinate, do not set for auto. This option must be an integer value.
X coordinate, do not set for auto. This option must be an integer value.
Border width in pixels. This option must be an integer value.
Mouse bindings. This option must be a section `mouse_generic', can be specified multiple times.
This section defines graph widget options.
Border color. This option must be string value.
Foreground color at the end of a bar (as gradient). This option must be string value.
Background color. This option must be string value.
Reverse/mirror the bar. This option must be a boolean value.
Foreground color of not filled bar/ticks. This option must be string value.
Foreground color in the center of the bar (as gradient). This option must be string value.
Foreground color. This option must be string value.
This section defines taglist widget options.
Y coordinate, do not set for auto. This option must be an integer value.
X coordinate, do not set for auto. This option must be an integer value.
Widget alignment. This option must be an alignment value.
Mouse bindings. This option must be a section `mouse_taglist', can be specified multiple times.
This section defines tasklist widget options
Styles to use for drawing. This option must be a section `styles'.
Show icons of windows. This option must be a boolean value.
Which windows to show: tags, all or focus. This option must be string value.
Text alignment. This option must be an alignment value.
Y coordinate, do not set for auto. This option must be an integer value.
X coordinate, do not set for auto. This option must be an integer value.
Mouse bindings. This option must be a section `mouse_generic', can be specified multiple times.
This section defines textbox widget options.
Style to use for drawing. This option must be a section `style'.
Default printed text. This option must be string value.
Widget alignment. This option must be an alignment value.
Text alignment. This option must be an alignment value.
Widget width. Set to 0 for auto. This option must be an integer value.
Y coordinate, do not set for auto. This option must be an integer value.
X coordinate, do not set for auto. This option must be an integer value.
Mouse bindings. This option must be a section `mouse_generic', can be specified multiple times.
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.
Quit awesome. No argument needed.
Move and resize a client. Argument should be in format "x y w h" with absolute (1, 20, 300, …) or relative (+10, -200, …) values.
Give focus to the next visible client in the stack. No argument needed.
Swap the currently focused client with the previous visible one. No argument needed.
Swap the currently focused client with the next visible one. No argument needed.
Toggle horizontal maximization for the focused client. No argument needed.
Move the client to the master area. No argument needed.
Toggle vertical maximization for the focused client. No argument needed.
Set the transparency of the selected client. Argument should be a floating between 0 and 100, -1 to disable.
Toggle the floating state of the focused client. No argument needed.
Toggle the scratch client's visibility. No argument needed.
Give focus to the previous visible client in the stack. No argument needed.
Kill the currently focused client. No argument needed.
Toggle maximization state for the focused client. No argument needed.
Toggle the scratch client attribute on the focused client. No argument needed.
Jump back in the focus history stack. Set arg to 0 for previous, -1 for previous of previous, etc.
Focus one of the visible clients by its name.
Set the layout of the current tag. Argument must be a relative or absolute integer of available layouts.
Resize the focused window with the mouse. No argument needed.
Move the focused window with the mouse. No argument needed.
Switch focus to a specified screen. Argument must be an absolute or relative screen number.
Move client to a screen. Argument must be an absolute or relative screen number.
Toggle the statusbar on or off. Argument must be a statusbar name, or no argument for all statusbars.
View the previous tag. No argument needed.
Toggle the visibility of a tag.
Create a new tag. Argument must be the tag name.
View the next tag. No argument needed.
View only this tag.
Tag the focused client with the given tag.
Toggle a tag on the focused client.
View the previously selected tags. No argument needed.
Toggle the visibility of the focused window's titlebar. No argument needed.
Spawn another process.
Restart awesome with the current command line. No argument needed.
Execute another process, replacing the current instance of awesome.
Send commands to widgets.
More examples are available on awesome's wiki: http://awesome.naquadah.org/wiki/
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
# if you start this from .xinitrc, the script will start before
# awesome, and will fail.
if [ -S ~/.awesome_ctl.0 ]; then
while true
do
echo "0 widget_tell bottom clock text `date`"
echo "" # an empty line flushes data inside awesome
sleep 1
done | awesome-client
else
sleep 1
fi
done
Note: What we are saying is "awesome-client, tell the bottom status bar's
widget named '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 you did not get what you were expecting, take a look at
~/.xsession-errors or the terminal where X got started.
1. Add an include directive into ~/.awesomerc
screen 0 { include(~/.awesome/bottom-status-bar) }
2. Create ~/.awesome/bottom-status-bar
statusbar "bottom"
{
position = "bottom"
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
# if you start this from .xinitrc, the script will start before
# awesome, and will fail.
if [ -S ~/.awesome_ctl.0 ]; then
while true; do
usage = `df /dev/sda5 | awk '/\/dev\/sda5/ { print 100-$5 }'`
echo "0 widget_tell bottom diskusage data disk ${usage}"
echo "" # an empty line flushes data inside awesome
sleep 600;
done | awesome-client
else
sleep 1
fi
done
Note: What we are saying is "awesome-client, tell the bottom status bar's
widget named '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 you did not get what you were expecting, take a look at
~/.xsession-errors or the terminal where X got started.
The following skeleton lists all available configuration options in awesomerc.
Note: when there is no whitespace, quotes are optional.
<boolean> -> true or false
<color> -> Color in X format or hexadecimal (e.g. #aabbcc)
<float> -> Floating numbers (e.g 0.2)
<font> -> Pango font: [FAMILY-LIST] [STYLE-OPTIONS] [SIZE] (e.g Sans Italic 12)
<identifier> -> A name used to identify (e.g foobar)
<image> -> A path to an image (e.g. /home/user/image.jpg)
<integer> -> A signed integer
<key> -> A KeySym (e.g. F10) or a KeyCodea (e.g #120)
<mod> -> A key modifier list (e.g. Mod1)
<regex> -> Regular expression
<string> -> A string
<string-list> -> A string list (e.g. {a, b, c, ...})
<uicb-arg> -> Argument to an uicb function
<uicb-cmd> -> Uicb function, see UICB FUNCTIONS
<style section> -> A style section: {fg= bg= border= font= shadow= shadow_offset= }
<{.., ...}> -> List of available options
[MULTI] -> This item can be defined multiple times
screen <identifier> [MULTI]
{
general
{
border = <integer>
snap = <integer>
resize_hints = <boolean>
sloppy_focus = <boolean>
sloppy_focus_raise = <boolean>
new_become_master = <boolean>
new_get_focus = <boolean>
opacity_unfocused = <float>
opacity_focused = <float>
floating_placement = <{smart,under_mouse}>
mwfact_lower_limit = <float>
mwfact_upper_limit = <float>
}
titlebar
{
position = <{top, bottom, left, right, auto, off}>
align = <{auto, left, right}>
width = <integer>
height = <integer>
text_align = <{left, center, right}>
styles
{
normal
{
<style section>
}
focus
{
<style section>
}
urgent
{
<style section>
}
}
}
statusbar <identifier> [MULTI]
{
position = <{top, bottom, left, right, auto, off}>
height = <integer>
width = <integer>
textbox <identifier> [MULTI]
{
x = <integer>
y = <integer>
align = <{auto, left, right}>
mouse [MULTI]
{
modkey = <mod>
button = <string>
command = <uicb-cmd>
arg = <uicb-arg>
}
width = <integer>
text = <string>
text_align = <{left, center, right}>
style
{
<style section>
}
}
emptybox <identifier> [MULTI]
{
x = <integer>
y = <integer>
align = <{auto, left, right}>
mouse [MULTI]
{
modkey = <mod>
button = <string>
command = <uicb-cmd>
arg = <uicb-arg>
}
width = <integer>
style
{
<style section>
}
}
taglist <identifier> [MULTI]
{
x = <integer>
y = <integer>
align = <{auto, left, right}>
mouse [MULTI]
{
modkey = <mod>
button = <string>
command = <uicb-cmd>
}
}
layoutinfo <identifier> [MULTI]
{
x = <integer>
y = <integer>
align = <{auto, left, right}>
mouse [MULTI]
{
modkey = <mod>
button = <string>
command = <uicb-cmd>
arg = <uicb-arg>
}
}
iconbox <identifier> [MULTI]
{
x = <integer>
y = <integer>
align = <{auto, left, right}>
mouse [MULTI]
{
modkey = <mod>
button = <string>
command = <uicb-cmd>
arg = <uicb-arg>
}
image = <image>
resize = <boolean>
}
focusicon <identifier> [MULTI]
{
x = <integer>
y = <integer>
align = <{auto, left, right}>
mouse [MULTI]
{
modkey = <mod>
button = <string>
command = <uicb-cmd>
arg = <uicb-arg>
}
}
progressbar <identifier> [MULTI]
{
x = <integer>
y = <integer>
align = <{auto, left, right}>
mouse [MULTI]
{
modkey = <mod>
button = <string>
command = <uicb-cmd>
arg = <uicb-arg>
}
data <identifier> [MULTI]
{
fg = <color>
fg_center = <color>
fg_end = <color>
fg_off = <color>
bg = <color>
bordercolor = <color>
reverse = <boolean>
}
width = <integer>
gap = <integer>
border_width = <integer>
border_padding = <integer>
ticks_gap = <integer>
ticks_count = <integer>
height = <float>
vertical = <boolean>
}
graph <identifier> [MULTI]
{
x = <integer>
y = <integer>
align = <{auto, left, right}>
mouse [MULTI]
{
modkey = <mod>
button = <string>
command = <uicb-cmd>
arg = <uicb-arg>
}
data <identifier> [MULTI]
{
max = <float>
scale = <boolean>
fg = <color>
fg_center = <color>
fg_end = <color>
vertical_gradient = <boolean>
draw_style = <{bottom, top, line}>
}
width = <integer>
grow = <{left, right}>
height = <float>
bg = <color>
bordercolor = <color>
}
tasklist <identifier> [MULTI]
{
x = <integer>
y = <integer>
mouse [MULTI]
{
modkey = <mod>
button = <string>
command = <uicb-cmd>
arg = <uicb-arg>
}
styles
{
normal
{
<style section>
}
focus
{
<style section>
}
urgent
{
<style section>
}
}
text_align = <{left, center, right}>
show = <{all,tags,focus}>
show_icons = <boolean>
}
}
tags
{
tag <identifier> [MULTI]
{
layout = <string>
mwfact = <float>
nmaster = <integer>
ncol = <integer>
}
}
styles
{
normal
{
<style section>
}
focus
{
<style section>
}
urgent
{
<style section>
}
}
layouts
{
layout <title> [MULTI]
{
image = <image>
}
}
padding
{
top = <integer>
bottom = <integer>
right = <integer>
left = <integer>
}
}
rules
{
rule [MULTI]
{
xproperty_name = <string>
xproperty_value = <regex>
name = <regex>
tags = <regex>
icon = <string>
float = <{auto,true,false}>
master = <{auto,true,false}>
titlebar
{
position = <{top, bottom, left, right, auto, off}>
align = <{auto, left, right}>
width = <integer>
height = <integer>
text_align = <{left, center, right}>
styles
{
normal
{
<style section>
}
focus
{
<style section>
}
urgent
{
<style section>
}
}
}
screen = <integer>
opacity = <float>
}
}
keys
{
key [MULTI]
{
modkey = <mod>
key = <key>
command = <uicb-cmd>
arg = <uicb-arg>
}
keylist [MULTI]
{
modkey = <mod>
keylist = <key, ...>
command = <uicb-cmd>
arglist = <string-list>
}
}
mouse
{
root [MULTI]
{
modkey = <mod>
button = <string>
command = <uicb-cmd>
arg = <uicb-arg>
}
client [MULTI]
{
modkey = <mod>
button = <string>
command = <uicb-cmd>
arg = <uicb-arg>
}
titlebar [MULTI]
{
modkey = <mod>
button = <string>
command = <uicb-cmd>
arg = <uicb-arg>
}
}
menu <identifier> [MULTI]
{
width = <integer>
height = <integer>
x = <integer>
y = <integer>
styles
{
normal
{
<style section>
}
focus
{
<style section>
}
urgent
{
<style section>
}
}
}
awesome(1) awesome-client(1) awesome-menu(1) awesome-message(1)
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).
http://awesome.naquadah.org