wmii/man/wmii.tex

\begin{Name}{1}{wmii}{Kris Maglione}{}{wmii - window manager improved, improved}
	\Prog{wmii}-VERSION
\end{Name}

\section{SYNOPSIS}
\Prog{wmii} \oOptArg{-a}{<address>} \oOptArg{-c}{<wmiirc>} \\
\Prog{wmii} \Opt{-v}

\section{DESCRIPTION}

\subsection{Overview}

\Prog{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.

\Prog{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.

\Prog{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
\Cmd{wmiir}{1}.  This allows simple and powerful remote control
of the core window manager.

\Prog{wmii} basically consists of clients, columns, views, and
the bar, which are described in detail in the
\textbf{Terminology} section.

\subsection{Terminology}

\begin{description}
\item[Display] A running X server instance consisting of input
	devices and screens.
\item[Screen] A physical or virtual (Xinerama or \Cmd{Xnest}{1})
	screen of an X display. A screen displays a bar window
	and a view at a time.
\item[Window] A (rectangular) drawable X object which is
	displayed on a screen, usually an application window.
\item[Client] An application window surrounded by a frame window
	containing a border and a titlebar.
\item[Floating layer] A screen layer of \Prog{wmii} on top of
	all other layers, where clients are arranged in a
	classic (floating) way.  They can be resized or moved
	freely.
\item[Managed layer] A screen layer of \Prog{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.
\item[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.
	\emph{work}, or several tags, e.g.  \emph{work+mail}.
	Tags are separated with the \emph{+} character.
\item[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.
\item[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.
\item[Bar] The bar at the bottom of the screen displays a label
	for each view and allows the creation of arbitrary
	user\-defined labels.
\item[Event] An event is a message which can be read from a
	special file in the filesystem of \Prog{wmii}, such as a
	mouse button press, a key press, or a message written by
	a different 9P-client.
\end{description}

\subsection{Basic window management}

Running a raw \Prog{wmii} process without a \Cmd{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 \emph{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
\emph{address} of \Prog{wmii} with any 9P-capable client, such
as \Cmd{wmiir}{1}

\subsection{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
\File{CONFPREFIX/wmii-3.5} to \File{\$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:

\begin{Table}[]{2}
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 \\
\end{Table}

\subsection{Default Key Bindings}
\subsubsection{Moving Around}
\begin{Table}[]{2}
\textbf{Key} & \textbf{Action} \\
Mod-h	& Move to a window to the \emph{left} of the one currently
	focused \\
Mod-l	& Move to a window to the \emph{right} of the one currently
	focused \\
Mod-j	& Move to the window \emph{below} the one currently focused \\
Mod-k	& Move to a window \emph{above} the one currently focused \\
Mod-space & Toggle between the managed and floating layers \\
Mod-t \emph{tag} & Move to the view of the given \emph{tag} \\
Mod-\emph{[0-9]} & Move to the view with the given number \\
\end{Table}

\subsubsection{Moving Things Around}
\begin{Table}[]{2}
\textbf{Key} & \textbf{Action} \\
Mod-Shift-h	& Move the current window \emph{window} to a
	column on the \emph{left} \\
Mod-Shift-l	& Move the current window to a column
	on the \emph{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 \emph{tag}	& Move the current window to the
	view of the given \emph{tag} \\
Mod-Shift-\emph{[0-9]}	& Move to the current window to the
	view with the given number \\
\end{Table}

\subsubsection{Miscellaneous}
\begin{Table}[]{2}
\textbf{Key} & \textbf{Action} \\
Mod-m	& Switch the current column to \emph{max mode} \\
Mod-s	& Switch the current column to \emph{stack mode} \\
Mod-d	& Switch the current column to \emph{default mode} \\
Mod-Shift-c	& \Prog{Kill} the selected client \\
Mod-p \emph{program}	& \Prog{Execute} \emph{program} \\
Mod-a \emph{action}	& \Prog{Execute} the named \emph{action} \\
Mod-Enter	& \Prog{Execute} an \Prog{xterm} \\
\end{Table}

\section{Configuration}

If you feel the need to change the default configuration, then
customize (as described above) the \Prog{wmiirc} action.  This
action is executed at the end of the \Prog{wmii} script and does
all the work of setting up the window manager, the key bindings,
the bar labels, etc.

\section{Filesystem}

Most aspects of \Prog{wmii} are controlled via the filesystem.
It is usually accessed via the \Cmd{wmiir}{1} command, but it
can be accessed by any \texttt{9P} client, including plan9port's
\Cmd{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.

\subsubsection{Hierarchy}
\begin{description}
\item[/] Global control files
\item[/client/\emph{*}/] Client control files
\item[/tag/\emph{*}/] View control files
\item[/lbar/, /rbar/] Files representing the contents of the
	bottom bar
\end{description}

\subsubsection{The / Hierarchy}
\begin{description}
\item[colrules] The \emph{colrules} file contains a list of
	rules which affect the width of newly created columns.
	Rules have the form: \\ \SP % Yuck! (kludge)
	\MANbr
	\SP\SP /\Arg{regex}/ -> \Arg{width}\oArg{+width...} \\ \SP
	\MANbr
	When a new column, \Arg{n}, is created on a view whose
	name matches \Arg{regex}, the \Arg{n}th given
	\Arg{width} percentage of the screen is given to it. If
	there is no \Arg{n}th width, 1/\emph{ncol}th of the
	screen is given to it.
\item[tagrules] The \emph{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: \\ \SP
	\MANbr
	\SP\SP /\Arg{regex}/ -> \Arg{tag}\oArg{+tag...} \\ \SP
	\MANbr
	When a client's \Arg{name}:\Arg{class}:\Arg{title} matches
	\Arg{regex}, it is given the tagstring \Arg{tag}. There are
	two special tags. \emph{!}, which is deprecated, and identical
	to \emph{sel}, represents the current tag. \emph{\Tilde}
	represents the floating layer.
\item[keys] The \emph{keys} file contains a list of keys which
	\Prog{wmii} will grab. Whenever these key combinations
	are pressed, the string which represents them are
	written to \File{/event} as: Key \Arg{string}
\item[event] The \emph{event} file never returns EOF while
	\Prog{wmii} is running. It stays open and reports events
	as they occur. Included among them are:
	\begin{description}
	\item[\emph{Not}Urgent \Arg{client} \Arg{Manager\Bar Client}]
		\Arg{client}'s urgent hint has been set or
		unset. The second arg is \emph{Client} if it's
		been set by the client, and \emph{Manager} if
		it's been set by \Prog{wmii} via a control
		message.
	\item[\emph{Not}UrgentTag \Arg{tag} \Arg{Manager\Bar Client}]
		A client on \Arg{tag} has had its urgent hint
		set, or the last urgent client has had its
		urgent hint unset.
	\item[ClientClick\Bar ClientMouseDown \Arg{client} \Arg{button}]
		A client's titlebar has either been clicked or
		has a button pressed over it.
	\item[\emph{Left\Bar Right}Bar\emph{Click\Bar MouseDown} \Arg{button} \Arg{bar}]
		A left or right bar has been clicked or has a
		button pressed over it.
	\item[...] To be continued...
	\end{description}
\item[ctl] The \emph{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:
	\begin{description}
	\item[quit] Quit \Prog{wmii}
	\item[exec \Arg{prog}] Replace \Prog{wmii} with
		\emph{prog}
	\end{description}
\end{description}

\subsubsection{The /client/ Hierarchy}

Each directory under \File{/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 \File{sel} directory, which
represents the currently selected client.

\begin{description}
\item[ctl] When read, the \File{ctl} file returns the X window id
	of the client. The following commands may be written to
	it:
	\begin{description}
	\item[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.
	\item[\Arg{Not}Urgent] Set or unset the client's urgent
		hint.
	\item[\Arg{Not}Fullscreen]

	\end{description}
\item[label] Set or read a client's label (title).
\item[props] Returns a clients class and label as:
	\emph{name}:\emph{class}:\emph{label}
\item[tags] Set or read a client's tags. Tags are separated by
	\emph{+} or \emph{-}. Tags beginning with \emph{+} are
	added, while those beginning with \emph{-} are removed.
	If the tag string written begins with \emph{+} or
	\emph{-}, the written tags are added to or removed from
	the client's set, otherwise, the set is overwritten.
\end{description}

\subsubsection{The /tag/ Hierarchy}

Each directory under \File{/tag/} represents a view, containing
all of the clients with the given tag applied. The special
\File{sel} directory represents the currently selected tag.

\begin{description}
\item[ctl] The \File{ctl} file can be read to retrieve the name
	of the tag the directory represents, or written with the
	following commands:
	\begin{description}
	\item[select] Select a client: \\
		\SP\SP select \Arg{direction} \\
		\SP\SP select \Arg{frame} \\
	\item[send] Send a client somewhere:
		\begin{description}
		\item[send \Arg{client|sel} \Arg{up|down|left|right}]
		\item[send \Arg{client|sel} \Arg{area}] Send
			\Arg{client} to the nth \Arg{area}
		\item[send \Arg{client|sel} toggle] Toggle
			\Arg{client} between the floating and
			managed layer.
		\end{description}
	\item[swap] Swap a client with another. Same syntax as
		send.
        \item[grow] Grow or shrink a client.
                \SP\SP grow \Arg{<frame>} \Arg{<direction>} \Arg{[amount]}
        \item[nudge] Nudge a client in a given direction.
                \SP\SP grow \Arg{<frame>} \Arg{<direction>} \Arg{[amount]}
	\end{description}

        Where the arguments are defined as follows:
        \begin{description}
        \item[area] Selects a column or the floating area. \\
            \SP\SP area ::= "\Tilde"\SP | <number> | "sel" \\
            Where ~ represents the floating area and <number>
            represents a column index, starting at one.
        \item[frame] Selects a client window. \\
            \SP\SP frame ::= <area> <space> <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.
        \item[amount] The amount to grow or nudge something. \\
            \SP\SP amount ::= <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.
	\end{description}

\item[index] Read for a description of the contents of a tag.
\end{description}

\subsubsection{The /rbar/, /lbar/ Hierarchy}

The files under \File{/rbar/} and \File{/lbar/} represent the
items of the bar at the bottom of the screen. Files under
\File{/lbar/} appear on the left side of the bar, while those
under \File{/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.

\section{FILES}

\begin{description}
\item[/tmp/ns.$USER.${DISPLAY\%.0}/wmii] The wmii socket file
	which provides a 9P service.
\item[CONFPREFIX/wmii-3.5] Global action directory.
\item[\$HOME/.wmii-3.5] User-specific action directory.  Actions
	are first searched here.
\end{description}

\section{ENVIRONMENT}

\begin{description}
\item[HOME, DISPLAY] See the section \textbf{FILES} above.
\end{description}

The following variables are set and exported within \Prog{wmii} and
thus can be used in actions:

\begin{description}
\item[WMII\_ADDRESS] Socket file of Used by \Cmd{wmiir}{1}.
\end{description}

\section{SEE ALSO}
\Cmd{dmenu}{1}, \Cmd{wmiir}{1}

[1] http://www.suckless.org/wiki/wmii/tips/9p\_tips