wmii/cmd/wm/wmiiwm.1

.TH WMIIWM 1 wmii-4
.SH NAME
wmiiwm \- window manager improved 2 (core)
.SH SYNOPSIS
.B wmiiwm
.B \-a
.I <address>
.RB [ \-c ]
.RB [ \-v ]
.SH DESCRIPTION
.SS Overview
.BR wmiiwm (1)
is the core of window manager improved 2.
.P
.B 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.
.P
.B 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.
.P
.B 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
.BR wmiir (1) .
This allows simple and powerful remote control of the core window manager.
.P
.B wmii
basically consists of clients, columns, views, and the bar, which are described
in detail in the
.B Terminology
section.
.SS Options
.TP
.BI \-a " address"
Lets you specify the address which
.B wmiiwm
uses to listen for connections.  The syntax for
.I address
is taken (along with many other profound ideas) from the Plan 9 operating
system and has the form
.B unix!/path/to/socket 
for unix socket files, and
.B tcp!hostname!port
for tcp sockets.
.TP
.B \-c
Checks if another window manager is running. If not it exits with termination code
0.
.TP
.B \-v
Prints version information to stdout, then exits.
.SS Terminology
.TP 2
Display
A running X server instance consisting of input devices and screens.
.TP 2
Screen
A physical or virtual (Xinerama or 
.BR Xnest (1))
screen of an X display. A screen displays a bar window and a view at a time.
.TP 2
Window
A (rectangular) drawable X object which is displayed on a screen, usually an
application window.
.TP 2
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.
.TP 2
Floating layer
A screen layer of
.B wmii
on top of all other layers, where clients are arranged in a classic (floating)
way. They can be resized or moved freely.
.TP 2
Managed layer
A screen layer of
.B 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.
.TP 2
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.
.IR work ,
or several tags, e.g.
.IR work+mail .
Tags are separated with the
.I +
character.
.TP 2
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.
.TP 2
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.
.TP 2
Bar
The bar at the bottom of the screen displays a label for each view and
allows the creation of arbitrary user\-defined labels.
.TP 2
Event
An event is a message which can be read from a special file in the filesystem
of
.BR wmiiwm ,
such as a mouse button press, a key press, or a message written by a different
9P\-client.
.SS Basic window management
Running a raw
.B wmiiwm
process without the
.BR 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
.I Mod1 (Alt)
modifier key. Other interactions like customizing the style, killing or
retagging clients, or grabbing keys cannot be achieved without accessing the
filesystem.
.P
The filesystem can be accessed by connecting to the
.I address
of
.B wmiiwm
with any 9P\-capable client, like
.BR wmiir (1).
.SS File system
The
.B 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
.B Syntax
section below.
.TP 2
Root directory
.PD 0
.RS 2
.TP 2
/bar
This directory contains a representation of each label in the bar.
.PD
.TP
/client
This directory contains a representation of each client.
.TP
/ctl
This file understands the internal commands
.IR quit ,
which quits the window manager, and
.I view
.IR <tag> ,
which switches to a view for the specific tag.
.TP
/def
This directory contains a representation of all default options.
.TP
/event
This file reports events. Reading this file is blocking, this means that
a 9P\-client will not exit until
.B wmiiwm
quits, or until the client is terminated explicitely.
.TP
/tags
This file contains a newline\-separated list of all tags currently in use.
.TP
/view
This and all other directories contain a representation of a view. The
.I /view
directory points to the currently selected view.
.RE
.TP
Bar directory
.PD 0
.RS 2
.TP 2
/bar/X/colors
This file defines the colors of the label as an RGB\-tuple.
.PD
.TP
/bar/X/data
This file contains the text displayed by the label; it may be empty.
.RE
.TP
Clients directory
.PD 0
.RS 2
.TP 2
/client/X/class
This file contains the X property
.PD
.I WM_CLASS
of the client in the form of
.IR <Class> : <instance> .
.TP
/client/X/ctl
This file understands the internal client\-specific commands
.IR kill ,
which kills (closes) the client nicely,
.I sendto
.IR <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
.IR swap <prev|next|up|down> ,
which swaps the client with an adjacent client in the specified
direction.
.TP
/client/X/geom
This file contains the geometry of the client's frame and can be used
to resize the client.
.TP
/client/X/index
This file contains the index of the client in the
.I /client
namespace.
.TP
/client/X/name
This file contains the X property
.IR WM_NAME ,
the client's name.
.TP
/client/X/tags
This file contains the tags of the client.
.RE
.TP
Defaults directory
.PD 0
.RS 2
.TP 2
/def/border
This file defines the default border width for all clients in
.PD
.I <0..n>
pixels.
.TP
/def/colmode
This file defines the default column mode of newly created columns.
.TP
/def/colwidth
This file defines the default width of newly created columns.
.TP
/def/font
This file defines the X11 font to be used.
.BR xfontsel (1)
can be used to obtain valid fontnames.
.TP
/def/grabmod
This file defines the default modifier for mouse\-grabs.
.TP
/def/keys
This file contains a newline\-separated list of all shortcuts which should
be grabbed by
.BR wmiiwm .
These are then reported as events.
.TP
/def/normcolors
This file defines the colors of unselected clients and bar labels
.TP
/def/rules
This file defines the rules for applying default tags to all clients with the
.I nil
tag and newly created clients.
.TP
/def/selcolors
This file defines the colors of selected clients and bar labels.
.RE
.TP
View directory
.PD 0
.RS 2
.TP 2
/view/X
This directory contains a representation of a column or the floating layer. The
.I /view/sel
directory points to the currently selected column or the floating layer.
.PD
.TP
/view/ctl
This file understands the internal view\-specific command
.I select
.IR <0..n> ,
which selects the specified area; 0 means floating layer, all other numeric
values address one of the columns, from left to right.
.TP
/view/name
This file contains the view's name, which corresponds to the currently viewed
clients containing the equivalent tag.
.RE
.TP
Column and floating layer directory
.PD 0
.RS 2
.TP 2
/view/X/Y
This directory contains a representation of a client of this column or the
floating layer respectively. Its contents are the same as in the
.I /client/X
namespace described above.
.PD
.TP
/view/X/ctl
This file understands the internal column\-specific command
.I select
.IR <0..n> ,
which selects the specific client from top to bottom.
.TP
/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.
.RE
.SS 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.
.TP 2
colors, selcolors, normcolors
Each of these files expects three blank\-separated color values of the form
.I #RRGGBB #RRGGBB
.IR #RRGGBB .
These tupples define foreground, background, and border colors respectively.
.TP 2
geom
This file expects four blank\-separated alphanumeric values which define the
client's geometry in the order
.I <x>
.I <y>
.I <width>
.IR <height> .
Each value can be absolute like
.IR <0..n> ,
or an alignment value such as
.IR north ,
.IR west ,
.IR south ,
.IR east ,
or
.IR 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
.I +
or
.I \-
operators, which makes them relative to the old value, e.g.
.IR \-40 .
Alignment values can be appended with a relative value to address special positions, e.g.
.IR south\-16 .
.TP 2
colmode, mode
Each of these files expects one of the values
.IR default ,
.IR stack ,
or
.IR max ,
defining the default, stacking, or maximized mode for columns respectively.
.TP 2
grabmod
This file expects one of the values
.IR Mod1 ,
.IR Mod2 ,
.IR Mod3 ,
.IR Mod4 ,
or
.IR Mod5 .
The value corresponds to the modifier key defined in X.
For most keyboard layouts,
.IR Mod1
is the
.IR Alt
key.
.TP 2
keys
This file expects a newline\-separated list of shortcuts of the form
.BI [<modifier>\-] <key> .
The modifier can be one or a combination of the following values:
.IR Mod1 ,
.IR Mod2 ,
.IR Mod3 ,
.IR Mod4 ,
.IR Mod5 ,
.IR Control ,
and
.IR Shift .
For example, a valid modifier might be
.IR 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
.BR xev (1)
utility.
.TP 2
rules
This file expects a newline\-separated list of rules, each taking the form
.B /regexp/
\->
.IR <tag> ,
where
.I regexp
must be a POSIX compliant regular expression as defined in
.BR regex (7).
See the
.B wmiirc
script for examples.
The rules are matched against the
.I class
and 
.I 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.
.RS 2
.PP
If the rules file is empty,
.B wmiiwm
assigns the
.I nil
tag to each client by default, resulting in only the nil\-view.
Clients that contain a tag already, except the
.I nil
tag, are not matched.
.PP
The special
.I ~
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
.I !
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
.I nil
is desired, e.g.
.IR 1,
then the last rule should be defined in the following form:
.B /.*/
\->
.IR <default\-tag> .
.SS Processing events
To run
.B wmiiwm
in a useful way, it needs to be controlled by reading events
from the
.I /event
file described above.
.B wmiiwm reports the following events:
.TP 2
BarClick <label> <button>
This event is reported whenever a label in the bar is clicked.
The
.IR <label>
argument contains the name of the label in the
.I /bar
namespace. The
.IR <button>
argument contains the index of the mouse button that was pressed during the
click, e.g.
.IR 1,
if it was the left mouse button.
.TP 2
ClientClick <index> <button>
This event is reported whenever a client frame is clicked.
The
.IR <index>
argument is the index of this client in the
.I /client
namespace. The
.IR <button>
argument contains the index of the mouse button that was pressed during the
click, e.g.
.IR 1,
if it was the left mouse button.
.TP 2
ClientFocus <index>
This event is reported whenever a client is focused. The
.IR <index>
argument is the index of this client in the
.I /client
namespace.
.TP 2
CreateClient <index>
This event is reported whenever a client is created. The
.IR <index>
argument is the index of this client in the
.I /client
namespace.
.TP 2
Key <shortcut>
This event is reported whenever a shortcut is pressed that was
grabbed through writing the
.I /def/keys
file.
.TP 2
User defined
Any writes to the
.I /event
file will be reported to all readers. This allows to implement user defined
events.
.SH SEE ALSO
.BR wmii (1),
.BR wmiimenu (1),
.BR wmiir (1)