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 https://github.com/alvarezp/superkb.git 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.