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 100, 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 100, 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}> }
553 [MULTI] means, you can use an item multiple times.
556 screen <integer> [MULTI]
561 new_become_master = <boolean>
562 new_get_focus = <boolean>
563 opacity_unfocused = <integer>
564 opacity_focused = <integer>
565 resize_hints = <boolean>
566 sloppy_focus = <boolean>
567 sloppy_focus_raise = <boolean>
569 floating_placement = <{smart,under_mouse}>
570 mwfact_lower_limit = <float>
571 mwfact_upper_limit = <float>
579 tag <identifier> [MULTI]
581 layout = <{dwindle,floating,max,
582 spiral,tile,tileleft,tilebottom,tiletop}>
590 layout <{dwindle,floating,max,
591 spiral,tile,tileleft,
592 tilebottom,tiletop}> { image = <image> } [MULTI]
596 normal { <style section> }
597 focus { <style section> }
598 urgent { <style section> }
607 statusbar <identifier> [MULTI]
609 position = <{top,bottom,left,right,off}>
613 taglist <identifier> [MULTI]
615 x = <integer> y = <integer>
616 align = <{auto,right,left}>
619 button = <integer> modkey = {<mod>, ...}
620 command = <uicb-cmd> arg = <uicb-arg>
623 layoutinfo <identifier>
625 x = <integer> y = <integer>
626 align = <{auto,right,left}>
629 button = <integer> modkey = {<mod>, ...}
630 command = <uicb-cmd> arg = <uicb-arg>
633 focusicon <identifier>
635 x = <integer> y = <integer>
636 align = <{auto,right,left}>
639 button = <integer> modkey = {<mod>, ...}
640 command = <uicb-cmd> arg = <uicb-arg>
643 tasklist <identifier>
647 normal { <style section> }
648 focus { <style section> }
650 show_icons = <boolean>
651 show = <{all,tags,focus}>
652 text_align = <{center,left,right}>
653 x = <integer> y = <integer>
656 command = <uicb-cmd> arg = <uicb-arg>
657 button = <integer> modkey = {<mod>, ...}
660 textbox <identifier> [MULTI]
662 style { <style section> }
665 text_align = <{center,left,right}>
666 x = <integer> y = <integer>
667 align = <{auto,right,left}>
670 button = <integer> modkey = {<mod>, ...}
671 command = <uicb-cmd> arg = <uicb-arg>
674 iconbox <identifier> [MULTI]
678 x = <integer> y = <integer>
679 align = <{auto,right,left}>
682 button = <integer> modkey = {<mod>, ...}
683 command = <uicb-cmd> arg = <uicb-arg>
686 progressbar <identifier> [MULTI]
690 reverse = <boolean> bg = <color> bordercolor = <color>
691 fg = <color> fg_center = <color> fg_end = <color>
698 x = <integer> y = <integer>
699 align = <{auto,right,left}>
702 button = <integer> modkey = {<mod>, ...}
703 command = <uicb-cmd> arg = <uicb-arg>
706 graph <identifier> [MULTI]
710 scale = <boolean> max = <float> draw_style = <{bottom, top, line}>
711 fg = <color> fg_center = <color> fg_end = <color>
712 vertical_gradient = <boolean>
716 padding_left = <integer>
717 grow = <{left, right}>
719 bordercolor = <color>
720 x = <integer> y = <integer>
721 align = <{auto,right,left}>
724 button = <integer> modkey = {<mod>, ...}
725 command = <uicb-cmd> arg = <uicb-arg>
735 xproperty_name = <string>
736 xproperty_value = <regex>
737 float = <{auto,true,false}>
738 master = <{auto,true,false}>
753 key = <key> modkey = {<mod>, ...}
754 command = <uicb-cmd> arg = <uicb-arg>
758 keylist = {<key>, ...}
759 modkey = {<mod>, ...}
761 arglist = {<uicb-arg>, ...}
768 button = <integer> modkey = {<mod>, ...}
769 command = <uicb-cmd> arg = <uicb-arg>
773 button = <integer> modkey = {<mod>, ...}
774 command = <uicb-cmd> arg = <uicb-arg>
777 ..............................................
782 Check awesome's wiki: http://awesome.naquadah.org/wiki/
784 Simple textbox example
785 ~~~~~~~~~~~~~~~~~~~~~~
786 ..............................................
787 1. Add an include directive into ~/.awesomerc
790 include(~/.awesome/bottom-status-bar)
792 2. Create ~/.awesome/bottom-status-bar
800 3. Check the configuration file for errors
803 Configuration file OK.
805 Note: If you see anything other than "Configuration file OK." you have a
808 4. Create ~/bin/awesome-clock
813 echo "0 widget_tell clock text `date`"
814 echo "" # an empty line flushes data inside awesome
816 done | awesome-client
818 Note: What we're saying is "awesome-client, tell widget 'clock' to set
819 it's 'text' property to date's output".
821 5. Make your ~/bin/awesome-clock executable
823 $ chmod a+x ~/bin/awesome-clock
827 ~/bin/awesome-clock &
832 8. If your didn't get what you were expecting, take a look at
833 ~/.xsession-errors or the terminal where X got started.
834 ..............................................
836 Simple progressbar example
837 ~~~~~~~~~~~~~~~~~~~~~~~~~~
838 ..............................................
840 1. Add an include directive into ~/.awesomerc
844 include(~/.awesome/bottom-status-bar)
847 2. Create ~/.awesome/bottom-status-bar
849 progressbar diskusage
853 bordercolor = "#006e96"
856 fg_center = "#daaf0a"
863 3. Check the configuration file for errors
866 Configuration file OK.
868 Note: If you see anything other than "Configuration file OK," you have a
871 4. Create ~/bin/awesome-diskusage
875 usage = `df /dev/sda5 | awk '/\/dev\/sda5/ { print 100-$5 }'`
876 echo "0 widget_tell diskusage data disk ${usage}"
877 echo "" # an empty line flushes data inside awesome
879 done | awesome-client
882 Note: What we're saying is "awesome-client, tell widget 'diskusage' to
883 set it's 'data' property named 'disk' to ${usage}."
885 5. Make ~/bin/awesome-diskusage executable
887 $ chmod a+x ~/bin/awesome-diskusage
891 ~/bin/awesome-diskusage &
896 8. If your didn't get what you were expecting, take a look at
897 ~/.xsession-errors or the terminal where X got started.
898 ..............................................
903 awesome(1) awesome-client(1)
908 This man page was written by Julien Danjou <julien@danjou.info>, Marco Candrian <mac@calmar.ws>
909 and Chris Ciulla <chris.ciulla@gmail.com> (Simple Examples).
913 http://awesome.naquadah.org