wmii.man1 (19390B)
1 WMII 2 wmii-@VERSION@ 3 2010 June 4 5 %!includeconf: header.t2t 6 7 = NAME = 8 9 wmii - Window Manager Improved² 10 11 = SYNOPSIS = 12 13 wmii [-a <address>] [-r <wmiirc>] + 14 wmii -v 15 16 = DESCRIPTION = 17 18 == Overview == 19 20 `wmii` is a dynamic window manager for X11. In contrast to 21 static window management the user rarely has to think about how 22 to organize windows, no matter what he is doing or how many 23 applications are used at the same time. The window manager 24 adapts to the current environment and fits to the needs of the 25 user, rather than forcing him to use a preset, fixed layout and 26 trying to shoehorn all windows and applications into it. 27 28 `wmii` supports classic and tiled window management with 29 extended keyboard and mouse control. Classic window management 30 arranges windows in a floating layer in which tyen can be moved 31 and resized freely. Tiled window management arranges windows in 32 vertical columns. Each column holds an arbitrary number 33 arbitrary windows and arranges them vertically in a 34 non-overlapping manner. They can then be moved and resized, 35 among and within columns, at will. 36 37 `wmii` provides a virtual filesystem which represents the 38 internal state similar to the procfs of Unix operating systems. 39 Modifying this virtual filesystem results in changing the state 40 of the window manager. The virtual filesystem service can be 41 accessed through 9P-capable client programs, like 42 wmiir(1). This allows simple and powerful remote control 43 of the core window manager. 44 45 == Command Line Arguments == 46 47 : -a <address> 48 Specifies the address on which `wmii` should listen for 49 connections. The address takes the form 50 `<protocol>!<address>`. The default is of the form: 51 52 ``` unix!/tmp/ns.$USER.${DISPLAY%.0}/wmii 53 which opens a unix socket per Plan 9 Port conventions. To 54 open a TCP socket, listening at port 4332 on the loopback 55 interface, use: 56 57 ``` tcp!localhost!4332 58 $WMII_NAMESPACE is automatically set to this value. 59 60 : -r <wmiirc> 61 Specifies which rc script to run. If <wmiirc> consists of a 62 single argument, $WMII_CONFPATH is searched before $PATH. 63 Otherwise, it is passed to the shell for evaluation. The 64 environment variables $WMII_ADDRESS and $WMII_CONFPATH are 65 preset for the script. 66 : 67 == Terminology == 68 69 : Display 70 A running X server instance consisting of input 71 devices and screens. 72 : Screen 73 A physical or virtual (Xinerama or Xnest(1)) 74 screen of an X display. 75 : Window 76 A (rectangular) drawable X object which is 77 displayed on a screen, usually an application window. 78 : Client 79 An application window surrounded by a frame window 80 containing a border and a titlebar. 81 : Floating layer 82 A screen layer of `wmii` on top of all other layers, 83 where clients are arranged in a classic (floating) 84 manner. They can be resized or moved freely. 85 : Managed layer 86 A screen layer of `wmii` underneath the floating layer, 87 where clients are arranged in a non-overlapping 88 (managed) manner. Here, the window manager dynamically 89 assigns each client a size and position. The managed 90 layer consists of columns. 91 : Tag 92 Alphanumeric strings which can be assigned to a 93 client. This provides a mechanism to group clients with 94 similar properties. Clients can have one tag, e.g. 95 _work_, or several tags, e.g. _work+mail_. 96 Tags are separated with the _+_ character. 97 : View 98 A set of clients containing a specific tag, quite 99 similar to a workspace in other window managers. It 100 consists of the floating and managed layers. 101 : Column 102 A column is a screen area which arranges clients 103 vertically in a non-overlapping way. Clients can be 104 moved and resized between and within columns freely. 105 : Bar 106 The bar at the bottom of the screen displays a label 107 for each view and allows the creation of arbitrary 108 user-defined labels. 109 : Event 110 An event is a message which can be read from a 111 special file in the filesystem of `wmii`, such as a 112 mouse button press, a key press, or a message written by 113 a different 9P-client. 114 : 115 116 == Basic window management == 117 118 Running a raw `wmii` process without a wmiirc(1) script provides 119 basic window management capabilities. However, to use it 120 effectively, remote control through its filesystem interface is 121 necessary. Without such a script, it is only possible to move 122 and resize clients with the mouse, but not to change their tags 123 or to switch views. Other interactions, such as customizing the 124 style, killing or retagging clients, and grabbing keys, cannot 125 be achieved without accessing the filesystem. 126 127 The filesystem can be accessed by connecting to the //address// 128 of `wmii` with any 9P-capable client, such as wmiir(1) 129 130 == Actions == 131 132 The default configuration provides for a special menu of 133 actions. These consist of either shell scripts in $WMII_CONFPATH 134 or action definitions included in wmiirc. 135 136 Here is a list of the default actions: 137 138 | exec | Replace the window manager with another program 139 | quit | Leave the window manager nicely 140 | rehash | Refresh the program list 141 | showkeys | Display a list of key bindings recognized by wmii 142 | status | Periodically print date and load average to the bar 143 | welcome | Display a welcome message that contains the wmii tutorial 144 145 == Default Key Bindings == 146 147 All of the provided `wmiirc` scripts accept at least the following key 148 bindings. They should also provide a `showkeys` action to open a 149 key binding quick-reference. 150 151 === Moving Around === 152 153 || Key | Action 154 | Mod-h | Move to a window to the _left_ of the one currently focused 155 | Mod-l | Move to a window to the _right_ of the one currently focused 156 | Mod-j | Move to the window _below_ the one currently focused 157 | Mod-k | Move to a window _above_ the one currently focused 158 | Mod-space | Toggle between the managed and floating layers 159 | Mod-t <tag> | Move to the view of the given <tag> 160 | Mod-n | Move to the next view 161 | Mod-b | Move to the previous view 162 | Mod-//[0-9]// | Move to the view with the given number 163 164 === Moving Things Around === 165 166 || Key | Action 167 | Mod-Shift-h | Move the current window _window_ to a column on the _left_ 168 | Mod-Shift-l | Move the current window to a column on the _right_ 169 | Mod-Shift-j | Move the current window below the window beneath it. 170 | Mod-Shift-k | Move the current window above the window above it. 171 | Mod-Shift-space | Toggle the current window between the managed and floating layer 172 | Mod-Shift-t <tag> | Move the current window to the view of the given <tag> 173 | Mod-Shift-//[0-9]// | Move the current window to the view with the given number 174 175 === Miscellaneous === 176 177 || Key | Action 178 | Mod-m | Switch the current column to _max mode_ 179 | Mod-s | Switch the current column to _stack mode_ 180 | Mod-d | Switch the current column to _default mode_ 181 | Mod-Shift-c | `Kill` the selected client 182 | Mod-p <program> | `Execute` <program> 183 | Mod-a <action> | `Execute` the named <action 184 | Mod-Enter | `Execute` an `@TERMINAL@` 185 186 = Configuration = 187 188 If you feel the need to change the default configuration, then 189 customize (as described above) the `wmiirc` action. This 190 action is executed at the end of the `wmii` script and does 191 all the work of setting up the window manager, the key bindings, 192 the bar labels, etc. 193 194 == Filesystem == 195 196 Most aspects of `wmii` are controlled via the filesystem. It is 197 usually accessed via the wmiir(1) command, but it can be 198 accessed by any ``9P``, including plan9port's 9P[1], and can be 199 mounted natively on Linux via v9fs[1], and on Inferno (which man 200 run on top of Linux). All data in the filesystem, including 201 filenames, is UTF-8 encoded. However, when accessed via 202 wmiir(1), text is automatically translated to and from your 203 locale encoding. 204 205 The filesystem is, as are many other 9P filesystems, entirely 206 synthetic. The files exist only in memory, and are not written 207 to disk. They are generally initiated on wmii startup via a 208 script such as wmiirc. Several files are used to issue commands, 209 others simply act as if they were ordinary files (their contents 210 are updated and returned exactly as written), though writing 211 them has side-effects (such as changing key bindings). A 212 description of the filesystem layout and control commands 213 follows. 214 215 == Hierarchy == 216 217 : / 218 Global control files 219 : /client/_*_/ 220 Client control files 221 : /tag/_*_/ 222 View control files 223 : /lbar/, /rbar/ 224 Files representing the contents of the bottom bar 225 : 226 227 == The / Hierarchy == 228 229 : colrules 230 The _colrules_ file contains a list of 231 rules which affect the width of newly created columns. 232 Rules have the form: 233 234 ``` /<regex>/ -> <width>[+<width>]* 235 Where, 236 237 ``` <width> := <percent of screen> | <pixels>px 238 When a new column, <n>, is created on a view whose name 239 matches <regex>, it is given the <n>th supplied <width>. 240 If there is no <n>th width, it is given 1/<ncol>th of the 241 screen. 242 243 : rules 244 PROVISIONAL 245 246 The _rules_ file contains a list of rules that may be used 247 to automatically set properties of new clients. Rules are 248 specified as: 249 250 ``` /<regex>/ <key>=<value> ... 251 where each <key> represents a command in the clients _ctl_ 252 file, and each <value> represents the value to assign to it. 253 The rules are applied when the client is first started and 254 the contents of the _props_ file match the regular 255 expression <regex>. 256 257 Additionally, the following keys are accepted and have 258 special meaning: 259 260 >> 261 : continue 262 Normally, when a matching rule is encountered, rule 263 matching stops. When the continue key is provided 264 (with any value), matching continues at the next 265 rule. 266 : force-tags=<tags> 267 Like _tags_, but overrides any settings obtained 268 obtained from the client's group or from the 269 **\_WMII_TAGS** window property. 270 << 271 : keys 272 The _keys_ file contains a list of keys which 273 `wmii` will grab. Whenever these key combinations 274 are pressed, the string which represents them are 275 written to '/event' as: Key <string> 276 : event 277 The _event_ file never returns EOF while 278 `wmii` is running. It stays open and reports events 279 as they occur. Included among them are: 280 >> 281 : [Not]Urgent <client> [Manager|Client] 282 <client>'s urgent hint has been set or 283 unset. The second arg is [Client] if it's 284 been set by the client, and [Manager] if 285 it's been set by `wmii` via a control 286 message. 287 : [Not]UrgentTag <tag> [Manager|Client] 288 A client on <tag> has had its urgent hint 289 set, or the last urgent client has had its 290 urgent hint unset. 291 : Client<Click|MouseDown> <client> <button> 292 A client's titlebar has either been clicked or 293 has a button pressed over it. 294 : [Left|Right]Bar[Click|MouseDown] <button> <bar> 295 A left or right bar has been clicked or has a 296 button pressed over it. 297 : 298 << 299 300 For a more comprehensive list of available events, see 301 _wmii.pdf_[2] 302 303 : ctl 304 The _ctl_ file takes a number of messages to 305 change global settings such as color and font, which can 306 be viewed by reading it. It also takes the following 307 commands: 308 >> 309 : quit 310 Quit `wmii` 311 : exec <prog> 312 Replace `wmii` with <prog> 313 : spawn <prog> 314 Spawn a new program, as if by the _-r_ flag. 315 : 316 << 317 : 318 319 == The /client/ Hierarchy == 320 321 Each directory under '/client/' represents an X11 client. 322 Each directory is named for the X window id of the window the 323 client represents, in the form that most X utilities recognize. 324 The one exception is the special 'sel' directory, which 325 represents the currently selected client. 326 327 : ctl 328 When read, the 'ctl' file returns the X window id 329 of the client. The following commands may be written to 330 it: 331 >> 332 : allow <flags> 333 The set of unusual actions the client is allowed to 334 perform, in the same format as the tag set. 335 >> 336 : activate 337 The client is allowed to activate 338 itself – that is, focus its window and, 339 as the case may require, uncollapse it 340 and select a tag it resides on. This 341 flag must be set on a client if you wish 342 it able to activate itself from the 343 system tray. 344 << 345 : floating <on | off | always | never> 346 Defines whether this client is likely to float when 347 attached to a new view. Ordinarilly, the value 348 changes automatically whenever the window is 349 moved between the floating and managed layers. 350 However, setting a value of _always_ or _never_ 351 overrides this behavior. Additionally, dialogs, 352 menus, docks, and splash screens will always 353 float unless this value is set to _never_. 354 : fullscreen <on | off | toggle> 355 Sets the client's fullscreen state. 356 : group <group id> 357 The client's group ID, or 0 if not part of a group. 358 Clients tend to open with the same tags and in the 359 same columns as the last active member of their 360 group. Setting this property is only useful when 361 done via the rules file. 362 : kill 363 Close the client's window. 364 : pid 365 Read-only value of the PID of the program that 366 owns the window, if the value is available and 367 the process is on the same machine as wmii. 368 : slay 369 Forcibly kill the client's connection to the X 370 server, closing all of its windows. Kill the parent 371 process if the client's PID is available. 372 : tags <tags> 373 The client's tags. The same as the tags file. 374 : urgent <on | off | toggle> 375 Set or unset the client's urgent hint. 376 << 377 378 : label 379 Set or read a client's label (title). 380 : props 381 Returns a clients class and label as: 382 <instance>:<class>:<label>. 383 : tags 384 Set or read a client's tags. Tags are separated by 385 **+**, **-**, or **^**. Tags beginning with **+** are 386 added, while those beginning with **-** are removed and 387 those beginning with **^** are toggled. If the tag 388 string written begins with **+**, **^**, or **-**, the 389 written tags are added to or removed from the client's 390 set, otherwise the set is overwritten. 391 : 392 393 == The /tag/ Hierarchy == 394 395 Each directory under '/tag/' represents a view, containing 396 all of the clients with the given tag applied. The special 397 'sel' directory represents the currently selected tag. 398 399 : ctl 400 The 'ctl' file can be read to retrieve the name 401 of the tag the directory represents, or written with the 402 following commands: 403 >> 404 : select 405 Select a client: 406 select [left|right|up|down] + 407 select [<row number>|sel] [<frame number>] + 408 select client <client> 409 : send 410 Send a client somewhere: 411 >> 412 : send [<client>|sel] [up|down|left|right] 413 : send [<client>|sel] <area> 414 Send <client> to the _n_th <area> 415 : send [<client>|sel] toggle 416 Toggle <client> between the floating and managed layer. 417 << 418 : swap 419 Swap a client with another. Same syntax as send. 420 421 : grow 422 Grow or shrink a client. 423 424 ``` grow <frame> <direction> [<amount>] 425 : nudge 426 Nudge a client in a given direction. 427 428 ``` grow <frame> <direction> [<amount>] 429 : 430 << 431 Where the arguments are defined as follows: 432 >> 433 : area 434 Selects a column or the floating area. 435 436 ``` area ::= <area_spec> | <screen_spec>:<area_spec> 437 When <screen_spec> is omitted and <area_spec> is not "sel", 438 0 is assumed. "sel" by itself represents the selected client no 439 matter which screen it is on. 440 441 ``` area_spec ::= "~" | <number> | "sel" 442 Where "~" represents the floating area and <number> represents a column 443 index, starting at one. 444 445 ``` screen_spec ::= <number> 446 Where <number> representes the 0-based Xinerama screen number. 447 448 : frame 449 Selects a client window. 450 451 ``` frame ::= <area> <index> | <area> sel | client <window-id> 452 Where <index> represents the nth frame of <area> or <window-id> is 453 the X11 window id of the given client. 454 455 : amount 456 The amount to grow or nudge something. 457 458 ``` amount ::= <number> | <number>px 459 If "px" is given, <number> is interperated as an exact pixel count. 460 Otherwise, it's interperated as a "reasonable" amount, which is 461 usually either the height of a window's title bar, or its sizing 462 increment (as defined by X11) in a given direction. 463 << 464 : index 465 Read for a description of the contents of a tag. 466 : 467 468 469 == The /rbar/, /lbar/ Hierarchy == 470 471 The files under '/rbar/' and '/lbar/' represent the 472 items of the bar at the bottom of the screen. Files under 473 '/lbar/' appear on the left side of the bar, while those 474 under '/rbar/' appear on the right, with the leftmost item 475 occupying all extra available space. The items are sorted 476 lexicographically. 477 478 The files may be read or written to obtain or alter the colors 479 and text of the bars. The format is similar to the various _ctl_ 480 files and should be self explanitory. 481 482 = FILES = 483 484 : /tmp/ns.$USER.${DISPLAY%.0}/wmii 485 The wmii socket file which provides a 9P service. 486 : @GLOBALCONF@ 487 Global action directory. 488 : @LOCALCONF@ 489 User-specific action directory. Actions are first searched here. 490 : 491 492 = ENVIRONMENT = 493 494 : $HOME, $DISPLAY 495 See the section **FILES** above. 496 : 497 The following variables are set and exported within `wmii` and 498 thus can be used in actions: 499 500 : $WMII_ADDRESS 501 The address on which `wmii` is listening. 502 : $WMII_CONFPATH 503 The path that wmii searches for its configuration 504 scripts and actions. 505 : $NAMESPACE 506 The namespace directory to use if no address is provided. 507 : 508 = SEE ALSO = 509 wimenu(1), wmii9menu(1), witray(1), wmiir(1), wihack(1) + 510 @DOCDIR@/wmii.pdf 511 @DOCDIR@/FAQ 512 513 [1] http://www.suckless.org/wiki/wmii/tips/9p_tips + 514 [2] @DOCDIR@/wmii.pdf 515