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*::
  25     Hide or show statusbar.
  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 *x*::
 178     Horizontal offset (auto-alignment if not set).
 179 *y*::
 180     Vertical offset (auto-alignment if not set).
 181
 182 textbox
 183 ~~~~~~~
 184 This widget shows a text.
 185
 186 *mouse*::
 187     Set mouse bindings.
 188 *font*::
 189     Font to use.
 190 *bg*::
 191     Background color.
 192 *fg*::
 193     Foreground color.
 194 *width*::
 195     Set width.
 196 *text*::
 197     Text to change.
 198 *align*::
 199     Text alignement.
 200 *x*::
 201     Horizontal offset (auto-alignment if not set).
 202 *y*::
 203     Vertical offset (auto-alignment if not set).
 204
 205 iconbox
 206 ~~~~~~~
 207 This widget shows an icon.
 208
 209 *mouse*::
 210     Set mouse bindings.
 211 *image*::
 212     Image file.
 213 *resize*::
 214     Resize icon to fit into statusbar.
 215 *x*::
 216     Horizontal offset (auto-alignment if not set).
 217 *y*::
 218     Vertical offset (auto-alignment if not set).
 219
 220 progressbar
 221 ~~~~~~~~~~~
 222 This widget shows one or more progress-bars.
 223
 224 *mouse*::
 225     Set mouse bindings.
 226 *width*::
 227     Set width.
 228 *bar*::
 229     Draws a bar; Options: fg, bg, bcolor.
 230 *fg*::
 231     Foreground color.
 232 *bg*::
 233     Background color.
 234 *bcolor*::
 235     Border color.
 236 *x*::
 237     Horizontal offset (auto-alignment if not set).
 238 *y*::
 239     Vertical offset (auto-alignment if not set).
 240
 241 FILES
 242 -----
 243 For an example of an awesomerc file, see the file provided with the sources.
 244
 245 EXAMPLES
 246 --------
 247
 248 The general config and subconfig options for the awesomerc:
 249
 250 ..............................................
 251 Note: when there are no whitespace, quotes are optional.
 252
 253 <boolean>       -> "true" or "false"
 254 <color>         -> #ff9933 (hexadecimal color notation: #red green blue)
 255 <float>         -> 0.3, 0,8 (often values between 0 and 1 are useful)
 256 <font>          -> Xft font: mono-10, fixed-12, sans-8, ...
 257 <identifier>    -> foobar (choose a name/string)
 258 <image>         -> "/home/awesome/pics/icon.png" (path to image)
 259 <integer>       -> 1, 10, -3 (positive numbers are required mostly)
 260 <key>           -> a, 1, F10 (see /usr/include/X11/keysymdef.h w/o XK_ or 'xev')
 261 <mod>           -> "Mod1", "Mod4", "Control" (modifiers)
 262 <regex>         -> regular expression
 263 <string>        -> "foo bar"
 264 <uicb-arg>      -> prog, 3... (argument to a uicb function, where required)
 265 <uicb-cmd>      -> spawn, exec, client_tag... (see UICB FUNCTIONS above)
 266 <{.., ...}>     -> list of available options
 267
 268 [MULTI] means, you can use an item multiple times.
 269
 270 screen <integer> [MULTI]
 271 {
 272     general
 273     {
 274         allow_lower_floats = <boolean>
 275         border = <integer>
 276         focus_move_pointer = <boolean>
 277         font = <font>
 278         new_become_master = <boolean>
 279         opacity_unfocused = <integer>
 280         resize_hints = <boolean>
 281         sloppy_focus = <boolean>
 282         snap = <integer>
 283     }
 284     tags
 285     {
 286         tag <identifier> [MULTI]
 287         {
 288             layout = <{dwindle,floating,max,
 289                      spiral,tile,tileleft}>
 290             mwfact = <float>
 291             nmaster = <integer>
 292         }
 293     }
 294     layouts
 295     {
 296         layout <{dwindle,floating,max,
 297                  spiral,tile,tileleft}> { image = <image> } [MULTI]
 298     }
 299     colors
 300     {
 301         tab_border = <color>
 302         normal_fg = <color>
 303         normal_bg = <color>
 304         normal_border = <color>
 305         focus_fg = <color>
 306         focus_bg = <color>
 307         focus_border = <color>
 308         urgent_fg = <color>
 309         urgent_bg = <color>
 310     }
 311     padding
 312     {
 313         top = <integer>
 314         bottom = <integer>
 315         left = <integer>
 316         right = <integer>
 317     }
 318     statusbar <identifier> [MULTI]
 319     {
 320         position = <{top,bottom,left,right}>
 321         height = <integer>
 322         width = <integer>
 323
 324         taglist <identifier> [MULTI]
 325         {
 326             x = <integer> y = <integer>
 327             mouse [MULTI]
 328             {
 329                 button = <integer> modkey = {<mod>, ...}
 330                 command = <uicb-cmd> arg = <uicb-arg>
 331             }
 332         }
 333         layoutinfo <identifier>
 334         {
 335             x = <integer> y = <integer>
 336             mouse [MULTI]
 337             {
 338                 button = <integer> modkey = {<mod>, ...}
 339                 command = <uicb-cmd> arg = <uicb-arg>
 340             }
 341         }
 342         netwmicon <identifier>
 343         {
 344             x = <integer> y = <integer>
 345             mouse [MULTI]
 346             {
 347                 button = <integer> modkey = {<mod>, ...}
 348                 command = <uicb-cmd> arg = <uicb-arg>
 349             }
 350         }
 351         focustitle <identifier>
 352         {
 353             fg = <color>
 354             bg = <color>
 355             font = <font>
 356             align = <{center,left,right}>
 357             x = <integer> y = <integer>
 358             mouse [MULTI]
 359             {
 360                 button = <integer> modkey = {<mod>, ...}
 361                 command = <uicb-cmd> arg = <uicb-arg>
 362             }
 363         }
 364         tasklist <identifier>
 365         {
 366             fg = <color>
 367             bg = <color>
 368             focus_fg = <color>
 369             focus_bg = <color>
 370             font = <font>
 371             show_icons = <boolean>
 372             align = <{center,left,right}>
 373             x = <integer> y = <integer>
 374             mouse [MULTI]
 375             {
 376                 command = <uicb-cmd> arg = <uicb-arg>
 377                 button = <integer> modkey = {<mod>, ...}
 378             }
 379         }
 380         textbox <identifier> [MULTI]
 381         {
 382             text = <string>
 383             bg = <color>
 384             fg = <color>
 385             font = <font>
 386             width = <integer>
 387             align = <{center,left,right}>
 388             x = <integer> y = <integer>
 389             mouse [MULTI]
 390             {
 391                 button = <integer> modkey = {<mod>, ...}
 392                 command = <uicb-cmd> arg = <uicb-arg>
 393             }
 394         }
 395         iconbox <identifier> [MULTI]
 396         {
 397             image = <image>
 398             resize = <boolean>
 399             x = <integer> y = <integer>
 400             mouse [MULTI]
 401             {
 402                 button = <integer> modkey = {<mod>, ...}
 403                 command = <uicb-cmd> arg = <uicb-arg>
 404             }
 405         }
 406         progressbar <identifier> [MULTI]
 407         {
 408             bar { bcolor = <color> bg = <color> fg = <color> } [MULTI]
 409             gap = <integer>
 410             width = <integer>
 411             height = <float>
 412             lpadding = <integer>
 413             x = <integer> y = <integer>
 414             mouse [MULTI]
 415             {
 416                 button = <integer> modkey = {<mod>, ...}
 417                 command = <uicb-cmd> arg = <uicb-arg>
 418             }
 419         }
 420     }
 421 }
 422 rules
 423 {
 424     rule [MULTI]
 425     {
 426         name = <regex>
 427         xproperty_name = <string>
 428         xproperty_value = <regex>
 429         float = <boolean>
 430         tags = <regex>
 431         screen = <integer>
 432         icon = <image>
 433         not_master = <boolean>
 434     }
 435 }
 436 keys
 437 {
 438     key [MULTI]
 439     {
 440         key = <key> modkey = {<mod>, ...}
 441         command = <uicb-cmd> arg = <uicb-arg>
 442     }
 443     keylist [MULTI]
 444     {
 445         keylist = {<key>, ...}
 446         modkey = {<mod>, ...}
 447         command = <uicb-cmd>
 448         arglist = {<uicb-arg>, ...}
 449     }
 450 }
 451 mouse
 452 {
 453     client [MULTI]
 454     {
 455         button = <integer> modkey = {<mod>, ...}
 456         command = <uicb-cmd> arg = <uicb-arg>
 457     }
 458     root [MULTI]
 459     {
 460         button = <integer> modkey = {<mod>, ...}
 461         command = <uicb-cmd> arg = <uicb-arg>
 462     }
 463 }
 464 ..............................................
 465
 466
 467 SEE ALSO
 468 --------
 469 awesome(1) awesome-client(1)
 470
 471
 472 AUTHORS
 473 -------
 474 This man page was written by Julien Danjou <julien@danjou.info> and Marco Candrian <mac@calmar.ws>.
 475
 476 WWW
 477 ---
 478 http://awesome.naquadah.org