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.
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
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.
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:
-
If the specified application is already loaded and active, the handler should
do nothing.
-
If there is a currently active application, the handler should "hide" the
application. This involves calling the application's module_hide( )
routine.
-
If the application is not currently loaded, the handler should load it and
call its module_goTo( ) routine with the context it returned
the last time it was closed (this context should probably be stored in a
database). Note that memoryAvailable should be examined here and if
necessary RequestMemory( ) called to insure there
is enough memory.
-
The handler should then call module_show( ) on the application
being switched to.
-
If a new application has been loaded, the module variable should be stored
in a list of loaded application modules (this makes step 3 easier).
-
The code should note that the given application has been switched to, for
implementation of a LRU unloading scheme--handy in case we need to unload
older applications when memory gets low.
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.