ruby-wmii: Ruby configuration/scripting for the wmii window manager

ruby-wmii a fairly powerful Ruby script to configure and script the wmii-3 WM. It is much larger and more complex than the sample shell script included in wmii-3, but in exchange it allows you to code fairly complex behavior easily (for instance, ruby-wmii includes a powerful keyboard-controlled bookmark manager), and the basics work better in several ways:

• tracking and disposal of child processes
• protection against runtime errors, so wmiirc doesn't die leaving you with a broken environment
• auto-updating program lists with caching
• powerful internal actions without external scripts
• logging

• wmii compatibility
• Installation and usage
• darcs repository
• Installing
• Customization
• Third party plugins, configurations, tips & tricks...
• Advanced functionality
• FAQ
• Default behavior
• Key bindings
• Internal actions (MODKEY-a)
• License

wmii compatibility

Latest news [2007-12-04] ruby-wmii updated for use with wmii 3.6 The previous code has been moved to the -3.1 branches, and both head and branch-ruby-ixp work with 3.6. Still no tarball release, and the documentation on this site has yet to be updated. The standard plugins are being converted (some bugs remain), 3rd party plugins might require modifications.

ruby-wmii works with wmii-3.1. The internal FS layout is routinely broken on each wmii release, and I've been waiting for an official release of wmii-3.6 for a while but it never seems to arrive, so I'm staying with my current setup, which works just fine.

If you want to use ruby-wmii, you'll need:

• wmii-3.1.tar.gz
• this two-line patch by Suraj N. Kurapati (see this discussion on wmii's mailing list), if you want to use the ruby-ixp branch, which feels snappier than the trunk (that's the branch I'm using currently, so there are probably more bugs in the trunk). Note that ruby-ixp leaks memory, but this is not a problem since you can restart wmiirc without leaving X once a day or so with Alt+a wmiirc (you could easily have it restart automatically too).

Installation and usage

The latest version is ruby-wmii-0.3.1.tar.gz. You can read the release notes and report bugs here.

Older release notes:

• ruby-wmii 0.3.0: extensibility via plugins, easier upgrades, new applets (MPD, battery monitor)...
• Automagic (generalizable) working set discovery, improved ruby-wmii WM scripting 0.2.1

darcs repository

You can find the repository (including head and other development branches) at http://eigenclass.org/repos/ruby-wmii

Installing

Run the included install.rb script with

 ruby install.rb

to install wmiirc and the standard plugin.

You'll be shown a help message with xmessage the first time you restart wmii if it's the first time you run ruby-wmii or you're upgrading from an older version. You can also find it at the top of the wmiirc script, or get it with

 Alt-a config-help

Customization

You can edit $HOME/.wmii-3/wmiirc-config.rb and reload the configuration with Mod1-a -> wmiirc as often as needed until you're satisfied with the result.

I'm very interested in innovative key bindings --- the usability space is best explored in parallel. Feel free to contact me at <mfp@acm.org> (any feedback appreciated; please add 'wmii' to the subject line to get past the spam filters).

Third party plugins, configurations, tips & tricks...

This is a wiki after all! Feel free to share your tips, point to your plugins... on the "community" page.

Advanced functionality

ruby-wmii includes

• modal key bindings: raw (pass-through) and normal
• volume control with the mouse wheel
• namespaces (subtagging)
• internal actions: browser, google, rename-view, screenshot
• working set inference
• many tagging/retagging mechanisms
• most convenient bookmark management (complete-as-you-type, powerful searching, del.icio.us syncing...)

Several applets:

• mpd: control the Music Player Daemon
• battery-monitor
• configurable status bar
• volume control
• most convenient bookmark management (complete-as-you-type, powerful searching, del.icio.us syncing...)

...

FAQ

You can read the FAQ (and add your questions) here.

Default behavior

Key bindings

These are the default aliases:

   MODKEY   Mod1
   MODKEY2  Mod4  (often win key)
   UP       k
   DOWN     j
   LEFT     h
   RIGHT    l

MODKEY2-space        Switch between raw and normal input modes.
                     The current mode is indicated in the bar. All other key
                     bindings are ignored in raw mode.
MODKEY-Control-y     Run program with given tag (uses wmiimenu twice to get
                     the tag and the program).
MODKEY-a             Ask for action and execute it.
                     Includes internal and external (i.e. dependent on a
                     script in $HOME/.wmii-3) actions. Remembers the last
                     actions executed and presents them at the beginning.
MODKEY-p             Ask for a program and execute it.
                     The list of programs is updated periodically and cached.
                     Remembers the last programs executed and presents them at
                     the beginning.
MODKEY-0..9          Choose either the corresponding numerical view (if it
                     exists) or the (N-last_numerical_view)th non-numeric view
                     e.g. if the views are  1 2 3 4 code irc web
                     and you press MODKEY-6, it'll take you to  irc
MODKEY-Shift-0..9    Either replace the the numeric tag of the current client
                     or retag it as the (N-last_numerical_view)th non-numeric
                     view.
MODKEY-t             Ask for view to move to.
                     Tries to sort the choices intelligently based on
                     previous movement.
MODKEY-LEFT          Select prev column.
MODKEY-RIGHT         Select next column.
MODKEY-UP            Select prev client.
MODKEY-DOWN          Select next client.
MODKEY-space         Toggle managed/floating layer.
MODKEY-d             Set default mode.
MODKEY-s             Set stacked mode.
MODKEY-m             Set max mode.
MODKEY-f             Maximize current floating client.
MODKEY-i             Move bottom of current client down (i.e. enlarge)
MODKEY-Shift-i       Move bottom of current client up (i.e. shrinken).
MODKEY-Return        Launch terminal.
MODKEY-Shift-LEFT    Send to prev column.
MODKEY-Shift-RIGHT   Send to next column.
MODKEY-Shift-DOWN    Swap with lower client.
MODKEY-Shift-UP      Swap with upper client.
MODKEY-Shift-space   Toggle managed/floating layer for client.
MODKEY-Shift-c       Kill current client
MODKEY-r             Go back to previous view (where we came from).
                     Pressing more than once makes you cycle between 2 views.
MODKEY-Control-UP,
MODKEY-comma         Move to (lexicographically) preceding view.
MODKEY-Control-DOWN,
MODKEY-period        Move to (lexicographically) following view.
MODKEY2-Shift-UP,
MODKEY2-comma        Move to (lexicographically) preceding view within
                     current namespace.
MODKEY2-Shift-DOWN,
MODKEY2-period       Move to (lexicographically) following view within
                     current namespace.
MODKEY-Shift-t       Retag current client. Allows +/- modifiers to add/remove
                     tag.
MODKEY-Shift-r       Retag current client and move to corresponding view.
                     Alloes +/- modifiers.
MODKEY2-Shift-t      Retag in the namespace. Given a client tagged as foo+bar:
                       baz   retags it as bar:baz
                       +baz  retags it as foo+bar+bar:baz
                     Given foo+bar:baz, -baz  retags as  foo
MODKEY2-Shift-r      Retag as MODKEY2-Shift-t and moves to new view.
MODKEY2-a..z         Jump to first view whose name starts with the given
                     letter, sorted with intellisort (favors views chosen
                     before)
MODKEY-plus          Move forward in view history
MODKEY-minus         Move backwards in view history.
MODKEY-b             Open bookmark (see README.applets for further
                     information).
MODKEY-Shift-b       Bookmark URL in X11 primary selection buffer. Again, see
                     README.applets.

Internal actions (MODKEY-a)

 browser:     if given an argument, open the given URL in a browser, otherwise
              ask for it
 google:      same as 'browser', but searches with google
 screenshot:  takes a screenshot in $HOME/tmp/NAME-IDX.png, where NAME is
              either the given parameter or 'screenshot', and IDX is
              incremented automatically
 rename-view: change the name of the current view, and retag all clients
              accordingly. Takes the new name as a parameter, or asks for it.
 wmiirc:      reload the wmiirc configuration
 config-help: shows information about how to use and configure wmiirc, as well
              as how to write plugins

License

ruby-wmii is licensed under the same terms as Ruby; see LICENSE.