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