Palm OS Programming, 2nd Edition

Modifying the Sample Application

Now that you have your development environment and tools working and have successfully downloaded and run the sample application on both a handheld and POSE, it is time to modify some things. In order to get some practice making changes to the application and rebuilding, we have four different changes we’d like you to make to the sample:

• Change the application name.

• Change the location of a button.

• Register the creator ID and change to appropriate settings.

• Add a second button that beeps.

As you might have expected, the changes move from easier to more difficult.

Change the Application Name

The task at this point is to change the application name that appears in the Application launcher from Starter to Hello. Here are the steps you take:

1. In Resources.rcp, change the following line:

   APPLICATIONICONNAME 1000 "Starter"

   to:

   APPLICATIONICONNAME 1000 "Hello"

2. Make the application (which should cause PilRC to run and the PRC to be rebuilt).

3. Load the application on the handheld or POSE to see the changed icon name (see Figure 4-30).

Figure 4-30. Name changed in the Application launcher

Change the Location of a Button

Now, it time to change the location of the Goto Second Form button so that it’s up and to the left of where it was originally located. Here are the steps:

1. Open Resources.rcp, and change the following lines (we’re changing the top-left coordinates of the Goto Second Form button):

   BUTTON "Goto Second Form" ID MainGotoSecondFormButton AT
     (PrevLeft PrevBottom + 5 AUTO AUTO)

   to:

   BUTTON "Goto Second Form" ID MainGotoSecondFormButton AT
     (20 20 AUTO AUTO)

2. Make the application (which should cause PilRC to run and the PRC to be rebuilt).

3. Load the application on the handheld or POSE to see the changed button location (see Figure 4-31).

Figure 4-31. Button location changed in application

Register the Creator ID and Set It Appropriately

All Palm OS applications require a unique four-character creator ID. Before you distribute your application, you’ll need to register a creator ID and change your application to use it. You register a unique creator ID with Palm at http://www.palmos.com/dev/tech/palmos/creatorid. There’s no charge for registering and it is simple to do. All that is required is a unique four-character ID (note that all lowercase letters are reserved by Palm). There’s a lookup function provided to see whether someone has already used the creator ID in which you’re interested.

You should register your creator ID as soon as you begin work on any application that you’ll be distributing. To encourage this virtuous behavior we have included this task within the tutorial. Before we get to those tasks, however, we want to show what it looks like to register an ID with Palm.

Figure 4-32 shows the creator ID registration form filled in with the creator ID NR01. Figure 4-33 shows the result of submitting the registration to Palm. Now, we’ve got that unique creator ID and no other application can register it.

Figure 4-32. Filling out the form to register a creator ID

Figure 4-33. Notification that the creator ID has been registered

It’s up to us to actually change the application itself to use our new ID (and yes, we’ll need a different creator ID for every application we distribute). We’ll actually be changing two things:

• The creator ID of the database itself

• The name of the database (which, by convention, includes the creator ID appended to it)

We’ll discuss databases, creator IDs, and database names in more detail in Chapter 10.

Changing the creator ID in CodeWarrior

Here are the steps you use to change the creator ID in CodeWarrior:

1. Open the Target Settings dialog box by choosing OReilly Starter (Debug) Settings from the Edit menu (or just click on the Target Settings icon in the project—it’s the leftmost icon in the Project window).

2. Choose the PalmRez PostLinker panel, and change the ???? (the default creator ID) in two places in the dialog box:

   • Change the creator ID from ???? to NR01

   • Change the Database Name from OReilly Starter-???? to OReilly Starter-NR01

   Then click Apply (or Save on Mac OS) and close the dialog box.

3. Now you can make, and it will rebuild your application using the new creator ID. Keep in mind, however, that there are two targets for this project:

   • A debug target

   • A release target

   We’ve got to change the creator ID for both of them.

4. To change the second target, (using the pop up at the top left of the project window) change OReilly Starter (debug) to OReilly Starter (release). Then, make the same changes as before in the PalmRez Post Linker panel of the Target Settings dialog box. Do another make.

5. When you’re done, you might want to switch the current target back to OReilly Starter (debug).

Changing the creator ID in PRC-Tools

Here are the steps you take to change the creator ID using PRC-Tools:

1. The creator ID is stored in the .def file. Open the MyProject.def file and change both occurrences of ???? to NR01:

   application { "OReillyStarter-NR01" "NR01" backup }

2. Do a make and the application will be rebuilt with the new creator ID.

Add a Second Button That Beeps

Your last task is to try adding another button to the second form. When the user taps on it, you want the device to beep.

For now, you should follow our instructions by rote without expecting explanations for things. You’ll learn the reasons for this in later chapters. Here are the robotic steps you take:

1. Open ResourceDefines.h, and add a new constant for the new button (the new line is emphasized):

   #define SecondGotoMainFormButton       3001
   #define SecondBeepButton               3002

2. Add the button to the .rcp file. This will make the button appear when the second form is shown. The new lines of code you add are emphasized:

   FORM ID SecondForm AT (0 0 160 160)
   USABLE
   BEGIN
     TITLE "OReilly Starter Second"
     BUTTON "Goto Main Form" ID SecondGotoMainFormButton AT
       (40 130 AUTO AUTO)
     BUTTON "Beep" ID SecondBeepButton AT 
                               (PREVLEFT PREVBOTTOM+5 AUTO AUTO)
   END

3. Now, add code to make the button actually do something. In this case, you’ll make it beep. Open SecondForm.c and add a new case for the new button. The new code is emphasized:

   Boolean SecondFormHandleEvent(EventPtr eventP)
   {
     Boolean handled = false;
     FormPtr frmP;
   
     switch (eventP->eType) {
     case frmOpenEvent:
       frmP = FrmGetActiveForm(  );
       SecondFormInit(frmP);
       FrmDrawForm(frmP);
       // Here's where you'd add a call to FrmSetFocus.
       handled = true;
       break;
   
     case ctlSelectEvent:
       switch (eventP->data.ctlSelect.controlID) {
       case SecondGotoMainFormButton:
         FrmGotoForm(MainForm);
         handled = true;
         break;    
   case SecondBeepButton:
         SndPlaySystemSound(sndAlarm);
         handled = true;
   break;
       }
       break;
   
     case frmCloseEvent:
       SecondFormDeinit(FrmGetActiveForm(  ));
       handled = false;
       break;
     default:
       break;
     }
   
     return handled;
   }

4. Finally it is time to build the PRC.

5. Once it is built, install it on the handheld or on POSE (you may have to enable sound on POSE in the Preferences dialog box in order to hear anything).

6. When you open the second form, it should contain a new button. Tapping on it should cause a beep.

You should now be ready to delve into the intricacies of the Palm OS. With a working development environment, a small bit of practice working with a project, and sample application, it is time to learn about the OS in detail.