Palm Programming: The Developer's Guide

Other Times Your Application Is Called

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.

Launch Codes

Within the Palm OS, the launch code specifies to the application which of the circumstances just listed exist and what the application needs to do. These codes arrive at the application’s PilotMain routine by way of its launchCode parameter. Here are some common launch codes:

sysAppLaunchCmdFind

This code tells the application to look up a particular text string and return information about any matching data.

sysAppLaunchCmdGoTo

This code tells the application to open, if it isn’t already open, and then to go to the specified piece of data.

sysAppLaunchCmdNormalLaunch

As we have already seen, this code opens the application normally.

Launch Flags

Associated with these launch codes are various launch flags. The launch flags specify important information about how the application is being executed. Here are some examples:

• 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.

A Few Scenarios

To help make this whole relationship between the application and when it gets called by the system clear, let’s look at some examples of when this happens and what the flow of the code is like.

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 flags.

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, sysAppLaunchCmdFind , but with the launch flag sysAppLaunchFlagSubCall , 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)