7 awesomerc - Configuration file for the 'awesome window manager'
16 <item> [<argument>] { <option> = <value>, ... }
27 The awesomerc file contains configuration informations for *awesome*. It can
28 be used to configure the behaviour and look of awesome in a variety of ways.
30 It is read at startup.
34 awesomerc contains 4 global sections: *screen*, *rules*, *keys* and *mouse* which
39 This is the global section for a physical screen. It must have a title with screen number,
40 starting at 0. It contains several subsections, which are *general*, *tags*, *layouts*, *styles*,
41 *padding* and *statusbar*.
45 General is a section containing some general options for this screen.
48 This section defines the parameters of the windows titlebar.
50 This defines the window borders size in pixel.
52 If this is set to true, new windows will become the master window.
54 If this is set to true, new windows will get focus.
56 If this is set to a float value between 0 and 1, non-focused windows will have this opacity.
57 This requires an external XComposite manager.
59 If this is set to a float value between 0 and 1, focused windows will have this opacity.
60 This requires an external XComposite manager.
62 If this is set to true, resize hints given by the window will be respected.
63 If this is set to false, window size will be forced.
64 If you dislike gaps between windows, you should try to set it to false.
66 If this is set to true, focus will be set to the window under the mouse. If not,
67 you will have to click on a window to set it focused.
69 If this is set to true with sloppy_focus, when a window is focused with the mouse
70 it will be raised on top of the windows stack.
72 Snap windows to the screen border when it is this pixel away only from the border.
74 Select the floating placement algorithm to use when placing window.
78 Tags is a section containing one or more tag sections, which defines a tag.
82 Tag is a section which contains several options defining a tag.
85 Layout is a name of an available layout which will be set by default on this tag.
87 Set the default master width factor for this tag.
89 Set the default number of columns for non-master windows for this tag.
91 Set the default number of windows which will be treated as master for this tag.
95 Layouts is a section containing a layout list, where each layout is a layout section.
99 Layout is a section which define a layout. It has a title which is the algorithm to use.
102 Set the image path used to describe this layouts, useful in layoutinfo widget.
106 Styles is a section containing the style parameters which is composed of a normal, focus and urgent
107 subsection each ones containing:
112 Set the foreground color.
114 Set the background color.
116 Set the window's border color.
118 Set the shadow color.
120 Set the shadow offset in pixel.
124 Padding is a section containing screen padding parameters.
127 Set the top padding in pixel.
129 Set the bottom padding in pixel.
131 Set the left padding in pixel.
133 Set the right padding in pixel.
137 Statusbar are sections containing statusbars parameters. Each statusbar section
138 must have a title which is the statusbar name. Each statusbar can have none or
139 several widgets (see WIDGETS section for more details) each one identified by its
143 Default statusbar position.
145 Statusbar height. By default, is auto computed with font size.
147 Statusbar width. By default, it will be whole screen.
151 Rules is a section containing a rule list to automatically configure windows.
155 Rule are sections containing the auto-configuration options for one window.
158 Set the window name for name matching as a regular expression.
160 Set the name of the XProperty for XProperty matching.
162 Set the regular expression to match against the named XProperty's value.
164 Set the window to be floating. One of auto, true or false. Defaults to auto.
166 Set the window to be the master. One of auto, true or false. Defaults to
169 Set the tags to be assigned to the window as a regular expression.
171 Set the screen the window should show up on.
173 Set the window's icon.
175 Set the window's opacity.
179 Keys is the section to define your keybindings in. It may consist of multiple
180 key and keylist entries.
184 In a key section you define a single keybinding.
187 The keysym you want to bind.
189 Modifiers that need to be pressed for this binding.
191 The *uicb function* to call.
193 The argument to the *uicb function*, if needed.
197 In a keylist you can define multiple very similar keybindings at once. For
198 example you can define <Mod1>-{1..9} to switch the view to tag 1..9
202 The list of keysyms to bind.
204 Modifiers that need to be pressed for these bindings.
206 The *uicb function* to call.
208 The list of arguments to the *uicb function*, if needed. *Must* match the
213 In the mouse section you may define mouse button bindings for the root and
218 Defines a mouse button binding for events on clients.
221 The mouse button you want to bind.
223 Modifiers that need to be pressed for this binding.
225 The *uicb function* to call.
227 The argument to the *uicb function*, if needed.
231 Defines a mouse button binding for events on the root window.
234 The mouse button you want to bind.
236 Modifiers that need to be pressed for this binding.
238 The *uicb function* to call.
240 The argument to the *uicb function*, if needed.
245 In awesome, a lot of *functions* are available. These functions are called
246 uicb (User Interface Call Backs). Each function can be bound to a key shortcut
252 This function quits awesome.
253 *statusbar_toggle* statusbar-identifier::
254 Hide or show statusbar (with no argument, toggle all).
256 Execute an external program.
258 Replace awesome with another window manager.
261 *widget_tell* widget-identifier data::
262 Feed information to your widgets.
267 Closes the focused client.
268 *client_moveresize* x y width height::
269 Dynamically move and resize floating windows.
270 Coordinates can be relative or absolute. Relative values must begin with + or -.
271 E.g: to move a window 10 pixels up: "+0 \+10 +0 +0" To move a window
272 in the upper left corner and increase its width by 10px: "0 0 \+0 +10"
273 *client_settrans* float::
274 Set client transparency, number can be a relative or absolute floating number in percentage.
276 Swap window placement with the next displayed window.
278 Swap window placement with the previous displayed window.
282 Focus previous window.
284 Set window fullscreen. Calling this function another time will reset the window to its previous state.
285 *client_togglehorizontalmax*::
286 Set window's horizontal size to display width. Calling another time will reset the window to its previous state.
287 *client_toggleverticalmax*::
288 Set window's vertical size to display height. Calling another time will reset the window to its previous state.
289 *client_togglefloating*::
290 Set window floating or tiled.
292 Set window as master window.
293 *client_movetoscreen* relative or absolute integer::
294 Move focused window to the nth screen, or next (+1) or previous (-1). If no screen_number is set, move to the next screen.
295 *client_tag* tag number::
296 Tag focused window with this tag.
298 Add or remove tag to focused window.
300 Move client window with mouse.
301 *client_resizemouse*::
302 Resize client window with mouse.
303 *client_setscratch*::
304 Set or unset client as being the scratch window.
305 *client_togglescratch*::
306 Toggle scratch window.
307 *client_toggletitlebar*::
308 Toggle window titlebar.
312 *tag_setlayout* relative or absolute integer::
313 Set layout number; or just switch to the next layout for current tag.
314 *tag_toggleview* tag::
315 Add windows tagged with tag number to current display.
316 *tag_view* tag number::
317 View windows tagged with tag number.
319 Show windows tagged with next tag in list.
321 Show windows tagged with previous tag in list.
322 *tag_prev_selected*::
323 Switch back to the previously displayed set of tags.
324 *tag_setmwfact* relative or absolute float::
325 Set master width factor.
326 *tag_setncol* relative or absolute integer::
327 Set number of columns for non-master windows.
328 *tag_setnmaster* relative or absolute integer::
329 Set number of master windows.
331 Create a new tag with that name.
335 *focus_client_byname* string::
336 Give client focus by its name.
337 *focus_history* negative number::
338 Focus the client that had focused nth focus switch earlier.
342 *screen_focus* relative or absolute integer::
343 Select Screen and focus first window and move mouse.
347 Statusbars can be customized by modifying widgets names, order and options.
351 This widget shows the tag list.
356 Horizontal offset (auto-alignment if not set).
358 Vertical offset (auto-alignment if not set).
364 This widget shows a icon for the selected layout.
369 Horizontal offset (auto-alignment if not set).
371 Vertical offset (auto-alignment if not set).
377 This widget shows a icon for the focused window using NET_WM_ICON or icon file set in rule.
382 Horizontal offset (auto-alignment if not set).
384 Vertical offset (auto-alignment if not set).
390 This widget shows a list of running windows.
395 Style section with normal, focus and urgent subsections.
399 Show applications icons.
401 Show all windows from all tags, tags clients only or focused client.
403 Horizontal offset (auto-alignment if not set).
405 Vertical offset (auto-alignment if not set).
409 This widget shows a text.
416 Style section with <style section>
422 Horizontal offset (auto-alignment if not set).
424 Vertical offset (auto-alignment if not set).
430 This widget shows an icon.
437 Resize icon to fit into statusbar.
439 Horizontal offset (auto-alignment if not set).
441 Vertical offset (auto-alignment if not set).
447 This widget shows one or more progress-bars.
450 Draws a bar for each data section;
451 Options: reverse, fg, fg_center, fg_end, bg, bordercolor.
453 Reverse/mirror the bar.
457 Foreground color in the center of the bar (as gradient).
459 Foreground color at the end of a bar (as gradient).
469 Set height (i.e. 0.9 = 90%)
471 Empty space on both sides.
473 Draw the bar(s) vertically/standing up.
475 Horizontal offset (auto-alignment if not set).
477 Vertical offset (auto-alignment if not set).
483 This widget shows a graph.
486 Defines a data-stream section;
487 Options: max, scale, fg, fg_center, fg_end and draw_style.
489 This value prints a full graph (default = 100).
491 Re-scales when input > max (see below).
495 Foreground color in the center of the bar (as gradient).
497 Foreground color at the end of a bar (as gradient).
499 If true, create a gradient from 0 > full instead of new > old values
501 bottom (fills from bottom to top), top, or line.
507 Set height (i.e. 0.9 = 90%).
509 Empty space on the left.
511 Put new values onto the 'left' or 'right'.
517 Horizontal offset (auto-alignment if not set).
519 Vertical offset (auto-alignment if not set).
525 Here is the global configuration file format, with a list of options
528 ..............................................
529 Note: when there is no whitespace, quotes are optional.
531 <boolean> -> "true" or "false"
532 <color> -> #ff9933 (hexadecimal color notation: #red green blue)
533 <float> -> 0.3, 0,8 (often values between 0 and 1 are useful)
534 <font> -> Pango font: sans 10, sans italic 10, fixed 12, ...
535 <identifier> -> foobar (choose a name/string)
536 <image> -> "/home/awesome/pics/icon.png" (path to image)
537 <integer> -> 1, 10, -3 (positive numbers are required mostly)
538 <key> -> a, 1, F10 (see /usr/include/X11/keysymdef.h w/o XK_ or 'xev')
539 or a keycode beginning with #
540 <mod> -> "Mod1", "Mod4", "Control" (modifiers)
541 <regex> -> regular expression
542 <string> -> "foo bar"
543 <uicb-arg> -> prog, 3... (argument to a uicb function, where required)
544 <uicb-cmd> -> spawn, exec, client_tag... (see UICB FUNCTIONS above)
545 <position> -> list of position: off, top, right, left, bottom, auto
546 <{.., ...}> -> list of available options
547 <style section> -> a section with font, fg, bg, border, shadow and shadow_offset options.
548 { font = <font> fg = <color> bg = <color> border = <color>
549 shadow = <color> shadow_offset = <integer> }
550 <titlebar> -> a section with position and icon position.
551 { position = <position> icon = <position> text_align = <{center,right,left}>
552 height = <integer> width = <integer> styles { } }
554 [MULTI] means, you can use an item multiple times.
557 screen <integer> [MULTI]
562 new_become_master = <boolean>
563 new_get_focus = <boolean>
564 opacity_unfocused = <integer>
565 opacity_focused = <integer>
566 resize_hints = <boolean>
567 sloppy_focus = <boolean>
568 sloppy_focus_raise = <boolean>
570 floating_placement = <{smart,under_mouse}>
571 mwfact_lower_limit = <float>
572 mwfact_upper_limit = <float>
580 tag <identifier> [MULTI]
582 layout = <{dwindle,floating,max,
583 spiral,tile,tileleft,tilebottom,tiletop}>
591 layout <{dwindle,floating,max,
592 spiral,tile,tileleft,
593 tilebottom,tiletop}> { image = <image> } [MULTI]
597 normal { <style section> }
598 focus { <style section> }
599 urgent { <style section> }
608 statusbar <identifier> [MULTI]
610 position = <{top,bottom,left,right,off}>
614 taglist <identifier> [MULTI]
616 x = <integer> y = <integer>
617 align = <{auto,right,left}>
620 button = <integer> modkey = {<mod>, ...}
621 command = <uicb-cmd> arg = <uicb-arg>
624 layoutinfo <identifier>
626 x = <integer> y = <integer>
627 align = <{auto,right,left}>
630 button = <integer> modkey = {<mod>, ...}
631 command = <uicb-cmd> arg = <uicb-arg>
634 focusicon <identifier>
636 x = <integer> y = <integer>
637 align = <{auto,right,left}>
640 button = <integer> modkey = {<mod>, ...}
641 command = <uicb-cmd> arg = <uicb-arg>
644 tasklist <identifier>
648 normal { <style section> }
649 focus { <style section> }
651 show_icons = <boolean>
652 show = <{all,tags,focus}>
653 text_align = <{center,left,right}>
654 x = <integer> y = <integer>
657 command = <uicb-cmd> arg = <uicb-arg>
658 button = <integer> modkey = {<mod>, ...}
661 textbox <identifier> [MULTI]
663 style { <style section> }
666 text_align = <{center,left,right}>
667 x = <integer> y = <integer>
668 align = <{auto,right,left}>
671 button = <integer> modkey = {<mod>, ...}
672 command = <uicb-cmd> arg = <uicb-arg>
675 iconbox <identifier> [MULTI]
679 x = <integer> y = <integer>
680 align = <{auto,right,left}>
683 button = <integer> modkey = {<mod>, ...}
684 command = <uicb-cmd> arg = <uicb-arg>
687 progressbar <identifier> [MULTI]
691 reverse = <boolean> bg = <color> bordercolor = <color>
692 fg = <color> fg_center = <color> fg_end = <color>
699 x = <integer> y = <integer>
700 align = <{auto,right,left}>
703 button = <integer> modkey = {<mod>, ...}
704 command = <uicb-cmd> arg = <uicb-arg>
707 graph <identifier> [MULTI]
711 scale = <boolean> max = <float> draw_style = <{bottom, top, line}>
712 fg = <color> fg_center = <color> fg_end = <color>
713 vertical_gradient = <boolean>
717 padding_left = <integer>
718 grow = <{left, right}>
720 bordercolor = <color>
721 x = <integer> y = <integer>
722 align = <{auto,right,left}>
725 button = <integer> modkey = {<mod>, ...}
726 command = <uicb-cmd> arg = <uicb-arg>
736 xproperty_name = <string>
737 xproperty_value = <regex>
738 float = <{auto,true,false}>
739 master = <{auto,true,false}>
754 key = <key> modkey = {<mod>, ...}
755 command = <uicb-cmd> arg = <uicb-arg>
759 keylist = {<key>, ...}
760 modkey = {<mod>, ...}
762 arglist = {<uicb-arg>, ...}
769 button = <integer> modkey = {<mod>, ...}
770 command = <uicb-cmd> arg = <uicb-arg>
774 button = <integer> modkey = {<mod>, ...}
775 command = <uicb-cmd> arg = <uicb-arg>
778 ..............................................
783 Check awesome's wiki: http://awesome.naquadah.org/wiki/
785 Simple textbox example
786 ~~~~~~~~~~~~~~~~~~~~~~
787 ..............................................
788 1. Add an include directive into ~/.awesomerc
791 include(~/.awesome/bottom-status-bar)
793 2. Create ~/.awesome/bottom-status-bar
801 3. Check the configuration file for errors
804 Configuration file OK.
806 Note: If you see anything other than "Configuration file OK." you have a
809 4. Create ~/bin/awesome-clock
814 echo "0 widget_tell clock text `date`"
815 echo "" # an empty line flushes data inside awesome
817 done | awesome-client
819 Note: What we're saying is "awesome-client, tell widget 'clock' to set
820 it's 'text' property to date's output".
822 5. Make your ~/bin/awesome-clock executable
824 $ chmod a+x ~/bin/awesome-clock
828 ~/bin/awesome-clock &
833 8. If your didn't get what you were expecting, take a look at
834 ~/.xsession-errors or the terminal where X got started.
835 ..............................................
837 Simple progressbar example
838 ~~~~~~~~~~~~~~~~~~~~~~~~~~
839 ..............................................
841 1. Add an include directive into ~/.awesomerc
845 include(~/.awesome/bottom-status-bar)
848 2. Create ~/.awesome/bottom-status-bar
850 progressbar diskusage
854 bordercolor = "#006e96"
857 fg_center = "#daaf0a"
864 3. Check the configuration file for errors
867 Configuration file OK.
869 Note: If you see anything other than "Configuration file OK," you have a
872 4. Create ~/bin/awesome-diskusage
876 usage = `df /dev/sda5 | awk '/\/dev\/sda5/ { print 100-$5 }'`
877 echo "0 widget_tell diskusage data disk ${usage}"
878 echo "" # an empty line flushes data inside awesome
880 done | awesome-client
883 Note: What we're saying is "awesome-client, tell widget 'diskusage' to
884 set it's 'data' property named 'disk' to ${usage}."
886 5. Make ~/bin/awesome-diskusage executable
888 $ chmod a+x ~/bin/awesome-diskusage
892 ~/bin/awesome-diskusage &
897 8. If your didn't get what you were expecting, take a look at
898 ~/.xsession-errors or the terminal where X got started.
899 ..............................................
904 awesome(1) awesome-client(1)
909 This man page was written by Julien Danjou <julien@danjou.info>, Marco Candrian <mac@calmar.ws>
910 and Chris Ciulla <chris.ciulla@gmail.com> (Simple Examples).
914 http://awesome.naquadah.org