Some documentation

This page is divided into several sections. Please use the floating menu at the right to navigate through it.

Source code

The source code is managed under Git. To get it, make sure you have Git installed and use:

git clone git://superkb.git.sourceforge.net/gitroot/superkb superkb-git

Also, the source code has a lot of FIXME which need work. They are documented throughout the code.

Compilation

a simple make should do it. However, in some distributions, you must issue the command two times.

Superkb uses a file named "configuration" to keep track of detected system settings. This file can contain the following directives:

• PUTICON_GDKPIXBUF={y|m|n}: whether to compile support for Gdk-Pixbuf library (y), include support for it as a module (m), or not include support for it at all (n). It is normally detected by the Makefile by using pkg-config gdk-pixbuf-xlib-2.0.
• PUTICON_IMLIB2={y|m|n}: whether to compile support for Imlib2 library (y), include support for it as a module (m), or not include support for it at all (n). It is normally detected by the Makefile by using imlib2-config.

Installation

A simple make install should do. Paths are fixed at this moment.

Configuration

Superkb looks for a file named .superkbrc in the $HOME directory. The file is interpreted as a script, so if a command conflicts with another, the second one wins. Comments are indicated by a pound sign (#) and the rest of the line is ignored. Basic syntax is "KEYWORD value", but if a value includes a space, it must be enclosed in double quotation marks. Currently supported directives are:

• IMAGELIB {gdkpixbuf|imbli2}: Set the icon loading library to use. Support for it must be either compiled in or included as a module. See Compilation for more information. Default value: "imlib2".
• FONT "font name": The XLFD name of the font to use. I recommend to use a scalable font. I use xfontsel -pattern "*-0-0-0-0-*-0-*" to find a font chooser with suitable fonts. But there are reports that this doesn't necesarily work. Don't forget the double quotes on the font name, since most fonts contain spaces in their names. Default value: "-*-bitstream vera sans-bold-r-*-*-*-*-*-*-*-*-*-*".
• BACKGROUND r g b: Sets the background color to use. Each value must be in the range of 0 to 65535. This is likely to change in the future. Default value: 59500 59500 59500. (Yes, it's ugly.)
• FOREGROUND r g b: Sets the foreground color to use. Each value must be in the range of 0 to 65535. This is likely to change in the future. Default value: 2000 2000 2000. (Heh, it's ugly too.)
• DELAY seconds: Sets the amount of time to wait for before the keyboard is shown, after holding the Super key down. Decimal values are accepted. Default value: 0.5.
• SUPERKEY1_STRING: Sets the first Super key, by name. Default value: "Super_L"
• SUPERKEY2_STRING: Sets the second Super key, by name. Default value: "Super_R"
• SUPERKEY1_CODE: Sets the first Super key, by X key code.
• SUPERKEY1_STRING: Sets the second Super key, by X key code.
• KEY COMMAND key mask command icon [feedback]: Launches an arbitrary command. "Key" sets the key to use. Not all keys work at this moment, but letters and function keys (as in "F1" should work. "Mask" is reserved for future use; just put a 0 in there. "Command" is the command to run (don't forget the double quotes if needed) and "Icon" is the ABSOLUTE location to the icon file to show on the keyboard. The optional "feedback" string should appear with the line to be appended to the FEEDBACK_HANDLER. For example, if the FEEDBACK_HANDLER is 'xmessage -timeout 2 -center Launching ', the "feedback" string should be set to something like "gedit", so it shows "Launching gedit" on the screen. Note that omiting the "feedback" string disables the feedback for that KEY.
• KEY DOCUMENT key mask document icon [feedback]: Uses the DOCUMENT_HANDLER to open the specified document. "Key" sets the key to use. Not all keys work at this moment, but letters and function keys (as in "F1" should work. "Mask" is reserved for future use; just put a 0 in there. "Command" is the command to run (don't forget the double quotes if needed) and "Icon" is the ABSOLUTE location to the icon file to show on the keyboard. The optional "feedback" string should appear with the line to be appended to the FEEDBACK_HANDLER. For example, if the FEEDBACK_HANDLER is 'xmessage -timeout 2 -center Launching ', the "feedback" string should be set to something like "gedit", so it shows "Launching gedit" on the screen. Note that omiting the "feedback" string disables the feedback for that KEY.
• DOCUMENT_HANDLER string: Indicates what program should be used to open a document specified with a KEY DOCUMENT directive.
• FEEDBACK_HANDLER string: Sets the program to use to send the feedback when a KEY gets executed. Technically speaking, the command actually sent, is the "feedback" on the KEY command concatenated to the FEEDBACK_HANDLER parameter.
• SUPERKEY_REPLAY { 0 | 1 }: Sets whether the Super key should be resent to the original input window, so the typical key usage won't get lost. For instance, if the F10 key is set as the Super key, this would allow the key to be sent again if the key is hit (as opposed to held down or combined with another key to launch something). This way, GNOME apps that have a menu will show it.

Testing on distributions

These are installation notes and instructions on specific distributions. Comments and additions are welcome.

Ubuntu 6.06 LTS (Dapper Drake)

• Prepare your Ubuntu installation:
  • Run Synaptic Package Manager, from System > Administration
  • Click Reload
  • Mark "make", "libimlib2-dev", "gcc" (not -4.0, not -3.x, just plain "gcc").
  • Click Apply and continue as usual
• Update libimlib2. (At the moment of writing, Ubuntu doesn't include the required libimlib2, not even as an update):
  • wget http://easynews.dl.sourceforge.net/sourceforge/enlightenment/imlib2-1.2.2.tar.gz
  • tar xvzf imlib2-1.2.2.tar.gz
  • cd imlib2-1.2.2
  • ./configure --prefix=/usr && make
  • sudo make install
• Install Superkb:
  • Download Superkb from the Download section.
  • tar xvzf superkb-0.10-tar.gz —or— tar xvjf superkb-0.10.tar.bz2
  • cd superkb-0.10
  • sudo make install
• Configure Superkb:
  • cp sample-config/superkbrc-gnome $HOME/.superkbrc
  • Edit $HOME/.superkbrc with gedit or any other text-editor:
    • Change the first line ("IMAGELIB gdkpixbuf") to "IMAGELIB imlib2"
    • You may need to set the font. Check the above, in the documentation for the FONT directive for more info.
    • Save and quit.
• Run it by typing "superkb".
• You may want to include it in your list of running programs by adding it in System > Preferences > Sessions > Startup Programs.

I have Superkb running in my Ubuntu 6.06 LTS workstation at work.

There are issues when running Superkb on Ubuntu on an IBM Thinkpad T42. The laptop doesn't include a Win key, and the key I wanted to use (Forward) sends KeyPress and KeyRelease simultaneously, whatever its AutoRepeat status is. This makes it unusable for Superkb at this moment.

Arch Linux 0.7

I have Superkb running in my Arch Linux 0.7.

Ubuntu 6.10 (Edgy Eft)

Before installing Superkb you must upgrade your X.org because of an existing bug. There are precompiled packages for i386 for Ubuntu Edgy available, so it should be just a matter of installing it using dpkg. This is what worked for me:

1. Issue dpkg -l | grep ^ii | grep -E "^ii..(xdmx-tools|xdmx|xnest|xserver-xephyr|xserver-xorg-core|xserver-xorg-dev|xvfb)". The resulting list are the packages you need to upgrade, so:
2. Download them from http://people.ubuntu.com/~seb128/xorg-server-edgy-update/.
3. Run sudo dpkg -i package-name.deb for each downloaded file.
4. Restart your X server.

Now that you have updated your Edgy X.org, follow the instructions for Ubuntu 6.06 LTS (Dapper Drake).

Fedora Core 6

Due to a bug in Xorg included in Fedora Core 6, Superkb can't run at all. This was fixed in Xorg shortly after Fedora Core 6 was released. I have no info regarding updates that fix Xorg in Fedora Core 6.

Fedora Core 5

• Prepare your Fedora Core 5 installation:
  • Open a terminal window.
  • yum install imlib2-devel xorg-x11-devel gcc
• Update libimlib2. (At the moment of writing, Fedora Core 5 doesn't include the required libimlib2, not even as an update):
  • wget http://easynews.dl.sourceforge.net/sourceforge/enlightenment/imlib2-1.2.2.tar.gz
  • tar xvzf imlib2-1.2.2.tar.gz
  • cd imlib2-1.2.2
  • ./configure --prefix=/usr && make
  • su -c "make install"
• Install Superkb:
  • Download Superkb from the Download section.
  • tar xvzf superkb-0.10-tar.gz —or— tar xvjf superkb-0.10.tar.bz2
  • cd superkb-0.10
  • su -c "make install"
• Configure Superkb:
  • cp sample-config/superkbrc-gnome $HOME/.superkbrc
  • Edit $HOME/.superkbrc with gedit or any other text-editor:
    • Change the first line ("IMAGELIB gdkpixbuf") to "IMAGELIB imlib2"
    • You may need to set the font. Check the above, in the documentation for the FONT directive for more info.
    • Save and quit.
• Run it by typing "superkb".

Debian Sid

Due to a bug in Xorg included in Debian Sid, Superkb can't run at all. This was fixed in Xorg shortly after Debian Sid was released. I have no info regarding updates that fix Xorg in Debian Sid.