Some Pekwm configurations

December 30, 2007

I’ve recently started using Pekwm again. Pekwm is a light window manager, in looks similar to Openbox or Fluxbox that allows you to tab windows, has good keychains options, can use dynamic menus (‘pipe-menus’ in Openbox) and supports pixmap themes. I played with it a little nearly a year ago, but never long enough to explore all its possibilities. I’ve now grown very fond of it, and have worked out solutions to all the little things that bothered me at first. The documentation is excellent and covers all what you need to configure Pekwm (the documentation is for Pekwm 0.1.5, though, and doesn’t cover some of the new features introduced in the latest stable version, 0.1.6). Below are some of my own settings to make Pekwm behave the way I want it to. This is meant mainly to remind me what I did if I need to reinstall Pekwm later on, but perhaps some of you will find some use for it as well.

Focus on click

By default Pekwm focuses a window when you move your mouse over it. To change it to a ‘focus on click’ behaviour is made very simple by the developers. In your mouse file look for the following lines and do what it says:

#Remove the following line if you want to use click to focus.
And: #Uncomment the following line if windows should raise when clicked.

Changing the way the menu behaves

The default configuration in Pekwm (and Fluxbox, actually) for the display of menus, specifically the hiding or closing of menus, irritates me. To close an open menu, you either have to launch one of the items on the menu or right click on the menu heading. I am, however, used to Openbox’ approach: when you click anywhere outside the menu or when a new menu is launched, the open menu simply disappears. Here is how to achieve this in Pekwm.

All of this is obviously done in the mouse file. First of all, I added “HideAllMenus” before all “ShowMenu” commands. In this way, if I open the root menu any window menu that might have been open automatically disappears. Here is an example from the FrameTitle section:

ButtonRelease = "3" { Actions = "HideAllMenus; ShowMenu Window" }

Then add the same command to the right clicks on the window decorations and window clients. In the FrameTitle and OtherTitle sections, create the following line:

ButtonRelease = "1" { Actions = "HideAllMenus; Raise; Focus; ActivateClient" }

In the Client section, add the following:

ButtonPress = "1" { Actions = "HideAllMenus; Focus; Raise" }

Edit the following lines in the keys file, to make menus disappear when you switch desktops:

KeyPress = "Ctrl Mod1 Left" { Actions = "HideAllMenus; GotoWorkspace Left" }
KeyPress = "Ctrl Mod1 Right" { Actions = "HideAllMenus; GotoWorkspace Right" }

Autohiding the harbour

The harbour is Pekwm’s version of Openbox’ dock or Fluxbox’ slit. It is the place where dockapps are loaded. Unlike the dock and the slit, the harbour cannot be set to autohide. Since I don’t like panels, I use the harbour for a system tray (docker) and a clock (bbtime or lal), but I don’t want to have it always on top or always below all other windows; nor do I want a strut for it. Here is what I did to create a ‘semi-autohiding’ harbour. My harbour shows up in the lower right corner of my screen.

In the Down part of the ScreenEdge section of the mouse file, I added the following line:

Enter = "Any Any" { Actions = "Toggle HarbourHidden" }

This toggles the harbour whenever I move my mouse to the bottom of the screen. The downside is that there is no ‘autohide’ feature; to make the dock disappear again you have to move your mouse back to the bottom of the screen.

To set the harbour to disappear again, I’ve configured Pekwm to hide the harbour again when I click on a window or window title. I added the option “Set HarbourHidden” to the following lines.

In the Client section:

ButtonPress = "1" { Actions = "HideAllMenus; Set HarbourHidden; Focus; Raise" }

In the FrameTitle section:

ButtonRelease = "1" { Actions = "HideAllMenus; Set HarbourHidden; Raise; Focus; ActivateClient" }

In the OtherTItle section:

ButtonRelease = "1" { Actions = "HideAllMenus; Set HarbourHidden; Raise; Focus" }

This isn’t quite autohiding, but it is good enough for me.

Normal alt-tab behaviour

As I don’t use a panel, the way the alt-tab window switching works is a big deal for me. I’ve never grown very fond of Fluxbox, for example, because it doesn’t have an alt-tab display. The default alt-tab behaviour in Pekwm does not focus the next window and place it at the top of the list. The default alt-tab therefore switches between windows in the order that they were launched. Impractical in my book, but this is easy to change. In the keys file, change “NextFrame” and “PreviousFrame” into “NextFrameMRU” and “PreviousFrameMRU” (there is already a default entry with these commands). Reload Pekwm and you will have a ‘normal’ alt-tab.


Pekwm is a great window manager. The only downside is its scarcity of good themes. You can find a few on Box-look, Hewphoria, and FreshMeat, but most of these are visibly several years old (some aesthetics change rapidly). So if you use Pekwm and have some artistic ability, please create some new themes!

Here is a screenshot of my current Pekwm setup. Yes, that is a purple desktop 🙂


You can use several applications to adjust the volume. Try alsamixer, a command-line mixer for alsa which comes with ubuntu (part of alsa-utils), or one of the many frontends for it: alsamixergui; qamix, a Qt front-end for alsamixer; gamix, a Gtk front-end; or (if you can tolerate gnome dependencies) gnome-alsamixer. You can also use xfce4-mixer, though it loads xfce-mcs-manager which might interfere with your gtk settings if you use another method to apply these. You can use all of these to control the volume, 3D switches, the volume of CD audio, line-in, headphones, phone, etc.

There are also several dockapps available to adjust the volume. Have a look here.

Several panels also have plugins to adjust the volume: this is the case for the lxpanel, perlpanel, xfce4-panel (using xfce4-mixer), gnome-panel, and kicker.

While all these applications may be useful, it is generally easier to change the volume by pressing a single key or a combination of keys on your keyboard. How can you accomplish this in Openbox?

The following commands turn the volume up and down:

    Up: amixer -q set PCM 1+ unmute

    Down: amixer -q set PCM 1- unmute

To toggle mute, use the following command:

    amixer -q set PCM toggle

If you’d rather change the master volume (as opposed to the PCM), use the following commands:

    Up: amixer -q set Master 1+ unmute

    Down: amixer -q set Master 1- unmute

    Mute: amixer -q set Master toggle

To make these commands more convenient, assign keyboard bindings to them in the rc.xml file. I use Ctrl+Up, Ctrl+Down, and Ctrl+Alt+End to turn the volume up, down and on/off. If you are more of a mouse person, you could also use a dockapp with launchers and assing the above commands to some launchers.

If you like an on-screen display when you change the volume, you can use OSDsh, a small application that shows the volume levels of your soundcard whenever they change. It is in the Ubuntu repositories.

In order to use OSDsh, you have to run it in the background. Install the application (duh!), and add the following lines to your autostart file (~/.config/openbox/

	osdsh &
	(sleep 1 && osdctl -m 1) &

You can use themes to adjust the looks of OSDsh. To create your own themes, use the command “osdshconfig“. Themes allow you to change the colours, position, fonts, shadow offset, outline width and the delay of the on-screen-display. To apply them, use the following command in your autostart file, after “osdsh &”:

	osdctl -S /path/to/your/theme/file

There are several ways to set the wallpaper when you use a window manager, like Openbox, without a desktop environment. Some window managers, like Fluxbox and Icewm, can set a desktop background (with fbsetbg and icewmbg respectively); Openbox doesn’t deal with the desktop, so you’ll have to use a separate application to accomplish this. The following might still be useful for Fluxbox and Icewm users, as some of the applications discussed below do more than simply display an image on the desktop.

The most popular ways to set a desktop wallpaper in Openbox is by using either Feh or Nitrogen (see my Openbox guide), but there are many other possibilities. I will discuss a few here. If you know of any others, please let me know.

Below I only mention the options and configurations I found useful and/or interesting. Most of the applications have a lot more options than those listed below. As always, I recommend reading the man pages (type “man name of the application” in a terminal) for each app to see what it all can do.

All of the applications discussed here are in the Ubuntu repositories (from Dapper onwards).Many of them are quite old, but they still do the job.

I generally use Feh (both as an image viewer and to set the wallpaper), though I am also fond of Habak and Hsetroot. Use whatever you like best.


Xli is an “X image loading utility”. Like Feh, Xli is basically an image viewer, that can optionally display an image on the desktop.

To use xli as an image viewer, use the following command:

	xli /path/to/image

When viewing an image with xli, you can rotate the image clockwise (press ‘r’) or counter-clockwise (press ‘l’) or change the brightness (press 0-9).

To set the desktop wallpaper with xli, use the following command:

	xli -onroot -fullscreen /path/to/image

Other options are -fillscreen (to fill the entire screen; the image will be zoomed if smaller than the screen) and -fit (makes the image fit to the screen; if the image is smaller it is tiled to fit the screen). If the image is smaller than the screen, xli will draw a border around the image; you can set the colour of the border with -border COLOUR. You can draw the image in greyscale (using -gray), brighten it (using -brighten percentage), or zoom in (using -zoom percentage).

(When I installed xli through aptitude in Dapper it installed the binary in /usr/X11R6/bin/. The command “xli” is therefore not recognised and should be replaced by /usr/X11R6/bin/xli.)

Xloadimage and Xsetbg

Xloadimage is also an image viewer for X. Xloadimage and its component xsetbg accomplish the same tasks as xli, and the very same commands that xli uses are used in xloadimage (just replace xli with xloadimage in the commands given above).


Esetroot is a simple, no-nonsense application to set the background. It belongs with Eterm, but can easily be used independently. Here are the basic commands (note that the proper command is Esetroot, not esetroot):

    To scale an image:

	Esetroot -s /path/to/image

    To centre an image:

	Esetroot -c /path/to/image

    To display an image in its original size:

	Esetroot /path/to/image


Gsetroot is a graphical (Gtk) front-end for esetroot. Its interface is fairly simple and straightforward: select the image you like to set as a wallpaper, select whether you want it centred, full size, or tiled. It has a ‘preview’ button, but I am not sure what it does, as it never worked on my computer. Here is what it looks like:



Hsetroot does a lot more than just displaying an image or a colour on the desktop. As the website tells you, hsetroot “is a tool which allows you to compose wallpapers.” Not only can it set solid colours, gradients or image files (centred, tiles, at full size or scaled), but it allows you to manipulate the images you want it to display as well. Thus you can tint an image, blur or sharpen it, adjust the brightness, contrast or gamma-level, flip the image (horizontally, vertically, or diagonally).

Here are some example:

	hsetroot -fill ~/Images/Desktops/bwwoodwall.jpg

This gives me the following desktop image:


If you would like to tint the image, so that it better matches the theme of your choice, this is the format you use:

	hsetroot -fill ~/Images/Desktops/bwwoodwall.jpg -tint '#B4A783'

This gives me the following desktop image:


Hsetroot does all this without altering the image file it uses, though you can ask it to save a copy of the image it creates.


Habak is a versatile tool to set the desktop wallpaper and is part of the T2 Linux distribution (or, according to the developers, the T2 “System Development Environment”). It is a very useful application if you like to stack images on the desktop (with or without transparency), though it does a few more things than that.

Like most applications discussed here, you can set a single image on the desktop (with “habak -hi /path/to/image/file), but you can also set a random wallpaper whenever the program is run. To do so, you have to direct habak to a directory of images (rather than a single image), for example: habak -hi ~/Images/Desktops/. Smaller images are automatically centred, images larger than your screen are automatically scaled. Neat.

You can set more than images with Habak. You can set a single line of text using the command habak -ht “put your text here”. The text can be a command, such as the date (`date +%Y-%m-%d`). You can also fade out every other line of your desktop image (some sort of interlace) with the following commands: habak -hI int or habak -hI INT. The first fades out every even line, the second every uneven line; use both of them (habak -hI int -hI INT) to fade out the entire image.

These are the basics of habak, and in “Habak speak” these three tools (-hi for images, -ht for text, and -hI for interlace) are called ‘habaks’. You can play with these habaks, and combine any number of them: you can set multiple images, with multiple lines of text and interlace. But to make things more interesting you can also use parameters to modify these habaks. Here are the modifiers:

    -mC: this centres the habak, and is used by default.
    -mp X,Y: this places the habak at the coordinates given for X and Y.
    -mS: this scales the habak, but respects the original proportions.
    -ms: this scales the habak, but disregards the original proportions.
    -mc: this modifies the colour of the habak. The colour string that should follow it is of the structure R,G,B,A — red, green, blue, and alpha (use something like gcolor2 to find out what the values are for your favourite colour). Thus -mc 0,0,0,255 gives black with no transparency. If unspecified, Habak uses the default semi-transparent light grey.
    -mf: this specifies the .ttf font to be used (you have to specify the entire path to the font file; make sure you specify the name of the font file, rather than the font name). If unspecified, a random font from ~/.fonts is used.
    -mh: this sets the font size (in pixels). The default is 30 pixels.

Place the modifier(s) before the habak you want to modify. The options are applied in the order that the options are listed in the command: if an image comes after a text string, it will cover the text.

As you may have realised by now, the above habaks and modifiers can accomplish a lot. Unfortunately, you can’t use Habak to display the time (as it doesn’t refresh automatically). If it could, I would use it to replace conky, which I only use to display the date and time anyway. (Xcompmgr doesn’t interfere with Habak.)


Cwallpaper is a front-end for applications that set wallpapers. The website boldly declares that “it has the ability to work with any root wallpaper changer”. I have used it succesfully with feh, fbsetbg, Esetroot, hsetroot, xli, and xsetbg. As a front-end for other wallpaper setters, Cwallpaper is useful for those users who like to use command line applications but also like at times a graphical user interface. If you generally use Feh for setting the wallpaper, for example, whatever wallpaper you set with CWallpaper will also be reloaded when you restart Openbox (with “eval `cat $HOME/.fehbg` &” in your autostart file, off course).

Here is what CWallpaper looks like:


Before you first run CWallpaper, you will have to configure it. You will find an example configuration file in /usr/share/cwallpaper (or /usr/local/share/cwallpaper). Copy that file to ~/.config/cwallpaper/ (create it if it doesn’t exist), and edit it to your liking. Specify whatever program you want to use (default is fbsetbg) and the commands it uses to scale, tile, and center the wallpaper (“–bg-scale”, “–bg-tile” and “–bg-center” for Feh, etc.).

Next, you will need to specify all the wallpapers you want CWallpaper to display in its window. These are set in the file ~/.config/cwallpaper/wallpapers by entering the full path to the image (including the image name!). This is rather a lot of work if you have a lot of wallpapers, but luckily CWallpaper comes with a handy script to accomplish this task nearly effortlessly. In /usr/share/cwallpaper you will find a script Copy this anywhere in your home directory (I keep it in the ~/.config/cwallpaper/ directory). Open the file with your favourite text editor and change all the “$1” with the path to your desktop wallpapers directory. Make the script executable (chmod a+x /path/to/script) and run it. It will automatically generate a wallpapers file in the ~/.config/cwallpaper/. (Note that the script also scans for image files in the subdirectories of the directory specified.) Now run cwallpaper and you will be able to set the wallpaper of your choice.


Do you like rotating wallpapers? Then chbg might be the application you were looking for. Chbg is a versatile application: its basic function is to change or rotate wallpaper images, but it can also act as screensaver (on its own or as a xscreensaver client), and a slide show application (in its own window). You can adjust the speed, the order in which the images are shown, the position of the images on your desktop or screen, the effects used when changing the image, and a lot more. (Have a look at the screenshots to see what it all can do)

Chbg has a graphical interface for basic configuration (chbg -setup). I have only used the older Gtk1.2 version though it has more recently been ported to Gtk+-2.0. Here is an image of the older configuration window:



What about an animated wallpaper? If you have xscreensaver installed, you can force it to run on the root window (i.e. the desktop). For guidelines how to do this, have a look at K.Mandla’s post (also here).


Telak is able to draw local or remote pictures on your desktop. It doesn’t draw the desktop itself (unless you specify that in the configuration file), but shows the image(s) above the desktop wallpaper. You can show multiple images at once, and have a different configuration for each image. You can invert the colours of the image, set the size of the image, the position on the desktop, and the refresh rate. Here is a sample entry in the configuration file (stored in ~/.telak/telakrc):

	url =
	width = 40
	height = 40
	x = 10
	y = 10
	refresh = 600

Telak is especially useful if you want your desktop to display changing graphs, or even webcam images.


If you like things psychedelic, xstarfish is your application! It is “an X wallpaper generator. XStarfish generates colourful, tiled images for your background using random numbers fed through mathematical functions. It does not use source image files, so it can generate its images nearly forever without running out of material.” Fun (and headaches) guaranteed!

Just run “xstarfish” and it will generate and display a lovely wallpaper. If want it to generate a new wallpaper every x minutes, seconds, or days, use the following command: “xstarfish -d INTERVAL“, where interval is the time you want xstarfish to sleep before creating a new wallpaper (seconds are the default). Be aware that it can take a while to generate a new image.

Here are a few sample screenshots:

xstarfish1 xstarfish2

I am clumsy and at times inattentive. Especially after a hard day’s work, I sometimes perform actions on my computer without giving them much thought. I close an application, whereas I only wanted to close the current page; I accidentally save older versions of files and overwrite my latest version in the process; or I reboot my computer when I wanted to log out or shut down. Sometimes my mouse slips and accidentally clicks “shut down” in the Openbox menu, allowing me to see all my unsaved OpenOffice documents disappear before me. I’m sure I’m not the only one who has such moments (or at least I hope so ;-)).

If possible I therefore want the computer to ask for a confirmation before I do something drastic. However much I love Openbox, I always missed a dialog box asking me to confirm whether I wanted to log out or shut down. Here is how you can create one.

Using gmessage (or xmessage if you like things ugly), you can create a dialog box that follows your gtk theme and asks you what action you want to take. Here is what mine looks like:


So how do you do it? First install gmessage:

	sudo aptitude install gmessage

Next create a script that looks a little like the one below (adapted from here):


gmessage "Are you sure you want to shut down your computer?" -center -title "Take action" -font "Sans bold 10" -default "Cancel" -buttons "_Cancel":1,"_Log out":2,"_Reboot":3,"_Shut down":4 >/dev/null

case $? in
echo "Exit";;
killall openbox;;
sudo shutdown -r now;;
sudo shutdown -h now;;

This gives the message you’ve seen above, centred on the screen. Cancel is the default button, pressing esc will close the window, pressing S will shut down, R reboot, L log out of Openbox. (I am not too sure if “killall openbox” is the best option to log out of Openbox, but it does the trick. If you know of a better way, please let me know.)

Change the above to suit your preferences. Have a look at “man gmessage” for more options. Save the script somewhere (I keep all my scripts in ~/.scripts/), and make the file executable:

	chmod a+x /path/to/script

Now you’ll want to add the script to your menu or create a keyboard binding for it in the rc.xml file. This is done like you would for any application, except that the command here is the path to the script, in my case /home/urukrama/.scripts/shutdown.

If you want to make the message box to display without any window decorations, either add the parameter “-borderless” to the above script (somewhere in the first part, for example after “-center“) or add the following to your rc.xml file in the applications section (at the end of the file):

<application name="gmessage">

This method work best if you allow users to shut down and reboot without administrative privileges, but will work also if you don’t — just replace all the “sudo”-s with “gksudo” in the script and it will ask you for your password before it shuts down.

To allow users to shut down without administrative privileges, do the following: Open a terminal and type

	sudo visudo

Add the following at the bottom of the page:

	ALL     ALL=NOPASSWD:/sbin/shutdown

Save and exit, and you won’t be needing your password to reboot or shut down. (If you prefer to use the “halt” command to shut down and reboot, replace the above line with ALL ALL=NOPASSWD:/sbin/halt.)

That’s it. The chances that you accidentally shut down or log out are now a bit smaller.