WMII(1)

NAME
wmii-VERSION

SYNOPSIS
wmii [-a<address>] [-c<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 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 nonoverlapping 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 9Pcapable 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.

  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 nonoverlapping (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 userdefined 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 effectively, 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/obj/ports/wmii-3.6p4/fake-alpha/usr/local/share/examples//wmii-3.5 to $HOME/.wmii-3.5 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

  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 to 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 customize (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 window 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 client, 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 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:

    NotUrgent 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 message.

    NotUrgentTag tag Manager|Client
        A client on tag has had its urgent hint set, or the last urgent client has had its urgent hint unset.

    ClientClick|ClientMouseDown client button
        A client's titlebar has either been clicked or has a button pressed over it.

    Left|RightBarClick|MouseDown button bar
        A left or right bar has been clicked or has a button pressed over it.

    ... To be continued...

ctl The ctl file takes a number of messages to change global settings 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

  The /client/ Hierarchy

Each directory under /client/ represents an X11 client. Each directory 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 windows), while the close command will replace it.

    NotUrgent
        Set or unset the client's urgent hint.

    NotFullscreen

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, otherwise, 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 represents 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.

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, respectively. 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/obj/ports/wmii-3.6p4/fake-alpha/usr/local/share/examples//wmii-3.5
    Global action directory.

$HOME/.wmii-3.5
    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
    Socket file of Used by wmiir(1).

SEE ALSO
dmenu(1), wmiir(1)

[1] http://www.suckless.org/wiki/wmii/tips/9p_tips