wmii

wmii.1 (18071B)

---

 .TH "WMII" 1 "2010 June" "wmii-@VERSION@"
 
 .SH NAME
 .P
 wmii \- Window Manager Improved²
 
 .SH SYNOPSIS
 .P
 wmii \fI[\-a \fI<address>\fR]\fR \fI[\-r \fI<wmiirc>\fR]\fR 
 .P
 wmii \-v
 
 .SH DESCRIPTION
 .SS Overview
 .P
 \fBwmii\fR 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
 \fBwmii\fR supports classic and tiled window management with
 extended keyboard and mouse control. Classic window management
 arranges windows in a floating layer in which tyen can be moved
 and resized freely. Tiled window management arranges windows in
 vertical columns.  Each column holds an arbitrary number
 arbitrary windows and arranges them vertically in a
 non\-overlapping manner. They can then be moved and resized,
 among and within columns, at will.
 
 .P
 \fBwmii\fR 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.
 
 .SS Command Line Arguments
 .TP
 \-a \fI<address>\fR
 Specifies the address on which \fBwmii\fR should listen for
 connections. The address takes the form
 \fB\fI<protocol>\fR!\fI<address>\fR\fR. The default is of the form:
 
 .nf
       unix!/tmp/ns.\fB$USER\fR.\fB${DISPLAY\fR%.0\fB}\fR/wmii
 .fi
 
 which opens a unix socket per Plan 9 Port conventions. To
 open a TCP socket, listening at port 4332 on the loopback
 interface, use:
 
 .nf
       tcp!localhost!4332
 .fi
 
 \fB$WMII_NAMESPACE\fR is automatically set to this value.
 
 .TP
 \-r \fI<wmiirc>\fR
 Specifies which rc script to run. If \fI<wmiirc>\fR consists of a
 single argument, \fB$WMII_CONFPATH\fR is searched before \fB$PATH\fR.
 Otherwise, it is passed to the shell for evaluation. The
 environment variables \fB$WMII_ADDRESS\fR and \fB$WMII_CONFPATH\fR are
 preset for the script.
 
 .SS Terminology
 .TP
 Display
 A running X server instance consisting of input
 devices and screens.
 .TP
 Screen
 A physical or virtual (Xinerama or Xnest(1))
 screen of an X display.
 .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 \fBwmii\fR on top of all other layers,
 where clients are arranged in a classic (floating)
 manner.  They can be resized or moved freely.
 .TP
 Managed layer
 A screen layer of \fBwmii\fR underneath the floating layer,
 where clients are arranged in a non\-overlapping
 (managed) manner.  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\fR, or several tags, e.g.  \fIwork+mail\fR.
 Tags are separated with the \fI+\fR 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. 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
 user\-defined labels.
 .TP
 Event
 An event is a message which can be read from a
 special file in the filesystem of \fBwmii\fR, such as a
 mouse button press, a key press, or a message written by
 a different 9P\-client.
 
 
 .SS Basic window management
 .P
 Running a raw \fBwmii\fR process without a wmiirc(1) script provides
 basic window management capabilities.  However, to use it
 effectively, remote control through its filesystem interface is
 necessary.  Without such a script, it is only possible to move
 and resize clients with the mouse, but not to change their tags
 or to switch views.  Other interactions, such as customizing the
 style, killing or retagging clients, and grabbing keys, cannot
 be achieved without accessing the filesystem.
 
 .P
 The filesystem can be accessed by connecting to the \fIaddress\fR
 of \fBwmii\fR with any 9P\-capable client, such as wmiir(1)
 
 .SS Actions
 .P
 The default configuration provides for a special menu of
 actions. These consist of either shell scripts in \fB$WMII_CONFPATH\fR
 or action definitions included in wmiirc.
 
 .P
 Here is a list of the default actions:
 
 .TS
 tab(^); ll.
  exec^Replace the window manager with another program
  quit^Leave the window manager nicely
  rehash^Refresh the program list
  showkeys^Display a list of key bindings recognized by wmii
  status^Periodically print date and load average to the bar
  welcome^Display a welcome message that contains the wmii tutorial
 .TE
 
 .SS Default Key Bindings
 .P
 All of the provided \fBwmiirc\fR scripts accept at least the following key
 bindings. They should also provide a \fBshowkeys\fR action to open a
 key binding quick\-reference.
 
 .SS Moving Around
 .TS
 tab(^); ll.
  \fBKey\fR^\fBAction\fR
  Mod\-h^Move to a window to the \fIleft\fR of the one currently focused
  Mod\-l^Move to a window to the \fIright\fR of the one currently focused
  Mod\-j^Move to the window \fIbelow\fR the one currently focused
  Mod\-k^Move to a window \fIabove\fR the one currently focused
  Mod\-space^Toggle between the managed and floating layers
  Mod\-t \fI<tag>\fR^Move to the view of the given \fI<tag>\fR
  Mod\-n^Move to the next view
  Mod\-b^Move to the previous view
  Mod\-\fI\fI[0\-9]\fR\fR^Move to the view with the given number
 .TE
 
 .SS Moving Things Around
 .TS
 tab(^); ll.
  \fBKey\fR^\fBAction\fR
  Mod\-Shift\-h^Move the current window \fIwindow\fR to a column on the \fIleft\fR
  Mod\-Shift\-l^Move the current window to a column on the \fIright\fR
  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 \fI<tag>\fR^Move the current window to the view of the given \fI<tag>\fR
  Mod\-Shift\-\fI\fI[0\-9]\fR\fR^Move the current window to the view with the given number
 .TE
 
 .SS Miscellaneous
 .TS
 tab(^); ll.
  \fBKey\fR^\fBAction\fR
  Mod\-m^Switch the current column to \fImax mode\fR
  Mod\-s^Switch the current column to \fIstack mode\fR
  Mod\-d^Switch the current column to \fIdefault mode\fR
  Mod\-Shift\-c^\fBKill\fR the selected client
  Mod\-p \fI<program>\fR^\fBExecute\fR \fI<program>\fR
  Mod\-a \fI<action>\fR^\fBExecute\fR the named <action
  Mod\-Enter^\fBExecute\fR an \fB@TERMINAL@\fR
 .TE
 
 .SH Configuration
 .P
 If you feel the need to change the default configuration, then
 customize (as described above) the \fBwmiirc\fR action.  This
 action is executed at the end of the \fBwmii\fR script and does
 all the work of setting up the window manager, the key bindings,
 the bar labels, etc.
 
 .SS Filesystem
 .P
 Most aspects of \fBwmii\fR 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\fI[1]\fR, and can be
 mounted natively on Linux via v9fs\fI[1]\fR, and on Inferno (which man
 run on top of Linux). All data in the filesystem, including
 filenames, is UTF\-8 encoded. However, when accessed via
 wmiir(1), text is automatically translated to and from your
 locale encoding.
 
 .P
 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 wmiirc. Several files are used to issue 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.
 
 .SS Hierarchy
 .TP
 /
 Global control files
 .TP
 /client/\fI*\fR/
 Client control files
 .TP
 /tag/\fI*\fR/
 View control files
 .TP
 /lbar/, /rbar/
 Files representing the contents of the bottom bar
 
 
 .SS The / Hierarchy
 .TP
 colrules
 The \fIcolrules\fR file contains a list of
 rules which affect the width of newly created columns.
 Rules have the form:
 
 .nf
       /\fI<regex>\fR/ -> \fI<width>\fR\fI[+\fI<width>\fR]\fR*
 .fi
 
 Where,
 
 .nf
       \fI<width>\fR := \fI<percent of screen>\fR | \fI<pixels>\fRpx
 .fi
 
 When a new column, \fI<n>\fR, is created on a view whose name
 matches \fI<regex>\fR, it is given the \fI<n>\fRth supplied \fI<width>\fR.
 If there is no \fI<n>\fRth width, it is given 1/\fI<ncol>\fRth of the
 screen.
 
 .TP
 rules
 \fBPROVISIONAL\fR
 
 The \fIrules\fR file contains a list of rules that may be used
 to automatically set properties of new clients. Rules are
 specified as:
 
 .nf
       /\fI<regex>\fR/ \fI<key>\fR=\fI<value>\fR ...
 .fi
 
 where each \fI<key>\fR represents a command in the clients \fIctl\fR
 file, and each \fI<value>\fR represents the value to assign to it.
 The rules are applied when the client is first started and
 the contents of the \fIprops\fR file match the regular
 expression \fI<regex>\fR.
 
 Additionally, the following keys are accepted and have
 special meaning:
 
 .RS 8
 .TP
 continue
 Normally, when a matching rule is encountered, rule
 matching stops. When the continue key is provided
 (with any value), matching continues at the next
 rule.
 .TP
 force\-tags=\fI<tags>\fR
 Like \fItags\fR, but overrides any settings obtained
 obtained from the client's group or from the
 \fB_WMII_TAGS\fR window property.
 .RS -8
 .TP
 keys
 The \fIkeys\fR file contains a list of keys which
 \fBwmii\fR will grab. Whenever these key combinations
 are pressed, the string which represents them are
 written to '/event' as: Key \fI<string>\fR
 .TP
 event
 The \fIevent\fR file never returns EOF while
 \fBwmii\fR is running. It stays open and reports events
 as they occur. Included among them are:
 .RS 8
 .TP
 \fI[Not]\fRUrgent \fI<client>\fR \fI[Manager|Client]\fR
 \fI<client>\fR's urgent hint has been set or
 unset. The second arg is \fI[Client]\fR if it's
 been set by the client, and \fI[Manager]\fR if
 it's been set by \fBwmii\fR via a control
 message.
 .TP
 \fI[Not]\fRUrgentTag \fI<tag>\fR \fI[Manager|Client]\fR
 A client on \fI<tag>\fR has had its urgent hint
 set, or the last urgent client has had its
 urgent hint unset.
 .TP
 Client\fI<Click|MouseDown>\fR \fI<client>\fR \fI<button>\fR
 A client's titlebar has either been clicked or
 has a button pressed over it.
 .TP
 \fI[Left|Right]\fRBar\fI[Click|MouseDown]\fR \fI<button>\fR \fI<bar>\fR
 A left or right bar has been clicked or has a
 button pressed over it.
 .RS -8
 
 For a more comprehensive list of available events, see
 \fIwmii.pdf\fR\fI[2]\fR
 
 .TP
 ctl
 The \fIctl\fR 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 8
 .TP
 quit
 Quit \fBwmii\fR
 .TP
 exec \fI<prog>\fR
 Replace \fBwmii\fR with \fI<prog>\fR
 .TP
 spawn \fI<prog>\fR
 Spawn a new program, as if by the \fI\-r\fR flag.
 .RS -8
 
 
 .SS The /client/ Hierarchy
 .P
 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.
 
 .TP
 ctl
 When read, the 'ctl' file returns the X window id
 of the client. The following commands may be written to
 it:
 .RS 8
 .TP
 allow \fI<flags>\fR
 The set of unusual actions the client is allowed to
 perform, in the same format as the tag set.
 .RS 8
 .TP
 activate
 The client is allowed to activate
 itself – that is, focus its window and,
 as the case may require, uncollapse it
 and select a tag it resides on. This
 flag must be set on a client if you wish
 it able to activate itself from the
 system tray.
 .RS -8
 .TP
 floating \fI<on | off | always | never>\fR
 Defines whether this client is likely to float when
 attached to a new view. Ordinarilly, the value
 changes automatically whenever the window is
 moved between the floating and managed layers.
 However, setting a value of \fIalways\fR or \fInever\fR
 overrides this behavior. Additionally, dialogs,
 menus, docks, and splash screens will always
 float unless this value is set to \fInever\fR.
 .TP
 fullscreen \fI<on | off | toggle>\fR
 Sets the client's fullscreen state.
 .TP
 group \fI<group id>\fR
 The client's group ID, or 0 if not part of a group.
 Clients tend to open with the same tags and in the
 same columns as the last active member of their
 group. Setting this property is only useful when
 done via the rules file.
 .TP
 kill
 Close the client's window.
 .TP
 pid
 Read\-only value of the PID of the program that
 owns the window, if the value is available and
 the process is on the same machine as wmii.
 .TP
 slay
 Forcibly kill the client's connection to the X
 server, closing all of its windows. Kill the parent
 process if the client's PID is available.
 .TP
 tags \fI<tags>\fR
 The client's tags. The same as the tags file.
 .TP
 urgent \fI<on | off | toggle>\fR
 Set or unset the client's urgent hint.
 .RS -8
 
 .TP
 label
 Set or read a client's label (title).
 .TP
 props
 Returns a clients class and label as:
 \fI<instance>\fR:\fI<class>\fR:\fI<label>\fR.
 .TP
 tags
 Set or read a client's tags. Tags are separated by
 \fB+\fR, \fB\-\fR, or \fB^\fR. Tags beginning with \fB+\fR are
 added, while those beginning with \fB\-\fR are removed and
 those beginning with \fB^\fR are toggled.  If the tag
 string written begins with \fB+\fR, \fB^\fR, or \fB\-\fR, the
 written tags are added to or removed from the client's
 set, otherwise the set is overwritten.
 
 
 .SS The /tag/ Hierarchy
 .P
 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.
 
 .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 8
 .TP
 select
 Select a client:
 select \fI[left|right|up|down]\fR 
 .P
 select \fI[\fI<row number>\fR|sel]\fR \fI[\fI<frame number>\fR]\fR 
 .P
 select client \fI<client>\fR
 .TP
 send
 Send a client somewhere:
 .RS 8
 .TP
 send \fI[\fI<client>\fR|sel]\fR \fI[up|down|left|right]\fR
 .TP
 send \fI[\fI<client>\fR|sel]\fR \fI<area>\fR
 Send \fI<client>\fR to the \fIn\fRth \fI<area>\fR
 .TP
 send \fI[\fI<client>\fR|sel]\fR toggle
 Toggle \fI<client>\fR between the floating and managed layer.
 .RS -8
 .TP
 swap
 Swap a client with another. Same syntax as send.
 
 .TP
 grow
 Grow or shrink a client.
 
 .nf
      grow \fI<frame>\fR \fI<direction>\fR \fI[\fI<amount>\fR]\fR
 .fi
 
 .TP
 nudge
 Nudge a client in a given direction.
 
 .nf
      grow \fI<frame>\fR \fI<direction>\fR \fI[\fI<amount>\fR]\fR
 .fi
 
 .RS -8
 Where the arguments are defined as follows:
 .RS 8
 .TP
 area
 Selects a column or the floating area.
 
 .nf
      area        ::= \fI<area_spec>\fR | \fI<screen_spec>\fR:\fI<area_spec>\fR
 .fi
 
 When \fI<screen_spec>\fR is omitted and \fI<area_spec>\fR is not "sel",
 0 is assumed. "sel" by itself represents the selected client no
 matter which screen it is on.
 
 .nf
      area_spec   ::= "~" | \fI<number>\fR | "sel"
 .fi
 
 Where "~" represents the floating area and \fI<number>\fR represents a column
 index, starting at one.
 
 .nf
      screen_spec ::= \fI<number>\fR
 .fi
 
 Where \fI<number>\fR representes the 0\-based Xinerama screen number.
 
 .TP
 frame
 Selects a client window.
 
 .nf
      frame ::= \fI<area>\fR \fI<index>\fR | \fI<area>\fR sel | client \fI<window-id>\fR
 .fi
 
 Where \fI<index>\fR represents the nth frame of \fI<area>\fR or \fI<window\-id>\fR is
 the X11 window id of the given client.
 
 .TP
 amount
 The amount to grow or nudge something.
 
 .nf
      amount ::= \fI<number>\fR | \fI<number>\fRpx
 .fi
 
 If "px" is given, \fI<number>\fR 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.
 .RS -8
 .TP
 index
 Read for a description of the contents of a tag.
 
 
 .SS The /rbar/, /lbar/ Hierarchy
 .P
 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.
 
 .P
 The files may be read or written to obtain or alter the colors
 and text of the bars. The format is similar to the various \fIctl\fR
 files and should be self explanitory.
 
 .SH FILES
 .TP
 /tmp/ns.\fB$USER\fR.\fB${DISPLAY\fR%.0\fB}\fR/wmii
 The wmii socket file which provides a 9P service.
 .TP
 @GLOBALCONF@
 Global action directory.
 .TP
 @LOCALCONF@
 User\-specific action directory. Actions are first searched here.
 
 
 .SH ENVIRONMENT
 .TP
 \fB$HOME\fR, \fB$DISPLAY\fR
 See the section \fBFILES\fR above.
 
 .P
 The following variables are set and exported within \fBwmii\fR and
 thus can be used in actions:
 
 .TP
 \fB$WMII_ADDRESS\fR
 The address on which \fBwmii\fR is listening.
 .TP
 \fB$WMII_CONFPATH\fR
 The path that wmii searches for its configuration
 scripts and actions.
 .TP
 \fB$NAMESPACE\fR
 The namespace directory to use if no address is provided.
 
 .SH SEE ALSO
 .P
 wimenu(1), wmii9menu(1), witray(1), wmiir(1), wihack(1) 
 .P
 @DOCDIR@/wmii.pdf
 @DOCDIR@/FAQ
 
 .P
 \fI[1]\fR http://www.suckless.org/wiki/wmii/tips/9p_tips 
 .P
 \fI[2]\fR @DOCDIR@/wmii.pdf
 
 
 .\" man code generated by txt2tags 2.5 (http://txt2tags.sf.net)
 .\" cmdline: txt2tags -o- wmii.man1