The Palm OS makes a
distinction between communicating with the active application and
communicating with a possibly inactive application. In this first
case, the active application is busy executing an event loop and can
be communicated with by posting events to the event queue. As shown
in Hello World, this was how our application got closed; the
appStopEvent was posted to the event queue. When
the active application gets that event, it quits.
Because there are other times that your application gets called by the Palm OS, there needs to be a way to communicate with it in those instances. First, let’s look at a list of the circumstances under which the system might want to talk to your application:
When the user does a Find, the system must ask each installed application to look for any records that match the Find request.
When beamed data is received, the system must ask the appropriate application (the one that is registered to receive the data) to handle the incoming item.
When a synchronization occurs, each application is notified after its data has been synced.
After a reset, each application is notified that a reset has occurred.
If the system time or date changes, each application is notified.
If the country changes, each application is notified.
In all these cases, a communication must take place to an inactive or closed application. The question is how the system does this. The answer is launch codes; all these communications are handled by your application’s launch codes.
Within the Palm OS, the launch
specifies to the application which of the circumstances just listed
exist and what the application needs to do. These codes arrive at the
routine by way of its
launchCode parameter. Here
are some common launch codes:
This code tells the application to look up a particular text string and return information about any matching data.
This code tells the application to open, if it isn’t already open, and then to go to the specified piece of data.
As we have already seen, this code opens the application normally.
Whether the application’s global variables are available. Globals are not available on many launch codes.
Whether the application is now the active application.
Whether it had already been open as the active application.
Whether some other application is active.
Example 4.12 shows what happens when a user does a
Find when the built-in application Memo Pad is open. The
PilotMain of Hello World is called with the
sysAppLaunchCmdFind launch code and with no launch
Example 4-12. Flow of Control When User Chooses Find When MemoPad Is Open
MemoPad's sysAppLaunchFlagNewStack AND PilotMain(sysAppLaunchCmdNormalLaunch,params, sysAppLaunchFlagNewGlobals AND flags) sysAppLaunchFlagUIApp MemoPad's EventLoop SysHandleEvent (enter) after user taps Find Loop through all applications: MemoPad's PilotMain(sysAppLaunchCmdFind, parameters, sysAppLaunchFlagSubCall) PilotMain(sysAppLaunchCmdFind, calls HelloWorld's PilotMain parameters, 0) SysHandleEvent (exit)
Now take a look in Example 4.13. This is what happens
when we do a Find with our application already open. In this case,
HelloWorld’s PilotMain is called with the
same launch code,
, but with the launch flag
, specifying that the HelloWorld
application is already open and running. This signifies that global
variables are available and that the
StartApplication routine has been called.
Example 4-13. Flow of Control When User Chooses Find When Hello World Is Open
HelloWorld's PilotMain( sysAppLaunchFlagNewStack AND sysAppLaunchCmdNormalLaunch, params, sysAppLaunchFlagNewGlobals AND flags) sysAppLaunchFlagUIApp HelloWorld's EventLoop SysHandleEvent (enter) after user taps Find Loop through all applications: HelloWorld's PilotMain(sysAppLaunchCmdFind, parameters, sysAppLaunchFlagSubCall) PilotMain(sysAppLaunchCmdFind,parameters, 0) SysHandleEvent (exit)