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 *bar*::
 460     Draws a bar; Options: fg, bg, bordercolor.
 461 *fg*::
 462     Foreground color.
 463 *fg_center*::
 464     Foreground color in the center of the bar (as gradient).
 465 *fg_end*::
 466     Foreground color at the end of a bar (as gradient).
 467 *bg*::
 468     Background color.
 469 *bordercolor*::
 470     Border color.
 471 *mouse*::
 472     Set mouse bindings.
 473 *width*::
 474     Set width.
 475 *height*::
 476     Set height (i.e. 0.9 = 90%)
 477 *padding*::
 478     Empty space on both sides.
 479 *x*::
 480     Horizontal offset (auto-alignment if not set).
 481 *y*::
 482     Vertical offset (auto-alignment if not set).
 483 *align*::
 484     Widget alignment.
 485
 486 graph
 487 ~~~~~
 488 This widget shows a graph.
 489
 490 *data*::
 491     Defines a data-stream section; Options: max, scale, fg and style.
 492 *max*::
 493     This value prints a full graph (default = 100)
 494 *scale*::
 495     Re-scales when input > max (see below).
 496 *fg*::
 497     Foreground color.
 498 *fg_center*::
 499     Foreground color in the center of the bar (as gradient).
 500 *fg_end*::
 501     Foreground color at the end of a bar (as gradient).
 502 *style*::
 503     bottom (fills to bottom with fg), top, or line.
 504 *mouse*::
 505     Set mouse bindings.
 506 *width*::
 507     Set width.
 508 *height*::
 509     Set height (i.e. 0.9 = 90%)
 510 *padding_left*::
 511     Empty space on the left.
 512 *bg*::
 513     Background color.
 514 *bordercolor*::
 515     Border color.
 516 *x*::
 517     Horizontal offset (auto-alignment if not set).
 518 *y*::
 519     Vertical offset (auto-alignment if not set).
 520 *align*::
 521     Widget alignment.
 522
 523 FORMAT
 524 ------
 525 Here is the global configuration file format, with a list of options
 526 and possible values.
 527
 528 ..............................................
 529 Note: when there is no whitespace, quotes are optional.
 530
 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>          -> Xft font: mono-10, fixed-12, sans-8, ...
 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 <{.., ...}>     -> list of available options
 546
 547 [MULTI] means, you can use an item multiple times.
 548
 549
 550
 551 screen <integer> [MULTI]
 552 {
 553     general
 554     {
 555         border = <integer>
 556         font = <font>
 557         new_become_master = <boolean>
 558         new_get_focus = <boolean>
 559         opacity_unfocused = <integer>
 560         resize_hints = <boolean>
 561         sloppy_focus = <boolean>
 562         sloppy_focus_raise = <boolean>
 563         snap = <integer>
 564         floating_placement = <{smart,under_mouse}>
 565     }
 566     tags
 567     {
 568         tag <identifier> [MULTI]
 569         {
 570             layout = <{dwindle,floating,max,
 571                      spiral,tile,tileleft,tilebottom,tiletop}>
 572             mwfact = <float>
 573             nmaster = <integer>
 574             ncol = <integer>
 575         }
 576     }
 577     layouts
 578     {
 579         layout <{dwindle,floating,max,
 580                  spiral,tile,tileleft,
 581                  tilebottom,tiletop}> { image = <image> } [MULTI]
 582     }
 583     colors
 584     {
 585         normal_fg = <color>
 586         normal_bg = <color>
 587         normal_border = <color>
 588         focus_fg = <color>
 589         focus_bg = <color>
 590         focus_border = <color>
 591         urgent_fg = <color>
 592         urgent_bg = <color>
 593     }
 594     padding
 595     {
 596         top = <integer>
 597         bottom = <integer>
 598         left = <integer>
 599         right = <integer>
 600     }
 601     statusbar <identifier> [MULTI]
 602     {
 603         position = <{top,bottom,left,right}>
 604         height = <integer>
 605         width = <integer>
 606
 607         taglist <identifier> [MULTI]
 608         {
 609             x = <integer> y = <integer>
 610             align = <{auto,right,left}>
 611             mouse [MULTI]
 612             {
 613                 button = <integer> modkey = {<mod>, ...}
 614                 command = <uicb-cmd> arg = <uicb-arg>
 615             }
 616         }
 617         layoutinfo <identifier>
 618         {
 619             x = <integer> y = <integer>
 620             align = <{auto,right,left}>
 621             mouse [MULTI]
 622             {
 623                 button = <integer> modkey = {<mod>, ...}
 624                 command = <uicb-cmd> arg = <uicb-arg>
 625             }
 626         }
 627         focusicon <identifier>
 628         {
 629             x = <integer> y = <integer>
 630             align = <{auto,right,left}>
 631             mouse [MULTI]
 632             {
 633                 button = <integer> modkey = {<mod>, ...}
 634                 command = <uicb-cmd> arg = <uicb-arg>
 635             }
 636         }
 637         tasklist <identifier>
 638         {
 639             fg = <color>
 640             bg = <color>
 641             focus_fg = <color>
 642             focus_bg = <color>
 643             font = <font>
 644             show_icons = <boolean>
 645             show = <{all,tags,focus}>
 646             text_align = <{center,left,right}>
 647             x = <integer> y = <integer>
 648             mouse [MULTI]
 649             {
 650                 command = <uicb-cmd> arg = <uicb-arg>
 651                 button = <integer> modkey = {<mod>, ...}
 652             }
 653         }
 654         textbox <identifier> [MULTI]
 655         {
 656             text = <string>
 657             bg = <color>
 658             fg = <color>
 659             font = <font>
 660             width = <integer>
 661             text_align = <{center,left,right}>
 662             x = <integer> y = <integer>
 663             align = <{auto,right,left}>
 664             mouse [MULTI]
 665             {
 666                 button = <integer> modkey = {<mod>, ...}
 667                 command = <uicb-cmd> arg = <uicb-arg>
 668             }
 669         }
 670         iconbox <identifier> [MULTI]
 671         {
 672             image = <image>
 673             resize = <boolean>
 674             x = <integer> y = <integer>
 675             align = <{auto,right,left}>
 676             mouse [MULTI]
 677             {
 678                 button = <integer> modkey = {<mod>, ...}
 679                 command = <uicb-cmd> arg = <uicb-arg>
 680             }
 681         }
 682         progressbar <identifier> [MULTI]
 683         {
 684             bar [MULTI]
 685             {
 686                 fg = <color> fg_center = <color> fg_end = <color>
 687                 bg = <color> bordercolor = <color>
 688             }
 689             gap = <integer>
 690             width = <integer>
 691             height = <float>
 692             padding = <integer>
 693             x = <integer> y = <integer>
 694             align = <{auto,right,left}>
 695             mouse [MULTI]
 696             {
 697                 button = <integer> modkey = {<mod>, ...}
 698                 command = <uicb-cmd> arg = <uicb-arg>
 699             }
 700         }
 701         graph <identifier> [MULTI]
 702         {
 703             data [MULTI]
 704             {
 705                 scale = <boolean> max = <float> style = <{bottom, top, line}>
 706                 fg = <color> fg_center = <color> fg_end = <color>
 707             }
 708             width = <integer>
 709             height = <float>
 710             padding_left = <integer>
 711             bg = <color>
 712             bordercolor = <color>
 713             x = <integer> y = <integer>
 714             align = <{auto,right,left}>
 715             mouse [MULTI]
 716             {
 717                 button = <integer> modkey = {<mod>, ...}
 718                 command = <uicb-cmd> arg = <uicb-arg>
 719             }
 720         }
 721     }
 722 }
 723 rules
 724 {
 725     rule [MULTI]
 726     {
 727         name = <regex>
 728         xproperty_name = <string>
 729         xproperty_value = <regex>
 730         float = <{auto,true,false}>
 731         master = <{auto,true,false}>
 732         tags = <regex>
 733         screen = <integer>
 734         icon = <image>
 735         opacity = <float>
 736     }
 737 }
 738 keys
 739 {
 740     key [MULTI]
 741     {
 742         key = <key> modkey = {<mod>, ...}
 743         command = <uicb-cmd> arg = <uicb-arg>
 744     }
 745     keylist [MULTI]
 746     {
 747         keylist = {<key>, ...}
 748         modkey = {<mod>, ...}
 749         command = <uicb-cmd>
 750         arglist = {<uicb-arg>, ...}
 751     }
 752 }
 753 mouse
 754 {
 755     client [MULTI]
 756     {
 757         button = <integer> modkey = {<mod>, ...}
 758         command = <uicb-cmd> arg = <uicb-arg>
 759     }
 760     root [MULTI]
 761     {
 762         button = <integer> modkey = {<mod>, ...}
 763         command = <uicb-cmd> arg = <uicb-arg>
 764     }
 765 }
 766 ..............................................
 767
 768 EXAMPLES
 769 --------
 770
 771 Check awesome's wiki: http://awesome.naquadah.org/wiki/
 772
 773
 774 SEE ALSO
 775 --------
 776 awesome(1) awesome-client(1)
 777
 778
 779 AUTHORS
 780 -------
 781 This man page was written by Julien Danjou <julien@danjou.info> and Marco Candrian <mac@calmar.ws>.
 782
 783 WWW
 784 ---
 785 http://awesome.naquadah.org