Description

Managing applets.

A new applet - say "Foobar" is integrated as follows.

Add a new entry to apps_config.H:
#if WITH_FOOBAR == 1

APP(Foobar, "foobar")

#endif
Implement your applet in a file named app_foobar.C. If the codes requires multiple files, name the lower-level files like app_foobar_mysubmodule.C.
The file app_foobar.C must contain the main applet function named AppFoobarFunc() (see FAppFunc) which implements all mandantory (= non-optional) operations from EAppOperation.
Adapt the Makefile accordingly to support the WITH_FOOBAR setting and include all necessary .C files.

Collaboration diagram for Applets:

Macros
#define	APP_INIT_OK ((void *) 1)
	Return value for 'appOpInit': Initialization was successful.

#define	APP_INIT_FAIL NULL
	Return value for 'appOpInit': Initialization failed.

Typedefs
typedef void *	FAppFunc(int appOp, void *data)
	Prototype for applet entry functions. Example: `void AppPhoneFunc (int appOp, void data)`

Enumerations
enum	EAppOperation { appOpInit = 0 , appOpDone , appOpLabel , appOpActivate , appOpLongPush , appOpUser = 0x80 }
	Applet operations. More...

Helpers for launch buttons ...
TTF_Font *	fntAppLabel
	Default font for launch buttons (read-only!).

#define	COL_APP_LABEL ToColor (0x60, 0x60, 0x60)
	Normal launcher labels.

#define	COL_APP_LABEL_LIVE WHITE
	App is active, and the user must be aware of that.

#define	COL_APP_LABEL_BUSY LIGHT_RED
	App is busy with something.

#define	COL_APP_LABEL_ALARM ToColor (0xff, 0x40, 0x40)
	Something very urgant/important is with the app.

#define	APP_SET_LABEL(BTN, ICON_NAME, TEXT, COLOR) ((CButton *) (BTN))->SetLabel ((COLOR), ICON_NAME "-48", TEXT, fntAppLabel)
	Set launcher appearance (standard color) and hotkey; Typical use: initialization.

#define	APP_SET_HOTKEY(BTN, HOTKEY) ((CButton *) (BTN))->SetHotkey (HOTKEY);
	Set launcher appearance; Typical use is to change color or label.

Macro Definition Documentation

#define APP_SET_LABEL	(	BTN,
		ICON_NAME,
		TEXT,
		COLOR
	)	((CButton *) (BTN))->SetLabel ((COLOR), ICON_NAME "-48", TEXT, fntAppLabel)

Set launcher appearance (standard color) and hotkey; Typical use: initialization.

<

Example:

APP_SET_LAUNCHER(data, "ic_foobar", "FooBar", SDLK_f);

Definition at line 162 of file apps.H.

#define APP_SET_HOTKEY	(	BTN,
		HOTKEY
	)	((CButton *) (BTN))->SetHotkey (HOTKEY);

Set launcher appearance; Typical use is to change color or label.

<

Example:

APP_SET_LAUNCHER(data, "ic_foobar", "FooBar", COL_APP_LIVE);

Definition at line 170 of file apps.H.

Applet operations.

Enumerator
appOpInit	Initialize applet. Argument: (none) Return: APP_INIT_OK \| APP_INIT_FAIL If APP_INIT_FAIL is returned, no other operations will be called again.
appOpDone	Shutdown applet; Called on shutdown (not for disabled apps).
appOpLabel	Set the launcher label. Argument: CButton launchButton = (CButton ) data; Return: return NULL; Set the 'launchButton' label using its 'CButton::SetLabel' methods. The app may store the latest passed button object and later change the label arbitrarily. The label must be transparent be colored according to the COL_APP_LABEL_ color scheme. 'launchButton' may be NULL, indicating that not button changes can be performed.
appOpActivate	Activate the main screen (no arguments, return value ignored).
appOpLongPush	A long push on the launcher button has been exercised (optional). Note: The applet has not been activated yet and will not be activated automatically.
appOpUser	First user-defined operation.

Definition at line 94 of file apps.H.