The State Table

An app is generally run through events passed in to it. These events are controlled by a series of state tables which indicate which events are to put the app into what state and how long to process that app for. A state table consists of a single byte followed by a series of three byte entries with a EVENT_END terminator byte after the last entry. Each entry has three parts to it:

1. The event code which indicates what event is to be accepted by this state table
2. The timer indicator to indicate how long to wait before firing off a timer if no other event occurs before it.  The values can be found in the table below
3. The new state to enter when this event is encountered

The initial byte is the state to enter if an event is encountered which does not match any entry in the table.

Special State Tables

State table 0 is always entered first for an app. It will almost always have an EVT_ENTER entry in it so that you can know when an application is first called.

If an app supports nesting (all WristApps might), then it will be entered by a call to State Table 1 with an EVT_NEST event. All other state tables are completely defined by the application and may be used in any way that you want. Often a separate state is used for each mode that the app might have (such as a set mode). In order to switch between states, either you code the new state with the event, such as with the EVT_SET operation OR you can post a user event which has an associated entry in the state table that has the new state for that event.

There are two special state values associated with an event. $FF is used to indicate that the app wishes to exit and go to the next app. For WristApps, this means go back to the time app. $FE is a special value used to handle returning from a EVT_NEST nesting. If all of the nested app processing occurs in state 1, then this value would appear for an entry in the state1 table. For all others, it is assumed to be the new state table to select. No error checking is done on any of these values.

One very nice thing that can be done with the events is posting a timer to go off if no other event occurs after the current event. There are two timers although only one can be active at a time. The reason for this is to allow the app to quickly distinguish between which event timed out without having to save some global variable. These timer values are fixed in the ROM and you select which timer interval you want through the value you set. For a strange happenstance, all of the intervals of the second timer are also available for the first time (but I would be careful not to count on that).

Nested Apps

One important event that an application should handle is the EVT_RESUME which occurs after a nested app terminates. This allows your application to pick up after an alarm or appointment has gone off. When you get this event, it is a pretty good idea to refresh the display since you don't know what state the other app left it in. You should also use this time to restore any system flags that you may have set. You should also be aware that before your app is suspended, the system will call your suspend function at WRIST_SUSPEND ($0113). That will be your chance to save any variables that you expect to have trashed.

Button Events

For the events, there are three forms of the button events. The EVT_NEXT, EVT_MODE, EVT_SET, EVT_PREV, and EVT_GLOW events allow you to see when the corresponding button is pressed. When you get one of these events, you will not get notification of when the button was released. There is a set of events EVT_DNNEXT, EVT_DNMODE, EVT_DNSET, EVT_DNPREV and EVT_DNGLOW which give you the down transition for those buttons and the corresponding set of events EVT_UPNEXT, EVT_UPMODE, EVT_UPSET (I like that name), EVT_UPPREV, and EVT_UPGLOW which tell you when the button has been released. It is the case that the UP event can be handled by a different state than the DN event.

If you want to get any of those buttons, you can look for EVT_ANY (and EVT_DNANY, EVT_UPANY) which will call when any of the 5 buttons have been pressed. In order to figure out which button was pressed, your code will need to look at BTN_PRESSED ($04c3) which will contain one of the EVT_NEXT, EVT_MODE, EVT_SET, EVT_PREV, and EVT_GLOW values. Often an application does not have an interest in the Indiglo button but cares about the other 4 buttons. For this, you can use EVT_ANY4 (and EVT_DNANY4, EVT_UPANY4) just the same way as the EVT_ANY events.

Timer Events

The EVT_TIMER1 and EVT_TIMER2 events come in when the timer associated with a particular event has elapsed without another event being posted. There is no requirement of using a particular timer for a given event other than to allow you to distinguish between which event occurred. The two timers have slightly different values for when they go off and that might slightly affect your choice of timers (but that is rare).  From experimentation, it appears that the time cycle for the TIMER1 is a bit slower than that for Timer2.  I recommend that you use Timer2 for any of the fast actions and timer1 for the slower ones (like timing out the display).

Other Events

The EVT_USER0, EVT_USER1, EVT_USER2, and EVT_USER3 events are for an application to use for anything it wants to. Most of the time, these are useful for transitioning to a different state. You can post an event by calling POSTEVENT.

The only other event is EVT_IDLE. This event is sent only to the TIME app when another app has been suspended because it was idle for more than three minutes.  Since a wristapp could never get this event, it is probably worth ignoring.

Event Constants

Here are the constants which you would find useful in creating your app:

State Table Values

EVT_NEXT	$00	Next button pressed (not interested in the up transition)
EVT_MODE	$01	Mode button pressed (not interested in the up transition)
EVT_SET	$02	Set/Delete button pressed (not interested in the up transition)
EVT_PREV	$03	Prev button pressed (not interested in the up transition)
EVT_GLOW	$04	Indiglo button pressed (not interested in the up transition)
EVT_ANY	$05	Any button pressed (not interested in the up transition)
EVT_ANY4	$06	Any button pressed except Indiglo (not interested in the up transition)
EVT_IDLE	$19	This is only sent to the TIME app when another app has been idle for more than three minutes
EVT_RESUME	$1a	Called when resuming from a nested app
EVT_ENTER	$1b	Initial state.
EVT_NEST	$1c	The state table 1 entry called when a nested application is called. It is the equivalent of EVT_ENTER for an interrupt. This only occurs for WristApps, Timer, and appt apps.
EVT_END	$1d	End of event table indicator
EVT_TIMER1	$1e	Timer event - This is fired for the TIM1_ values
EVT_TIMER2	$1f	Timer event - This is fired for the TIM2_ values
	$20-$36	UNUSED (I bet that you can have user specified events for these too)
EVT_USER0	$37	User specified events. Queued by calling POSTEVENT
EVT_USER1	$38	User specified events. Queued by calling POSTEVENT
EVT_USER2	$39	User specified events. Queued by calling POSTEVENT
EVT_USER3	$3a	User specified events. Queued by calling POSTEVENT
	$3b-$7f	UNUSED
EVT_DNNEXT	$80	Next button pressed
EVT_DNMODE	$81	Mode button pressed
EVT_DNSET	$82	Set/Delete button pressed
EVT_DNPREV	$83	Prev button pressed
EVT_DNGLOW	$84	Indiglo button pressed
EVT_DNANY	$85	Any of the four buttons Pressed
EVT_DNANY4	$86	Any button pressed except Indiglo
	$87-$9F	UNUSED
EVT_UPNEXT	$A0	Next button released
EVT_UPMODE	$A1	Mode button released
EVT_UPSET	$A2	Set/Delete button released
EVT_UPPREV	$A3	Prev button released
EVT_UPGLOW	$A4	Indiglo button released
EVT_UPANY	$A5	Any of the four buttons Released
EVT_UPANY4	$A6	Any button Released except Indiglo

Timer Constants

TIM_ONCE	$ff	No time interval. Operation is executed just once
TIM1_TIC	$00
TIM1_2TIC	$01
TIM1_3TIC	$02
TIM1_4TIC	$03
TIM1_HALFSEC	$04
TIM1_SECOND	$05
TIM1_SECHALF	$06
TIM1_TWOSEC	$07
TIM1_TWOSEC1	$08
TIM1_12SEC	$09
TIM1_18SEC	$0a
TIM2_TIC	$80	This is the typical scroll interval
TIM2_2TIC	$81
TIM2_4TIC	$82
TIM2_8TIC	$83	This is the normal blink interval
TIM2_12TIC	$84	Just over a second
TIM2_16TIC	$85	A second and a half
TIM2_24TIC	$86	Two and a half seconds
TIM2_32TIC	$87	Just over three seconds
TIM2_40TIC	$88	Four seconds
TIM2_48TIC	$89	Almost five seconds
TIM2_96TIC	$8a	Almost ten seconds

Note that the second part of this table is happen-stance since it is really a rollover of the second table on top of the first one. But it might be useful to someone...

TIM1_TICA	$0b	This is the typical scroll interval
TIM1_2TICA	$0c
TIM1_4TICA	$0d
TIM1_8TIC	$0e	This is the normal blink interval
TIM1_12TIC	$0f	Just over a second
TIM1_16TIC	$10	A second and a half
TIM1_24TIC	$11	Two and a half seconds
TIM1_32TIC	$12	Just over three seconds
TIM1_40TIC	$13	Four seconds
TIM1_48TIC	$14	Almost five seconds
TIM1_96TIC	$15	Almost ten seconds