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
 114 Screen
 115 ~~~~~~
 116 *screen_focus* relative or absolute integer::
 117     Select Screen and focus first window and move mouse.
 118
 119 WIDGETS
 120 -------
 121 Statusbars can be customized by modifying widgets names, order and options.
 122
 123 taglist
 124 ~~~~~~~
 125 This widget shows the tag list.
 126
 127 *mouse*::
 128     Set mouse bindings.
 129 *x*::
 130     Horizontal offset (auto-alignment if not set).
 131 *y*::
 132     Vertical offset (auto-alignment if not set).
 133
 134 layoutinfo
 135 ~~~~~~~~~~
 136 This widget shows a icon for the selected layout.
 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
 145 netwmicon
 146 ~~~~~~~~~
 147 This widget shows a icon for the focused window  using NET_WM_ICON or icon file set in rule.
 148
 149 *mouse*::
 150     Set mouse bindings.
 151 *x*::
 152     Horizontal offset (auto-alignment if not set).
 153 *y*::
 154     Vertical offset (auto-alignment if not set).
 155
 156 focustitle
 157 ~~~~~~~~~~
 158 This widget shows the title of the focused window.
 159
 160 *mouse*::
 161     Set mouse bindings.
 162 *font*::
 163     Font to use.
 164 *bg*::
 165     Background color.
 166 *fg*::
 167     Foreground color.
 168 *align*::
 169     Text alignement.
 170 *x*::
 171     Horizontal offset (auto-alignment if not set).
 172 *y*::
 173     Vertical offset (auto-alignment if not set).
 174
 175 tasklist
 176 ~~~~~~~~
 177 This widget shows a list of running windows.
 178
 179 *mouse*::
 180     Set mouse bindings.
 181 *font*::
 182     Font to use.
 183 *bg*::
 184     Background color.
 185 *fg*::
 186     Foreground color.
 187 *focus_bg*::
 188     Background color for focused window.
 189 *focus_fg*::
 190     Foreground color for focused window.
 191 *align*::
 192     Text alignement.
 193 *show_icons*::
 194     Show applications icons.
 195 *show_all*::
 196     Show all windows from all tags.
 197 *x*::
 198     Horizontal offset (auto-alignment if not set).
 199 *y*::
 200     Vertical offset (auto-alignment if not set).
 201
 202 textbox
 203 ~~~~~~~
 204 This widget shows a text.
 205
 206 *mouse*::
 207     Set mouse bindings.
 208 *font*::
 209     Font to use.
 210 *bg*::
 211     Background color.
 212 *fg*::
 213     Foreground color.
 214 *width*::
 215     Set width.
 216 *text*::
 217     Text to change.
 218 *align*::
 219     Text alignement.
 220 *x*::
 221     Horizontal offset (auto-alignment if not set).
 222 *y*::
 223     Vertical offset (auto-alignment if not set).
 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
 240 progressbar
 241 ~~~~~~~~~~~
 242 This widget shows one or more progress-bars.
 243
 244 *mouse*::
 245     Set mouse bindings.
 246 *width*::
 247     Set width.
 248 *height*::
 249     Set height (i.e. 0.9 = 90%)
 250 *padding_left*::
 251     Empty space on the left.
 252 *bar*::
 253     Draws a bar; Options: fg, bg, bordercolor.
 254 *fg*::
 255     Foreground color.
 256 *bg*::
 257     Background color.
 258 *bordercolor*::
 259     Border color.
 260 *x*::
 261     Horizontal offset (auto-alignment if not set).
 262 *y*::
 263     Vertical offset (auto-alignment if not set).
 264
 265 graph
 266 ~~~~~
 267 This widget shows a graph.
 268
 269 *scale*::
 270     Re-scales when input > max (see below).
 271 *max*::
 272     This value prints a full graph.
 273 *mouse*::
 274     Set mouse bindings.
 275 *width*::
 276     Set width.
 277 *height*::
 278     Set height (i.e. 0.9 = 90%)
 279 *padding_left*::
 280     Empty space on the left.
 281 *fg*::
 282     Foreground color.
 283 *bg*::
 284     Background color.
 285 *bordercolor*::
 286     Border color.
 287 *x*::
 288     Horizontal offset (auto-alignment if not set).
 289 *y*::
 290     Vertical offset (auto-alignment if not set).
 291
 292 OPTIONS
 293 --------
 294
 295 Configuration options and possible values.
 296
 297 ..............................................
 298 Note: when there is no whitespace, quotes are optional.
 299
 300 <boolean>       -> "true" or "false"
 301 <color>         -> #ff9933 (hexadecimal color notation: #red green blue)
 302 <float>         -> 0.3, 0,8 (often values between 0 and 1 are useful)
 303 <font>          -> Xft font: mono-10, fixed-12, sans-8, ...
 304 <identifier>    -> foobar (choose a name/string)
 305 <image>         -> "/home/awesome/pics/icon.png" (path to image)
 306 <integer>       -> 1, 10, -3 (positive numbers are required mostly)
 307 <key>           -> a, 1, F10 (see /usr/include/X11/keysymdef.h w/o XK_ or 'xev')
 308 <mod>           -> "Mod1", "Mod4", "Control" (modifiers)
 309 <regex>         -> regular expression
 310 <string>        -> "foo bar"
 311 <uicb-arg>      -> prog, 3... (argument to a uicb function, where required)
 312 <uicb-cmd>      -> spawn, exec, client_tag... (see UICB FUNCTIONS above)
 313 <{.., ...}>     -> list of available options
 314
 315 [MULTI] means, you can use an item multiple times.
 316
 317
 318
 319 screen <integer> [MULTI]
 320 {
 321     general
 322     {
 323         allow_lower_floats = <boolean>
 324         border = <integer>
 325         focus_move_pointer = <boolean>
 326         font = <font>
 327         new_become_master = <boolean>
 328         new_get_focus = <boolean>
 329         opacity_unfocused = <integer>
 330         resize_hints = <boolean>
 331         sloppy_focus = <boolean>
 332         snap = <integer>
 333     }
 334     tags
 335     {
 336         tag <identifier> [MULTI]
 337         {
 338             layout = <{dwindle,floating,max,
 339                      spiral,tile,tileleft}>
 340             mwfact = <float>
 341             nmaster = <integer>
 342         }
 343     }
 344     layouts
 345     {
 346         layout <{dwindle,floating,max,
 347                  spiral,tile,tileleft}> { image = <image> } [MULTI]
 348     }
 349     colors
 350     {
 351         tab_border = <color>
 352         normal_fg = <color>
 353         normal_bg = <color>
 354         normal_border = <color>
 355         focus_fg = <color>
 356         focus_bg = <color>
 357         focus_border = <color>
 358         urgent_fg = <color>
 359         urgent_bg = <color>
 360     }
 361     padding
 362     {
 363         top = <integer>
 364         bottom = <integer>
 365         left = <integer>
 366         right = <integer>
 367     }
 368     statusbar <identifier> [MULTI]
 369     {
 370         position = <{top,bottom,left,right}>
 371         height = <integer>
 372         width = <integer>
 373
 374         taglist <identifier> [MULTI]
 375         {
 376             x = <integer> y = <integer>
 377             mouse [MULTI]
 378             {
 379                 button = <integer> modkey = {<mod>, ...}
 380                 command = <uicb-cmd> arg = <uicb-arg>
 381             }
 382         }
 383         layoutinfo <identifier>
 384         {
 385             x = <integer> y = <integer>
 386             mouse [MULTI]
 387             {
 388                 button = <integer> modkey = {<mod>, ...}
 389                 command = <uicb-cmd> arg = <uicb-arg>
 390             }
 391         }
 392         netwmicon <identifier>
 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         focustitle <identifier>
 402         {
 403             fg = <color>
 404             bg = <color>
 405             font = <font>
 406             align = <{center,left,right}>
 407             x = <integer> y = <integer>
 408             mouse [MULTI]
 409             {
 410                 button = <integer> modkey = {<mod>, ...}
 411                 command = <uicb-cmd> arg = <uicb-arg>
 412             }
 413         }
 414         tasklist <identifier>
 415         {
 416             fg = <color>
 417             bg = <color>
 418             focus_fg = <color>
 419             focus_bg = <color>
 420             font = <font>
 421             show_icons = <boolean>
 422             show_all = <boolean>
 423             align = <{center,left,right}>
 424             x = <integer> y = <integer>
 425             mouse [MULTI]
 426             {
 427                 command = <uicb-cmd> arg = <uicb-arg>
 428                 button = <integer> modkey = {<mod>, ...}
 429             }
 430         }
 431         textbox <identifier> [MULTI]
 432         {
 433             text = <string>
 434             bg = <color>
 435             fg = <color>
 436             font = <font>
 437             width = <integer>
 438             align = <{center,left,right}>
 439             x = <integer> y = <integer>
 440             mouse [MULTI]
 441             {
 442                 button = <integer> modkey = {<mod>, ...}
 443                 command = <uicb-cmd> arg = <uicb-arg>
 444             }
 445         }
 446         iconbox <identifier> [MULTI]
 447         {
 448             image = <image>
 449             resize = <boolean>
 450             x = <integer> y = <integer>
 451             mouse [MULTI]
 452             {
 453                 button = <integer> modkey = {<mod>, ...}
 454                 command = <uicb-cmd> arg = <uicb-arg>
 455             }
 456         }
 457         progressbar <identifier> [MULTI]
 458         {
 459             bar { fg = <color> bg = <color> bordercolor = <color> } [MULTI]
 460             gap = <integer>
 461             width = <integer>
 462             height = <float>
 463             padding_left = <integer>
 464             x = <integer> y = <integer>
 465             mouse [MULTI]
 466             {
 467                 button = <integer> modkey = {<mod>, ...}
 468                 command = <uicb-cmd> arg = <uicb-arg>
 469             }
 470         }
 471         graph <identifier> [MULTI]
 472         {
 473             scale = <boolean>
 474             max = <float>
 475             width = <integer>
 476             height = <float>
 477             padding_left = <integer>
 478             fg = <color>
 479             bg = <color>
 480             bordercolor = <color>
 481             x = <integer> y = <integer>
 482             mouse [MULTI]
 483             {
 484                 button = <integer> modkey = {<mod>, ...}
 485                 command = <uicb-cmd> arg = <uicb-arg>
 486             }
 487         }
 488     }
 489 }
 490 rules
 491 {
 492     rule [MULTI]
 493     {
 494         name = <regex>
 495         xproperty_name = <string>
 496         xproperty_value = <regex>
 497         float = <{auto,true,false}>
 498         tags = <regex>
 499         screen = <integer>
 500         icon = <image>
 501         not_master = <boolean>
 502     }
 503 }
 504 keys
 505 {
 506     key [MULTI]
 507     {
 508         key = <key> modkey = {<mod>, ...}
 509         command = <uicb-cmd> arg = <uicb-arg>
 510     }
 511     keylist [MULTI]
 512     {
 513         keylist = {<key>, ...}
 514         modkey = {<mod>, ...}
 515         command = <uicb-cmd>
 516         arglist = {<uicb-arg>, ...}
 517     }
 518 }
 519 mouse
 520 {
 521     client [MULTI]
 522     {
 523         button = <integer> modkey = {<mod>, ...}
 524         command = <uicb-cmd> arg = <uicb-arg>
 525     }
 526     root [MULTI]
 527     {
 528         button = <integer> modkey = {<mod>, ...}
 529         command = <uicb-cmd> arg = <uicb-arg>
 530     }
 531 }
 532 ..............................................
 533
 534 EXAMPLES
 535 --------
 536
 537 Check awesome's wiki: http://awesome.naquadah.org/wiki/
 538
 539
 540 SEE ALSO
 541 --------
 542 awesome(1) awesome-client(1)
 543
 544
 545 AUTHORS
 546 -------
 547 This man page was written by Julien Danjou <julien@danjou.info> and Marco Candrian <mac@calmar.ws>.
 548
 549 WWW
 550 ---
 551 http://awesome.naquadah.org