Overview

wmii supports classic and tiled window management with extended keyboard 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 virtual 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 connections. 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 single argument, $WMII_CONFPATH is searched before $PATH. Otherwise, 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 display. 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 window 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

The filesystem can be accessed by connecting to the address of wmii with any 9P-capable client, such as wmiir(1)

Actions

Here is a list of the default actions:

Default Key Bindings

Moving Around

Moving Things Around

Miscellaneous

Filesystem

The filesystem is, as are many other 9P filesystems, entirely synthetic. 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 control 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 colrules. 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:

The /client/ Hierarchy

ctl

When read, the 'ctl' file returns the X window id of the client. The following commands may be written to it:

The /tag/ Hierarchy

ctl

The 'ctl' file can be read to retrieve the name of the tag the directory represents, or written with the following commands:

The /rbar/, /lbar/ Hierarchy

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, respectively. When writing the bar files, the colors may be omitted if the text would not otherwise appear to contain them.