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 UICB FUNCTIONS
  33 --------------
  34
  35 In awesome, a lot of *functions* are available. These functions are called
  36 uicb (User Interface Call Backs). Each function can be bound to a key shortcut
  37 or a mouse button.
  38
  39 General
  40 ~~~~~~~
  41 *quit*::
  42     This function quits awesome.
  43 *statusbar_toggle* statusbar-identifier::
  44     Hide or show statusbar (with no argument, toggle all).
  45 *spawn* client::
  46     Execute an external program.
  47 *exec* program::
  48     Replace awesome with another window manager (or itself; i.e. reload config).
  49 *widget_tell* widget-identifier data::
  50     Feed information to your widgets.
  51
  52 Client
  53 ~~~~~~
  54 *client_kill*::
  55     Closes the focused client.
  56 *client_moveresize* x y width height::
  57     Dynamically move and resize floating windows.
  58     Coordinates can be relative or absolute. Relative values must begin with + or -.
  59     E.g: to move a window 10 pixels up: "+0 \+10 +0 +0" To move a window
  60     in the upper left corner and increase its width by 10px: "0 0 \+0 +10"
  61 *client_settrans* float::
  62     Set client transparency, number can be a relative or absolute floating number in percentage.
  63 *client_swapnext*::
  64     Swap window placement with the next displayed window.
  65 *client_swapprev*::
  66     Swap window placement with the previous displayed window.
  67 *client_focusnext*::
  68     Focus next window.
  69 *client_focusprev*::
  70     Focus previous window.
  71 *client_togglemax*::
  72     Set window fullscreen. Calling this function another time will reset the window to its previous state.
  73 *client_togglehorizontalmax*::
  74     Set window's horizontal size to display width. Calling another time will reset the window to its previous state.
  75 *client_toggleverticalmax*::
  76     Set window's vertical size to display height. Calling another time will reset the window to its previous state.
  77 *client_togglefloating*::
  78     Set window floating or tiled.
  79 *client_zoom*::
  80     Set window as master window.
  81 *client_movetoscreen* relative or absolute integer::
  82     Move focused window to the nth screen, or next (+1) or previous (-1). If no screen_number is set, move to the next screen.
  83 *client_tag* tag number::
  84     Tag focused window with this tag.
  85 *client_toggletag*::
  86     Add or remove tag to focused window.
  87 *client_movemouse*::
  88     Move client window with mouse.
  89 *client_resizemouse*::
  90     Resize client window with mouse.
  91 *client_setscratch*::
  92     Set or unset client as being the scratch window.
  93 *client_togglescratch*::
  94     Toggle scratch window.
  95
  96 Tag
  97 ~~~
  98 *tag_setlayout* relative or absolute integer::
  99     Set layout number; or just switch to the next layout for current tag.
 100 *tag_toggleview* tag::
 101     Add windows tagged with tag number to current display.
 102 *tag_view* tag number::
 103     View windows tagged with tag number.
 104 *tag_viewnext*::
 105     Show windows tagged with next tag in list.
 106 *tag_viewprev*::
 107     Show windows tagged with previous tag in list.
 108 *tag_prev_selected*::
 109     Switch back to the previously displayed set of tags.
 110 *tag_setmwfact* relative or absolute float::
 111     Set master width factor.
 112 *tag_setncol* relative or absolute integer::
 113     Set number of columns for non-master windows.
 114 *tag_setnmaster* relative or absolute integer::
 115     Set number of master windows.
 116 *tag_create* name::
 117     Create a new tag with that name.
 118
 119 Focus
 120 ~~~~~
 121 *focus_client_byname* string::
 122     Give client focus by its name.
 123 *focus_history* negative number::
 124     Focus the client that had focused nth focus switch earlier.
 125
 126 Screen
 127 ~~~~~~
 128 *screen_focus* relative or absolute integer::
 129     Select Screen and focus first window and move mouse.
 130
 131 WIDGETS
 132 -------
 133 Statusbars can be customized by modifying widgets names, order and options.
 134
 135 taglist
 136 ~~~~~~~
 137 This widget shows the tag list.
 138
 139 *mouse*::
 140     Set mouse bindings.
 141 *x*::
 142     Horizontal offset (auto-alignment if not set).
 143 *y*::
 144     Vertical offset (auto-alignment if not set).
 145 *align*::
 146     Widget alignment.
 147
 148 layoutinfo
 149 ~~~~~~~~~~
 150 This widget shows a icon for the selected layout.
 151
 152 *mouse*::
 153     Set mouse bindings.
 154 *x*::
 155     Horizontal offset (auto-alignment if not set).
 156 *y*::
 157     Vertical offset (auto-alignment if not set).
 158 *align*::
 159     Widget alignment.
 160
 161 focusicon
 162 ~~~~~~~~~
 163 This widget shows a icon for the focused window  using NET_WM_ICON or icon file set in rule.
 164
 165 *mouse*::
 166     Set mouse bindings.
 167 *x*::
 168     Horizontal offset (auto-alignment if not set).
 169 *y*::
 170     Vertical offset (auto-alignment if not set).
 171 *align*::
 172     Widget alignment.
 173
 174 tasklist
 175 ~~~~~~~~
 176 This widget shows a list of running windows.
 177
 178 *mouse*::
 179     Set mouse bindings.
 180 *font*::
 181     Font to use.
 182 *bg*::
 183     Background color.
 184 *fg*::
 185     Foreground color.
 186 *focus_bg*::
 187     Background color for focused window.
 188 *focus_fg*::
 189     Foreground color for focused window.
 190 *text_align*::
 191     Text alignement.
 192 *show_icons*::
 193     Show applications icons.
 194 *show*::
 195     Show all windows from all tags, tags clients only or focused client.
 196 *x*::
 197     Horizontal offset (auto-alignment if not set).
 198 *y*::
 199     Vertical offset (auto-alignment if not set).
 200
 201 textbox
 202 ~~~~~~~
 203 This widget shows a text.
 204
 205 *mouse*::
 206     Set mouse bindings.
 207 *font*::
 208     Font to use.
 209 *bg*::
 210     Background color.
 211 *fg*::
 212     Foreground color.
 213 *width*::
 214     Set width.
 215 *text*::
 216     Text to change.
 217 *text_align*::
 218     Text alignement.
 219 *x*::
 220     Horizontal offset (auto-alignment if not set).
 221 *y*::
 222     Vertical offset (auto-alignment if not set).
 223 *align*::
 224     Widget alignment.
 225
 226 iconbox
 227 ~~~~~~~
 228 This widget shows an icon.
 229
 230 *mouse*::
 231     Set mouse bindings.
 232 *image*::
 233     Image file.
 234 *resize*::
 235     Resize icon to fit into statusbar.
 236 *x*::
 237     Horizontal offset (auto-alignment if not set).
 238 *y*::
 239     Vertical offset (auto-alignment if not set).
 240 *align*::
 241     Widget alignment.
 242
 243 progressbar
 244 ~~~~~~~~~~~
 245 This widget shows one or more progress-bars.
 246
 247 *bar*::
 248     Draws a bar; Options: fg, bg, bordercolor.
 249 *fg*::
 250     Foreground color.
 251 *fg_center*::
 252     Foreground color in the center of the bar (as gradient).
 253 *fg_end*::
 254     Foreground color at the end of a bar (as gradient).
 255 *bg*::
 256     Background color.
 257 *bordercolor*::
 258     Border color.
 259 *mouse*::
 260     Set mouse bindings.
 261 *width*::
 262     Set width.
 263 *height*::
 264     Set height (i.e. 0.9 = 90%)
 265 *padding*::
 266     Empty space on both sides.
 267 *x*::
 268     Horizontal offset (auto-alignment if not set).
 269 *y*::
 270     Vertical offset (auto-alignment if not set).
 271 *align*::
 272     Widget alignment.
 273
 274 graph
 275 ~~~~~
 276 This widget shows a graph.
 277
 278 *data*::
 279     Defines a data-stream section; Options: max, scale, fg and style.
 280 *max*::
 281     This value prints a full graph (default = 100)
 282 *scale*::
 283     Re-scales when input > max (see below).
 284 *fg*::
 285     Foreground color.
 286 *fg_center*::
 287     Foreground color in the center of the bar (as gradient).
 288 *fg_end*::
 289     Foreground color at the end of a bar (as gradient).
 290 *style*::
 291     bottom (fills to bottom with fg), top, or line.
 292 *mouse*::
 293     Set mouse bindings.
 294 *width*::
 295     Set width.
 296 *height*::
 297     Set height (i.e. 0.9 = 90%)
 298 *padding_left*::
 299     Empty space on the left.
 300 *bg*::
 301     Background color.
 302 *bordercolor*::
 303     Border color.
 304 *x*::
 305     Horizontal offset (auto-alignment if not set).
 306 *y*::
 307     Vertical offset (auto-alignment if not set).
 308 *align*::
 309     Widget alignment.
 310
 311 OPTIONS
 312 --------
 313
 314 Configuration options and possible values.
 315
 316 ..............................................
 317 Note: when there is no whitespace, quotes are optional.
 318
 319 <boolean>       -> "true" or "false"
 320 <color>         -> #ff9933 (hexadecimal color notation: #red green blue)
 321 <float>         -> 0.3, 0,8 (often values between 0 and 1 are useful)
 322 <font>          -> Xft font: mono-10, fixed-12, sans-8, ...
 323 <identifier>    -> foobar (choose a name/string)
 324 <image>         -> "/home/awesome/pics/icon.png" (path to image)
 325 <integer>       -> 1, 10, -3 (positive numbers are required mostly)
 326 <key>           -> a, 1, F10 (see /usr/include/X11/keysymdef.h w/o XK_ or 'xev')
 327                    or a keycode beginning with #
 328 <mod>           -> "Mod1", "Mod4", "Control" (modifiers)
 329 <regex>         -> regular expression
 330 <string>        -> "foo bar"
 331 <uicb-arg>      -> prog, 3... (argument to a uicb function, where required)
 332 <uicb-cmd>      -> spawn, exec, client_tag... (see UICB FUNCTIONS above)
 333 <{.., ...}>     -> list of available options
 334
 335 [MULTI] means, you can use an item multiple times.
 336
 337
 338
 339 screen <integer> [MULTI]
 340 {
 341     general
 342     {
 343         border = <integer>
 344         font = <font>
 345         new_become_master = <boolean>
 346         new_get_focus = <boolean>
 347         opacity_unfocused = <integer>
 348         resize_hints = <boolean>
 349         sloppy_focus = <boolean>
 350         sloppy_focus_raise = <boolean>
 351         snap = <integer>
 352         floating_placement = <{smart,under_mouse}>
 353     }
 354     tags
 355     {
 356         tag <identifier> [MULTI]
 357         {
 358             layout = <{dwindle,floating,max,
 359                      spiral,tile,tileleft,tilebottom,tiletop}>
 360             mwfact = <float>
 361             nmaster = <integer>
 362         }
 363     }
 364     layouts
 365     {
 366         layout <{dwindle,floating,max,
 367                  spiral,tile,tileleft,
 368                  tilebottom,tiletop}> { image = <image> } [MULTI]
 369     }
 370     colors
 371     {
 372         tab_border = <color>
 373         normal_fg = <color>
 374         normal_bg = <color>
 375         normal_border = <color>
 376         focus_fg = <color>
 377         focus_bg = <color>
 378         focus_border = <color>
 379         urgent_fg = <color>
 380         urgent_bg = <color>
 381     }
 382     padding
 383     {
 384         top = <integer>
 385         bottom = <integer>
 386         left = <integer>
 387         right = <integer>
 388     }
 389     statusbar <identifier> [MULTI]
 390     {
 391         position = <{top,bottom,left,right}>
 392         height = <integer>
 393         width = <integer>
 394
 395         taglist <identifier> [MULTI]
 396         {
 397             x = <integer> y = <integer>
 398             align = <{auto,right,left}>
 399             mouse [MULTI]
 400             {
 401                 button = <integer> modkey = {<mod>, ...}
 402                 command = <uicb-cmd> arg = <uicb-arg>
 403             }
 404         }
 405         layoutinfo <identifier>
 406         {
 407             x = <integer> y = <integer>
 408             align = <{auto,right,left}>
 409             mouse [MULTI]
 410             {
 411                 button = <integer> modkey = {<mod>, ...}
 412                 command = <uicb-cmd> arg = <uicb-arg>
 413             }
 414         }
 415         focusicon <identifier>
 416         {
 417             x = <integer> y = <integer>
 418             align = <{auto,right,left}>
 419             mouse [MULTI]
 420             {
 421                 button = <integer> modkey = {<mod>, ...}
 422                 command = <uicb-cmd> arg = <uicb-arg>
 423             }
 424         }
 425         tasklist <identifier>
 426         {
 427             fg = <color>
 428             bg = <color>
 429             focus_fg = <color>
 430             focus_bg = <color>
 431             font = <font>
 432             show_icons = <boolean>
 433             show = <{all,tags,focus}>
 434             text_align = <{center,left,right}>
 435             x = <integer> y = <integer>
 436             mouse [MULTI]
 437             {
 438                 command = <uicb-cmd> arg = <uicb-arg>
 439                 button = <integer> modkey = {<mod>, ...}
 440             }
 441         }
 442         textbox <identifier> [MULTI]
 443         {
 444             text = <string>
 445             bg = <color>
 446             fg = <color>
 447             font = <font>
 448             width = <integer>
 449             text_align = <{center,left,right}>
 450             x = <integer> y = <integer>
 451             align = <{auto,right,left}>
 452             mouse [MULTI]
 453             {
 454                 button = <integer> modkey = {<mod>, ...}
 455                 command = <uicb-cmd> arg = <uicb-arg>
 456             }
 457         }
 458         iconbox <identifier> [MULTI]
 459         {
 460             image = <image>
 461             resize = <boolean>
 462             x = <integer> y = <integer>
 463             align = <{auto,right,left}>
 464             mouse [MULTI]
 465             {
 466                 button = <integer> modkey = {<mod>, ...}
 467                 command = <uicb-cmd> arg = <uicb-arg>
 468             }
 469         }
 470         progressbar <identifier> [MULTI]
 471         {
 472             bar [MULTI]
 473             {
 474                 fg = <color> fg_center = <color> fg_end = <color>
 475                 bg = <color> bordercolor = <color>
 476             }
 477             gap = <integer>
 478             width = <integer>
 479             height = <float>
 480             padding = <integer>
 481             x = <integer> y = <integer>
 482             align = <{auto,right,left}>
 483             mouse [MULTI]
 484             {
 485                 button = <integer> modkey = {<mod>, ...}
 486                 command = <uicb-cmd> arg = <uicb-arg>
 487             }
 488         }
 489         graph <identifier> [MULTI]
 490         {
 491             data [MULTI]
 492             {
 493                 scale = <boolean> max = <float> style = <{bottom, top, line}>
 494                 fg = <color> fg_center = <color> fg_end = <color>
 495             }
 496             width = <integer>
 497             height = <float>
 498             padding_left = <integer>
 499             bg = <color>
 500             bordercolor = <color>
 501             x = <integer> y = <integer>
 502             align = <{auto,right,left}>
 503             mouse [MULTI]
 504             {
 505                 button = <integer> modkey = {<mod>, ...}
 506                 command = <uicb-cmd> arg = <uicb-arg>
 507             }
 508         }
 509     }
 510 }
 511 rules
 512 {
 513     rule [MULTI]
 514     {
 515         name = <regex>
 516         xproperty_name = <string>
 517         xproperty_value = <regex>
 518         float = <{auto,true,false}>
 519         master = <{auto,true,false}>
 520         tags = <regex>
 521         screen = <integer>
 522         icon = <image>
 523         opacity = <float>
 524     }
 525 }
 526 keys
 527 {
 528     key [MULTI]
 529     {
 530         key = <key> modkey = {<mod>, ...}
 531         command = <uicb-cmd> arg = <uicb-arg>
 532     }
 533     keylist [MULTI]
 534     {
 535         keylist = {<key>, ...}
 536         modkey = {<mod>, ...}
 537         command = <uicb-cmd>
 538         arglist = {<uicb-arg>, ...}
 539     }
 540 }
 541 mouse
 542 {
 543     client [MULTI]
 544     {
 545         button = <integer> modkey = {<mod>, ...}
 546         command = <uicb-cmd> arg = <uicb-arg>
 547     }
 548     root [MULTI]
 549     {
 550         button = <integer> modkey = {<mod>, ...}
 551         command = <uicb-cmd> arg = <uicb-arg>
 552     }
 553 }
 554 ..............................................
 555
 556 EXAMPLES
 557 --------
 558
 559 Check awesome's wiki: http://awesome.naquadah.org/wiki/
 560
 561
 562 SEE ALSO
 563 --------
 564 awesome(1) awesome-client(1)
 565
 566
 567 AUTHORS
 568 -------
 569 This man page was written by Julien Danjou <julien@danjou.info> and Marco Candrian <mac@calmar.ws>.
 570
 571 WWW
 572 ---
 573 http://awesome.naquadah.org