WMII(1)WMII(1)NAMEwmii - Window Manager Improved²
SYNOPSISwmii [-a <address>] [-r <wmiirc>]
wmii-v
DESCRIPTION
Overview
wmii is a dynamic window manager for X11. In contrast to static window
management the user rarely has to think about how to organize windows,
no matter what he is doing or how many applications are used at the
same time. The window manager adapts to the current environment and
fits to the needs of the user, rather than forcing him to use a preset,
fixed layout and trying to shoehorn all windows and applications into
it.
wmii supports classic and tiled window management with extended key‐
board and mouse control. The classic window management arranges windows
in a floating layer in which windows can be moved and resized freely.
The tiled window management is based on columns which split up the
screen horizontally. Each column handles arbitrary windows and arranges
them vertically in a non-overlapping way. They can then be moved and
resized between and within columns at will.
wmii provides a virtual filesystem which represents the internal state
similar to the procfs of Unix operating systems. Modifying this vir‐
tual filesystem results in changing the state of the window manager.
The virtual filesystem service can be accessed through 9P-capable
client programs, like wmiir(1). This allows simple and powerful remote
control of the core window manager.
wmii basically consists of clients, columns, views, and the bar, which
are described in detail in the Terminology section.
Command Line Arguments
-a <address>
Specifies the address on which wmii should listen for connec‐
tions. The address takes the form <protocol>!<address>. The
default is of the form:
unix!/tmp/ns.$USER.${DISPLAY%.0}/wmii
which opens a unix socket per Plan 9 Port conventions. To open a
TCP socket, listening at port 4332 on the loopback interface,
use:
tcp!localhost!4332
$WMII_NAMESPACE is automatically set to this value.
-r <wmiirc>
Specifies which rc script to run. If <wmiirc> consists of a sin‐
gle argument, $WMII_CONFPATH is searched before $PATH. Other‐
wise, it is passed to the shell for evaluation. The environment
variables $WMII_ADDRESS and $WMII_CONFPATH are preset for the
script.
== Terminology ==
Display
A running X server instance consisting of input devices and
screens.
Screen A physical or virtual (Xinerama or Xnest(1)) screen of an X dis‐
play. A screen displays a bar window and a view at a time.
Window A (rectangular) drawable X object which is displayed on a
screen, usually an application window.
Client An application window surrounded by a frame window containing a
border and a titlebar.
Floating layer
A screen layer of wmii on top of all other layers, where clients
are arranged in a classic (floating) way. They can be resized
or moved freely.
Managed layer
A screen layer of wmii behind the floating layer, where clients
are arranged in a non-overlapping (managed) way. Here, the win‐
dow manager dynamically assigns each client a size and position.
The managed layer consists of columns.
Tag Alphanumeric strings which can be assigned to a client. This
provides a mechanism to group clients with similar properties.
Clients can have one tag, e.g. work, or several tags, e.g.
work+mail. Tags are separated with the + character.
View A set of clients containing a specific tag, quite similar to a
workspace in other window managers. It consists of the floating
and managed layers.
Column A column is a screen area which arranges clients vertically in a
non-overlapping way. Columns provide three different modes,
which arrange clients with equal size, stacked, or maximized
respectively. Clients can be moved and resized between and
within columns freely.
Bar The bar at the bottom of the screen displays a label for each
view and allows the creation of arbitrary user-defined labels.
Event An event is a message which can be read from a special file in
the filesystem of wmii, such as a mouse button press, a key
press, or a message written by a different 9P-client.
Basic window management
Running a raw wmii process without a wmiirc(1) script provides basic
window management capabilities already. However, to use it effec‐
tively, remote control through its filesystem interface is necessary.
By default it is only usable with the mouse in conjunction with the
Mod1 (Alt) modifier key. Other interactions, such as customizing the
style, killing or retagging clients, and grabbing keys, cannot be
achieved without accessing the filesystem.
The filesystem can be accessed by connecting to the address of wmii
with any 9P-capable client, such as wmiir(1)
Actions
An action is a shell script in the default setup, but it can actually
be any executable file. It is executed usually by selecting it from
the actions menu. You can customize an action by copying it from the
global action directory '/usr/local/etc/wmii' to '$HOME/.wmii' and then
editing the copy to fit your needs. Of course you can also create your
own actions there; make sure that they are executable.
Here is a list of the default actions:
quit leave the window manager nicely
status periodically print date and load average to the bar
welcome display a welcome message that contains the wmii tutorial
wmiirc configure wmii
Default Key Bindings
All of the provided wmiirc scripts accept at least the following key
bindings. They should also provide a showkeys action to open a key
binding quick-reference.
Moving Around
Key Action
Mod-h Move to a window to the left of the one currently focused
Mod-l Move to a window to the right of the one currently focused
Mod-j Move to the window below the one currently focused
Mod-k Move to a window above the one currently focused
Mod-space Toggle between the managed and floating layers
Mod-t <tag> Move to the view of the given <tag>
Mod-[0-9] Move to the view with the given number
Moving Things Around
Key Action
Mod-Shift-h Move the current window window to a column on the left
Mod-Shift-l Move the current window to a column on the right
Mod-Shift-j Move the current window below the window beneath it.
Mod-Shift-k Move the current window above the window above it.
Mod-Shift-space Toggle the current window between the managed and floating layer
Mod-Shift-t <tag> Move the current window to the view of the given <tag>
Mod-Shift-[0-9] Move the current window to the view with the given number
Miscellaneous
Key Action
Mod-m Switch the current column to max mode
Mod-s Switch the current column to stack mode
Mod-d Switch the current column to default mode
Mod-Shift-c Kill the selected client
Mod-p <program> Execute <program>
Mod-a <action> Execute the named <action
Mod-Enter Execute an xterm
Configuration
If you feel the need to change the default configuration, then custom‐
ize (as described above) the wmiirc action. This action is executed at
the end of the wmii script and does all the work of setting up the win‐
dow manager, the key bindings, the bar labels, etc.
Filesystem
Most aspects of wmii are controlled via the filesystem. It is usually
accessed via the wmiir(1) command, but it can be accessed by any 9P,
including plan9port's 9P[1], and can be mounted natively on Linux via
v9fs[1], and on Inferno (which man run on top of Linux).
The filesystem is, as are many other 9P filesystems, entirely syn‐
thetic. The files exist only in memory, and are not written to disk.
They are generally initiated on wmii startup via a script such as
rc.wmii or wmiirc. Several files read commands, others simply act as if
they were ordinary files (their contents are updated and returned
exactly as written), though writing them has side-effects (such as
changing key bindings). A description of the filesystem layout and con‐
trol commands follows.
Hierarchy
/ Global control files
/client/*/
Client control files
/tag/*/
View control files
/lbar/, /rbar/
Files representing the contents of the bottom bar
The / Hierarchy
colrules
The colrules file contains a list of rules which affect the
width of newly created columns. Rules have the form:
/<regex>/ -> <width>[+<width>]*
When a new column, n, is created on a view whose name matches
<regex>, the nth given <width> percentage of the screen is given
to it. If there is no nth width, 1/ncolth of the screen is given
to it.
tagrules
The tagrules file contains a list of rules similar to the col‐
rules. These rules specify the tags a client is to be given when
it is created. Rules are specified:
/<regex>/ -> <tag>[+<tag>]*
When a client's <name>:<class>:<title> matches <regex>, it is
given the tagstring <tag>. There are two special tags. !, which
is deprecated, and identical to sel, represents the current tag.
~ represents the floating layer.
keys The keys file contains a list of keys which wmii will grab.
Whenever these key combinations are pressed, the string which
represents them are written to '/event' as: Key <string>
event The event file never returns EOF while wmii is running. It stays
open and reports events as they occur. Included among them are:
[Not]Urgent <client> [Manager|Client]
<client>'s urgent hint has been set or unset. The second
arg is [Client] if it's been set by the client, and
[Manager] if it's been set by wmii via a control mes‐
sage.
[Not]UrgentTag <tag> [Manager|Client]
A client on <tag> has had its urgent hint set, or the
last urgent client has had its urgent hint unset.
Client<Click|MouseDown> <client> <button>
A client's titlebar has either been clicked or has a
button pressed over it.
[Left|Right]Bar[Click|MouseDown] <button> <bar>
A left or right bar has been clicked or has a button
pressed over it.
For a more comprehensive list of available events, see wmii.pdf[2]
ctl The ctl file takes a number of messages to change global set‐
tings such as color and font, which can be viewed by reading it.
It also takes the following commands:
quit Quit wmii
exec <prog>
Replace wmii with <prog>
spawn <prog>
Spawn a new program, as if by the -r flag.
The /client/ Hierarchy
Each directory under '/client/' represents an X11 client. Each direc‐
tory is named for the X window id of the window the client represents,
in the form that most X utilities recognize. The one exception is the
special 'sel' directory, which represents the currently selected
client.
ctl When read, the 'ctl' file returns the X window id of the client.
The following commands may be written to it:
kill Close the client's window. This command will likely kill
the X client in the future (including its other win‐
dows), while the close command will replace it.
Urgent <on | off | toggle>
Set or unset the client's urgent hint.
Fullscreen <on | off | toggle>
label Set or read a client's label (title).
props Returns a clients class and label as: <name>:<class>:<label>
tags Set or read a client's tags. Tags are separated by + or -. Tags
beginning with + are added, while those beginning with - are
removed. If the tag string written begins with + or -, the
written tags are added to or removed from the client's set, oth‐
erwise, the set is overwritten.
The /tag/ Hierarchy
Each directory under '/tag/' represents a view, containing all of the
clients with the given tag applied. The special 'sel' directory repre‐
sents the currently selected tag.
ctl The 'ctl' file can be read to retrieve the name of the tag the
directory represents, or written with the following commands:
select Select a client: select [left|right|up|down]
select [<row number>|sel] [<frame number>]
select client <client>
send Send a client somewhere:
send [<client>|sel] [up|down|left|right]
send [<client>|sel] <area>
Send <client> to the nth <area>
send [<client>|sel] toggle
Toggle <client> between the floating and managed
layer.
swap Swap a client with another. Same syntax as send.
grow Grow or shrink a client.
grow <frame> <direction> [<amount>]
nudge Nudge a client in a given direction.
grow <frame> <direction> [<amount>]
Where the arguments are defined as follows:
area Selects a column or the floating area.
area ::= <area_spec> | <screen_spec>:<area_spec>
When <screen_spec> is omitted and <area_spec> is not
"sel", 0 is assumed. "sel" by itself represents the
selected client no matter which screen it is on.
area_spec ::= "~" | <number> | "sel"
Where "~" represents the floating area and <number> rep‐
resents a column index, starting at one.
screen_spec ::= <number>
Where <number> representes the 0-based Xinerama screen
number.
frame Selects a client window.
frame ::= <area> <index> | <area> sel | client <window-id>
Where <index> represents the nth frame of <area> or
<window-id> is the X11 window id of the given client.
amount The amount to grow or nudge something.
amount ::= <number> | <number>px
If "px" is given, <number> is interperated as an exact
pixel count. Otherwise, it's interperated as a "reason‐
able" amount, which is usually either the height of a
window's title bar, or its sizing increment (as defined
by X11) in a given direction.
index Read for a description of the contents of a tag.
The /rbar/, /lbar/ Hierarchy
The files under '/rbar/' and '/lbar/' represent the items of the bar at
the bottom of the screen. Files under '/lbar/' appear on the left side
of the bar, while those under '/rbar/' appear on the right, with the
leftmost item occupying all extra available space. The items are sorted
lexicographically.
The files may be read to obtain the colors and text of the bars. The
colors are at the beginning of the string, represented as a tuple of 3
hex color codes for the foreground, background, and border, respec‐
tively. When writing the bar files, the colors may be omitted if the
text would not otherwise appear to contain them.
FILES
/tmp/ns.$USER.${DISPLAY%.0}/wmii
The wmii socket file which provides a 9P service.
/usr/local/etc/wmii
Global action directory.
$HOME/.wmii
User-specific action directory. Actions are first searched here.
ENVIRONMENT
$HOME, $DISPLAY
See the section FILES above.
The following variables are set and exported within wmii and thus can
be used in actions:
$WMII_ADDRESS
The address on which wmii is listening.
$NAMESPACE
The namespace directory to use if no address is provided.
SEE ALSOdmenu(1), wmiir(1)
/usr/local/share/doc/wmii/wmii.pdf
[1] http://www.suckless.org/wiki/wmii/tips/9p_tips
[2] /usr/local/share/doc/wmii/wmii.pdf
wmii-3.9.2 Oct, 2009 WMII(1)
