mirror of
https://github.com/0intro/wmii
synced 2024-11-22 22:02:30 +03:00
432 lines
15 KiB
Plaintext
432 lines
15 KiB
Plaintext
WMII
|
|
|
|
Dec, 2008
|
|
|
|
%!includeconf: header.t2t
|
|
|
|
= NAME =
|
|
|
|
wmii - Window Manager Improved Improved
|
|
|
|
= SYNOPSIS =
|
|
|
|
wmii [-a <address>] [-c <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.
|
|
|
|
== 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
|
|
'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.
|
|
|
|
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 ==
|
|
|
|
=== 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 to 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 `xterm`
|
|
|
|
= 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 _n_th given
|
|
<width> percentage of the screen is given to it. If
|
|
there is no _n_th width, 1/_ncol_th 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.
|
|
: ...
|
|
To be continued...
|
|
:
|
|
<<
|
|
|
|
: 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>
|
|
:
|
|
:
|
|
|
|
== 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.
|
|
: [Not]Urgent
|
|
Set or unset the client's urgent hint.
|
|
: [Not]Fullscreen
|
|
<<
|
|
|
|
: 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 _n_th <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 ::= "~" | <number> | "sel"
|
|
|
|
Where represents the floating area and <number> represents a column
|
|
index, starting at one.
|
|
|
|
: 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.
|
|
: CONFPREFIX/wmii-3.5
|
|
Global action directory.
|
|
: $HOME/.wmii-3.5
|
|
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
|
|
Socket file of Used by wmiir(1).
|
|
:
|
|
= SEE ALSO =
|
|
dmenu(1), wmiir(1)
|
|
|
|
[1] http://www.suckless.org/wiki/wmii/tips/9p_tips
|
|
|