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
  91 Tag
  92 ~~~
  93 *tag_setlayout* relative or absolute integer::
  94     Set layout number; or just switch to the next layout for current tag.
  95 *tag_toggleview* tag::
  96     Add windows tagged with tag number to current display.
  97 *tag_view* tag number::
  98     View windows tagged with tag number.
  99 *tag_viewnext*::
 100     Show windows tagged with next tag in list.
 101 *tag_viewprev*::
 102     Show windows tagged with previous tag in list.
 103 *tag_prev_selected*::
 104     Switch back to the previously displayed set of tags.
 105 *tag_setmwfact* relative or absolute float::
 106     Set master width factor.
 107 *tag_setncol* relative or absolute integer::
 108     Set number of columns for non-master windows.
 109 *tag_setnmaster* relative or absolute integer::
 110     Set number of master windows.
 111 *tag_create* name::
 112     Create a new tag with that name.
 113
 114 Focus
 115 ~~~~~
 116 *focus_client_byname* string::
 117     Give client focus by its name.
 118 *focus_history* negative number::
 119     Focus the client that had focused nth focus switch earlier.
 120
 121 Screen
 122 ~~~~~~
 123 *screen_focus* relative or absolute integer::
 124     Select Screen and focus first window and move mouse.
 125
 126 WIDGETS
 127 -------
 128 Statusbars can be customized by modifying widgets names, order and options.
 129
 130 taglist
 131 ~~~~~~~
 132 This widget shows the tag list.
 133
 134 *mouse*::
 135     Set mouse bindings.
 136 *x*::
 137     Horizontal offset (auto-alignment if not set).
 138 *y*::
 139     Vertical offset (auto-alignment if not set).
 140
 141 layoutinfo
 142 ~~~~~~~~~~
 143 This widget shows a icon for the selected layout.
 144
 145 *mouse*::
 146     Set mouse bindings.
 147 *x*::
 148     Horizontal offset (auto-alignment if not set).
 149 *y*::
 150     Vertical offset (auto-alignment if not set).
 151
 152 netwmicon
 153 ~~~~~~~~~
 154 This widget shows a icon for the focused window  using NET_WM_ICON or icon file set in rule.
 155
 156 *mouse*::
 157     Set mouse bindings.
 158 *x*::
 159     Horizontal offset (auto-alignment if not set).
 160 *y*::
 161     Vertical offset (auto-alignment if not set).
 162
 163 focustitle
 164 ~~~~~~~~~~
 165 This widget shows the title of the focused window.
 166
 167 *mouse*::
 168     Set mouse bindings.
 169 *font*::
 170     Font to use.
 171 *bg*::
 172     Background color.
 173 *fg*::
 174     Foreground color.
 175 *align*::
 176     Text alignement.
 177 *x*::
 178     Horizontal offset (auto-alignment if not set).
 179 *y*::
 180     Vertical offset (auto-alignment if not set).
 181
 182 tasklist
 183 ~~~~~~~~
 184 This widget shows a list of running windows.
 185
 186 *mouse*::
 187     Set mouse bindings.
 188 *font*::
 189     Font to use.
 190 *bg*::
 191     Background color.
 192 *fg*::
 193     Foreground color.
 194 *focus_bg*::
 195     Background color for focused window.
 196 *focus_fg*::
 197     Foreground color for focused window.
 198 *align*::
 199     Text alignement.
 200 *show_icons*::
 201     Show applications icons.
 202 *show_all*::
 203     Show all windows from all tags.
 204 *x*::
 205     Horizontal offset (auto-alignment if not set).
 206 *y*::
 207     Vertical offset (auto-alignment if not set).
 208
 209 textbox
 210 ~~~~~~~
 211 This widget shows a text.
 212
 213 *mouse*::
 214     Set mouse bindings.
 215 *font*::
 216     Font to use.
 217 *bg*::
 218     Background color.
 219 *fg*::
 220     Foreground color.
 221 *width*::
 222     Set width.
 223 *text*::
 224     Text to change.
 225 *align*::
 226     Text alignement.
 227 *x*::
 228     Horizontal offset (auto-alignment if not set).
 229 *y*::
 230     Vertical offset (auto-alignment if not set).
 231
 232 iconbox
 233 ~~~~~~~
 234 This widget shows an icon.
 235
 236 *mouse*::
 237     Set mouse bindings.
 238 *image*::
 239     Image file.
 240 *resize*::
 241     Resize icon to fit into statusbar.
 242 *x*::
 243     Horizontal offset (auto-alignment if not set).
 244 *y*::
 245     Vertical offset (auto-alignment if not set).
 246
 247 progressbar
 248 ~~~~~~~~~~~
 249 This widget shows one or more progress-bars.
 250
 251 *bar*::
 252     Draws a bar; Options: fg, bg, bordercolor.
 253 *fg*::
 254     Foreground color.
 255 *fg_full*::
 256     Foreground color of a full bar (as gradient).
 257 *bg*::
 258     Background color.
 259 *bordercolor*::
 260     Border color.
 261 *mouse*::
 262     Set mouse bindings.
 263 *width*::
 264     Set width.
 265 *height*::
 266     Set height (i.e. 0.9 = 90%)
 267 *padding*::
 268     Empty space on both sides.
 269 *x*::
 270     Horizontal offset (auto-alignment if not set).
 271 *y*::
 272     Vertical offset (auto-alignment if not set).
 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_middle*::
 287     Color at the middle of the graph
 288 *fg_end*::
 289     Color at the end of the graph
 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
 309 OPTIONS
 310 --------
 311
 312 Configuration options and possible values.
 313
 314 ..............................................
 315 Note: when there is no whitespace, quotes are optional.
 316
 317 <boolean>       -> "true" or "false"
 318 <color>         -> #ff9933 (hexadecimal color notation: #red green blue)
 319 <float>         -> 0.3, 0,8 (often values between 0 and 1 are useful)
 320 <font>          -> Xft font: mono-10, fixed-12, sans-8, ...
 321 <identifier>    -> foobar (choose a name/string)
 322 <image>         -> "/home/awesome/pics/icon.png" (path to image)
 323 <integer>       -> 1, 10, -3 (positive numbers are required mostly)
 324 <key>           -> a, 1, F10 (see /usr/include/X11/keysymdef.h w/o XK_ or 'xev')
 325                    or a keycode beginning with #
 326 <mod>           -> "Mod1", "Mod4", "Control" (modifiers)
 327 <regex>         -> regular expression
 328 <string>        -> "foo bar"
 329 <uicb-arg>      -> prog, 3... (argument to a uicb function, where required)
 330 <uicb-cmd>      -> spawn, exec, client_tag... (see UICB FUNCTIONS above)
 331 <{.., ...}>     -> list of available options
 332
 333 [MULTI] means, you can use an item multiple times.
 334
 335
 336
 337 screen <integer> [MULTI]
 338 {
 339     general
 340     {
 341         border = <integer>
 342         font = <font>
 343         new_become_master = <boolean>
 344         new_get_focus = <boolean>
 345         opacity_unfocused = <integer>
 346         resize_hints = <boolean>
 347         sloppy_focus = <boolean>
 348         sloppy_focus_raise = <boolean>
 349         snap = <integer>
 350     }
 351     tags
 352     {
 353         tag <identifier> [MULTI]
 354         {
 355             layout = <{dwindle,floating,max,
 356                      spiral,tile,tileleft,tilebottom,tiletop}>
 357             mwfact = <float>
 358             nmaster = <integer>
 359         }
 360     }
 361     layouts
 362     {
 363         layout <{dwindle,floating,max,
 364                  spiral,tile,tileleft,
 365                  tilebottom,tiletop}> { image = <image> } [MULTI]
 366     }
 367     colors
 368     {
 369         tab_border = <color>
 370         normal_fg = <color>
 371         normal_bg = <color>
 372         normal_border = <color>
 373         focus_fg = <color>
 374         focus_bg = <color>
 375         focus_border = <color>
 376         urgent_fg = <color>
 377         urgent_bg = <color>
 378     }
 379     padding
 380     {
 381         top = <integer>
 382         bottom = <integer>
 383         left = <integer>
 384         right = <integer>
 385     }
 386     statusbar <identifier> [MULTI]
 387     {
 388         position = <{top,bottom,left,right}>
 389         height = <integer>
 390         width = <integer>
 391
 392         taglist <identifier> [MULTI]
 393         {
 394             x = <integer> y = <integer>
 395             mouse [MULTI]
 396             {
 397                 button = <integer> modkey = {<mod>, ...}
 398                 command = <uicb-cmd> arg = <uicb-arg>
 399             }
 400         }
 401         layoutinfo <identifier>
 402         {
 403             x = <integer> y = <integer>
 404             mouse [MULTI]
 405             {
 406                 button = <integer> modkey = {<mod>, ...}
 407                 command = <uicb-cmd> arg = <uicb-arg>
 408             }
 409         }
 410         netwmicon <identifier>
 411         {
 412             x = <integer> y = <integer>
 413             mouse [MULTI]
 414             {
 415                 button = <integer> modkey = {<mod>, ...}
 416                 command = <uicb-cmd> arg = <uicb-arg>
 417             }
 418         }
 419         focustitle <identifier>
 420         {
 421             fg = <color>
 422             bg = <color>
 423             font = <font>
 424             align = <{center,left,right}>
 425             x = <integer> y = <integer>
 426             mouse [MULTI]
 427             {
 428                 button = <integer> modkey = {<mod>, ...}
 429                 command = <uicb-cmd> arg = <uicb-arg>
 430             }
 431         }
 432         tasklist <identifier>
 433         {
 434             fg = <color>
 435             bg = <color>
 436             focus_fg = <color>
 437             focus_bg = <color>
 438             font = <font>
 439             show_icons = <boolean>
 440             show_all = <boolean>
 441             align = <{center,left,right}>
 442             x = <integer> y = <integer>
 443             mouse [MULTI]
 444             {
 445                 command = <uicb-cmd> arg = <uicb-arg>
 446                 button = <integer> modkey = {<mod>, ...}
 447             }
 448         }
 449         textbox <identifier> [MULTI]
 450         {
 451             text = <string>
 452             bg = <color>
 453             fg = <color>
 454             font = <font>
 455             width = <integer>
 456             align = <{center,left,right}>
 457             x = <integer> y = <integer>
 458             mouse [MULTI]
 459             {
 460                 button = <integer> modkey = {<mod>, ...}
 461                 command = <uicb-cmd> arg = <uicb-arg>
 462             }
 463         }
 464         iconbox <identifier> [MULTI]
 465         {
 466             image = <image>
 467             resize = <boolean>
 468             x = <integer> y = <integer>
 469             mouse [MULTI]
 470             {
 471                 button = <integer> modkey = {<mod>, ...}
 472                 command = <uicb-cmd> arg = <uicb-arg>
 473             }
 474         }
 475         progressbar <identifier> [MULTI]
 476         {
 477             bar [MULTI]
 478             {
 479                 fg = <color> fg_full = <color> fg_half = <color>
 480                 bg = <color> bordercolor = <color>
 481             }
 482             gap = <integer>
 483             width = <integer>
 484             height = <float>
 485             padding = <integer>
 486             x = <integer> y = <integer>
 487             mouse [MULTI]
 488             {
 489                 button = <integer> modkey = {<mod>, ...}
 490                 command = <uicb-cmd> arg = <uicb-arg>
 491             }
 492         }
 493         graph <identifier> [MULTI]
 494         {
 495             data [MULTI]
 496             {
 497                 scale = <boolean> max = <float> style = <{bottom, top, line}>
 498                 fg = <color> fg_middle = <color> fg_end = <color>
 499             }
 500             width = <integer>
 501             height = <float>
 502             padding_left = <integer>
 503             bg = <color>
 504             bordercolor = <color>
 505             x = <integer> y = <integer>
 506             mouse [MULTI]
 507             {
 508                 button = <integer> modkey = {<mod>, ...}
 509                 command = <uicb-cmd> arg = <uicb-arg>
 510             }
 511         }
 512     }
 513 }
 514 rules
 515 {
 516     rule [MULTI]
 517     {
 518         name = <regex>
 519         xproperty_name = <string>
 520         xproperty_value = <regex>
 521         float = <{auto,true,false}>
 522         master = <{auto,true,false}>
 523         tags = <regex>
 524         screen = <integer>
 525         icon = <image>
 526         opacity = <float>
 527     }
 528 }
 529 keys
 530 {
 531     key [MULTI]
 532     {
 533         key = <key> modkey = {<mod>, ...}
 534         command = <uicb-cmd> arg = <uicb-arg>
 535     }
 536     keylist [MULTI]
 537     {
 538         keylist = {<key>, ...}
 539         modkey = {<mod>, ...}
 540         command = <uicb-cmd>
 541         arglist = {<uicb-arg>, ...}
 542     }
 543 }
 544 mouse
 545 {
 546     client [MULTI]
 547     {
 548         button = <integer> modkey = {<mod>, ...}
 549         command = <uicb-cmd> arg = <uicb-arg>
 550     }
 551     root [MULTI]
 552     {
 553         button = <integer> modkey = {<mod>, ...}
 554         command = <uicb-cmd> arg = <uicb-arg>
 555     }
 556 }
 557 ..............................................
 558
 559 EXAMPLES
 560 --------
 561
 562 Check awesome's wiki: http://awesome.naquadah.org/wiki/
 563
 564
 565 SEE ALSO
 566 --------
 567 awesome(1) awesome-client(1)
 568
 569
 570 AUTHORS
 571 -------
 572 This man page was written by Julien Danjou <julien@danjou.info> and Marco Candrian <mac@calmar.ws>.
 573
 574 WWW
 575 ---
 576 http://awesome.naquadah.org