awesome/awesomerc.1.txt

577 lines
14 KiB
Plaintext

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_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).
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.
*bar*::
Draws a bar; Options: fg, bg, bordercolor.
*fg*::
Foreground color.
*fg_full*::
Foreground color of a full 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).
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_middle*::
Color at the middle of the graph
*fg_end*::
Color at the end of the graph
*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).
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')
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>
}
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>
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 [MULTI]
{
fg = <color> fg_full = <color> fg_half = <color>
bg = <color> bordercolor = <color>
}
gap = <integer>
width = <integer>
height = <float>
padding = <integer>
x = <integer> y = <integer>
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_middle = <color> fg_end = <color>
}
width = <integer>
height = <float>
padding_left = <integer>
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}>
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