Palm Programming: The Developer's Guide

Scenarios

Now that you have a better understanding of the code in the Hello World application, let’s take a close look at what happens as events are passed from the event queue into the event loop. Unlike our earlier example, where we hand-waved through the technical parts of what happens when a menu was chosen, we will now look with great detail at three different user actions and the flow through the code as these scenarios occur.

This first code excerpt shows what happens when a user opens the application by tapping on the application’s icon. Example 4.9 shows the flow of events. Pay particular attention to the frmLoadEvent , which is handled by ApplicationHandleEvent , and the frmOpenEvent, which is handled by MyFormHandleEvent.

Example 4-9. Flow of Control as Hello World Application Is Opened

PilotMain (enter)
  StartApplication (enter)
    FrmGotoForm(HelloWorldForm)                  open the HelloWorldForm
  StartApplication (exit)                        returns 0 (proceed)
  EventLoop (enter)
  EvtGetEvent                                    returns frmLoadEvent (formID 
                                                     HelloWorldForm)
    SysHandleEvent                               returns false
    MenuHandleEvent                              returns false
    ApplicationHandleEvent (enter)
      FrmInitForm(HelloWorldForm)                load the form
      FrmSetActiveForm(frm)                      activate the form
      FrmSetEventHandler(frm, MyFormHandleEvent) set the event handler
    ApplicationHandleEvent (exit)                returns true
  EvtGetEvent                                    returns frmOpenEvent
  SysHandleEvent                                 returns false
  MenuHandleEvent                                returns false
  ApplicationHandleEvent                         returns false
  FrmDispatchEvent (enter)                       calls form's event handler
    MyFormHandleEvent (enter)
      FrmDrawForm(FrmGetActiveForm())            draws the form and its contents
    MyFormHandleEvent (exit)                     returns true

In Example 4.10 our user taps on the button labeled “Button,” which in turn puts up an alert. Notice that eventually, the penDownEvent is transformed into a ctlSelectEvent , which is handled by our routine, MyFormHandleEvent.

Example 4-10. Flow of Control in Event Loop When “Button” Button Is Pressed

EvtGetEvent                         returns penDownEvent
SysHandleEvent                      returns false
MenuHandleEvent                     returns false
ApplicationHandleEvent                returns false
FrmDispatchEvent (enter)
  MyFormHandleEvent                 returns false
  CtlHandleEvent                    standard control-manager routine that posts 
                                       ctlEnterEvent to the event queue and returns true.
                                       a tap hits a usable control; a ctlEnterEvent is sent
FrmDispatchEvent (exit)             returns true

EvtGetEvent                         returns ctlEnterEvent
SysHandleEvent                      returns false
MenuHandleEvent                     returns false
ApplicationHandleEvent              returns false
FrmDispatchEvent (enter)
  MyFormHandleEvent                 returns false
  CtlHandleEvent                    inverts the button and waits for the pen to be lifted
                                       (EvtGetPen); when the pen is lifted, inverts
                                       the button; posts ctlSelectEvent to the event queue
                                       as the pen is lifted from the control; returns true
FrmDispatchEvent (exit)             returns true

EvtGetEvent                         returns ctlSelectEvent
SysHandleEvent                      returns false
MenuHandleEvent                     returns false
ApplicationHandleEvent              returns false
FrmDispatchEvent (enter)
  MyFormHandleEvent (enter)
    FrmAlert                        returns after the OK button has been pressed 
                                       (FrmDoAlert has its own event loop)
  MyFormHandleEvent (exit)          returns true

EvtGetEvent                         returns penUpEvent
SysHandleEvent                      returns false
MenuHandleEvent                     returns false
ApplicationHandleEvent              returns false
FrmDispatchEvent (enter)
  MyFormHandleEvent                 returns false
FrmDispatchEvent (exit)             returns false

Last, but not least, examine Example 4.11 to see what happens when the user finally chooses a menu item. The penDownEvent is transformed into a keyEvent (tapping on the hardware keys or on the soft buttons causes a keyEvent to be posted). When the user finally taps on a particular menu item, a menuEvent is posted to the event queue, which is once again handled by MyFormHandleEvent.

Example 4-11. Event Loop Handling a Menu Item

                  Tap on Menu button
EvtGetEvent                   returns penDownEvent
SysHandleEvent                tracks pen; doesn't return until pen up; returns true
  
EvtGetEvent                   returns penUpEvent
SysHandleEvent                posts keyDownEvent on the event queue and returns true
  
EvtGetEvent                   returns keyDownEvent with key: menuChr (0x105). This 
                                 is a special system key event that triggers menu
                                 code in MenuHandleEvent
SysHandleEvent                returns false
MenuHandleEvent               puts up menu bar and "First" menu and returns true

                              Tap on Second menu
EvtGetEvent                   returns penDownEvent
SysHandleEvent                returns false
MenuHandleEvent               puts up "Second" menu and returns true

EvtGetEvent                   returns penUpEvent
SysHandleEvent                returns false
MenuHandleEvent               returns false
ApplicationHandleEvent        returns false
FrmDispatchEvent (enter)      calls MyFormHandleEvent
  MyFormHandleEvent           returns false
FrmDispatchEvent (exit)       returns false

                              Tap on Beep More
EvtGetEvent                   returns penDownEvent
SysHandleEvent                returns false
MenuHandleEvent               removes menubar and menu and posts menuEvent to the 
                                 event queue and returns true

EvtGetEvent                   returns menuEvent with itemID: 1000
SysHandleEvent                returns false
MenuHandleEvent               returns false
ApplicationHandleEvent        returns false
FrmDispatchEvent (enter)      calls MyFormHandleEvent
  MyFormHandleEvent           beeps and returns true
FrmDispatchEvent (exit)       returns true

EvtGetEvent                   returns penUpEvent
SysHandleEvent                returns false
MenuHandleEvent               returns false
ApplicationHandleEvent        returns false
FrmDispatchEvent (enter)      calls MyFormHandleEvent
  MyFormHandleEvent           returns false
FrmDispatchEvent (exit)       returns false