Events, and the program's work, progresses in this manner until an event tells the program it should exit. This "stop event" tells the event loop to stop; the program does its exit processing, and returns to Palm OS.

Peeking behind the curtain - the source code
Looking at Listing A (see http://www.component-net.com/pp-extras/helloworld2.html), we see HELLO.PRC consists of six functions. Let's review each function. I'll take them roughly in the order they run.

Function 1: PilotMain()
We begin at PilotMain(). In most applications, this is the first function where the program gains control; the function called by Palm OS. Ours simply checks the "launch code" (more on that in a moment), calls the start-up routine, and enters the event loop. When the event loop returns (after the "stop event") PilotMain() calls the exit routine and returns to Palm OS.

Function 2: StartApplication()
StartApplication() does the program's setup and initialization. Many applications do more start-time processing than our application does, so I've written StartApplication() as a separate function. Given how little it does here, it could be merged into PilotMain().

Our StartApplication() simply tells Palm OS to use our main form. We do this by calling the system API FrmGotoForm(), giving it the ID number of the form we want. The header file HelloRsc.H defines all the form and control ID numbers. Think of HelloRsc.H as "Hello application Resources Header." We'll see more about resources after reviewing the source code. Listing B shows HelloRsc.H (see http://www.component-net.com/pp-extras/helloworld3.html).

Function 3: StopApplication()
Similarly, our StopApplication() also does very little; it too could be merged into PilotMain(). Again, since there's often more exit-time clean-up, I've written it as a separate function. Our StopApplication() simply tells the OS to close all open forms.

Applications which preserve information between uses would typically read the information in StartApplication() as they start and write it in StopApplication() as they exit.

Function 4: EventLoop()
As I wrote before, the real work is in the event loop; ours, predictably, is in the function named EventLoop(). EventLoop() gets the next event from Palm OS, and hands it off to event handlers until an event handler indicates it has handled the event. When the event loop calls EvtGetEvent(), Palm OS returns the event information as an EventType structure. This structure tells us the type of event and other pertinent information. We'll see this work later as we walk through a few events.

Each event handler checks if it should do anything with that type of event, does so if it should, and returns, indicating it did or did not do anything. Some handlers are part of Palm OS, others are part of the application.

The first, SysHandleEvent() is a Palm OS API that handles system events; things like turning the PalmPilot off, pressing one of the hardware buttons, doing a "find," and so forth.