DragonFly On-Line Manual Pages

Search: Section:  


AWESOME2RC(5)                                                    AWESOME2RC(5)

NAME

awesome2rc - Configuration file for the 'awesome2 window manager'

SYNOPSIS

<section> [title] { <option> = <value> <section> [title] { <option> = <value> ... } ... } <option> = <value> include(file.conf)

DESCRIPTION

The awesome2rc file contains configuration informations for awesome2. It can be used to configure the behaviour and look of awesome2 in a variety of ways. It is read at startup.

OPTIONS

awesome2rc 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. Base sections This section defines global awesome options. rules The rules section. This allows specific options for specific windows. This option must be a section `rules'. menu Menu options. This option must be a section `menu', can be specified multiple times, must have a unique title. screen 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. keys Key bindings. This option must be a section `keys'. mouse Mouse bindings. This option must be a section `mouse'. general This section defines general options. new_get_focus New windows get focus. This option must be a boolean value. floating_placement How to dispose floating windows. Can be smart or under_mouse. This option must be string value. new_become_master New windows become master windows. This option must be a boolean value. sloppy_focus_raise Raise the window if it is given focus with the mouse. This option must be a boolean value. sloppy_focus Enable sloppy focus, also known as focus follows mouse. This option must be a boolean value. mwfact_lower_limit Lower limit for the master window size factor. This option must be a float value. resize_hints Use resize hints when resizing tiled windows. Can produce gaps between windows. This option must be a boolean value. snap The number of pixels to snap when moving floating windows. This option must be an integer value. border The border size of windows in pixels. This option must be an integer value. mwfact_upper_limit Upper limit for the master window size factor. This option must be a float value. opacity_focused Opacity of windows when focused. This option must be a float value. opacity_unfocused Opacity of windows when unfocused. This option must be a float value. key This section defines a global key binding. arg Argument to use for command. This option must be string value. command Uicb command to run. This option must be string value. key Key to press. This option must be string value. modkey Modifier keys. This option must be string list. keylist This section defines keylist options. keylist List of keys, order matters. This option must be string list. arglist List of arguments for command, order matters. This option must be string list. command Uicb command to run. This option must be string value. modkey Modifier keys. This option must be string list. keys This section defines keys options. keylist A list of key bindings. This option must be a section `keylist', can be specified multiple times. key A key binding. This option must be a section `key', can be specified multiple times. layout This section defines layout options. image Image to represent layout in layoutinfo widget. This option must be string value. layouts This section defines layouts options. layout Available layout(s). This option must be a section `layout', can be specified multiple times, must have a title. menu This section defines menu options. styles Styles to use for this menu. This option must be a section `styles'. match_string String matching mode (true to complete string) This option must be a boolean value. height Height of the menu. Set to 0 for auto. This option must be an integer value. autocomplete Autocompletion (true or false) This option must be a boolean value. width Width of the menu. Set to 0 for auto. This option must be an integer value. y Y coordinate, do not set for auto. This option must be an integer value. x X coordinate, do not set for auto. This option must be an integer value. mouse This section defines mouse options. client Mouse bindings for the clients' window. This option must be a section `mouse_generic', can be specified multiple times. root Mouse bindings for the root window. This option must be a section `mouse_generic', can be specified multiple times. titlebar Mouse bindings for the clients' titlebar. This option must be a section `mouse_generic', can be specified multiple times. mouse_generic This section defines generic mouse bindings. button Mouse button. This option must be string value. arg Argument to use for command. This option must be string value. command Uicb command to run. This option must be string value. modkey Modifier keys. This option must be string list. mouse_taglist This section defines mouse bindings or the taglist widget. button Mouse button. This option must be string value. command Uicb command to run. This option must be string value. modkey Modifier keys. This option must be string list. padding This section defines padding options. top Top padding in pixels. This option must be an integer value. right Right padding in pixels. This option must be an integer value. left Left padding in pixels. This option must be an integer value. bottom Bottom padding in pixels. This option must be an integer value. rule This section defines rule options. opacity Opacity for this window. This option must be a float value. name Regexp to match the window against a string formatted like: class:name:title. This option must be string value. tags Tags matching that regexp to tag windows with. This option must be string value. screen Screen to start this window on. This option must be an integer value. float Set this window floating. This option must be string value. master Set this window as master. This option must be string value. xproperty_name Name of the xproperty to match. This option must be string value. titlebar Titlebar for this window. This option must be a section `titlebar'. xproperty_value Regexp value of the xproperty above to match. This option must be string value. icon Icon to use for that window. This option must be string value. rules This section defines rules options. rule A rule. A window can match one rule. This option must be a section `rule', can be specified multiple times. screen This section defines screen options. styles Styles definitions. This option must be a section `styles'. tags Tags definitions. This option must be a section `tags'. statusbar Statubar(s) definitions. This option must be a section `statusbar', can be specified multiple times, must have a unique title. general General options. This option must be a section `general'. padding Paddings definitions. This option must be a section `padding'. layouts Layouts definitions. This option must be a section `layouts'. titlebar Titlebar definitions. This option must be a section `titlebar'. statusbar This section defines statusbar options. tasklist Tasklist(s) widget(s). This option must be a section `widget_tasklist', can be specified multiple times, must have a unique title. layoutinfo Layoutinfo widget(s). This option must be a section `widget', can be specified multiple times, must have a unique title. graph Graph(s) widget(s). This option must be a section `widget_graph', can be specified multiple times, must have a unique title. height Statusbar height. Set to 0 for auto. This option must be an integer value. width Statusbar width. Set to 0 for auto. This option must be an integer value. emptybox Emptybox widget(s). This option must be a section `widget_emptybox', can be specified multiple times, must have a unique title. progressbar Progressbar widget(s). This option must be a section `widget_progressbar', can be specified multiple times, must have a unique title. position Statusbar position. This option must be a position value. focusicon Focusicon widget(s). This option must be a section `widget', can be specified multiple times, must have a unique title. taglist Taglist widget(s). This option must be a section `widget_taglist', can be specified multiple times, must have a unique title. iconbox Iconbox widget(s). This option must be a section `widget_iconbox', can be specified multiple times, must have a unique title. textbox Textbox widget(s). This option must be a section `widget_textbox', can be specified multiple times, must have a unique title. style This section defines a style. bg Background color. This option must be string value. fg Foreground color. This option must be string value. shadow_offset Shadow offset in pixels. This option must be an integer value. shadow Shadow color. This option must be string value. font Font to use. This option must be string value. border Windows border color. This option must be string value. styles This section defines several styles in a row. urgent Style used for windows with urgency hint. This option must be a section `style'. focus Style used for the focused window. This option must be a section `style'. normal Normal style. This option must be a section `style'. tag This section defines tag options. mwfact Default master width factor for this tag. This option must be a float value. ncol Default number of window columns for this tag. This option must be an integer value. layout Default layout for this tag. This option must be string value. nmaster Default number of master windows for this tag. This option must be an integer value. tags This section defines tags options. tag Available tag(s). This option must be a section `tag', can be specified multiple times, must have a unique title. titlebar This section defines a titlebar. styles Titlebar styles. This option must be a section `styles'. align Titlebar alignment around window. This option must be an alignment value. text_align Text alignment. This option must be an alignment value. height Titlebar height. Set to 0 for auto. This option must be an integer value. width Titlebar width. Set to 0 for auto. This option must be an integer value. position Titlebar position. This option must be a position value. widget This section defines common widgets options. y Y coordinate, do not set for auto. This option must be an integer value. x X coordinate, do not set for auto. This option must be an integer value. align Widget alignment. This option must be an alignment value. mouse Mouse bindings. This option must be a section `mouse_generic', can be specified multiple times. widget_emptybox This section defines emptybox widget options. style Style to use for drawing. This option must be a section `style'. align Widget alignment. This option must be an alignment value. width Widget width. Set to 0 for auto. This option must be an integer value. y Y coordinate, do not set for auto. This option must be an integer value. x X coordinate, do not set for auto. This option must be an integer value. mouse Mouse bindings. This option must be a section `mouse_generic', can be specified multiple times. widget_graph This section defines graph widget options. bordercolor Border color. This option must be string value. bg Background color. This option must be string value. data Data stream. This option must be a section `widget_graph_data', can be specified multiple times, must have a unique title. align Widget alignment. This option must be an alignment value. height Set height (i.e. 0.9 = 90%). This option must be a float value. width Widget width. Set to 0 for auto. This option must be an integer value. y Y coordinate, do not set for auto. This option must be an integer value. x X coordinate, do not set for auto. This option must be an integer value. mouse Mouse bindings. This option must be a section `mouse_generic', can be specified multiple times. grow Put new values onto the left or right. This option must be a position value. widget_graph_data This section defines graph data widget options. vertical_gradient fg, fg_center and fg_end define a vertical gradient. This option must be a boolean value. fg_end Foreground color at the end of a bar (as gradient). This option must be string value. draw_style Draw style. This option must be string value. scale Scale graph when values are bigger than max. This option must be a boolean value. max Value of a full graph. This option must be a float value. fg_center Foreground color in the center of the bar (as gradient). This option must be string value. fg Foreground color. This option must be string value. widget_iconbox This section defines iconbox widget options. align Widget alignment. This option must be an alignment value. y Y coordinate, do not set for auto. This option must be an integer value. x X coordinate, do not set for auto. This option must be an integer value. mouse Mouse bindings. This option must be a section `mouse_generic', can be specified multiple times. image Image to draw. This option must be string value. resize Enable automatic resize of the image. This option must be a boolean value. widget_progressbar This section defines progressbar widget options. ticks_gap Distance between the ticks. This option must be an integer value. vertical Draw the bar(s) vertically. This option must be a boolean value. border_padding Padding between border and ticks/bar. This option must be an integer value. data 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. align Widget alignment. This option must be an alignment value. gap Distance between individual bars. This option must be an integer value. height Set height (i.e. 0.9 = 90%). This option must be a float value. width Widget width. This option must be an integer value. ticks_count Number of ticks to draw. This option must be an integer value. y Y coordinate, do not set for auto. This option must be an integer value. x X coordinate, do not set for auto. This option must be an integer value. border_width Border width in pixels. This option must be an integer value. mouse Mouse bindings. This option must be a section `mouse_generic', can be specified multiple times. widget_progressbar_data This section defines graph widget options. bordercolor Border color. This option must be string value. fg_end Foreground color at the end of a bar (as gradient). This option must be string value. bg Background color. This option must be string value. reverse Reverse/mirror the bar. This option must be a boolean value. fg_off Foreground color of not filled bar/ticks. This option must be string value. fg_center Foreground color in the center of the bar (as gradient). This option must be string value. fg Foreground color. This option must be string value. widget_taglist This section defines taglist widget options. y Y coordinate, do not set for auto. This option must be an integer value. x X coordinate, do not set for auto. This option must be an integer value. align Widget alignment. This option must be an alignment value. mouse Mouse bindings. This option must be a section `mouse_taglist', can be specified multiple times. widget_tasklist This section defines tasklist widget options styles Styles to use for drawing. This option must be a section `styles'. show_icons Show icons of windows. This option must be a boolean value. show Which windows to show: tags, all or focus. This option must be string value. text_align Text alignment. This option must be an alignment value. y Y coordinate, do not set for auto. This option must be an integer value. x X coordinate, do not set for auto. This option must be an integer value. mouse Mouse bindings. This option must be a section `mouse_generic', can be specified multiple times. widget_textbox This section defines textbox widget options. style Style to use for drawing. This option must be a section `style'. text Default printed text. This option must be string value. align Widget alignment. This option must be an alignment value. text_align Text alignment. This option must be an alignment value. width Widget width. Set to 0 for auto. This option must be an integer value. y Y coordinate, do not set for auto. This option must be an integer value. x X coordinate, do not set for auto. This option must be an integer value. mouse Mouse bindings. This option must be a section `mouse_generic', can be specified multiple times.

UICB FUNCTIONS

In awesome2, 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. Awesome quit Quit awesome. No argument needed. Client client_moveresize Move and resize a client. Argument should be in format "x y w h" with absolute (1, 20, 300, ...) or relative (+10, -200, ...) values. client_focusnext Give focus to the next visible client in the stack. No argument needed. client_swapprev Swap the currently focused client with the previous visible one. No argument needed. client_swapnext Swap the currently focused client with the next visible one. No argument needed. client_togglehorizontalmax Toggle horizontal maximization for the focused client. No argument needed. client_zoom Move the client to the master area. No argument needed. client_toggleverticalmax Toggle vertical maximization for the focused client. No argument needed. client_settrans Set the transparency of the selected client. Argument should be an absolut or relativ floating between 0.0 and 1.0 client_togglefloating Toggle the floating state of the focused client. No argument needed. client_togglescratch Toggle the scratch client's visibility. No argument needed. client_focusprev Give focus to the previous visible client in the stack. No argument needed. client_kill Kill the currently focused client. No argument needed. client_togglemax Toggle maximization state for the focused client. No argument needed. client_setscratch Toggle the scratch client attribute on the focused client. No argument needed. Focus focus_history Jump back in the focus history stack. Set arg to 0 for previous, -1 for previous of previous, etc. focus_client_byname Focus one of the visible clients by its name. Layout tag_setlayout Set the layout of the current tag. Argument must be a relative or absolute integer of available layouts. Mouse client_resizemouse Resize the focused window with the mouse. No argument needed. client_movemouse Move the focused window with the mouse. No argument needed. Screen screen_focus Switch focus to a specified screen. Argument must be an absolute or relative screen number. client_movetoscreen Move client to a screen. Argument must be an absolute or relative screen number. Statusbar statusbar_toggle Toggle the statusbar on or off. Argument must be a statusbar name, or no argument for all statusbars. Tag tag_viewprev View the previous tag. No argument needed. tag_toggleview Toggle the visibility of a tag. tag_create Create a new tag. Argument must be the tag name. tag_viewnext View the next tag. No argument needed. tag_view View only this tag. client_tag Tag the focused client with the given tag. client_toggletag Toggle a tag on the focused client. tag_prev_selected View the previously selected tags. No argument needed. Titlebar client_toggletitlebar Toggle the visibility of the focused window's titlebar. No argument needed. General spawn Spawn another process. restart Restart awesome with the current command line. No argument needed. exec Execute another process, replacing the current instance of awesome. Widget widget_tell Send commands to widgets.

EXAMPLES

More examples are available on awesome2's wiki: http://awesome2.naquadah.org/wiki/ Simple textbox example 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 $ awesome2 -k Configuration file OK. Note: If you see anything other than "Configuration file OK." you have a typo somewhere. 4. Create ~/bin/awesome2-clock #!/bin/sh while true do # if you start this from .xinitrc, the script will start before # awesome2, 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 awesome2 sleep 1 done | awesome2-client else sleep 1 fi done Note: What we are saying is "awesome2-client, tell the bottom status bar's widget named 'clock' to set it's 'text' property to date's output". 5. Make your ~/bin/awesome2-clock executable $ chmod a+x ~/bin/awesome2-clock 6. Modify ~/.xinitrc ~/bin/awesome2-clock & exec awesome2 7. Restart awesome2 8. If you did not get what you were expecting, take a look at ~/.xsession-errors or the terminal where X got started. Simple progressbar example 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 $ awesome2 -k Configuration file OK. Note: If you see anything other than "Configuration file OK," you have a typo somewhere. 4. Create ~/bin/awesome2-diskusage #!/bin/sh while true do # if you start this from .xinitrc, the script will start before # awesome2, 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 awesome2 sleep 600; done | awesome2-client else sleep 1 fi done Note: What we are saying is "awesome2-client, tell the bottom status bar's widget named 'diskusage' to set it's 'data' property named 'disk' to ${usage}." 5. Make ~/bin/awesome2-diskusage executable $ chmod a+x ~/bin/awesome2-diskusage 6. Modify ~/.xinitrc ~/bin/awesome2-diskusage & exec awesome2 7. Restart awesome2 8. If you did not get what you were expecting, take a look at ~/.xsession-errors or the terminal where X got started.

AWESOMERC SKELETON

The following skeleton lists all available configuration options in awesome2rc. 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> match_string = <boolean> autocomplete = <boolean> styles { normal { <style section> } focus { <style section> } urgent { <style section> } } }

SEE ALSO

awesome2(1) awesome2-client(1) awesome2-menu(1) awesome2-message(1)

AUTHORS

This man page was written by Julien Danjou <julien@danjou.info[1]>, Marco Candrian <mac@calmar.ws[2]> and Chris Ciulla <chris.ciulla@gmail.com[3]> (Simple Examples).

WWW

http://awesome2.naquadah.org

NOTES

1. julien@danjou.info mailto:julien@danjou.info 2. mac@calmar.ws mailto:mac@calmar.ws 3. chris.ciulla@gmail.com mailto:chris.ciulla@gmail.com 02/19/2016 AWESOME2RC(5)

Search: Section: