Once the rocket launches, we want to update its position every few milliseconds. During that delay, we want to go idle too. We don't want to sit in a loop checking the time; that would keep the processor busy and use extra power.

Take a look at the event loop in Listing A (It's the second routine from the end; conveniently named EventLoop) at http://www.component-net.com/pp-extras/rocket0998.html.

The second argument to EvtGetEvent is how long to wait for an event. This is the number of milliseconds to wait. If an event comes in during that time, EvtGetEvent returns that event. If the specified time goes by, then EvtGetEvent returns with a nilEvent. This indicates to the program that the time-out occurred.

Normally, we just use evtWaitForever for how long to wait. It's defined in event.h as -1. Eponymously, it tells EvtGetEvent to wait forever for an actual event. (I've always wanted to use the word "eponymous". It's a lovely word that means "just as its name". See? Not only do you learn PalmPilot programming, you get a vocabulary lesson too!)

At the start, Rocketship sets is launched to evtWaitForever. This keeps us fully idle until the rocket is launched. After launch, is launched is set to 1; that gives us a nilEvent every millisecond. Looking at MainFormHandleEvent, each nilEvent calls RedrawRocket. RedrawRocket gets the current ticks and compares it to the ticks at the last time we moved plus the number of milliseconds we wait between moves. If enough millisecond ticks have passed, we update the rocket's position.

TimGetTicks simply returns a 32-bit number indicating the number of milliseconds since the PalmPilot started (or was reset). Since it's just returning that number, it's not doing any great work during the ticks prior to updating the rocket. The tick occurs, we get a nilEvent, we check the tick counter, we haven't waited long enough, so we return and wait for another tick. In-between each tick the processor's in low-power idle mode.

The hardware buttons
When the hardware buttons are pressed, Palm OS pushes special character codes onto the event stack, just as if keys were entered by the on-screen keyboard or Graffiti. The silkscreen buttons work the same way, too.

Normally, these key codes are intercepted by SysHandleEvent in EventLoop, but since we want to use them for moving the rocket left and right, we need to handle those special character events.

Looking again at EventLoop, notice the ButtonsHandleEvent before SysHandleEvent. Looking at ButtonsHandleEvent, you can see that several of the buttons have handlers; they move the rocket left or right, or speed up and slow down the rocket. The speed up/down values need more tuning; they're barely perceptable at best.

Each button handler does its processing, then returns "true" (handled). The remaining buttons, without handlers, will fall through and be processed by SysHandleEvent.