Applets

Description

Managing applets.

Developing new 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_LAUNCHER(BTN, ICON_NAME, TEXT, HOTKEY)
	Set launcher appearance (standard color) and hotkey; Typical use: initialization. More...
#define	APP_SET_LABEL(BTN, ICON_NAME, TEXT, COLOR)    ((CButton *) (BTN))->SetLabel ((COLOR), ICON_NAME "-48", TEXT, fntAppLabel)
	Set launcher appearance; Typical use is to change color or label. More...
#define	APP_SET_HOTKEY(BTN, HOTKEY)    ((CButton *) (BTN))->SetHotkey (HOTKEY);
	Set the hotkey.

General ...
void	AppsInit ()
void	AppsDone ()
static int	Apps ()

Sending intents to applets ...
void *	AppCall (EAppId appId, int appOp, void *data=NULL)
static void	AppActivate (EAppId appId)
static void	AppEscape ()
bool	AppEnabled (EAppId appId)

Convenience callbacks for push buttons ...
void	CbAppActivate (class CButton *, bool, void *appId)
void	CbAppEscape (class CButton *, bool, void *)

Macro Definition Documentation

APP_SET_LAUNCHER

#define APP_SET_LAUNCHER	(		BTN,
			ICON_NAME,
			TEXT,
			HOTKEY
	)

Value:

            ((CButton *) (BTN))->SetLabel (COL_APP_LABEL, ICON_NAME "-48", TEXT, fntAppLabel); \
            ((CButton *) (BTN))->SetHotkey (HOTKEY);

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

Example:

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

Definition at line 164 of file apps.H.

APP_SET_LABEL

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

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 174 of file apps.H.

Enumeration Type Documentation

EAppOperation

enum EAppOperation

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.