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