awesomerc.5.txt

   1 awesomerc(5)
   2 ===========
   3
   4 NAME
   5 ----
   6
   7 awesomerc - Configuration file for the 'awesome window manager'
   8
   9 SYNOPSIS
  10 --------
  11
  12 <item> [<argument>]
  13 {
  14     <option> = <value>
  15
  16     <item> [<argument>] { <option> = <value>, ... }
  17     ....
  18 }
  19
  20 <option> = <value>
  21
  22 include(file.conf)
  23
  24 DESCRIPTION
  25 -----------
  26
  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.
  29
  30 It is read at startup.
  31
  32 OPTIONS
  33 --------
  34 awesomerc contains 4 global sections: *screen*, *rules*, *keys* and *mouse* which
  35 are described here.
  36
  37 screen
  38 ~~~~~~
  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*, *colors*,
  41 *padding* and *statusbar*.
  42
  43 general
  44 ^^^^^^^
  45 General is a section containing some general options for this screen.
  46
  47 border::
  48     This defines the window borders size in pixel.
  49 font::
  50     This defines the general font used in awesome.
  51 new_become_master::
  52     If this is set to true, new windows will become the master window.
  53 new_get_focus::
  54     If this is set to true, new windows will get focus.
  55 opacity_unfocused::
  56     If this is set to true, non-focused windows will have this opacity.
  57     This requires an external XComposite manager.
  58 resize_hints::
  59     If this is set to true, resize hints given by the window will be respected.
  60     If this is set to false, window size will be forced.
  61     If you dislike gaps between windows, you should try to set it to false.
  62 sloppy_focus::
  63     If this is set to true, focus will be set to the window under the mouse. If not,
  64     you will have to click on a window to set it focused.
  65 sloppy_focus_raise::
  66     If this is set to true with sloppy_focus, when a window is focused with the mouse
  67     it will be raised on top of the windows stack.
  68 snap::
  69     Snap windows to the screen border when it is this pixel away only from the border.
  70 floating_placement::
  71     Select the floating placement algorithm to use when placing window.
  72
  73 tags
  74 ^^^^
  75 Tags is a section containing one or more tag sections, which defines a tag.
  76
  77 tag
  78 +++
  79 Tag is a section which contains several options defining a tag.
  80
  81 layout::
  82     Layout is a name of an available layout which will be set by default on this tag.
  83 mwfact::
  84     Set the default master width factor for this tag.
  85 ncol::
  86     Set the default number of columns for non-master windows for this tag.
  87 nmaster::
  88     Set the default number of windows which will be treated as master for this tag.
  89
  90 layouts
  91 ^^^^^^^
  92 Layouts is a section containing a layout list, where each layout is a layout section.
  93
  94 layout
  95 ++++++
  96 Layout is a section which define a layout. It has a title which is the algorithm to use.
  97
  98 image::
  99     Set the image path used to describe this layouts, useful in layoutinfo widget.
 100
 101 colors
 102 ^^^^^^
 103 Colors is a section containing the color parameters.
 104
 105 normal_fg::
 106     Set the normal foreground color.
 107 normal_bg::
 108     Set the normal background color.
 109 normal_border::
 110     Set the unfocused window's border color.
 111 focus_fg::
 112     Set the focused foreground color.
 113 focus_bg::
 114     Set the focused background color.
 115 focus_border::
 116     Set the focused window's border color.
 117 urgent_fg::
 118     Set the foreground color to use for urgent flag. This is mostly useful
 119     with the taglist widget which will use this color whenever a window sets its
 120     XUrgencyHint on a non-visible tag.
 121 urgent_bg::
 122    Set the background color to use for urgent flag.
 123
 124 padding
 125 ^^^^^^^
 126 Padding is a section containing screen padding parameters.
 127
 128 top::
 129     Set the top padding in pixel.
 130 bottom::
 131     Set the bottom padding in pixel.
 132 left::
 133     Set the left padding in pixel.
 134 right::
 135     Set the right padding in pixel.
 136
 137 statusbar
 138 ^^^^^^^^^
 139 Statusbar are sections containing statusbars parameters. Each statusbar section
 140 must have a title which is the statusbar name. Each statusbar can have none or
 141 several widgets (see WIDGETS section for more details) each one identified by its
 142 name.
 143
 144 position::
 145     Default statusbar position.
 146 height::
 147     Statusbar height. By default, is auto computed with font size.
 148 width::
 149     Statusbar width. By default, it will be whole screen.
 150
 151 rules
 152 ~~~~~
 153 Rules is a section containing a rule list to automatically configure windows.
 154
 155 rule
 156 ^^^^
 157 Rule are sections containing the auto-configuration options for one window.
 158
 159 name::
 160     Set the window name for name matching as a regular expression.
 161 xproperty_name::
 162     Set the name of the XProperty for XProperty matching.
 163 xproperty_value::
 164     Set the regular expression to match against the named XProperty's value.
 165 float::
 166     Set the window to be floating. One of auto, true or false. Defaults to auto.
 167 master::
 168     Set the window to be the master. One of auto, true or false. Defaults to
 169     auto.
 170 tags::
 171     Set the tags to be assigned to the window as a regular expression.
 172 screen::
 173     Set the screen the window should show up on.
 174 icon::
 175     Set the window's icon.
 176 opacity::
 177     Set the window's opacity.
 178
 179 keys
 180 ~~~~
 181 Keys is the section to define your keybindings in. It may consist of multiple
 182 key and keylist entries.
 183
 184 key
 185 ^^^
 186 In a key section you define a single keybinding.
 187
 188 key::
 189     The keysym you want to bind.
 190 mod::
 191     Modifiers that need to be pressed for this binding.
 192 command::
 193     The *uicb function* to call.
 194 arg::
 195     The argument to the *uicb function*, if needed.
 196
 197 keylist
 198 ^^^^^^^
 199 In a keylist you can define multiple very similar keybindings at once. For
 200 example you can define <Mod1>-{1..9} to switch the view to tag 1..9
 201 respectively.
 202
 203 keylist::
 204     The list of keysyms to bind.
 205 modkey::
 206     Modifiers that need to be pressed for these bindings.
 207 command::
 208     The *uicb function* to call.
 209 arglist::
 210     The list of arguments to the *uicb function*, if needed. *Must* match the
 211     length of *keylist*.
 212
 213 mouse
 214 ~~~~~
 215 In the mouse section you may define mouse button bindings for the root and
 216 client windows.
 217
 218 client
 219 ^^^^^^
 220 Defines a mouse button binding for events on clients.
 221
 222 button::
 223     The mouse button you want to bind.
 224 modkey::
 225     Modifiers that need to be pressed for this binding.
 226 command::
 227     The *uicb function* to call.
 228 arg::
 229     The argument to the *uicb function*, if needed.
 230
 231 root
 232 ^^^^
 233 Defines a mouse button binding for events on the root window.
 234
 235 button::
 236     The mouse button you want to bind.
 237 modkey::
 238     Modifiers that need to be pressed for this binding.
 239 command::
 240     The *uicb function* to call.
 241 arg::
 242     The argument to the *uicb function*, if needed.
 243
 244 UICB FUNCTIONS
 245 --------------
 246
 247 In awesome, a lot of *functions* are available. These functions are called
 248 uicb (User Interface Call Backs). Each function can be bound to a key shortcut
 249 or a mouse button.
 250
 251 General
 252 ~~~~~~~
 253 *quit*::
 254     This function quits awesome.
 255 *statusbar_toggle* statusbar-identifier::
 256     Hide or show statusbar (with no argument, toggle all).
 257 *spawn* client::
 258     Execute an external program.
 259 *exec* program::
 260     Replace awesome with another window manager (or itself; i.e. reload config).
 261 *widget_tell* widget-identifier data::
 262     Feed information to your widgets.
 263
 264 Client
 265 ~~~~~~
 266 *client_kill*::
 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.
 275 *client_swapnext*::
 276     Swap window placement with the next displayed window.
 277 *client_swapprev*::
 278     Swap window placement with the previous displayed window.
 279 *client_focusnext*::
 280     Focus next window.
 281 *client_focusprev*::
 282     Focus previous window.
 283 *client_togglemax*::
 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.
 291 *client_zoom*::
 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.
 297 *client_toggletag*::
 298     Add or remove tag to focused window.
 299 *client_movemouse*::
 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
 308 Tag
 309 ~~~
 310 *tag_setlayout* relative or absolute integer::
 311     Set layout number; or just switch to the next layout for current tag.
 312 *tag_toggleview* tag::
 313     Add windows tagged with tag number to current display.
 314 *tag_view* tag number::
 315     View windows tagged with tag number.
 316 *tag_viewnext*::
 317     Show windows tagged with next tag in list.
 318 *tag_viewprev*::
 319     Show windows tagged with previous tag in list.
 320 *tag_prev_selected*::
 321     Switch back to the previously displayed set of tags.
 322 *tag_setmwfact* relative or absolute float::
 323     Set master width factor.
 324 *tag_setncol* relative or absolute integer::
 325     Set number of columns for non-master windows.
 326 *tag_setnmaster* relative or absolute integer::
 327     Set number of master windows.
 328 *tag_create* name::
 329     Create a new tag with that name.
 330
 331 Focus
 332 ~~~~~
 333 *focus_client_byname* string::
 334     Give client focus by its name.
 335 *focus_history* negative number::
 336     Focus the client that had focused nth focus switch earlier.
 337
 338 Screen
 339 ~~~~~~
 340 *screen_focus* relative or absolute integer::
 341     Select Screen and focus first window and move mouse.
 342
 343 WIDGETS
 344 -------
 345 Statusbars can be customized by modifying widgets names, order and options.
 346
 347 taglist
 348 ~~~~~~~
 349 This widget shows the tag list.
 350
 351 *mouse*::
 352     Set mouse bindings.
 353 *x*::
 354     Horizontal offset (auto-alignment if not set).
 355 *y*::
 356     Vertical offset (auto-alignment if not set).
 357 *align*::
 358     Widget alignment.
 359
 360 layoutinfo
 361 ~~~~~~~~~~
 362 This widget shows a icon for the selected layout.
 363
 364 *mouse*::
 365     Set mouse bindings.
 366 *x*::
 367     Horizontal offset (auto-alignment if not set).
 368 *y*::
 369     Vertical offset (auto-alignment if not set).
 370 *align*::
 371     Widget alignment.
 372
 373 focusicon
 374 ~~~~~~~~~
 375 This widget shows a icon for the focused window  using NET_WM_ICON or icon file set in rule.
 376
 377 *mouse*::
 378     Set mouse bindings.
 379 *x*::
 380     Horizontal offset (auto-alignment if not set).
 381 *y*::
 382     Vertical offset (auto-alignment if not set).
 383 *align*::
 384     Widget alignment.
 385
 386 tasklist
 387 ~~~~~~~~
 388 This widget shows a list of running windows.
 389
 390 *mouse*::
 391     Set mouse bindings.
 392 *font*::
 393     Font to use.
 394 *bg*::
 395     Background color.
 396 *fg*::
 397     Foreground color.
 398 *focus_bg*::
 399     Background color for focused window.
 400 *focus_fg*::
 401     Foreground color for focused window.
 402 *text_align*::
 403     Text alignement.
 404 *show_icons*::
 405     Show applications icons.
 406 *show*::
 407     Show all windows from all tags, tags clients only or focused client.
 408 *x*::
 409     Horizontal offset (auto-alignment if not set).
 410 *y*::
 411     Vertical offset (auto-alignment if not set).
 412
 413 textbox
 414 ~~~~~~~
 415 This widget shows a text.
 416
 417 *mouse*::
 418     Set mouse bindings.
 419 *font*::
 420     Font to use.
 421 *bg*::
 422     Background color.
 423 *fg*::
 424     Foreground color.
 425 *width*::
 426     Set width.
 427 *text*::
 428     Text to change.
 429 *text_align*::
 430     Text alignement.
 431 *x*::
 432     Horizontal offset (auto-alignment if not set).
 433 *y*::
 434     Vertical offset (auto-alignment if not set).
 435 *align*::
 436     Widget alignment.
 437
 438 iconbox
 439 ~~~~~~~
 440 This widget shows an icon.
 441
 442 *mouse*::
 443     Set mouse bindings.
 444 *image*::
 445     Image file.
 446 *resize*::
 447     Resize icon to fit into statusbar.
 448 *x*::
 449     Horizontal offset (auto-alignment if not set).
 450 *y*::
 451     Vertical offset (auto-alignment if not set).
 452 *align*::
 453     Widget alignment.
 454
 455 progressbar
 456 ~~~~~~~~~~~
 457 This widget shows one or more progress-bars.
 458
 459 *data*::
 460     Draws a bar for each data section;
 461     Options: reverse, fg, fg_center, fg_end, bg, bordercolor.
 462 *reverse*::
 463     Reverse/mirror the bar.
 464 *fg*::
 465     Foreground color.
 466 *fg_center*::
 467     Foreground color in the center of the bar (as gradient).
 468 *fg_end*::
 469     Foreground color at the end of a bar (as gradient).
 470 *bg*::
 471     Background color.
 472 *bordercolor*::
 473     Border color.
 474 *mouse*::
 475     Set mouse bindings.
 476 *width*::
 477     Set width.
 478 *height*::
 479     Set height (i.e. 0.9 = 90%)
 480 *padding*::
 481     Empty space on both sides.
 482 *x*::
 483     Horizontal offset (auto-alignment if not set).
 484 *y*::
 485     Vertical offset (auto-alignment if not set).
 486 *align*::
 487     Widget alignment.
 488
 489 graph
 490 ~~~~~
 491 This widget shows a graph.
 492
 493 *data*::
 494     Defines a data-stream section;
 495     Options: max, scale, fg, fg_center, fg_end and style.
 496 *max*::
 497     This value prints a full graph (default = 100)
 498 *scale*::
 499     Re-scales when input > max (see below).
 500 *fg*::
 501     Foreground color.
 502 *fg_center*::
 503     Foreground color in the center of the bar (as gradient).
 504 *fg_end*::
 505     Foreground color at the end of a bar (as gradient).
 506 *style*::
 507     bottom (fills to bottom with fg), top, or line.
 508 *mouse*::
 509     Set mouse bindings.
 510 *width*::
 511     Set width.
 512 *height*::
 513     Set height (i.e. 0.9 = 90%)
 514 *padding_left*::
 515     Empty space on the left.
 516 *bg*::
 517     Background color.
 518 *bordercolor*::
 519     Border color.
 520 *x*::
 521     Horizontal offset (auto-alignment if not set).
 522 *y*::
 523     Vertical offset (auto-alignment if not set).
 524 *align*::
 525     Widget alignment.
 526
 527 FORMAT
 528 ------
 529 Here is the global configuration file format, with a list of options
 530 and possible values.
 531
 532 ..............................................
 533 Note: when there is no whitespace, quotes are optional.
 534
 535 <boolean>       -> "true" or "false"
 536 <color>         -> #ff9933 (hexadecimal color notation: #red green blue)
 537 <float>         -> 0.3, 0,8 (often values between 0 and 1 are useful)
 538 <font>          -> Xft font: mono-10, fixed-12, sans-8, ...
 539 <identifier>    -> foobar (choose a name/string)
 540 <image>         -> "/home/awesome/pics/icon.png" (path to image)
 541 <integer>       -> 1, 10, -3 (positive numbers are required mostly)
 542 <key>           -> a, 1, F10 (see /usr/include/X11/keysymdef.h w/o XK_ or 'xev')
 543                    or a keycode beginning with #
 544 <mod>           -> "Mod1", "Mod4", "Control" (modifiers)
 545 <regex>         -> regular expression
 546 <string>        -> "foo bar"
 547 <uicb-arg>      -> prog, 3... (argument to a uicb function, where required)
 548 <uicb-cmd>      -> spawn, exec, client_tag... (see UICB FUNCTIONS above)
 549 <{.., ...}>     -> list of available options
 550
 551 [MULTI] means, you can use an item multiple times.
 552
 553
 554
 555 screen <integer> [MULTI]
 556 {
 557     general
 558     {
 559         border = <integer>
 560         font = <font>
 561         new_become_master = <boolean>
 562         new_get_focus = <boolean>
 563         opacity_unfocused = <integer>
 564         resize_hints = <boolean>
 565         sloppy_focus = <boolean>
 566         sloppy_focus_raise = <boolean>
 567         snap = <integer>
 568         floating_placement = <{smart,under_mouse}>
 569         text_shadow_offset = <int>
 570         mwfact_lower_limit = <float>
 571         mwfact_upper_limit = <float>
 572     }
 573     tags
 574     {
 575         tag <identifier> [MULTI]
 576         {
 577             layout = <{dwindle,floating,max,
 578                      spiral,tile,tileleft,tilebottom,tiletop}>
 579             mwfact = <float>
 580             nmaster = <integer>
 581             ncol = <integer>
 582         }
 583     }
 584     layouts
 585     {
 586         layout <{dwindle,floating,max,
 587                  spiral,tile,tileleft,
 588                  tilebottom,tiletop}> { image = <image> } [MULTI]
 589     }
 590     colors
 591     {
 592         normal_fg = <color>
 593         normal_bg = <color>
 594         normal_border = <color>
 595         focus_fg = <color>
 596         focus_bg = <color>
 597         focus_border = <color>
 598         urgent_fg = <color>
 599         urgent_bg = <color>
 600     }
 601     padding
 602     {
 603         top = <integer>
 604         bottom = <integer>
 605         left = <integer>
 606         right = <integer>
 607     }
 608     statusbar <identifier> [MULTI]
 609     {
 610         position = <{top,bottom,left,right}>
 611         height = <integer>
 612         width = <integer>
 613
 614         taglist <identifier> [MULTI]
 615         {
 616             x = <integer> y = <integer>
 617             align = <{auto,right,left}>
 618             mouse [MULTI]
 619             {
 620                 button = <integer> modkey = {<mod>, ...}
 621                 command = <uicb-cmd> arg = <uicb-arg>
 622             }
 623         }
 624         layoutinfo <identifier>
 625         {
 626             x = <integer> y = <integer>
 627             align = <{auto,right,left}>
 628             mouse [MULTI]
 629             {
 630                 button = <integer> modkey = {<mod>, ...}
 631                 command = <uicb-cmd> arg = <uicb-arg>
 632             }
 633         }
 634         focusicon <identifier>
 635         {
 636             x = <integer> y = <integer>
 637             align = <{auto,right,left}>
 638             mouse [MULTI]
 639             {
 640                 button = <integer> modkey = {<mod>, ...}
 641                 command = <uicb-cmd> arg = <uicb-arg>
 642             }
 643         }
 644         tasklist <identifier>
 645         {
 646             fg = <color>
 647             bg = <color>
 648             focus_fg = <color>
 649             focus_bg = <color>
 650             font = <font>
 651             show_icons = <boolean>
 652             show = <{all,tags,focus}>
 653             text_align = <{center,left,right}>
 654             x = <integer> y = <integer>
 655             mouse [MULTI]
 656             {
 657                 command = <uicb-cmd> arg = <uicb-arg>
 658                 button = <integer> modkey = {<mod>, ...}
 659             }
 660         }
 661         textbox <identifier> [MULTI]
 662         {
 663             text = <string>
 664             bg = <color>
 665             fg = <color>
 666             font = <font>
 667             width = <integer>
 668             text_align = <{center,left,right}>
 669             x = <integer> y = <integer>
 670             align = <{auto,right,left}>
 671             mouse [MULTI]
 672             {
 673                 button = <integer> modkey = {<mod>, ...}
 674                 command = <uicb-cmd> arg = <uicb-arg>
 675             }
 676         }
 677         iconbox <identifier> [MULTI]
 678         {
 679             image = <image>
 680             resize = <boolean>
 681             x = <integer> y = <integer>
 682             align = <{auto,right,left}>
 683             mouse [MULTI]
 684             {
 685                 button = <integer> modkey = {<mod>, ...}
 686                 command = <uicb-cmd> arg = <uicb-arg>
 687             }
 688         }
 689         progressbar <identifier> [MULTI]
 690         {
 691             data [MULTI]
 692             {
 693                 reverse = <boolean> bg = <color> bordercolor = <color>
 694                 fg = <color> fg_center = <color> fg_end = <color>
 695             }
 696             gap = <integer>
 697             width = <integer>
 698             height = <float>
 699             padding = <integer>
 700             x = <integer> y = <integer>
 701             align = <{auto,right,left}>
 702             mouse [MULTI]
 703             {
 704                 button = <integer> modkey = {<mod>, ...}
 705                 command = <uicb-cmd> arg = <uicb-arg>
 706             }
 707         }
 708         graph <identifier> [MULTI]
 709         {
 710             data [MULTI]
 711             {
 712                 scale = <boolean> max = <float> style = <{bottom, top, line}>
 713                 fg = <color> fg_center = <color> fg_end = <color>
 714             }
 715             width = <integer>
 716             height = <float>
 717             padding_left = <integer>
 718             bg = <color>
 719             bordercolor = <color>
 720             x = <integer> y = <integer>
 721             align = <{auto,right,left}>
 722             mouse [MULTI]
 723             {
 724                 button = <integer> modkey = {<mod>, ...}
 725                 command = <uicb-cmd> arg = <uicb-arg>
 726             }
 727         }
 728     }
 729 }
 730 rules
 731 {
 732     rule [MULTI]
 733     {
 734         name = <regex>
 735         xproperty_name = <string>
 736         xproperty_value = <regex>
 737         float = <{auto,true,false}>
 738         master = <{auto,true,false}>
 739         tags = <regex>
 740         screen = <integer>
 741         icon = <image>
 742         opacity = <float>
 743     }
 744 }
 745 keys
 746 {
 747     key [MULTI]
 748     {
 749         key = <key> modkey = {<mod>, ...}
 750         command = <uicb-cmd> arg = <uicb-arg>
 751     }
 752     keylist [MULTI]
 753     {
 754         keylist = {<key>, ...}
 755         modkey = {<mod>, ...}
 756         command = <uicb-cmd>
 757         arglist = {<uicb-arg>, ...}
 758     }
 759 }
 760 mouse
 761 {
 762     client [MULTI]
 763     {
 764         button = <integer> modkey = {<mod>, ...}
 765         command = <uicb-cmd> arg = <uicb-arg>
 766     }
 767     root [MULTI]
 768     {
 769         button = <integer> modkey = {<mod>, ...}
 770         command = <uicb-cmd> arg = <uicb-arg>
 771     }
 772 }
 773 ..............................................
 774
 775 EXAMPLES
 776 --------
 777
 778 Check awesome's wiki: http://awesome.naquadah.org/wiki/
 779
 780
 781 SEE ALSO
 782 --------
 783 awesome(1) awesome-client(1)
 784
 785
 786 AUTHORS
 787 -------
 788 This man page was written by Julien Danjou <julien@danjou.info> and Marco Candrian <mac@calmar.ws>.
 789
 790 WWW
 791 ---
 792 http://awesome.naquadah.org