Powerlaunch

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:

[mode-1]
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.

Interface

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 myns.glade 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'.

Namespaces

The base name of a config or glade file is a namespace. For example, powerlaunch.conf specifies a namespace of powerlaunch and foo.glade 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.

Modes

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.

Handlers

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".

Events

Keys

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:

on_init: guaranteed to be run before anything in the mode is used/called. This is not inherited like other handlers.

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.

Actions

Arguments

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:

$variables means to substitute the value of variable here.
$func{arg}: means to run a builtin function with the given argument and replace the current argument with the return value. See below for functions.
`command` means execute the given command and substitute the output. Variable expansions are processed within the backticks.

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.

Functions

$expr{...}: evaluates an expression, similar to the GNU expr tool. However, also automatically handles floating point numbers in addition to integers and strings.
$sys{var} returns the value of a system variable. Some system variables include: version, mode, lastmode.
$int{...}, $float{...}, $double{...}, $boolean{...}: changes the given string to the given type (for example, useful for dbus_call to set the correct types)

General

default_inherit [mode]: all modes inherit the handlers of this mode
eval [action]: evaluates the given string as an action
exec [program]: runs program
inherit [mode]: the current mode inherits the handlers of the given mode (see Modes section)
load [namespace]: ensures the given namespace is loaded
mode_switch [mode]: switches to the given mode
reload: reload the configuration for the program
set [variable] [value]: set the value of a variable (global scope)
unset [variable]: unsets a variable
quit: quits powerlaunch entirely (there's probably no reason to do this)

Files

$file{/path/to/file}: The entire contents of the file as a string
file_write /path/to/file contents: Sets the contents of the file

Flow control

call [handler] [arg1] [arg2] ...: runs the given handler in the context of the current mode with the given arguments. The arguments can be retrieved from the handler using $1, $2, ..., $9
confirm [text]: pop up dialog with text and ok or cancel button. On cancel, stop all further actions in the list.
define [macro] [handler]: defines a macro. For example, after running "define foo mode.handler", "foo blah" will be equivalent to "call mode.handler blah"
if [condition] [then-handler] [else-handler]: A basic conditional. If condition is "true" where true is defined as anything that is not a null string or "0", then the 'then-handler' is called. Otherwise, the else-handler (which is optional) is called.
ifeq [var] [test1] [handler1] [test2] [handler2] ... [else-handler]: Basically a switch/case statement. Compares var with test1, test2, etc., until it finds a match and runs the given handler. If nothing matches, runs the else handler (which is optional)
macro [name] [arg1] [arg2] ...: "macro foo blah" is equivalent to "foo blah" but may be helpful in cases like "macro $var"
sleep [seconds]: sleep before continuing in action list
timer_set [name] [seconds]: calls the given handler (once) in the given time. Timers are global and there can be at most one active timer for any handler at any time.
timer_cancel [name]: cancels a timer

Graphical user interface

$widget{widget_name} returns the value for widget (depends on type of the widget).
window_new [name] [normal|fullscreen|center|bottom|top|dialog|none] [title]. Creates a new top-level window of the given name. The second argument is the window type. If it's none, a hidden window that grabs all events is created. A 'normal' window will be a non-fullscreen window. "fullscreen" and "dialog" represent a fullscreen and a dialog top-level window. The other types create a window that fits its contents and is located at the specified position on the screen. Something can be inserted in the top-level window via "widget_add [name] [widget-name]". The window title is optional.
widget_add [container-name] [widget-name] [rename-new-widget]. Adds a widget (named as gladefile.name) to a container to the given container widget (specified as just the name). The new widgets created can then be referred to as container.widget and further subwidgets can be specified as container.widget.subwidget. You can also directly refer to container.subwidget, but only if subwidget is a child of the last widget added to a container. You can always use the full name. The third argument is optional and if given, the new widget is renamed to use that name. This is useful if there are name conflicts such as when adding two of the same widget to one container.
widget_set [widget] [param]: A general form for setting the value of a widget. Every widget has a default property that is set by widget_set and returned by $widget{...}.
widget_color [widget] [type1] [color1] [type2] [color2] ...: Sets colors for a widget. Valid types are 'fg', 'bg', 'base', and 'text'. Colors can be specified in any form recognized by GTK+ such as names like "red", hex specifications like #abcdef, or expressions like 'mix(0.5, "red", "blue")'.
banner [text]: display informational banner on the screen

Subsystems

Documentation in progress

DBus

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

Hal

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

GConf

You can retrieve gconf values and be notified on changes.

$gconf{...key...}
gconf_add:
gconf_set:
gconf_unset:

Variables

Some variables that have builtin meaning:

banner_icon: icon to use for banners

The following can be used to retrieve call arguments in a handler (either from a 'call' or from a dbus handler)

$1..$9: numbered argument of the current 'call' action

Default Config Files

Config

common.conf

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

switch [mode]: change modes. Calls the on_leave handler for the old mode and on_enter for the new mode.
hide: hides the launcher
show: shows the launcher

systemui.conf

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

tklock.conf

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

mpc.conf

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.conf

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

Widgets

basic.glade

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.

default.glade

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.

Links