From ArchWiki
Jump to navigation Jump to search

Gnome-colors-add-files-to-archive.pngThis article is being considered for archiving.Gnome-colors-add-files-to-archive.png

Reason: Last release 2006; not packaged. (Discuss in Talk:Ruby-wmii#)


While wmii can be configured using most any language, this document focuses on the excellent ruby-wmii project developed by Mauricio Fernandez (mfp).

Note: ruby-wmii is no longer maintained. Try sunaku's Ruby wmiirc instead.


You'll need to install Ruby, which is available in [extra]. 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.


To get a copy of the development version of ruby-wmii from mfp's repository, checkout the code using darcs (darcs available in [extra] repos):

user@host % cd ~/src
user@host % darcs get --partial ruby-wmii
user@host % cd ruby-wmii
user@host % ruby install.rb

This copy can then be updated at any time via:

user@host % cd ~/src/ruby-wmii
user@host % darcs pull
user@host % ruby install.rb

This last command will copy the updated ruby-wmii over what you have in ~/.wmii-3. CAUTION: This will overwrite any changes you have in ~/.wmii-3/wmiirc or ~/.wmii-3/standard-plugin.rb. For this reason, you shouldn't edit these files! Rather, make config changes in ~/.wmii-3/wmiirc-config.rb, and if you want to modify a plugin, copy it into a new file under ~/.wmii-3/plugins and make your edits in this file.


One utility which might not be present on your system is ssid. If you lack this application you will find that the trust Mod-p menu will no longer launch applications. It is a tiny application intended as a replacement for setsid and can be found on the wmii website at [1]. It needs to be built and put somewhere that wmii-ruby can find it.

user@host % tar -xvzf ssid-0.1.tar.gz 
user@host % make
user@host % make install

Personally I prefer not ever to run a make install unless through a PKGBUILD so you can alternatively copy the ssid binary somewhere into your local user's path.

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 is controlled through a filesystem interface using the 9P2000 protocol, which in turn is derived from the plan 9 operating system. As such, there are also libraries such as ruby-ixp which can be used to manipulate the window manager programmatically over 9P. 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 do not 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| do
         mpd =
         r = mpd.__send__(action, *args) "MPD #{action}"
   mpdserv = = "Connecting: #{server}"
   update_bar = lambda do
     if /^Connecting/ =~
       mpdserv = =[-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)] = text + "#{author} - #{title} " + mpdserv.strf("(%e/%l)") + " [#{server}]"
     else   # Player is stopped or connection not yet initialized... = "[#{server}]: NOT PLAYING"
   keys = wmii.plugin_config["nogoma:mpd"]["switch_server"] || ["MODKEY-Control-m"]
   wmii.on_key(*keys) do
     wmii.wmiimenu([]) do |server| = "Connecting: #{server}"
   # Initialize MPD status do
     loop{ begin;; 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 do
         mpd =
         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

POP/IMAP Mail Checker (w/ SSL)

mailchecker at Why the lucky stiff's homepage.

Bookmark manager

Bookmark manager in the development darcs repos for ruby-wmii, on mfp's site. To get a recent copy of ruby-wmii, follow the #darcs directions.

Feature list:

  • mouse-less interaction
  • search as you type (extended autocompletion) for both title and URLs: the set of bookmarks matching what I'm typing at any position in the title or the URL is updated instantaneously as I type
  • integration: importing bookmarks from and getting new ones automatically
  • tagging (it will import your tags if you let it try)
  • powerful search expressions (as many criteria as you want):
    • all bookmarks in the last week: ~d <7d
    • all bookmarks whose description matches a regexp: ~t regexp
    • all bookmarks with "redhanded" on the description or the URL, defined/last used in the last month: redhanded ~d <1m
    • all bookmarks with "ruby" on the URL, defined/last used in 2006: ~d 2006 ~u ruby
    • all bookmarks tagged as "blog", defined/last used in Q1: :blog ~d q1
  • progressive refining: I can enter successive expressions and each one further restricts the possible choices, which are shown in the menu

Users Configs

Add your configuration URL to the list