awesomerc.1.txt

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