Powerlaunch is a general event handler system that is entirely controlled by config files. The code knows nothing about the Maemo platform. Only the default set of config files tells powerlaunch how to act like systemui.

The default config directories are first $HOME/.powerlaunch (/home/user/.powerlaunch by default) followed by /etc/powerlaunch. Config files are named with a .conf extension and glade interface files have a .glade extension. The default main config file is powerlaunch.conf.

Note this documentation is not close to complete.

Config file

The format of a config file is similar to the standard .ini config file format with sections and key/value pairs. Sections represent modes. Within each mode, there are key/value pairs that represent event handlers and actions. Actions are separated by semicolons. For example, the following:
key_down = banner hello; switch mode-2
says that when in mode "mode-1" if the key_down event is received (when the down key is pressed), run the list of actions given which include displaying a banner and switching the mode. Lines that begin with a space are considered to be a continuation of the previous line.


You can edit the interface by using Glade and specifying the particular widget layout you want in the config file.

The top-level window will not be used by powerlaunch but glade requires a top-level window. So to create a new layout, add a window as a pseudo-container, and add your desired layout as a child of this window. For example, you can add a vertical box called "mylayout" as the top child of a window. Then you can use "window_new my_win_name dialog mylayout" as an action in the config file to load it into a dialog window. See the existing glade files for examples that you can edit and change.

Widgets are specified in the glade file. The names of widgets are also of the form namespace.widget-name. For example, the action "window_new win fullscreen myns.coollayout" will look for the file and find a widget named coollayout. The topmost window is referred to as 'win' and so the entire name of a widget can be specified as 'win.widget.subwidget'.


The base name of a config or glade file is a namespace. For example, powerlaunch.conf specifies a namespace of powerlaunch and is in the namespace of foo. When the program needs to find the config file for a namespace, it first looks in the user's directory followed by the system-wide directory. Thus, if you wish to override the config file for any namespace, simply create you own file of the same name in the ~/.powerlaunch/ directory. All mode and widget names are local to a namespace so you can have multiple modes called 'main' if they are in different namespaces. Namespace files are automatically loaded as they are needed. For example, if the action "call myns.mymode.myhandler" is seen, the namespace "myns" is loaded (i.e. myns.conf is looked for in ~/.powerlaunch/ or /etc/powerlaunch/), and the handler called myhandler in mode mymode is called.


At any given time, powerlaunch is in one mode. The default initial mode is "powerlaunch.main". The initial mode can be changed from the command line when launching powerlaunch with the '-m' option.

Mode names are case-sensitive and should use only the following safe characters (a-zA-Z0-9_-). Other characters probably will work also but you shouldn't rely on it. Modes can be either fully qualified with namespace, such as 'powerlaunch.main', or relative like 'main' in which case it refers to the namespace of the mode you are currently in.

Modes contains a list of handlers. In addition, modes can have an arbitrary number of parent modes (inheritance tree). When a handler is called, it is first looked for in the given mode and if it's not found, the parent modes are used one at a time until it is handled. The more recently modes added via the 'inherit' action have higher priority over previously inherited modes.

A special mode called "main" in each namespace is guaranteed to be initialized (i.e. the on_init handler is called) upon loading of the namespace file.


Handler names are case-sensitive and should use only the following safe characters (a-zA-Z0-9_-). Other characters probably will work also but you shouldn't rely on it. Arbitrary handler names can be called via the 'call' action so you can use handlers as macros or function calls if you wish.

Like modes, handlers can be either fully qualified or not. For example, the full name of a handler is represented as "namespace.mode.handler".



One type of event are key presses, whether it be device keys or other keys from an attached keyboard. Keys are specified by their keyvals and call two handlers on key press and release, e.g. key_press_ff1b or key_release_ff1b.

In common.conf, symbolic names are defined so you can more typically just use: key_power, key_up, key_down, key_left, key_right, key_select, key_fullscreen, key_menu, key_home, key_plus, key_minus, key_escape.

Program Events

The program generates certain events that can be handled. These include:

Widget Events

When buttons are clicked, a handler is called in the context of the current mode using the name of the button. For example, if a button is named "key_up" (as seen from glade), then when that button is pressed, it should act equivalently to pressing the up hardware key.



All argument strings for actions are treated as follows. Arguments are separated by spaces. Strings with spaces should be quoted e.g. "this is a string". In addition to literal strings, the following are interpreted specially: The standard backslash-escaping is understood within quotes, braces, and backticks.

For example, "set foo $bar" means assign foo the value of the bar variable and "widget_set label_foo `date +'%Y/%m/%d %H:%M'`" means format the current date and time and set it as the text of label foo.

Note that for the actions that take a time in seconds (i.e. sleep and timer_set), you can get down to milliseconds resolution by specifying a decimal, e.g. 1.5.




Flow control

Graphical user interface


Documentation in progress


If the program receives any dbus method calls, an event handler is looked for that matches the method name.


You can retrieve properties from Hal devices and be notified on changes. Run lshal to see all devices and properties.


You can retrieve gconf values and be notified on changes.


Some variables that have builtin meaning: The following can be used to retrieve call arguments in a handler (either from a 'call' or from a dbus handler)

Default Config Files



This file contains common handlers/modes designed to be used as macros and the base for other modes. These macros are defined:


This file tries to duplicate the default systemui interface as closely as possible:


This file implements a touchscreen/keypad lock similar to the default lock found with systemui. Run 'switch tklock.main' to lock the device.


This file implements a mode for controlling mpd (music player daemon) via mpc. This includes a pocket mode where the screen is locked but some keys are enabled for controlling music while the device is in the pocket.


N810 specific config (e.g. hardware lock button).


This file simply contains single widgets and is designed to be used in building up more complex layouts. For example, basic.label is a single label. Other possibly useful widgets are: hbox, vbox, button, image, calendar.

This contains the keyimages layout which contains images for each of the keys and is laid out as the keys are found on the N800.