Group

A Group allows organization of components, its child components. Its children are visually clipped to appear only within the Group's interior.

A Group also serves to cluster Choices. The user will only be able to choose one Choice child of any Group.

Group Looks

0 Plain, Transparent.
1 Drawn in Box.
2 White Background.
3 Black Background.
4 Bordered. Round corners.

Group Properties

Standard Properties: borderBottom, borderLeft, borderRight, borderTop, caption, children, class, enabled, height, left, look, numChildren, parent, proto, sizeHControl, sizeVControl, tile, tileHAlign, tileHInset, tileLayout, tileSpacing, tileVAlign, tileVInset, top, version, visible, width.

sizeHControl, sizeVControl:
Only SIZE_AS_NEEDED and SIZE_AS_SPECIFIED will be supported. SIZE_AS_NEEDED will only be partially supported: when the component becomes visible and has height or width of zero, the component will size itself to a default value.

Group Events

None.

Group Actions

None.


Keyboard

The keyboard component resides in the system module. It keeps track of which component is the "focus"--the component which should receive text that the user enters.

Because this component resides in the system module, you will use the system:keyboard syntax to access it, as in the following example:

system:keyboard.focus = PasswordEntry

An application that wishes to handle _focusChanged( ) events can create its own Keyboard component.

Keyboard Properties

Standard Properties: class, parent, proto, version.

focus component
The system focus. This is the component to which keyboard input is passed. Since many specific User Interfaces allow components to be navigated to and activated from the keyboard, these may have the focus just as well as text and entry components. Setting focus to a component within a non-modal window while a modal window is visible will silently fail.
Bringing a form, dialog or floater to the front can set the system focus to one of the window's children (or possibly itself if none of its children will accept the focus). Some components can not accept the focus, attempting to set focus to one of these components will not change focus.
focusInterest integer (0-1)
This property is useful for Keyboard components created by applications: if it is 1, then the component will raise _focusChanged( ) events when the focus changes; if it is 0, then the component won't raise events.

Keyboard Events

_focusChanged( )

_focusChanged( self AS keyboard )

This event is generated if there is a change in focus, after the internal system mechanisms have been carried out. The system:keyboard.focus property will have been updated by the time the event handler is called.

Keyboard Actions

CreateCharEvent( )

CreateCharEvent(action AS integer, char AS integer, modifierState AS integer)

Simulate a keyboard event, as if the user had entered text via the keyboard.

Pass:

action integer (0, 1,2, 5)
0: Press and Release
This action generates both a key press and release for the indicated character.
1: Press
Signify the character generated as the press of a key.
2: Repeat
Signify the character generated as being a repeated character event, as if a physical key was being held down.
5: Release
Signify the character generated as being the release of a key.
char integer
Unicode value of the character entered. Special keys have special values: KEY_BS (Backspace), KEY_DEL (Delete), KEY_ENTER, KEY_KP_RETURN (Numeric Keypad Enter), KEY_HOME, KEY_TAB, KEY_END, KEY_ESC, KEY_UP_ARROW, KEY_LEFT_ARROW, KEY_RIGHT_ARROW, KEY_DOWN_ARROW.
modifierState integer
The state of the Alt, Ctrl, and Shift keys and the state of the Caps Lock, Num Lock, and Scroll Lock modifiers. To specify which keys/modifiers are active, add together all numbers that apply from the following list:
LEFT_ALT - &H0080
RIGHT_ALT - &H0040
LEFT_CTRL - &H0020
RIGHT_CTRL - &H0010
LEFT_SHIFT - &H0008
RIGHT_SHIFT - &H0004
CAPS_LOCK - &H0400
NUM_LOCK - &H0200
SCROLL_LOCK - &H0100

CreateCharEventString( )

CreateCharEventString( newText AS string )

This action generates one or more "character events," as if the user had pressed keys on the keyboard.

Pass:

newText string
Text representing the character events. For example, the string "pi/2" would result in the same behavior as if the user had typed p, i, /, 2.
The plus sign, caret, percent, curly brace, and parenthesis characters are used to represent modifier keys and special keys. To include these characters in your string, enclose them in curly braces: {+} {^} {%} {(} {)} {{} {}}.
To specify a key with one or more modifier keys, precede the regular key string with one or more of the characters: + Shift ^ Ctrl % Alt
For example, to simulate a Ctrl-Shift-Q, use the string "+^q." To simulate the modifier keys being held down while other keys are pressed, enclose the string for the other keys in parentheses. For instance, to simulate holding down the Shift key while pressing the I, B, and M keys, use the string "+(ibm)." Inside parentheses, all of these special characters `+', `^', `%', `(` lose their special meaning--the only special characters recognized are `{`, `}', and `)'. This means that you can not do nested parentheses or change the modifier keys while inside parentheses. So "+(Hi ^there)" will be treated as "+(Hi {^}there)," and "+(Hi (there))" will be treated as "+(Hi {(}there){)}."
The following strings represent special keys:
{BACKSPACE}, {BS}, {BKSP} Backspace
{BREAK} Break
{CAPSLOCK} Caps Lock
{CLEAR} Clear
{DELETE} {DEL} Delete
{DOWN} Down Arrow
{END} End
{ENTER} ~ Enter
{ESCAPE} {ESC} Esc
{F1}, {F2}, {F3}, {F4}, {F5}, {F6}, F1, F2, F3, F4, F5, F6, F7, F8, F9, F10, F11, F12, {F7}, {F8}, {F9}, {F10}, {F11}, {F12}
{HELP} Help
{HOME} Home
{INSERT} Ins
{LEFT} Left Arrow
{NUMLOCK} Num Lock
{PGDN} Page Down
{PGUP} Page Up
{PRTSC} Print Screen
{RIGHT} Right Arrow
{SCROLLLOCK} Scroll Lock
{TAB} Tab
{UP} Up Arrow


Label

A Label displays a single-line text string. The text appears in the system font, and may not be edited by the user.

Label Looks

The following look is available:

0 Default Label
A plain label.

Label Properties

Standard Properties: caption, class, enabled, height, left, look, parent, proto, sizeHControl, sizeVControl, top, version, visible, width.

sizeHControl, sizeVControl:
Only SIZE_AS_NEEDED and SIZE_AS_SPECIFIED are supported.

Label Events

None.

Label Actions

None.


Launcher

This component keeps track of information useful when launching applications: it keeps track of how much memory is available and how well sleeping applications fit into that memory. This component resides in the system module. Thus, to interact with it, your program will probably use a syntax like that in the following example:

system:launcher!RequestMemory( 2 ) REM We'll need another 2K soon

Applications which will handle Launcher events can create their own Launcher components.

Launcher Properties

Standard Properties: class, parent, proto, version.

memoryAvailable integer
This read-only property reflects the estimated amount of free heap memory available for loading applications. The value decreases when applications are loaded, and increases when they are unloaded.
When this value becomes negative _memoryDemand( ) events will be raised, which cause the system to attempt to unload sleeping applications. This should get memoryAvailable back above zero. The memoryAvailable value is typically less than the actual amount of free memory, as the system needs to keep a certain amount in reserve to allow for fragmentation and sudden rushes in memory use before protection mechanisms can react.
memoryReserve integer
This read-only property holds the amount of memory to subtract from the true number of free kilobytes when calculating memoryAvailable. Designed to insure that there is always some memory around when memoryAvailable becomes negative. Specifically, this value has to be large enough such that if memoryAvailable is sitting at 0, and a large allocation occurs, there will be enough memory left to unload applications before we actually run out of memory.

Launcher Events

_hardIconPressed( )

_hardIconPressed( self AS launcher, icon AS integer )

This event is generated when the user presses one of the device's "hard icons." Typically, an application's Launcher won't do anything at this point, but will instead allow the system Launcher to do its thing.

Pass:

self launcher
The component experiencing the event
icon integer (range is device-specific)
Which icon was tapped.

_hide( )

_hide( self AS launcher, application AS string )

The launcher should respond to this event by hiding the named application. This normally means calling that application's module_hide( ) routine, and the module_show( ) routine of some other application.

Pass:

self launcher
The component experiencing the event.
application string
The application to hide.

_memoryDemand( )

_memoryDemand( self AS launcher, memoryDemanded AS integer )

This event is generated whenever memoryAvailable becomes negative--however, if there is more than one Launcher component active on the device when this happens, not all of them will necessarily detect this event. The youngest Launcher will first have a chance to handle the event--if it can free up enough memory such that memoryAvailable goes positive, then other launchers will never generate the event. If it can't free up enough memory, the next youngest Launcher will generate the event, and get its chance to free up memory. Finally, if no other Launcher can free up enough memory, the system Launcher will unload some applications.

When this event is generated, any flushable applications in the cache should already have been flushed by the _memoryRequest( ) handler in the system module.

Chances are, there is an application that is using too much memory; it should now be unloaded (with apology) to the user. The next possibility is that too many apps are attempting to keep from being unloaded by setting preventUnload to non-zero. These should be unloaded at this time, because the system is very low on memory.

Pass:

self launcher
The component experiencing the event.
memoryDemanded integer(0-32767)
The amount of memory, in kilobytes, demanded.

_memoryRequest( )

_memoryRequest( self AS launcher, memoryNeeded AS integer )

This event is generated whenever a RequestMemory( ) action is invoked that requests more memory than is available. If possible, sufficient memory to honor the request should be freed up in this handler.

Applications or modules that can reduce the amount of memory they are using can have their own Launcher component, and handle this event by reducing their memory usage. Otherwise, the system Launcher component may unload some applications that are currently loaded but not in use.

If there is more than one Launcher component, the memoryRequest event will be generated for as many of them as it takes to free up the requested memory. The components will generate the events in order from youngest to oldest. The system module's Launcher component will get the event last, after any loaded applications free as much memory as they can.

Pass:

self launcher
The component experiencing the event.
memoryDemanded integer (0-32767)
The amount of memory demanded, measured in kilobytes.

_outOfMemory( )

_outOfMemory( self AS launcher )

This event is generated if the system is in dire trouble. If an application has demanded memory, and no Launcher has been able to free up enough memory, this event is generated. The system has severe memory problems, perhaps severe fragmentation or a memory leak.

After all applications' Launchers have had their chance to handle this event, the system Launcher module will apologize to the user and reboot.

Pass:

self Launcher
The component experiencing the event.

_setContext( )

_setContext( self AS launcher, application AS string, context AS string  )

This event is generated when the Launcher tries to "go to" a specific context within a specific application. The application should be brought to the front if running, loaded if it's not running. The typical handler for this event will do what the handler for the _switchTo( ) event does, except that it will pass the supplied context string to the application's module_goTo( ) routine.

Pass:

self launcher
The component experiencing the event.
application string
A module locator string for the governing module of an application, like those passed to LoadModule( ).
context string
Context as passed to the module_goTo( ) routine of the application module. The null string ("") may be passed to invoke the application in its initialized state.

_switchTo( )

_switchTo( self AS launcher, application AS string )

This event is generated when this Launcher wants to switch to an application, as the result of the SwitchTo( ) action. A handler for this action will normally proceed as follows:

Pass:

self launcher
The component experiencing the event.
application string
A string describing the location of the module to switch to--as you might pass to LoadModule( ).

Launcher Actions

Hide( )

Hide( application AS string )

Use this action to hide an application and to show another application.

Pass:

application string
The application to hide.

RequestMemory( )

RequestMemory( memoryRequested AS integer ) AS integer

Requests that the system free memory for upcoming use. This action, intelligently used, can minimize user-perceived delays.

This function is good to call from strategic points in an application where the application knows it will need more memory soon and the user is likely to tolerate a delay.

If sufficient memory was not freed, then the action will return zero.

SetContext( )

SetContext( application AS string, context AS string )

Use this action to go to a particular context within a specified application.

If you're using your own Launcher component, this action will generate a _setContext( ) event.

SwitchTo( )

SwitchTo( application AS string ) AS string

Use this action to switch to an application: to load the application if it's not already loaded, and to bring it to the front.

If you're using your own Launcher component instead of the system's Launcher, invoking this event generates a SwitchTo( ) action.