Palm OS Programming, 2nd Edition

CodeWarrior

This first tutorial goes through CodeWarrior. As most Palm OS application development takes place in CodeWarrior, it seemed like a good place to start. Here is what the tutorial describes:

• What CodeWarrior includes (which tools you install and use)

• How to install and use the newest 4.0 SDK from Palm with CodeWarrior

• How to install a PilRC plug-in

• How to use some stationery (OReilly Starter) that we provide, which makes creating a new project much easier

• The various settings in CodeWarrior

• Creating a new project

• Making a PRC file

• A quick walkthrough of the CodeWarrior IDE

• Using Constructor to create resources

What CodeWarrior Includes

We’re discussing CodeWarrior for Palm OS Platform 7.0, the current release in mid-2001. When you install CodeWarrior, it will put these tools on your computer:

CodeWarrior IDE

This is a project-based Integrated Development Environment (IDE).

Constructor for Palm OS

This is a graphical resource editor.

Palm OS Emulator (3.0a7)

This is not the latest version of POSE; see Section 4.6 later in this chapter for information on getting the latest version.

Palm OS 3.5 SDK

This software development kit (SDK) includes header files, libraries, examples, and documentation. It can be used to create applications that run on any earlier version of the OS as well. It can’t be used, however, to access any 4.0-specific APIs (see Section 4.2.2, for information).

The header files and libraries are kept in Metrowerks\CodeWarrior for Palm OS Platform 7.0\Palm OS 3.5 Support.

Palm OS 3.5 SDK Stationery

These are the starting points of projects for creating applications. These stationery projects are kept in Metrowerks\CodeWarrior for Palm OS Platform 7.0\Stationery\Palm OS 3.5.

Handspring SDK

A separate SDK includes the headers and documentation for using Handspring-specific APIs.

If you do a Thrill Seekers install of CodeWarrior, it’ll also install the PilRC plug-in. This allows you to use PilRC files to specify your resources. However, the version of the plug-in is 2.6, which is not the latest. See Section 4.2.3 for information on how to get the latest version.

Installing 4.0 SDK

In order to use 4.0-specific APIs, you need to use the 4.0 SDK. As with the other SDKs, you can always use the 4.0 SDK to develop applications that will work with an earlier OS—just don’t use the new 4.0 APIs. In general, you’ll want to use the latest SDK available.

The 4.0 SDK can be downloaded from the Palm OS web site: http://www.palmos.com/dev/tech/tools/sdk40.html.

For Windows or Mac OS, the SDK is available as an executable installer. It installs the SDK in the appropriate locations within the CodeWarrior folder.

Installing additional examples

While the SDK will include the minimum necessary to compile projects (headers, libraries, and updated tools), you’ll also want to have the example files as well as the documentation. To get these you need to download the documentation and examples from Palm’s web site (http://www.palmos.com/dev/). Once you have done so, follow these steps:

1. Uncompress the documentation and move it to the Palm Documentation folder. Name it Palm OS 4.l0 Docs.

2. Uncompress the examples folder and move it to the CodeWarrior Examples folder. Name it Palm OS 4.0 SDK Examples.

The naming conventions for the 4.0 SDK have changed slightly from that used by previous SDKs. Rather than putting the SDK version number as part of the folder name, the folder name is now generic. As things stood, when a new SDK came out, projects had to be modified in order to reflect the new folder name. By using a generic name, future changes to new SDKs are as simple as removing the old folder and replacing it with a new one.

The headers and libraries in a subfolder of the CodeWarrior folder called Palm OS Support. The stationery is kept in a Palm OS Application subfolder within the Stationery folder.

Installing PilRC Plug-in

We will be using PilRC to create resources in this book. We use PilRC rather than Constructor because:

• .rcp text files can easily be displayed in the book.

• They are cross-platform. They work with both CodeWarrior (Mac OS and Windows) and with PRC-Tools.

• We like them—we find it much easier to work with text files. For example, source code control and finding differences between two versions of a file are easier to do with text.

The latest version of the PilRC plug-in can always be downloaded from http://www.calliopeinc.com/pilrcplugin.html.

The current version as of this writing is 2.8. (Look on the web site for the most recent version.) Install it by moving it to:

• Mac OS: Metrowerks CodeWarrior:CodeWarrior Plugins:Compilers

• Windows: Metrowerks\CodeWarrior for Palm OS Platform 7.0\Bin\Plugins\Compiler

Installing OReilly Stationery

We know our job is to make things as simple as possible for you. As a result, we imagine that when you create a new CodeWarrior project you would like it to be as easy as can be expected. The stationery that ships with CodeWarrior is too complicated for our tastes. We find that using this default stationery as a starting point causes us to spend a fair amount of time removing functionality we don’t want before we can even begin adding our own code.

So, presto, we have made life easier. We’ve created some new, very simple stationery that has the correct structure of a Palm OS application. Of course, it doesn’t actually do very much, but that way it’s easier to use as the basis of a new application. A bonus feature is that our stationery has been set up already to use the PilRC plug-in. You can:

1. Download this stationery from http://www.calliopeinc.com/stationery.html.

2. Install it by moving it to Metrowerks\CodeWarrior for Palm OS Platform 7.0\Stationery\Palm OS Application (or Metrowerks CodeWarrior:(Project Stationery):Palm OS Application for Mac OS).

CodeWarrior Setup

Now, it is time to set the various settings in CodeWarrior. In order for you to do this, you need to run it. Launch it according to your platform and then continue reading.

In Windows, run CodeWarrior using Start → Program Files → CodeWarrior for Palm OS Platform 7.0 → CodeWarrior IDE. In Mac OS, launch CodeWarrior IDE 4.1.

Launching POSE automatically

Changing a couple of settings will make using CodeWarrior much more handy. The first change is to enable CodeWarrior to launch POSE automatically. You need to do the following:

1. Inform CodeWarrior of the location of POSE. Choose Edit → Preferences to open the IDE Preferences dialog box.

2. At the left side, choose the Palm Connection Settings panel (see Figure 4-8). For the Target, select Palm OS Emulator.

3. Select Choose to specify the location of POSE. If you’d like CodeWarrior to automatically launch POSE every time CodeWarrior is started, check Always launch emulator.

4. Click OK to dismiss the dialog box.

Figure 4-8. Requesting that CodeWarrior automatically launch POSE

If you checked Always launch emulator, then from now on, CodeWarrior will automatically start POSE. If you haven’t checked it, you can still cause CodeWarrior to launch POSE by choosing Palm → Launch Emulator.

Multifile searching

It’s also very handy to set up CodeWarrior’s multifile search to allow easy searching of the headers and Palm OS examples.

1. Select the Multifile Search dialog box with the Search → Find in Files menu item.

2. Click on the In Files project tab.

3. Add the 4.0 SDK header files to the list of files to search by dragging the Palm OS Support folder (from Windows Explorer or the Finder) to the File Set area of the dialog box (see Figure 4-9).

4. Click the Save This Set button and name the set Palm 4.0 Includes (Figure 4-10).

5. In a similar fashion, create a new file set containing the contents of the Palm OS 4.0 Examples folder. Name it Palm 4.0 Examples.

Figure 4-9. Find in Files dialog box with Palm OS Support files dragged in

Figure 4-10. Naming the file set

Once you’ve created these file sets, it’ll be easy to search for text in the headers, or examples by using the Find in Files dialog box and choosing the appropriate file set.

Creating a New Project

To create a new project in CodeWarrior:

1. Choose File → New.

2. Select Palm OS Application from the Project tab.

3. Give your project a name, and a location (see Figure 4-11). Then, click OK.

   If Palm OS Application Stationery doesn’t appear in the list of projects, you haven’t installed the 4.0 SDK. (See Section 4.2.2 earlier in this chapter for instructions.)

4. Select OReillyStarter as the project stationery (see Figure 4-12). Click OK; CodeWarrior will duplicate the project, along with all the files in the project and name it MyProject.

   If OReillyStarter doesn’t appear in the list of stationery, you haven’t installed it. (See Section 4.2.4 for instructions.)

5. Once you’ve created the new project, the project window will be displayed (see Figure 4-13).

Figure 4-11. New project window

Figure 4-12. Selecting the project stationery

Figure 4-13. The MyProject window

Making a PRC

Now that you have CodeWarrior up and running and a brand new skeleton project to work with, it is time to practice making the project. CodeWarrior will do the following when you select Project → Make:

• Compile all needed source files and link them together.

• Use PilRC to compile the resource file.

• Run the PalmRez PostLinker to combine the code and the resources into a PRC file. If you have installed and used the OReilly Stationery it creates a PRC named OreillyStarter .prc in the (CW Debug) directory.

That’s it—you should now have a working project and a PRC file that you can download to a device.

If you already know how to use CodeWarrior or you want to continue straightaway with the tutorial, go directly to Section 4.5.

The next two sections deal with various settings and tools in CodeWarrior that you can read about now or later as you prefer.

CodeWarrior IDE

We want to tell you a little more about the CodeWarrior IDE. We will just provide a brief introduction to the major parts of the IDE. To get the most out of this very full-featured environment, we recommend reading the documentation, including Getting Started with Palm OS, Targeting Palm OS Platform, and IDE User Guide.

CodeWarrior is project-based, where a project contains one or more targets. A target is a set of files sharing common build settings. A project can contain multiple targets. For example, a project might have a release target and a debug target, each with different build settings.

The Project window

The Files panel of the Project window (see Figure 4-14) displays the files in the project organized into groups. Double-clicking on a group opens that group. Double-clicking on a file opens the file. Table 4-2 shows the columns of information.

Table 4-2. Columns in the CodeWarrior MyProject window

Column	What it is
	The checkmark indicates that the file needs to be recompiled.
File	Filename.
Code	Size of the code (if this is a source file and has been compiled).
Data	Size of the data (if the file is a source file and has been compiled).
	The • indicates the file is in the current target.
	The • indicates the file is enabled for source-level debugging.
	The header files included by the file (if the file has been compiled).

Figure 4-14. The Files panel of the project window

The second panel is the Segments panel (accessed by clicking on the Segments tab). It is used to organize your source files into multiple segments. This is only needed if you have a large application (in which your code exceeds 64 KB). The Targeting Palm OS Platform manual discusses how to modify a target to support multiple segments.

The third panel is the Targets panel (click on the Targets tab), which displays all the targets for the project.

At the top left of the project window is a pop up that allows you to change the current target.

The Project Settings dialog box

The Project Settings dialog box sets all the various build options for the current target. You can bring up that dialog box either by tapping on the leftmost button at the top of the project window, or by choosing Edit → Target Settings.

There are a number of useful panels in this dialog box. Table 4-3 contains an extremely brief description of how you’ll use them when doing Palm OS development.

Table 4-3. CodeWarrior Project Settings panels

Panel name	What it does
Target Settings	This panel controls the name of the target and the location of the final output PRC file.
Access Paths	This panel controls where CodeWarrior will search for include files. If you specify a directory, CodeWarrior will search in that directory, and in any subdirectories.
68K Target	This panel controls the output that the linker creates. The filename specified here must match the Mac resource files specified in the PalmRez Post Linker panel.
C/C++ Language	This panel allows you to control exactly how the C and C++ compiler are used. You can turn on the C++ compiler by checking Activate C++ Compiler. Theprefix file is CodeWarrior’s answer to command-line #defines. Specify a prefix file here and it will be automatically included at the very beginning of any C or C++ source file.
PalmRez Post Linker	This panel controls how the PRC file will be built. Here, you specify the name of the PRC file that is generated (output file), along with the type, creator ID, attributes, and database name of the application.

Constructor for Palm OS

Constructor is a graphical resource editor that was originally developed by Metrowerks. It has since been turned over to Palm and is now developed by them. It can be used to create resources graphically when using CodeWarrior (see Figure 4-15). Notice also that it is a separate application that edits resource files (of extension .rsrc or .rsr). These files can then be added to your project.

Figure 4-15. Constructor editing a form resource within a resource file

If you want to use Constructor you can look at the Constructor for Palm OS documentation that’s part of the Palm OS SDK. It covers Constructor’s use in detail.

At this point you should know everything necessary to start using CodeWarrior for a Palm Project. You should have done the following:

• Created a sample Palm OS simple application using OReilly Stationery

• Compiled it to create a brand new PRC file named OreillyStarter.prc

You should also know about CodeWarrior’s IDE and the benefits of PilRC versus Constructor.

You are done with CodeWarrior, skip to Section 4.5. That is the next step in your tutorial. The following tutorial uses PRC-Tools to duplicate the same steps we just did in the CodeWarrior tutorial.