From ArchWiki
Revision as of 17:21, 7 July 2006 by Gandalf (talk | contribs) (Adding users configs section)
Jump to navigation Jump to search

Here are some starter pointers to configuring the WMII window manager.

Getting started

After installing wmii with a simple pacman -S wmii (available from the [community] repos), setting your ~/.xinitrc will enable you to fire up wmii with startx:

setxkbmap -option ctrl:swapcaps
autocutsel -selection CLIPBOARD -fork
autocutsel -selection PRIMARY -fork
exec wmii &

The calls to autocutsel (also available in [community]) keep the different X Clipboards synchronized. Note, however, that the copy/paste semantics will become like traditional X copying; selecting text will copy it to the clipboard, overwriting previous contents. This can be annoying when using Firefox; you copy something by selecting it, hop over to FF to paste it, hit Ctrl-L, and all of a sudden the old URL is selected, overwriting your first selection! If you keep this limitation in mind, it can be avoided; a cleaner solution would be welcome.

Configuration (Ruby)

While it can be configured using most any language, this section will be focussed on the excellent ruby-wmii project developed by Mauricio Fernandez (mfp). As such, we need to install Ruby, which is available in [current]. Furthermore, some plugins may require additional ruby libraries, such as the MPD plugin which requires ruby-mpd from [community].

mfp's project has many useful basic bar applets and configurations; with the 0.3.0 release, the script has adopted a useful plugin architecture making overriding or adding functionality simple.

The ruby-wmii project is installed to ~/.wmii-3, consisting of:

  • ~/.wmii-3/wmiirc -- The heart of the ruby-wmii scripts; shouldn't be edited. This is what is run when wmii starts.
  • ~/.wmii-3/wmiirc-config.rb -- Your config file, which should be edited (running wmiirc script will create it if it doesn't already exist)
  • ~/.wmii-3/plugins -- A directory containing plugins (sets of keybindings and bar applets)
  • ~/.wmii-3/plugins/standard-plugin.rb -- The default plugins, which you needn't edit.

Low level access

The wmiir command can be used to manipulate wmii at a low level; read the manpage for details (although this isn't really necessary for a new user!). Control scripts in different languages can use this command to control wmii . wmii bases itself in "plan 9", an older window manager. As such, there are also libraries such as ruby-ixp which can be used to manipulate the window manager programmatically, using the "9p" specification. This is technically faster, as no calling of external programs such as 'wmiir is then needed; however, at the time of writing, ruby-ixp is quite new and isn't used by the ruby-wmii project.


ruby-wmii's plugins consist of both bar applets and key bindings. The standard-plugin.rb file provides the following plugins: volume, mode, dict, battery-monitor, mpd, cpuinfo, status. These are mostly self-explanatory, except perhaps mode, which toggles between wmii catching key combos and passing them to programs directly. It also provides a lot of sensible key bindings and actions, such as being able to tag and rename windows with ease (check out this for more information about tagging in wmii).

Bar applets are used by editing ~/.wmii-3/wmiirc-config.rb, and modifying/adding "use_bar_applet" lines. Traditionally, numbers are used to modify the order in which plugins appear in the bar; I personally prefer to specify them thusly:

 order_index = 1
 from "nogoma" do
   %w{mpd}.each do |plugin|
     use_bar_applet plugin, "%03d" % order_index
     order_index += 1
 from "standard"  do
   %w{cpuinfo volume status battery-monitor mode}.each do |plugin|
     use_bar_applet plugin, "%03d" % (order_index)
 # More configuration...

This will cause mpd (my custom one, listed below, in namespace "nogoma"), cpuinfo, etc. to be included in the bar, in the given order.

Many plugins also provide parameters that can be modified. For example, the "volume" plugin allows you to specify the mixer used:

 plugin_config["standard:volume"]["mixer"] = "Headphone"

Here, we've set the mixer parameter of the volume plugin in the standard namespace to be "Headphone". These sort of configuration parameters make life a lot easier as users don't need to create custom plugins to modify existing behaviour.


Another aspect of wmii is keybindings; how different key combinations affect the wm. Some plugins define key combos by default when they're used; others define sets of bindings that can be selectively included/excluded in the wmiirc-config.rb. They can be used by including:


in your wmiirc-config.rb

Basic keybindings can also be made with the on_key command in wmiirc-config.rb:

on_key("MODKEY-LEFT") {


Don't forget you can leverage most all of the power of Ruby when using this control script; there are a lot more functions and helpers the ruby-wmii project provides. The files are fairly self documenting, and Ruby a fairly sensible and readable language. Don't be afraid to experiment and add new plugins and keybindings!

Arch user contributions

Here are some plugins/snippets from users on the Arch forums.

MPD (modified for use w/ multiple hosts)

I (nogoma) like to be able to control either mpd on my laptop when out and about, or my media pc via my laptop when at home. So, I (trivially) modified the standard mpd plugin to allow me to change hosts. The ruby-wmii is relatively self-documenting about how to define your own plugins; hopefully the below makes sense (it defines a new plugin in the "nogoma" namespace, which contains a bar applet called "mpd". Notice that this new applet doesn't conflict with the mpd applet shipped w/ ruby-wmii, because it is referred to as "nogoma:mpd" instead of "standard:mpd").

Plugin.define "nogoma" do
 # {{{ MPD Bar
 bar_applet("mpd", 100) do |wmii, bar|
   require 'mpd'
   server = wmii.plugin_config["nogoma:mpd"]["default_host"] || `hostname`
   mpd_do_action = lambda do |action, *args|
     Thread.new do
         mpd = MPD.new(server)
         r = mpd.__send__(action, *args)
         LOGGER.info "MPD #{action}"
   mpdserv = MPD.new
   bar.data = "Connecting: #{server}"
   update_bar = lambda do
     if /^Connecting/ =~ bar.data
       mpdserv = MPD.new(server = bar.data.split[-1])
       mpdserv_status = mpdserv.status["state"]
       show_info = false
     case mpdserv_status
     when 'play' : text = ">>: "; show_info = true
     when 'pause': text = "||: "; show_info = true
     else show_info = false
     if show_info
       title = mpdserv.strf("%t")[0..(wmii.plugin_config["standard:mpd"]["title_maxlen"] || -1)]
       author = mpdserv.strf("%a")[0..(wmii.plugin_config["standard:mpd"]["author_maxlen"] || -1)]
       bar.data = text + "#{author} - #{title} " + mpdserv.strf("(%e/%l)") + " [#{server}]"
     else   # Player is stopped or connection not yet initialized...
       bar.data = "[#{server}]: NOT PLAYING"
   keys = wmii.plugin_config["nogoma:mpd"]["switch_server"] || ["MODKEY-Control-m"]
   wmii.on_key(*keys) do
     wmii.wmiimenu([]) do |server|
       bar.data = "Connecting: #{server}"
   # Initialize MPD status
   Thread.new do
     loop{ begin; update_bar.call; rescue Exception; end; sleep 1 }
   bar.on_click(MOUSE_SCROLL_UP)  { mpd_do_action[:previous] }
   bar.on_click(MOUSE_SCROLL_DOWN){ mpd_do_action[:next] }
   bar.on_click(MOUSE_BUTTON_LEFT) do
     Thread.new do
         mpd = MPD.new(server)
         mpdserv_status = mpd.status
         mpd.close rescue nil
       case mpdserv_status["state"]
       when "play":           mpd_do_action[:pause]
       when "pause", "stop" : mpd_do_action[:play]
   bar.on_click(MOUSE_BUTTON_RIGHT) do
     mpd_handle = wmii.on_createclient do |cid|
       wmii.write("/view/sel/sel/ctl", "sendto 0")
       wmii.write("/view/sel/sel/geom", "400 0 center+200 south")
       wmii.unregister mpd_handle
     wmii.write("/view/ctl", "select toggle")
     term = wmii.plugin_config["standard"]["x-terminal-emulator"] || "xterm"
     system "wmiisetsid #{term} -e ncmpc -h #{server}&"

This plugin also provides the default keybinding of MODKEY-Control-M for switching hosts. Typing in a new hostname and hitting enter will cause the mpd applet to try connecting to that host. It also exposes two configuration values which can be set:

 plugin_config["nogoma:mpd"]["default_host"] = "foohost" # host to connect to on startup
 plugin_config["nogoma:mpd"]["switch_server"] = "MODKEY-Control-m" # Key combo to change current host

Users Configs

Add your configuration URL to the list