WMII(1)

okay so this is the WMII(1) page from the General Commands Manual, and it's all about wmii — Window Manager Improved². bestie, it's giving "my windows are organized and my life is together" energy. 💅

🌸 NAME 🌸

wmii — Window Manager Improved².

✨ SYNOPSIS ✨

wmii [-a <address>] [-r <wmiirc>]

wmii -v

🦋 DESCRIPTION 🦋

💖 Overview 💖

wmii is a dynamic window manager for X11. The whole point: in contrast to static window management, you rarely have to think about how to organize windows, no matter what you're doing or how many applications you're using at the same time. The window manager adapts to the current environment and fits your needs, instead of forcing you to use a preset, fixed layout and trying to shoehorn every window and application into it. periodt. ✨

It supports classic and tiled window management with extended keyboard and mouse control. Classic window management arranges windows in a floating layer where they can be moved and resized freely. Tiled window management arranges windows in vertical columns. Each column holds an arbitrary number of arbitrary windows and arranges them vertically in a non-overlapping way. Then you can move and resize them, among and within columns, at will. 🦋

wmii also gives you a virtual filesystem that represents its internal state similar to the procfs of Unix operating systems. Modifying this virtual filesystem changes 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. iykyk. 😭🔥

💅 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.
• -v — it appears in the synopsis as wmii -v; this page doesn't give it a description, so no invented lore here, bestie. 🙈

🧚 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.
• 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) manner. They can be resized or moved freely.
• Managed layer — A screen layer of wmii 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.
• 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. 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. 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. 🫶

The filesystem can be accessed by connecting to the address of wmii with any 9P-capable client, such as wmiir(1).

🎀 Actions 🎀

The default configuration provides for a special menu of actions. These consist of either shell scripts in $WMII_CONFPATH or action definitions included in wmiirc.

Here is a list of the default actions:

• 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.

🌟 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 🦋

• 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-n — Move to the next view.
• Mod-b — Move to the previous view.
• Mod-[0-9] — Move to the view with the given number.

💜 Moving Things Around 💜

• Mod-Shift-h — Move the current 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 🍓

• 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 💖

okay so if the default setup just isn't giving what you need, then customize (as described above) the wmiirc action. like, that's the whole move. this action is executed at the end of the wmii script and it does literally all the work of setting up the window manager, the key bindings, the bar labels, etc. she's the main character of your setup, fr.

🗂️ Filesystem

most aspects of wmii are controlled via the filesystem — yes, THE filesystem, we're doing plan 9 things here 💅. it's 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 may 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. thoughtful queen ✨

the filesystem is, as are many other 9P filesystems, entirely synthetic. the files exist only in memory, and are not written to disk. no cap, nothing persists — it's all vibes in RAM 🫶. 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, bestie 👑

🌳 Hierarchy

• / — global control files, the big ones
• /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>]*

where,

<width> := <percent of screen> | <pixels>px

when a new column, <n>, is created on a view whose name matches <regex>, it is given the <n>th supplied <width>. and if there is no <n>th width? it just gets 1/<ncol>th of the screen. generous 💅

rules — PROVISIONAL

the rules file contains a list of rules that may be used to automatically set properties of new clients. rules are specified as:

/<regex>/ <key>=<value> ...

where each <key> represents a command in the client's ctl file, and each <value> represents the value to assign to it. the rules are applied when the client is first started and the contents of the props file match the regular expression <regex>.

additionally, the following keys are accepted and have special meaning — these are the bonus lore drops 🦋:

• 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. so it's like "keep going bestie, don't stop at me" ✨
• force-tags=<tags> — like tags, but overrides any settings obtained obtained from the client's group or from the _WMII_TAGS window property. (yes, that's "obtained obtained" — iykyk, periodt 💀)

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. bye bestie 😭
• exec <prog> — replace wmii with <prog>. like a full transformation, main character swap 🔥
• 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. she's the chosen one 💅

ctl

when read, the ctl file returns the X window id of the client. the following commands may be written to it:

• allow <flags> — the set of unusual actions the client is allowed to perform, in the same format as the tag set.
  • 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. no flag, no self-activation, that's the rule 🎀
• floating <on | off | always | never> — defines whether this client is likely to float when attached to a new view. ordinarily, the value changes automatically whenever the window is moved between the floating and managed layers. however, setting a value of always or never overrides this behavior. additionally, dialogs, menus, docks, and splash screens will always float unless this value is set to never.
• fullscreen <on | off | toggle> — sets the client's fullscreen state. go big 🌈
• group <group id> — 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.
• kill — close the client's window.
• 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.
• 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. brutal, iconic, necessary 💀
• tags <tags> — the client's tags. the same as the tags file.
• urgent <on | off | toggle> — set or unset the client's urgent hint. 🚨

label

set or read a client's label (title).

props

returns a client's class and label as: <instance>:<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 and those beginning with ^ are toggled. 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. overwrite is giving "new me, who dis" 🙈

---

🦋 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>] (yes, it says grow under nudge — that's what the page says, don't @ me 🫠)

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> represents 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 interpreted as an exact pixel count. otherwise, it's interpreted 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. reasonable is subjective, bestie ✨

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. leftmost ate and left no crumbs 👑

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 ctl files and should be self explanatory. you got this 💅

💖 FILES 💖

okay so here's where wmii keeps its stuff, bestie — memorize these paths, they're lowkey the keys to the kingdom 👑

• /tmp/ns.$USER.${DISPLAY%.0}/wmii — this is the wmii socket file, and it's the main character fr: it provides a 9P service. yes, that 9P. slay ✨
• /nix/store/slssan5bnbckq9395sb3rjcrds2k5h1v-wmii-0-unstable-2023-09-30/etc/wmii-hg — the global action directory 🗂️
• ~/.wmii-hg — the user-specific action directory 🎀 and heads up: actions are searched here first. so your personal stuff wins, periodt.

---

🌸 ENVIRONMENT 🌸

• $HOME, $DISPLAY — see the FILES section up there ☝️ that's the whole vibe, they're what those paths get built from.

and now the fun part — the following variables are set and exported within wmii, which means you can literally use them inside your actions, no cap:

• $WMII_ADDRESS — the address on which wmii is listening 📡
• $WMII_CONFPATH — the path that wmii searches for its configuration scripts and actions 🔍
• $NAMESPACE — the namespace directory to use if no address is provided 🧚

---

🦋 SEE ALSO 🦋

go read your siblings, they're iconic in their own right 💅

• wimenu(1), wmii9menu(1), witray(1), wmiir(1), wihack(1)

and the bonus reading material 📚 — actual real files, go touch them:

/nix/store/slssan5bnbckq9395sb3rjcrds2k5h1v-wmii-0-unstable-2023-09-30/share/doc/wmii/wmii.pdf
/nix/store/slssan5bnbckq9395sb3rjcrds2k5h1v-wmii-0-unstable-2023-09-30/share/doc/wmii/FAQ

plus two numbered references, in case you need the receipts 🧾:

• [1] http://www.suckless.org/wiki/wmii/tips/9p_tips
• [2] /nix/store/slssan5bnbckq9395sb3rjcrds2k5h1v-wmii-0-unstable-2023-09-30/share/doc/wmii/wmii.pdf

---

and that's the whole page, bestie 🫶 go forth, configure your window manager, and be the main character of your own desktop 🏆

k bye, this was wmii, dated 2010 June, filed under WMII(1) — a genuine vintage icon, still serving looks in an wmii- source package near you 💜✨