WMIIWM(1)

NAME
wmiiwm - window manager improved 2 (core)

SYNOPSIS
wmiiwm -a <address> [-c] [-v]

DESCRIPTION

  Overview
wmiiwm(1) is the core of window manager improved 2.

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

  Options

-a address
    Lets you specify the address which wmiiwm uses to listen for connections. The syntax for address is taken (along with many other profound ideas) from the Plan 9 operating system and has the form unix!/path/to/socket for unix socket files, and tcp!hostname!port for tcp sockets.

-c  Checks if another window manager is running. If not it exits with termination code 0.

-v  Prints version information to stdout, then exits.

  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 title-bar. The title-bar contains three labels. The first one displays the tags of a client, the second one displays the client's title, and the third one displays the client's index and the total number of clients within the column. If the client is focused within the column, the third label is highlighted. If the client is attached to the floating layer, a ~ character is prepended in the third label as well.

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 similiar 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 wmiiwm, such as a mouse button press, a key press, or a message written by a different 9P-client.

  Basic window management
Running a raw wmiiwm process without the wmii(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 like customizing the style, killing or retagging clients, or grabbing keys cannot be achieved without accessing the filesystem.

The filesystem can be accessed by connecting to the address of wmiiwm with any 9P-capable client, like wmiir(1).

  File system
The wmiiwm filesystem is designed with simplicity and clarity in mind. It consists of logical namespaces which represent its internal state and data structure in a straight-forward way. The following is a short description of each file and directory contained within the filesystem. For more information on the actual data stored in these files and the syntax recognized by each, see the Syntax section below.

Root directory
    /bar
        This directory contains a representation of each label in the bar.

    /client
        This directory contains a representation of each client.

    /ctl
        This file understands the internal commands quit, which quits the window manager, and view <tag>, which switches to a view for the specific tag.

    /def
        This directory contains a representation of all default options.

    /event
        This file reports events. Reading this file is blocking, this means that a 9P-client will not exit until wmiiwm quits, or until the client is terminated explicitely.

    /tags
        This file contains a newline-separated list of all tags currently in use.

    /view
        This and all other directories contain a representation of a view. The /view directory points to the currently selected view.

Bar directory
    /bar/X/colors
        This file defines the colors of the label as an RGB-tuple.

    /bar/X/data
        This file contains the text displayed by the label; it may be empty.

Clients directory
    /client/X/class
        This file contains the X property WM_CLASS of the client in the form of <Class>:<instance>.

    /client/X/ctl
        This file understands the internal client-specific command kill, which kills (closes) the client nicely.

    /client/X/geom
        This file contains the geometry of the client's frame.

    /client/X/index
        This file contains the index of the client in the /client namespace.

    /client/X/name
        This file contains the X property WM_NAME, the client's name.

    /client/X/tags
        This file contains the tags of the client.

Defaults directory
    /def/border
        This file defines the default border width for all clients in <0..n> pixels.

    /def/colmode
        This file defines the default column mode of newly created columns.

    /def/colwidth
        This file defines the default width of newly created columns.

    /def/font
        This file defines the X11 font to be used. xfontsel(1) can be used to obtain valid fontnames.

    /def/grabmod
        This file defines the default modifier for mouse-grabs.

    /def/keys
        This file contains a newline-separated list of all shortcuts which should be grabbed by wmiiwm. These are then reported as events.

    /def/normcolors
        This file defines the colors of unselected clients and bar labels

    /def/rules
        This file defines the rules for applying default tags to all clients with the nil tag and newly created clients.

    /def/selcolors
        This file defines the colors of selected clients and bar labels.

View directory
    /view/X
        This directory contains a representation of a column or the floating layer. The /view/sel directory points to the currently selected column or the floating layer.

    /view/ctl
        This file understands the internal view-specific command select <0..n>, which selects the specified area; 0 means floating layer, all other numeric values address one of the columns, from left to right.

    /view/name
        This file contains the view's name, which corresponds to the currently viewed clients containing the equivalent tag.

Column and floating layer directory
    /view/X/Y
        This directory contains a representation of a client of this column or the floating layer respectively. Its contents are roughly the same as in the /client/X namespace described above. There are two important differences though: First, the ctl file accepts the additional commands sendto <prev|next|0..n|toggle>, which sends the client to the previous, next, or explicitely addressed column, or toggles it between the floating and managed layer, and swap <prev|next|up|down>, which swaps the client with an adjacent client in the specified direction. Second, the geom file is writable, so it can be used to resize the client.

    /view/X/ctl
        This file understands the internal column-specific command select <0..n>, which selects the specific client from top to bottom.

    /view/X/mode
        This file defines the column mode of this column, described in detail below. Note, floating layer directories do not contain this file.

  Syntax
All files of the filesystem described above can be read, most of them can be written as well. Most of them only can be written using valid syntax.

colors, selcolors, normcolors
    Each of these files expects three blank-separated color values of the form #RRGGBB #RRGGBB #RRGGBB. These tupples define foreground, background, and border colors respectively.

geom
    This file expects four blank-separated alphanumeric values which define the client's geometry in the order <x> <y> <width> <height>. Each value can be absolute like <0..n>, or an alignment value such as north, west, south, east, or center. The alignment values address the screen border or center respectively. Thus they provide a resolution-independent way of addressing specific coordinates. Absolute values can be prepended with the + or - operators, which makes them relative to the old value, e.g. -40. Alignment values can be appended with a relative value to address special positions, e.g. south-16.

colmode, mode
    Each of these files expects one of the values default, stack, or max, defining the default, stacking, or maximized mode for columns respectively.

grabmod
    This file expects one of the values Mod1, Mod2, Mod3, Mod4, or Mod5. The value corresponds to the modifier key defined in X. For most keyboard layouts, Mod1 is the Alt key.

keys
    This file expects a newline-separated list of shortcuts of the form [<modifier>-]<key>. The modifier can be one or a combination of the following values: Mod1, Mod2, Mod3, Mod4, Mod5, Control, and Shift. For example, a valid modifier might be Mod1-Control-Shift. It's also possible to have no modifier at all (just a key). This is still valid syntax. The key and modifier values must correspond to the key symbols reported by the xev(1) utility.

rules
    This file expects a newline-separated list of rules, each taking the form /regexp/ -> <tag>, where regexp must be a POSIX compliant regular expression as defined in regex(7). See the wmiirc script for examples. The rules are matched against the class and name file contents of a client whenever the rules file is written. The order in which the rules occur is important since they are applied from top to bottom.

    If the rules file is empty, wmiiwm assigns the nil tag to each client by default, resulting in only the nil-view. Clients that contain a tag already, except the nil tag, are not matched.

    The special ~ tag makes the matched client floating at the time of creation or retag. It has to be assigned in a seperate rule and is always matched. The special ! tag causes the matched client to inherit the currently viewed tag but only if no rule has matched yet. It should always be defined right before the point where the default tag is assigned. If a default tag other than nil is desired, e.g. 1, then the last rule should be defined in the following form: /.*/ -> <default-tag>.

  Processing events
To run wmiiwm in a useful way, it needs to be controlled by reading events from the /event file described above. wmiiwm reports the following events:

BarClick <label> <button>
    This event is reported whenever a label in the bar is clicked. The <label> argument contains the name of the label in the /bar namespace. The <button> argument contains the index of the mouse button that was pressed during the click, e.g. 1, if it was the left mouse button.

ClientClick <index> <button>
    This event is reported whenever a client frame is clicked. The <index> argument is the index of this client in the /client namespace. The <button> argument contains the index of the mouse button that was pressed during the click, e.g. 1, if it was the left mouse button.

ClientFocus <index>
    This event is reported whenever a client is focused. The <index> argument is the index of this client in the /client namespace.

CreateClient <index>
    This event is reported whenever a client is created. The <index> argument is the index of this client in the /client namespace.

Key <shortcut>
    This event is reported whenever a shortcut is pressed that was grabbed through writing the /def/keys file.

User defined
    Any writes to the /event file will be reported to all readers. This allows to implement user defined events.

SEE ALSO
wmii(1), wmiimenu(1), wmiir(1)