In this chapter you will see how to control wmii through scripts. I will give you some pointers, that you can start scripting on your own.
As mentioned earlier, the only requirement for interacting with wmii is to access its file-system service. The easiest way to do this, is by using the wmiir tool. Thus shell scripts are the easiest way of adapting wmii too fit your needs.
Hence, you can control wmii in any programming language you want. However, wmii's default scripts are written in a subset of ``sh'' that is POSIX compliant, to keep wmii as portable as possible.
To keep simplicity, the following examples will stick to ``sh'' as well, and don't depend on python, tcl, ruby, ...
In wmii you may group certain tasks into actions. Actions are nothing more than simple scripts which are located either in your local or in the default wmii configuration directory 8. Through pressing MOD-a you can open the actions menu. It works similar to the program menu, but only displays actions.
You might want to add your own actions through writing shell scripts in the default wmii configuration directory or in the $HOME/.wmii-3.
This works, because in the wmii controlling script exports the variable
$PATH as
$PATH=~/.wmii-3:$CONFPREFIX/wmii:$PATH before
launching the wmiiwm, this way local user actions under
~/.wmii-3 take precedence over the defaults from
$CONFPREFIX/wmii of the default actions.
You may edit this file on the fly, which means you don't need to
stop wmii before editing. After you've finished editing, you may
simply run wmiirc and the changes will take effect immediately.
To do so, just open the actions menu (with pressing MOD-a) and
choose the wmiirc action. It's also possible to launch wmii actions
directly from a terminal, which is a neat side effect that results from
exporting $PATH in the wmii startup script.
wmiirc is a special ``sh''-script which is launched on startup of wmii to take care of configuring and controlling wmii.
It does so through writing data to several files of the virtual wmii file-system, and through reading events reported by wmii during runtime. Events are mostly shortcut presses, mouse clicks or user-defined. The events are processed in a loop in the script.
Thus, for the basic configuration of wmii, like changing the default modifier key MOD=Mod1 or the navigation keys this script is the place to look at.
The name wmiirc means wmii run command, because ``rc'' is an old Unix abbreviation for ``run command''.
The style of wmii-3 is defined through font and colour values, which are unobtrusively exported with the following environment variables.
WMII_SELCOLORS='#000000 #eaffff #8888cc'
WMII_NORMCOLORS='#000000 #ffffea #bdb76b'
WMII_FONT=static
WMII_SELCOLORS defines the colours of the selected client's window
title and border, whereas WMII_NORMCOLORS defines the colours of all
unselected clients. The numbers are hexadecimal rgb tuple-values, which you
might know from HTML. You can grab them with the Gimps colour-chooser for instance.
The first colour defines the text colour of strings in bars and menus. The second colour defines the background colour of bars and clients, and the third colour defines the 1px borders surrounding bars and clients.
WMII_FONT defines the font which should be used for drawing text.
in title-bars, the status-bar, and the wmiimenu.
You can query for different fonts using xfontsel for instance.
The status bar of wmii has it's own /bar directory with
a subdirectory for each of the labels created. So while editing
this document my status-bar looked like:
$ wmiir read /bar
d-r-x------ salva salva 0 Mon Apr 17 14:19:51 2006 1
d-r-x------ salva salva 0 Mon Apr 17 14:19:51 2006 2
d-r-x------ salva salva 0 Mon Apr 17 14:19:51 2006 status
At the same time each of the subdirectories contains two files,
$ wmiir read /bar/status
--rw------- salva salva 23 Mon Apr 17 14:22:14 2006 colors
--rw------- salva salva 23 Mon Apr 17 14:22:14 2006 data
The first file contains the colour definitions that control how the bar will be drawn, while the second contains the data which is displayed.
Now you can start your own experiments by creating a new label, and
exploring and modifying it by reading & writing values to it's
colors & data files. A nice feature of the bar
(and clients) is that they generate events corresponding to mouse
clicks on them. You can open a terminal and run
wmiir read /event to see how the events are generated
when you click onto the status-bar. This is a mechanism that allows
controlling applications directly from the bar. If you've
finished and you want to get rid of your label,
a wmiir remove /bar/foo command.
If you want to learn more, take a look at the status script and visit http://wmii.de for good examples, like the following:
Now open the default status script and try to understand yourself, how it works
#!/bin/sh
# periodically print date and load average to the bar
xwrite() {
file="$1"; shift
echo -n "$@" | wmiir write "$file"
}
wmiir remove /bar/status 2>/dev/null && sleep 2
wmiir create /bar/status
xwrite /bar/status/colors $WMII_NORMCOLORS
while xwrite /bar/status/data `date` `uptime | sed 's/.*://; s/,//g'`
do
sleep 1
done
. The first line is a handy xwrite function declaration, to prevent you from several verbosity
when issuing a write to some file. The following 3 lines take care of
creating and setting up the status label. The last section is a
while loop
that tries to write the system load and date information
to the bar.
The tricky bit is, that it tries. So what could make the write
fail? If xwrite tried to write to a non existent (removed)
label, then it would fail, thus the condition of the loop would be
false, and the status script exits cleanly, which makes sense
because nobody wants a program that updates a nonexistent label.
Now go back to the first lines of the script, and note
that there is a sleep delay between the removal of the
label and it's creation.
This ensures that the status label will not exist, hence all
the writes made from any previously running status script
will fail, thus they will finish. This way we make sure that
we only run one status script at each time. And thus we keep the
one-to-one correspondence between label and status script.
As mentioned before, you can achieve more powerful things with tags, than with the standard key-bindings. You might use any string as a tag. You may even use more than one tag per client. To do so, you have to separate the tags with a ``+''.
echo -n web+code | wmiir write /view/sel/sel/tags
This command would give the current focused client the tags ``web'' and ``code''.
You can now view the ``web'' tag by executing the following:
echo -n view web | wmiir write /ctl
As the development of wmii-3 progressed, it became clear that this action is so common, that it got its own keybinding. By default MOD-t brings up a menu to choose a view and MOD-Shift-t brings up a menu enabling you to assign new tags to the focused client.