wmii/man/wmii.1

'\" t
.\" Manual page created with latex2man on Wed Oct 15 16:08:29 EDT 2008
.\" NOTE: This file is generated, DO NOT EDIT.
.de Vb
.ft CW
.nf
..
.de Ve
.ft R

.fi
..
.TH "WMII" "1" "  Wed Dec 31 19:00:00 EDT 1969
" "" ""
.SH NAME
wmii\-VERSION
.PP
.SH SYNOPSIS
wmii
[\fB\-a\fP\fI<address>\fP]
[\fB\-c\fP\fI<wmiirc>\fP]
.br
wmii
\fB\-v\fP
.PP
.SH DESCRIPTION
.PP
.SS OVERVIEW
.PP
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. 
.PP
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. 
.PP
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 
\fIwmiir\fP(1)\&.
This allows simple and powerful remote control 
of the core window manager. 
.PP
wmii
basically consists of clients, columns, views, and 
the bar, which are described in detail in the 
\fBTerminology\fP
section. 
.PP
.SS TERMINOLOGY
.PP
.TP
Display
A running X server instance consisting of input 
devices and screens. 
.TP
Screen
A physical or virtual (Xinerama or \fIXnest\fP(1))
screen of an X display. A screen displays a bar window 
and a view at a time. 
.TP
Window
A (rectangular) drawable X object which is 
displayed on a screen, usually an application window. 
.TP
Client
An application window surrounded by a frame window 
containing a border and a titlebar. 
.TP
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. 
.TP
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. 
.TP
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. 
\fIwork\fP,
or several tags, e.g. \fIwork+mail\fP\&.
Tags are separated with the \fI+\fP
character. 
.TP
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. 
.TP
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
Bar
The bar at the bottom of the screen displays a label 
for each view and allows the creation of arbitrary 
userdefined labels. 
.TP
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. 
.PP
.SS BASIC WINDOW MANAGEMENT
.PP
Running a raw wmii
process without a \fIwmiirc\fP(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 \fIMod1 (Alt)\fP
modifier key. Other interactions, such as customizing the style, 
killing or retagging clients, and grabbing keys, cannot be 
achieved without accessing the filesystem. 
.PP
The filesystem can be accessed by connecting to the 
\fIaddress\fP
of wmii
with any 9P\-capable client, such 
as \fIwmiir\fP(1)
.PP
.SS ACTIONS
.PP
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 
CONFPREFIX/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. 
.PP
Here is a list of the default actions: 
.PP
.TS
tab(&) expand;
l lS.
T{
quit 
T}&T{
leave the window manager nicely 
T}
T{
status 
T}&T{
periodically print date and load average to the bar 
T}
T{
welcome 
T}&T{
display a welcome message that contains the wmii tutorial 
T}
T{
wmiirc 
T}&T{
configure wmii 
T}
.TE
.PP
.SS DEFAULT KEY BINDINGS
.SS Moving Around
.PP
.TS
tab(&) expand;
l lS.
T{
\fBKey\fP
T}&T{
\fBAction\fP
T}
T{
Mod\-h 
T}&T{
Move to a window to the \fIleft\fP
of the one currently 
focused 
T}
T{
Mod\-l 
T}&T{
Move to a window to the \fIright\fP
of the one currently 
focused 
T}
T{
Mod\-j 
T}&T{
Move to the window \fIbelow\fP
the one currently focused 
T}
T{
Mod\-k 
T}&T{
Move to a window \fIabove\fP
the one currently focused 
T}
T{
Mod\-space 
T}&T{
Toggle between the managed and floating layers 
T}
T{
Mod\-t \fItag\fP
T}&T{
Move to the view of the given \fItag\fP
T}
T{
Mod\-\fI[0\-9]\fP
T}&T{
Move to the view with the given number 
T}
.TE
.PP
.SS Moving Things Around
.PP
.TS
tab(&) expand;
l lS.
T{
\fBKey\fP
T}&T{
\fBAction\fP
T}
T{
Mod\-Shift\-h 
T}&T{
Move the current window \fIwindow\fP
to a 
column on the \fIleft\fP
T}
T{
Mod\-Shift\-l 
T}&T{
Move the current window to a column 
on the \fIright\fP
T}
T{
Mod\-Shift\-j 
T}&T{
Move the current window below the window 
beneath it. 
T}
T{
Mod\-Shift\-k 
T}&T{
Move the current window above the window 
above it. 
T}
T{
Mod\-Shift\-space 
T}&T{
Toggle the current window between the 
managed and floating layer 
T}
T{
Mod\-Shift\-t \fItag\fP
T}&T{
Move the current window to the 
view of the given \fItag\fP
T}
T{
Mod\-Shift\-\fI[0\-9]\fP
T}&T{
Move to the current window to the 
view with the given number 
T}
.TE
.PP
.SS Miscellaneous
.PP
.TS
tab(&) expand;
l lS.
T{
\fBKey\fP
T}&T{
\fBAction\fP
T}
T{
Mod\-m 
T}&T{
Switch the current column to \fImax mode\fP
T}
T{
Mod\-s 
T}&T{
Switch the current column to \fIstack mode\fP
T}
T{
Mod\-d 
T}&T{
Switch the current column to \fIdefault mode\fP
T}
T{
Mod\-Shift\-c 
T}&T{
Kill
the selected client 
T}
T{
Mod\-p \fIprogram\fP
T}&T{
Execute
\fIprogram\fP
T}
T{
Mod\-a \fIaction\fP
T}&T{
Execute
the named \fIaction\fP
T}
T{
Mod\-Enter 
T}&T{
Execute
an xterm
T}
.TE
.PP
.SH CONFIGURATION
.PP
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. 
.PP
.SH FILESYSTEM
.PP
Most aspects of wmii
are controlled via the filesystem. 
It is usually accessed via the \fIwmiir\fP(1)
command, but it 
can be accessed by any 9P
client, including plan9port\&'s 
\fI9P\fP(1),
and can be mounted natively on Linux via v9fs[1], 
and on Inferno (which man run on top of Linux). 
.PP
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. 
.PP
.SS Hierarchy
.TP
/
Global control files 
.TP
/client/\fI*\fP/
Client control files 
.TP
/tag/\fI*\fP/
View control files 
.TP
/lbar/, /rbar/
Files representing the contents of the 
bottom bar 
.PP
.SS The / Hierarchy
.TP
colrules
The \fIcolrules\fP
file contains a list of 
rules which affect the width of newly created columns. 
Rules have the form: 
.br
\fB \fP
.br
\fB \fP\fB \fP/\fIregex\fP/
\-> \fIwidth\fP[\fI+width...\fP]
.br
\fB \fP
.br
When a new column, \fIn\fP,
is created on a view whose 
name matches \fIregex\fP,
the \fIn\fPth
given 
\fIwidth\fP
percentage of the screen is given to it. If 
there is no \fIn\fPth
width, 1/\fIncol\fPth
of the 
screen is given to it. 
.TP
tagrules
The \fItagrules\fP
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: 
.br
\fB \fP
.br
\fB \fP\fB \fP/\fIregex\fP/
\-> \fItag\fP[\fI+tag...\fP]
.br
\fB \fP
.br
When a client\&'s \fIname\fP:\fIclass\fP:\fItitle\fP
matches 
\fIregex\fP,
it is given the tagstring \fItag\fP\&.
There are 
two special tags. \fI!\fP,
which is deprecated, and identical 
to \fIsel\fP,
represents the current tag. \fI~\fP
represents the floating layer. 
.TP
keys
The \fIkeys\fP
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 \fIstring\fP
.TP
event
The \fIevent\fP
file never returns EOF while 
wmii
is running. It stays open and reports events 
as they occur. Included among them are: 
.RS
.TP
\fINot\fPUrgent \fIclient\fP \fIManager|Client\fP
\fIclient\fP\&'s
urgent hint has been set or 
unset. The second arg is \fIClient\fP
if it\&'s 
been set by the client, and \fIManager\fP
if 
it\&'s been set by wmii
via a control 
message. 
.TP
\fINot\fPUrgentTag \fItag\fP \fIManager|Client\fP
A client on \fItag\fP
has had its urgent hint 
set, or the last urgent client has had its 
urgent hint unset. 
.TP
ClientClick|ClientMouseDown \fIclient\fP \fIbutton\fP
A client\&'s titlebar has either been clicked or 
has a button pressed over it. 
.TP
\fILeft|Right\fPBar\fIClick|MouseDown\fP \fIbutton\fP \fIbar\fP
A left or right bar has been clicked or has a 
button pressed over it. 
.TP
\&.\&.\&.
To be continued... 
.RE
.RS
.PP
.RE
.TP
ctl
The \fIctl\fP
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: 
.RS
.TP
quit
Quit wmii
.TP
exec \fIprog\fP
Replace wmii
with 
\fIprog\fP
.RE
.RS
.PP
.RE
.PP
.SS The /client/ Hierarchy
.PP
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. 
.PP
.RE
.TP
ctl
When read, the ctl
file returns the X window id 
of the client. The following commands may be written to 
it: 
.RS
.TP
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. 
.TP
\fINot\fPUrgent
Set or unset the client\&'s urgent 
hint. 
.TP
\fINot\fPFullscreen
.RS
.PP
.RE
.RE
.PP
.RE
.TP
label
Set or read a client\&'s label (title). 
.TP
props
Returns a clients class and label as: 
\fIname\fP:\fIclass\fP:\fIlabel\fP
.TP
tags
Set or read a client\&'s tags. Tags are separated by 
\fI+\fP
or \fI\-\fP\&.
Tags beginning with \fI+\fP
are 
added, while those beginning with \fI\-\fP
are removed. 
If the tag string written begins with \fI+\fP
or 
\fI\-\fP,
the written tags are added to or removed from 
the client\&'s set, otherwise, the set is overwritten. 
.PP
.SS The /tag/ Hierarchy
.PP
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. 
.PP
.TP
ctl
The ctl
file can be read to retrieve the name 
of the tag the directory represents, or written with the 
following commands: 
.RS
.TP
select
Select a client: 
.br
\fB \fP\fB \fPselect \fIdirection\fP
.br
\fB \fP\fB \fPselect \fIframe\fP
.br
.TP
send
Send a client somewhere: 
.RS
.TP
send \fIclient|sel\fP \fIup|down|left|right\fP
.TP
send \fIclient|sel\fP \fIarea\fP
Send 
\fIclient\fP
to the nth \fIarea\fP
.TP
send \fIclient|sel\fP toggle
Toggle 
\fIclient\fP
between the floating and 
managed layer. 
.RE
.RS
.PP
.RE
.TP
swap
Swap a client with another. Same syntax as 
send. 
.TP
grow
Grow or shrink a client. 
\fB \fP\fB \fPgrow \fI<frame>\fP
\fI<direction>\fP
\fI[amount]\fP
.TP
nudge
Nudge a client in a given direction. 
\fB \fP\fB \fPgrow \fI<frame>\fP
\fI<direction>\fP
\fI[amount]\fP
.RE
.RS
.PP
Where the arguments are defined as follows: 
.RS
.RE
.TP
area
Selects a column or the floating area. 
.br
\fB \fP\fB \fParea ::= "~"\fB \fP| <number> | "sel" 
.br
Where   represents the floating area and <number> 
represents a column index, starting at one. 
.TP
frame
Selects a client window. 
.br
\fB \fP\fB \fPframe ::= <area> <space> <index> | <area> "sel" | client <window\-id> 
.br
Where <index> represents the nth frame of <area> or 
<window\-id> is the X11 window id of the given client. 
.TP
amount
The amount to grow or nudge something. 
.br
\fB \fP\fB \fPamount ::= <number> "px"? 
.br
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. 
.RE
.RS
.PP
.RE
.TP
index
Read for a description of the contents of a tag. 
.PP
.SS The /rbar/, /lbar/ Hierarchy
.PP
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. 
.PP
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. 
.PP
.SH FILES
.PP
.TP
/tmp/ns.USER.{DISPLAY%\&.0}/wmii
The wmii socket file 
which provides a 9P service. 
.TP
CONFPREFIX/wmii\-3.5
Global action directory. 
.TP
$HOME/.wmii\-3.5
User\-specific action directory. Actions 
are first searched here. 
.PP
.SH ENVIRONMENT
.PP
.TP
HOME, DISPLAY
See the section \fBFILES\fP
above. 
.PP
The following variables are set and exported within wmii
and 
thus can be used in actions: 
.PP
.TP
WMII_ADDRESS
Socket file of Used by \fIwmiir\fP(1)\&.
.PP
.SH SEE ALSO
\fIdmenu\fP(1),
\fIwmiir\fP(1)
.PP
[1] http://www.suckless.org/wiki/wmii/tips/9p_tips 
.PP
.\" NOTE: This file is generated, DO NOT EDIT.