NAME¶
wmii - Window Manager Improved²
SYNOPSIS¶
wmii
[-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 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¶
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
'/etc/X11/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 x-terminal-emulator |
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, 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:
- [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
message.
- [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 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>
- spawn <prog>
- Spawn a new program, as if by the -r flag.
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.
- 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, 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.
- 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>
represents 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
"reasonable" 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, 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.
- /etc/X11/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 ALSO¶
dmenu(1),
wmiir(1)
/build/buildd-wmii_3.9.2+debian-4-amd64-MrupLm/wmii-3.9.2+debian/debian/wmii/usr/share/doc/wmii/wmii.pdf
[1] http://www.suckless.org/wiki/wmii/tips/9p_tips
[2]
/build/buildd-wmii_3.9.2+debian-4-amd64-MrupLm/wmii-3.9.2+debian/debian/wmii/usr/share/doc/wmii/wmii.pdf