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, 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

• 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

  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 https://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 <[email protected]> (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

Several applets:

• mpd: control the Music Player Daemon
• battery-monitor
• configurable status bar
• volume control

…

  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.