Alarm

The Alarm provides a mechanism which notifies a user when a specified time and date have arrived. Once the Alarm has been set, the alarm notification will be received at the specified time and date even if the Alarm component's module is not currently loaded. On some devices, the alarm may even cause the device to power up if it is off when the specified date and time occur.

If the Alarm is enabled when the program's module is unloaded or the device shuts down, then the module's module_goTo( ) routine will be called when the Alarm triggers. If the Alarm is not enabled when the program's module is unloaded or the device shuts down, then the Alarm will forget its alarm date and alarm time; the value of all its properties will be lost.

Applications should use Alarms sparingly. A Calendar program, for example, might have only one Alarm component, and have that set to the closest even for which the user desires an alarm. When that event occurs, the Alarm could be set to the next event the user needs to be notified about.

Alarm Properties

Standard Properties: class, enabled, parent, version

enabled:
Set this property to one to turn on the alarm; set it to zero to turn it off.
parent:
The only valid parent is the null component, also known as "app."
moduleContext string
If the Alarm's module is loaded as a result of the alarm, this value will be passed as the context argument to the module_goTo( ) routine.
uniqueID string
This string uniquely identifies the Alarm, differentiating it from any other Alarm components which may be on the device at the time. To make your Alarm's name unique, you might want to name it after your company and application name--For example, "Sanrio Keroppi's Day Hopper." This property must be set to something other than its default for the alarm to be useful. Changing the value of this property causes the Alarm to forget its alarm time and alarm date.

Alarm Events

The alarm has no event. When the alarm triggers, the application's module_goTo( ) routine is called with value of the Alarm's moduleContext property passed as the context argument to module_goTo( ). The Alarm's enabled property becomes zero when this happens.

Alarm Actions

GetAlarmDate( )

GetAlarmDate( ) AS STRUCT Date

Get date of alarm. The date is returned in a Date structure:

STRUCT Date
year AS integer
month AS integer
day AS integer
END STRUCT

Make sure that you've set the uniqueID property to a non-empty string before invoking this action; otherwise, an error will result.

GetAlarmTime( )

GetAlarmTime( ) AS STRUCT TimeOfDay

Get time of alarm. The time is represented as a TimeOfDay structure:

STRUCT TimeOfDay
hour AS integer
minute AS integer
second AS integer
END STRUCT

Make sure that you've set the uniqueID property to a non-empty string before invoking this action; otherwise, an error will result.

SetAlarmDate( )

SetAlarmDate(date AS STRUCT Date)

Set date of alarm.

Make sure that you've set the uniqueID property to a non-empty string before invoking this action; otherwise, an error will result.

SetAlarmTime( )

SetAlarmTime(time AS STRUCT TimeOfDay)

Set time of alarm.

Make sure that you've set the uniqueID property to a non-empty string before invoking this action; otherwise, an error will result.


Busy

A component of this type resides in the system module. It is used to mark the system "busy." While busy, the system will accept no user input.

To make the system "busy" for a few seconds while completing some intense computation, most applications will use code like the following:

system:busy!Enter( )
...intense computation...
system:busy!Leave( )

Applications may create and use their own Busy components.

Busy Properties

Standard Properties: class, parent, proto, version.

busyCount integer (0-32767)
This read-only property is the current "busy" count. If it is greater than zero, the system is busy and will ignore user input. This count increments each time !Enter( ) is invoked, and decrements each time !Leave( ) is invoked.
busyTotal integer (0-32767)
This read-only property is the sum of all the device's Busy components' busyCount properties. If it is greater than zero, the system is busy and will ignore user input.

Busy Events

_busyTotalChanged( )

_busyTotalChanged( self AS busy )

Called whenever busyTotal becomes zero or non-zero, indicating that the busy status needs to be changed. Used by the System Module to know when to display busy status.

Pass:

self busy
The component experiencing the event.

Busy Actions

Enter( )

Enter( )

This property marks the system as "busy": the system will accept no user input, and may put up some busy indicator, such as an hourglass or wristwatch icon.

If your program is about to carry out some intense computation that will slow down the device for 1 - 4 seconds, warn the user by marking the system busy (and marking the system not busy when done).

REM We're beginning a time-intensive operation, so mark system busy.
system:busy.Enter( )

ComputeAllTotals( )
UpdateAllNumbers( )

REM We're done with the time-intensive operation, so mark system not busy.
system:busy.Leave( )

If you will be slowing down the system for more than four seconds, consider providing feedback to the user so they will know the system hasn't crashed. You might want to give the user some idea of what percent of the task has been completed. You may not want to mark the system busy in these cases: instead, you might want to provide a way for the user to cancel the operation.

The user would have no way to access this if the system has been marked busy.

Leave( )

Leave( )

Undo the effects of a previous invocation of the Enter( ) action.


Button

A Button is a simple component which generates an event when pressed.

Button Looks

The following looks are available:

Button Properties

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

height, width:
There is a bug: A Button which is the child of a Table component may appear very small.
sizeHControl, sizeVControl:
only SIZE_AS_NEEDED and SIZE_AS_SPECIFIED values are supported.
cancel integer (0-1)
Set this property to 1 to mark this button as the Cancel button for a dialog. If the user presses the Esc key, this button will generate a _pressed( ) event. Note that this property does not cause the dialog to actually close when the button is tapped or the Esc key is pressed. For that, use the closeDialog integer.
closeDialog integer (0-1)
If this property is set to one, then pressing this button will result in the closing of any dialog box that the button is in. (The dialog box's visible property will be set to zero.) The dialog box will close after the button's _pressed( ) event handler, if any, executes.
default integer (0-1)
If this Button is in a dialog box and its default property is 1, then it will be the default action for that dialog. Setting a button's default value will not take effect until the next time the button goes from being invisible to being visible (i.e., its visible property changes from zero to one).
destructive integer (0-1)
If this Button destroys (i.e., irrevocably changes) data, set this property to one. This ensures that this Button will never be a dialog's default Button.

Button Events

_pressed( )

_pressed( self AS button )

This event is generated when the user clicks the Button.

Pass:

self button
The Button handling the event.

Button Actions

None


Choice

The Choice provides an exclusive choice. If a component has more than one Choice children, at most one may be selected. Note that the List also provides a mechanism for presenting the user with an exclusive choice.

Choice Looks

The following looks are available:

Choice Properties

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

enabled:
In general, user input cannot change a disabled component; there is an exception for Choices: If the user selects another Choice with the same parent, then the disabled choice's status will change from 1 to 0.
sizeHControl, sizeVControl:
only SIZE_AS_NEEDED and SIZE_AS_SPECIFIED behavior is supported.
choice component
This read-only property keeps track of the selected Choice within this Choice's group. If no Choice is selected, this property will be the null component.
status integer (0-1)
Flag indicating whether the Choice is currently selected.

Choice Events

_changed( )

_changed( self AS choice )

This event is generated when the user

The de-selected Choice generates its event before the selected one.

Choice Actions

None.


Clipboard

A Clipboard component monitors the system clipboard. It is used to implement "Edit" menu functionality. There is a clipboard component in the system module. Most applications that need custom Edit menu behavior will interact with this component. For example, to determine whether the current clipboard can be pasted as a string, one would use the following code:

IF system:clipboard!QueryItem("string") THEN
...
END IF

Applications may have their own Clipboard components, useful if you wish to handle its events.

Clipboard Properties

Standard Properties: class, parent, proto, version

activeSelection component
This read-only property keeps track of the component which has the active selection: the component which most recently gained the exclusive focus (its focusState property became 2) while its clipboardable property was set. If no component is the active selection, then this property will be the null component: you may test for this condition with the IsNullComponent( ) function.
copyable integer (0-1)
The copyable property is read-only, and specifies whether the current active selection is a possible candidate for being copied to the clipboard.
deletable integer (0-1)
The deletable property is read-only, and specifies whether the current active selection could be deleted.
pastable integer (0-1)
The pastable property is read-only, and specifies whether the active selection could accept the current contents of the clipboard.

Clipboard Events

_clipboardChanged( )

_clipboardChanged( self AS clipboard )

This event is called whenever the current clipboard item changes.

_selectionChanged( )

_selectionChanged( self AS clipboard )

This event is called whenever the current selection changes.

Clipboard Actions

Copy( )

Copy( )

Tells the component with the active selection to "copy" its selection to the clipboard.

Pass:

Nothing.

Cut( )

Cut( )

Tells the component with the active selection to "cut" its selection--actually a "copy" followed by a "delete."

Pass:

Nothing.

Delete( )

Delete( )

Tells the component with the active selection to delete the selected data.

Pass:

Nothing.

GetItem( )

GetItem( format AS string ) AS ...

This action returns the specified format if it is currently available on the clipboard.

Pass:

format string
The data type of interest. Possibilities include: "array," "fax," "float," "graphic," "integer," "long," "sound," "spreadsheet," and "string."

Paste( )

Paste( )

Tells the component with the active selection to paste the clipboard data to the selection.

Pass:

Nothing.

QueryItem( )

QueryItem( format AS string ) AS integer

This action determines whether the specified format is currently available on the clipboard without actually returning the item.

Pass:

format string
The data type of interest. Possibilities include: "array," "fax," "float," "graphic," "integer," "long," "sound," "spreadsheet," and "string."

SetItem( )

SetItem( item )

This action sets the current clipboard item to the passed item, in the format implied by the variant type.

Pass:

item
The data to be registered as the current clipboard item. Supported data types include: array, fax, float, graphic, integer, long, sound, spreadsheet, and string.


Clipper

The Clipper is a simple view window. It clips drawing of its children to its bounds. The Clipper is a "primitive" component type: it doesn't do much, but if you're working on a heavily customized UI, you'll probably find it useful.

Clipper Properties

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

borderBottom, borderLeft, borderRight, borderTop:
As clippers have no borders, these properties will all have value zero.
sizeHControl, sizeVControl:
Only SIZE_AS_NEEDED and SIZE_AS_SPECIFIED are supported. SIZE_AS_NEEDED is partially supported: when the component becomes visible and their height or width is zero, the component will size itself to a default value.

Clipper Events

None.

Clipper Actions

None.