Segmenting an Application

A Palm OS application is a collection of resources packed together into a resource database. Because of limitations in the current HotSync architecture, no single resource can be larger than roughly 64K. If a resource is larger than 64K, your application fails to load into either the Palm OS Emulator or onto a Palm OS handheld via HotSync Manager.
Each application includes a resource of type 'CODE'. This is the resource that stores your application's compiled code and is the most likely resource to exceed the 64K resource size limit. When this happens, you need to segment your application. The process of segmenting an application breaks a large CODE resource into multiple, smaller CODE resources. An application that has been broken in to multiple CODE resources is called a multi-segment application.
There are two ways to create a multi-segment application. If you are using Metrowerks CodeWarrior and creating an application from scratch, you can select "Palm OS Multi-Segment App" from the "New Project" window. This stationery includes the necessary library and linker settings to build a multi-segment application.
If you are converting an existing single-segment application to a multi-segment application, you need to replace the "StartupCode.lib" file with a "MSL Runtime Palm OS (xx).lib". Additionally, you need to disable the "Link Single Segment" flag in the "68K Linker" settings of your project's settings. If you have enabled the 4-byte ints option in the "68K Processor" preferences in your project, then you need to use the "MSL Runtime Palm OS (4I).lib"; otherwise use the "MSL Runtime Palm OS (2I).lib".
To create a new segment, click on the "Segment" tab in your project window. You can then create a new segment by selecting "Create New Segment" from the "Project" menu. Name your segment as appropriate and click "OK". Once you have multiple segments you can simply drag files from one segment to another as appropriate. Note that all segmentation takes place under the "Segment" tab and not the "Files" tab.
There are a few important points to keep in mind. The first segment MUST contain the "MSL Runtime Palm OS (xx).lib", your application's PilotMain() function, and any code that is executed when PilotMain() receives a launch command other than sysAppLaunchCmdNormalLaunch. This stipulation is is necessary because A5-relative data is not relocated when the application is called with any other launch code, causing all global variable addresses to be incorrect.
All other files in your application can be placed in any segment you wish.
If you intend to use functions defined in another segment, they must be declared as "extern" in the segment you are calling from so that the compiler knows that function exists in another segment.
Note to Codewarrior users The best way to determine which files can go into segments other than segment 1 is to:
comment out the code in PilotMain() that handles the sysAppLaunchCmdNormalLaunch command
select the "Generate Link Map" option from the "68K Linker" preferences in your project
rebuildAny file that shows up in the link map on a line beginning with "Code:" must be in the first segment. The link map file is created in the same folder as your project and ends in ".map". Double-click its icon to view the link map. The map includes some functions that the OS usees, you can ignore these functions (most begin and end with two underscore characters ie: __)

How do I create a color icon for my application ?

Note that this article was written in the year 2000, for Palm OS 3.5, which did not include direct color, nor support for higher density screens. This article is still accurate; however, there are more possible members in the bitmap family for direct color bitmaps and higher densities. Make sure you use the most recent version of Constructor or PilRC, and see if your IDE came with starter projects which include a pre-configured and complete set of icons.

You can use the most recent Constructor versions to create color icons. This article provides step-by-step instructions for Constructor. However, you can use any of several other development tools as alternatives, if you wish. For example:

• PalmRI is a tool running on DOS and Windows, which takes a .prc or .pdb and adds images directly (.bmp, .gif, .jpg, .ico, .emf, or .wmf).
• Many other developers use PILRC to create their UI resources. This tool now allows creation of color icons and bitmaps and is more integrated into the gcc toolset than the other tools are.

To create color icons with Constructor, follow these steps:

1. Make sure you are using the most recent version of CodeWarrior and Constructor. If you have CodeWarrior for Palm OS r7 or higher, that will suffice.

2. Remove any old icons from your project, so you don't confuse things by having duplicate objects.

3. In Constructor, create a new App Icon Family in your project resource file, with ID 1000, by clicking on "App Icon Families" and pressing Control-K. Select the ID if it isn't already 1000, and set it to 1000 because that's the ID you must use for the large application icon.

4. Double-click on the new App Icon Family you created. Specify a width and height of 32 pixels, then click where it says "Family Items" and press Control-K twice.

5. Set the first family member to be a one-bit depth icon, no transparency, no compression, and then make up a new bitmap ID (a typical ID for this icon is 1001.)

6. In the second family member, set its depth to 8 bit, with transparency, then choose a color to be the transparent color (for example, the bright green one near the bottom left corner), turn off compression, and then make up a new bitmap ID (for example, 1008.)

7. Click the "Create" button for the first (black and white) family member. The dialog that comes up lets you edit that icon. (Its title bar says "Bitmap ID 1001"; that's correct.)

8. Go to the Options menu and select "Set Image Size." Specify 32 by 32 and click "Resize."

9. Go to the Colors menu and select "Black & White (1-bit depth)."

10. Draw your icon. Even though the window is 32 by 32, you should only use the top 22 pixels, and your drawing should be no wider than 22 pixels, centered horizontally in the window. This is not strictly necessary unless you want to maintain compatibility with all versions of Palm OS and all the known application launching programs. 22x22 is the "proper" size, but using 32x32 and centering horizontally but not vertically makes it work everywhere, at the expense of a few extra bytes in your icons.

11. When you're done with your black and white icon, repeat the process for the 8-bit version. (Click "Create," set the size to 32x32 and the color depth to 8, and draw.) It saves time to copy the black and white icon's data into the color icon, and then adjust the colors to look right.

12. To create the small application icons, do the same except create an App Icon Family with id 1001 and new IDs for the icons for the 1-bit and 8-bit bitmaps (for example, 1011 and 1018), and set the sizes to be 9 high by 15 wide.

Then save and build your project. If you end up with a generic application icon, make sure you're using ID 1000 and are using (minimally) the 3.5 SDK with CodeWarrior R6, or preferably something considerably newer.