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