1.2. 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 (O'Reilly 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
1.2.1. What CodeWarrior Includes
 | We're discussing CodeWarrior for Palm OS Platform, 7.0, the release current in mid-2001. The instructions will also have notes for CodeWarrior for Palm OS Platform, 8.0, the release current in early-2002. |
When you install CodeWarrior, it will put the following tools on your computer:
- The CodeWarrior IDE
This is a project-based Integrated Development Environment (IDE).
- Constructor for Palm OS
Graphical resource editor.
- Palm OS Emulator (3.0a7 for the 7.0 version of CodeWarrior, 3.3 for the 8.0 version)
3.0a7 is not the latest version of POSE; see “Installing PRC on POSE” on page 124 for information on getting the latest version.
- Palm OS SDK (3.5 for the 7.0 version of CodeWarrior, 4.0 for the 8.0 version)
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. The 3.5 SDK can't be used, however, on any 4.0-specific APIs (see “Installing 4.0 SDK” on page 102 for information).
The header files and libraries are kept in:
- Palm OS SDK Stationery (3.5 for the 7.0 version of CodeWarrior, 4.0 for the 8.0 version)
These are the starting points of projects for creating applications. These stationery projects are kept in this folder structure:
Metrowerks CodeWarrior \Palm OS 3.5\Stationery
- Handspring SDK
A separate SDK includes the headers and documentation for using Handspring-specific APIs.
The installer will also install the PilRC plug-in (by default for CW 8, only f you do a Thrill Seekers install of CodeWarrior V7). This allows you to use PilRC files to specify your resources. However, the version of the plug-in is not the latest. See “Installing PilRC Plugin” on page 103 for information on how to get the latest version.
1.2.2. 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. If you're using CodeWarrior 8.0, then the 4.0 SDK is already installed.
The 4.0 SDK can be downloaded from the Palm OS web site: www.palmos.com/dev/tools/sdk40.html.
1.2.2.1. Windows and Mac OS
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.
1.2.2.2. 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 (www.palm.com/devzone). Once you have done so, follow these steps:
Uncompress the Documentation and move it to the Palm Documentation folder. Name it Palm OS 4.0 Docs.
Uncompress the Examples 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 use the new SDK to reflect the new folder name. By using a generic name, future changes to use 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.
1.2.3. Installing PilRC Plugin
We will be using PilRC to create resources in this book (we discussed their use and installation in “Installing PilRC Plugin” on page 103). 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 plugin can always be downloaded from:
www.calliopeinc.com/pilrcplugin.html
The version current as of this writing is 2.9p10a. (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\Bin\Plugins\Compiler
1.2.4. 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 (not a lot of stuff to remove). 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 setup already to use the PilRC plugin.
Download this stationery from:
www.calliopeinc.com/stationery.html
Install it by moving it to:
Metrowerks CodeWarrior\Project Stationery\Palm OS Application
1.2.5. CodeWarrior Setup
Now, it is time to change the various settings in CodeWarrior to be to your liking. In order for you to do that you need to run it. Launch it as appropriate for your platform and then continue reading.
1.2.5.1. Windows
Run CodeWarrior using Start->Program Files->CodeWarrior for Palm OS Platform 7.0->CodeWarrior IDE.
1.2.5.2. Mac OS
Launch CodeWarrior IDE 4.1.
1.2.5.3. 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. To do so, you need to:
Inform CodeWarrior of the location of POSE. Use the Edit->Preferences... menu item to bring up the IDE preferences dialog.
From the left-hand-side, choose the Palm Connection Settings panel (see Figure 1-8). For the Target, specify “Palm OS Emulator”. Use the Choose... button to specify the location of POSE. If you'd like CodeWarrior to automatically launch POSE every time CodeWarrior is started, check Always launch emulator. Click OK to dismiss the dialog.
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 using the Palm->Launch Emulator menu item.
1.2.6. Multi-File Searching
It's also very handy to setup CodeWarrior's multi-file search to allow easy searching of the headers and of the Palm OS examples. To do so:
Select the multi-file search dialog with the Search->Find in Files... menu item.
Click on the In Files project tab.
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 (see Figure 1-9). Click on the Save this set... button and name the set “Palm 4.0 Includes” (see Figure 1-10).
In a similar fashion, create a new files set containing the contents of the Palm OS 4.0 Examples folder. Name it “Palm 4.0 Examples”.
Once you've created these file sets, it'll be very easy to search for text in the headers, or in the examples by using the Find in Files dialog and choosing the appropriate file set.
1.2.7. Creating a new project
To create a new project in CodeWarrior:
Use the File->New... menu item.
Select Palm OS Application from the Project tab.
Give your project a name, and a location (see Figure 1-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 “Installing 4.0 SDK” on page 102 for instructions.)
Select OReillyStarter as the project stationery (see Figure 1-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 “Installing OReilly Stationery” on page 103 for instructions.)
Once you've created the new project, the project window will be displayed (see Figure 1-13).
1.2.8. CodeWarrior IDE
Now, 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.
1.2.8.1. The Project Window
The Files panel of the Project window (see Figure 1-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 1-2. Columns in the CodeWarrior Project window
| Column | What it is |
|---|---|
 | The checkmark indicates that the file needs to be recompiled |
| Files | 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) |
The second panel is the Segments panel (accessed by clicking on the Segments tab—see Figure 1-14). It is used to organize your source files into multiple segments. This is only needed if you have a large application (where your code exceeds 64KB). 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 popup allowing you to change the current target.
1.2.8.2. The Project Settings
The project settings dialog is used to set all the various build options for the current target. You can bring up that dialog by either tapping on the leftmost button at the top of the project window, or by using the Edit->MyTarget Settings... menu item.
There are a number of useful panels in this dialog, Table 4-3 contains an extremely brief description of how you'll use them when doing Palm OS development.
Table 1-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 File name 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. The Prefix 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. |
1.2.9. 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 graphically create resources when using CodeWarrior (see Figure 1-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.
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 you need to start using CodeWarrior for a Palm Project. You should have:
created a sample Palm OS simple application using O'Reilly Stationery
compiled it to create a brand new PRC file named Starter.PRC
You should also know about CodeWarrior's IDE and the benefits of PilRC versus Constructor.
You are done with CodeWarrior, go to “Installing PRC on Handheld” on page 122. That section 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.)