This chapter is the place to start if you're new to programming for Palm OS® devices. It summarizes what's unique about writing applications for Palm Powered™ devices and tells you where to go for more in-depth information. It covers:
Why Programming for Palm OS Is Different
Palm OS Programming Concepts
Processor Differences
Uniquely Identifying Your Palm OS Application
Making Your Application Run on Different Devices
Programming Tools
Where to Go from Here
Read this chapter for a high-level introduction to Palm OS programming. The rest of this book provides the details.
Why Programming for Palm OS Is Different
Like most programmers, you have probably written a desktop application—an application that is run on a desktop computer such as a PC or a Macintosh computer. Applications written for devices, specifically Palm Powered devices, are a bit different from those written for desktop computers because the Palm Powered device is designed differently than a desktop computer. As well, the way in which users interact with a device differs from the way they interact with a desktop computer.
This section describes how these differences affect the design of a Palm OS® application.
Screen Size
Palm Powered device screens are often only 160x160 or 320x320 pixels, so the amount of information you can display at one time is limited.
For this reason, you must design your user interface carefully with different priorities and goals than are used for large screens. Strive for a balance between providing enough information and overcrowding the screen. See the book Exploring Palm OS: User Interface Guidelines for more detailed information on designing the user interface.
Note that the screen size is not necessarily fixed: some Palm Powered devices allow the user to rotate the display or to collapse the input area. If the user collapses the input area, there is more space available to the application.
Quick Turnaround Expected
On a PC, users don't mind waiting a few seconds while an application loads because they usually plan to use the application for an extended amount of time.
By contrast, the average device user uses a device application 15 to 20 times per day for much briefer periods of time, often just a few seconds. Speed is therefore a critical design objective for devices and is not limited to execution speed of the code. The total time needed to navigate, select, and execute commands can have a big impact on overall efficiency.
To maximize performance, the user interface should minimize navigation between windows, opening of dialogs, and so on. The layout of application screens needs to be simple so that the user can pick up the product and use it effectively after a short time. It's especially helpful if the user interface of your application is consistent with other applications on the device so users work with familiar patterns.
The Palm OS development team has put together a set of design guidelines that were used as the basis for the applications resident on the device (Memo Pad, Address Book, and so on). These guidelines are summarized in the book Exploring Palm OS: User Interface Guidelines.
PC Connectivity
PC connectivity is an integral component of the Palm Powered device. The device comes with a cradle or cable that connects to a desktop PC and with software for the PC that provides "one-button" backup and synchronization of all data on the device to the user's PC.
Many Palm OS applications have a corresponding application on the desktop. To share data between the device's application and the desktop's application, you write a conduit. A conduit is a plug-in to the HotSync® technology that runs when you press the HotSync button. A conduit synchronizes data between the application on the desktop and the application on the device. To write a conduit, you use the Conduit Developer's Kit (CDK). See the documentation provided with the CDK for more information on writing conduits.
Input Methods
Most users of Palm Powered devices don't have a full-sized keyboard or mouse. When entering data directly into the device, depending on the design of the device most users either use a pen—by writing characters in the input area or by tapping on an on-screen keyboard—or they type on a miniature "thumb board."
While pen strokes, the keyboard dialog, or a miniature keyboard are useful ways of entering data, they are not as convenient as using the full-sized desktop computer with its keyboard and mouse. Therefore, you should not require users to enter a lot of data on the device itself.
Many Palm Powered devices support external keyboards, which are sold separately. Do not rely on your users having an external keyboard.
Power
Palm Powered devices run on batteries and thus do not have the same processing power as a desktop PC. If your application needs to perform a computationally-intensive task, see if there isn't a way to perform that task in the desktop application instead of the device application.
Memory
Compared to a desktop computer, Palm Powered devices have limited heap and storage space. Different devices within the family of Palm Powered devices might have on the order of 16 Mb to 128 Mb of dynamic memory and storage available, in total. The device does not have a disk drive or PCMCIA support.
File System
Except when working with external storage media (SD cards, Memory Sticks, and the like), Palm OS does not use a traditional file system. You store data in memory chunks called records, which are grouped into databases. A database is analogous to a file. The difference is that data is broken down into multiple records instead of being stored in one contiguous chunk. To save space, you edit a database in place in memory instead of creating it in RAM and then writing it out to storage.
Applications written specifically for Palm OS Cobalt can take advantage of the advanced capabilities of the Schema database format. Schema databases have many of the features of relational databases and give applications greater power and flexibility in working with their data.
Backward Compatibility
Not all Palm Powered devices run the same version of Palm OS. Users are not expected to upgrade their versions of Palm OS as they would an operating system on a desktop computer. New versions of the operating system are designed in such a way that applications that run on a previous version will most likely run on the newer version as well. This allows you to write applications that can be deployed on a wider variety of Palm Powered devices, increasing the potential market for your applications. See "Making Your Application Run on Different Devices" for details.
Palm OS Programming Concepts
Palm OS applications are event-driven programs that are most often written in C. Although Palm OS Cobalt supports multiple threads and processes, the user primarily interacts with only one program at a time. To successfully build a Palm OS application, you have to understand how the system itself is structured and how to structure your application.
- Each application has a
PilotMain()
function that is equivalent tomain
in C programs. To launch an application, the system callsPilotMain()
and sends it a launch code. The launch code may specify that the application is to become active and display its user interface (called a normal launch), or it may specify that the application should simply perform a small task and exit without displaying its user interface.The sole purpose of the
PilotMain()
function is to receive launch codes and respond to them. (See Chapter 2, "Application Start and Stop.") - Palm OS applications are largely event-driven and so contain an event loop; however, this event loop is only started in response to the normal launch. Your application may perform work outside the event loop in response to other launch codes. Chapter 3, "Events and the Event Loop," describes the main event loop.
- Most Palm OS applications contain a user interface made up of forms, which are analogous to windows in a desktop application. The user interface may contain both predefined UI elements (sometimes referred to as UI objects), and custom UI elements. (See Exploring Palm OS: User Interface)
- All applications should use the memory and data management facilities provided by the system. (See Exploring Palm OS: Memory, Databases, and Files)
- Applications employ operating system services by calling Palm OS functions. Palm OS consists of several "managers," which are groups of functions that work together to implement a feature. As a rule, all functions that belong to one manager use the same prefix and work together to implement a certain aspect of functionality.
Managers are available to, for example, generate sounds, send alarms, perform network communication, and beam information through an infrared port. A good way to find out the capabilities of the Palm OS is to scan the tables of contents of the various books that make up the Exploring Palm OS series.
API Naming Conventions
The following conventions are used throughout most of the Palm OS API:
- Functions start with a capital letter.
- All functions belonging to a particular manager start with a short prefix, such as "Ctl" for control functions or "Ftr" for functions that are part of the Feature Manager.
- Events and other constants start with a lowercase letter.
- Structure elements start with a lowercase letter.
- Typedefs start with a capital letter and end with "Type" (for example,
DateFormatType
, found inDateTime.h
). - Notifications start with a prefix (most often, "sys") followed by the word "Notify." For example,
sysNotifyAppLaunchingEvent
. - Launch codes have a prefix followed by "LaunchCmd," as in
sysAppLaunchCmdNormalLaunch
. - Members of an enumerated type start with a lowercase prefix followed by a name starting with a capital letter, as follows:
enum formObjects { frmFieldObj, frmControlObj, frmListObj, frmTableObj, frmBitmapObj, frmLineObj, frmFrameObj, frmRectangleObj, frmLabelObj, frmTitleObj, frmPopupObj, frmGraffitiStateObj, frmGadgetObj}; typedef enum formObjects FormObjectKind;
Integrating Programs with the Palm OS Environment
When users work with a Palm OS application, they expect to be able to switch to other applications, have a way to enter data right on the device, access information with the global find, receive alarms, and so on. Your application will integrate well with others if you follow the guidelines in this section. Integrate with the system software as follows:
- Handle
sysAppLaunchCmdNormalLaunch
- Handle or ignore other application launch codes as appropriate. For more information, see Chapter 2, "Application Start and Stop."
- Be sure your application uses the system preferences for numeric formats, date, time, and start day of week. See Chapter 3, "Preferences," of Exploring Palm OS: System Management for instructions on how to do so.
- Don't obscure shift indicators.
In addition, follow these rules:
- Store state information in the application preferences database, not in the application record database. See Chapter 3, "Preferences," of Exploring Palm OS: System Management for more information on preferences.
- If your application uses the serial port, be sure to close the port when you no longer need it so that the HotSync application can use it.
- Ensure that your application properly handles the global find. Generally, searches and sorts aren't case sensitive.
- If your application supports private records, be sure they are unavailable to the global find when they should be hidden.
- Integrate with the Launcher application by providing an application name, two application icons, and a version string as described in Chapter 11, "Integrating with the Application Launcher," of Exploring Palm OS: User Interface.
- Follow the guidelines detailed in Exploring Palm OS: User Interface Guidelines.
- Ensure that your application properly handles system messages during and after synchronization.
- Ensure that protected records and masked record contents are not displayed if the user has so indicated.
- Ensure that your application uses a consistent default state when the user enters it:
- Some applications have a fixed default; for example, the Date Book always displays the current day when launched.
- Other applications return to the place the user exited last. In that case, remember to provide a default if that place is no longer available. Because of HotSync operations and Preferences, don't assume the application data is the same as it was when the user looked at it last.
- If your application uses sounds, be sure it uses the Warning and Confirmation sounds properly.
Writing Robust Code
To make your programs more robust and to increase their compatibility with the widest variety of Palm OS products, it is strongly recommended that you follow the guidelines and practices outlined in this section.
- Check assumptions.
You can write defensive code by making frequent use of the
DbgOnlyFatalErrorIf()
macro, which enables your debug builds to check assumptions. Many bugs are caught in this way, and these "extra" calls don't weigh down your shipping application. You can keep more important checks in the release builds by using theErrFatalErrorIf()
function. - Avoid continual polling.
To conserve the battery, avoid continual polling. If appropriate, take advantage of the
keyUpEvent
or the facilities for performing event-based pen tracking to avoid polling altogether. - Avoid reading and writing to
NULL
(or low memory).In Palm OS Cobalt reading and writing to NULL will cause your application to crash. When calling functions that allocate memory, at least make sure that the pointers they return are non-
NULL
. (If you can do better validation than that, so much the better.) Also check that pointers your code obtains from structures or other function calls are notNULL
. Consider adding to your debug build a#define
that overrides the memory management functions with a version that validates the arguments passed to it. - Check result codes when allocating memory.
Because various Palm Powered devices have larger or smaller amounts of available memory, it is always a good idea to check result codes carefully when allocating memory.
- Avoid making assumptions about the screen.
The size and shape of the screen, the screen buffer, and the number of pixels per bit aren't set in stone—they vary from one Palm Powered device to another. Don't hack around the windowing and drawing functions; the functions provided are optimized to make best use of the underlying hardware and to allow multiple applications and system services to share it.
- Built-in applications can change.
The format and size of the preferences (and data) for the built-in applications is subject to change. Write your code defensively, and consider disabling your application if it is run on an untested version of the OS.
Uniquely Identifying Your Palm OS Application
Each Palm OS application—in fact, each Palm OS database—is uniquely identified by a combination of its name and a four-byte creator ID. By assigning the application's creator ID to all of the databases related to an application, you associate those databases with the application. The OS takes advantage of this; for instance, the Launcher's Info panel uses the creator ID to calculate the total memory used by each application.
Each database on the Palm Powered device has a type as well as a creator ID. The database type allows applications and the OS to distinguish among multiple databases with the same creator ID. For applications, set the database type to sysFileTApplication
('appl'
). For each database associated with an application, set the database type to any other value (as long as it isn't composed entirely of lowercase letters, since those are reserved by PalmSource). Certain predefined types—such as 'appl'
(application) or 'libr'
(library)—have special meaning to Palm OS. For instance, the Launcher looks at the database type to determine which databases are applications.
Types and creator IDs are case-sensitive and are composed of four ASCII characters in the range 32-126 (decimal). Types and creator IDs consisting of all lowercase letters are reserved for use by PalmSource, so any type or creator ID that you choose must contain at least one uppercase letter, digit, or symbol1.
To protect your application from conflicting with others, you need to register your creator ID with PalmSource, which maintains a database of registered IDs. To choose and register a creator ID, see this web page:
http://dev.palmos.com/creatorid/
Note that you don't need to register database types as you do creator IDs. Each creator ID in effect defines a new space of types, so there is no connection between two databases with type 'Data'
but with different creator IDs.
IMPORTANT: Applications with identical creator IDs cannot coexist on the same device; during installation the new application will replace the existing application that possesses the same creator ID. Further, the new application could well corrupt any databases that were associated with the preexisting application. For this reason, all applications should have their own unique creator ID.
Finally, creator IDs aren't used only to identify databases. They are also used, among other things, when getting or setting application preferences, to register for notifications, and to identify features.
Making Your Application Run on Different Devices
There are many different devices that run Palm OS, and each may have a different version of the operating system installed on it. Users are not expected to upgrade the Palm OS as they would an operating system on a desktop computer. This fact makes backward compatibility more crucial for Palm OS applications.
This section describes how to make sure your application runs on as many devices as possible by discussing:
- Processor Differences
- Running New Applications on an Older Device
- Compiling Older Applications with the Latest SDK
Processor Differences
The original Palm OS devices—and, as of this writing, the majority of the installed base—employ a Motorola Dragonball™ processor that is part of the 68000 family. Palm Powered devices running Palm OS Garnet and Palm OS Cobalt use an ARM™ processor (available from a variety of manufacturers). To ensure compatibility, Palm OS Garnet introduced the Palm OS Application Compatibility Environment (PACE), which emulates the instruction set from the earlier class of Palm Powered devices and allows most applications written for those devices to continue to run on an ARM-based device. PACE is present in Palm OS Cobalt as well. While Palm OS Garnet only allowed developers to create applications that worked through PACE, however, Palm OS Cobalt gives developers the choice of developing a traditional Palm OS application that runs through PACE, or developing an application that runs "natively"—one that is compiled for the ARM processor and that can directly call the operating system.
How you choose to develop your Palm OS applications depends on a number of factors. Perhaps most important is what devices you are targeting. If you want to target the largest possible set of customers you'll likely want to write your application to be compatible with a number of earlier versions of Palm OS. If you do this, however, be aware that:
- Applications written expressly for Palm OS Cobalt will run faster than those that must work through PACE.
- PACE does not provide full access to many of the new features introduced in Palm OS Cobalt. Schema databases, advanced graphics, and multithreading are just some of the things you give up by not targeting the Palm OS Cobalt native environment.
IMPORTANT: The Exploring Palm OS series is intended for developers creating native applications for Palm OS Cobalt. If you are interested in developing applications that work through PACE and that also run on earlier Palm OS releases, you should be reading the latest versions of the Palm OS Programmer's API Reference and Palm OS Programmer's Companion instead.
Running New Applications on an Older Device
PalmSource works hard to maintain binary compatibility between versions of Palm OS. Even with the switch from the 68K-based Dragonball processor to an ARM-based one compatibility is largely maintained through the use of the Palm OS Application Compatibility Environment (PACE). Because of this, applications can be written that will run on all versions of the operating system (provided the application doesn't use any features specific to one version of the operating system). In other words, if you wrote your application using only features available in Palm OS 1.0, then your application should run on all devices. If you use 2.0 features, your application won't run on the earliest Palm Powered devices, but it will run on all those running Palm OS 2.0 and later.
NOTE: As explained in the previous section, this discussion is aimed at applications written using the "68K" APIs—those APIs exposed in Palm OS Cobalt via PACE. Applications written to run natively on the ARM processor will not run on any Palm Powered device running a version of Palm OS prior to 6.0.
How can you tell which features are available in each version of the operating system? There are a couple of way to do so:
- The Palm OS Programmer's API Reference has a "Compatibility Guide" appendix. This guide lists the features and functions introduced in each operating system version greater than 1.0.
- The header file
CoreTraps.h
(SysTraps.h
on versions of Palm OS before 3.5) lists all of the system traps available. Traps are listed in the order in which they were introduced to the system, and comments in the file clearly mark where each operating system version begins.
Programmatically, you can use the Feature Manager to determine which features are available on the system the application is running on. Note that you can't always rely on the operating system version number to guarantee that a feature exists. For example, Palm OS version 3.2 introduced wireless support, but not all Palm Powered devices have that capability. Thus, checking that the system version is 3.2 (or greater) does not guarantee that wireless support exists. Consult the "Compatibility Guide" in the Palm OS Programmer's API Reference to learn how to check for the existence of each specific feature.
Compiling Older Applications with the Latest SDK
As a rule, all Palm OS applications developed with an earlier version of the Palm OS platform SDK should run error-free on the latest release. This rule applies to Palm OS Cobalt as long as your application continues to use the "68K" APIs supported by PACE. Converting an existing application so that it runs natively on Palm OS Cobalt is a somewhat more involved task; see Exploring Palm OS: Porting Applications to Palm OS Cobalt for a complete discussion of this process.
If you want to compile your older application under the latest release, you need to watch out for functions with a changed API. For any of these functions, the old function still exists with a suffix noting the last release that fully supports it, such as "V40" for Palm OS 4.0.
When a given function has been so renamed, you have two options:
- Change the function name in your code to keep using the old API. Your application will then run error free on the newer and the older devices.
- Update your application to use the new API. The application will then run error free and have access to some new functionality; however, it will no longer run on older devices that use prior releases of the OS.
Programming Tools
Several tools are available that help you build, test, and debug Palm OS applications. The set of tools you can choose from is large and growing: see http://www.palmos.com/dev/tools/ for information about your development language and tool options.
The book Palm OS Programming Development Tools Guide describes the PalmSource-provided debugging tools available on your development platform. The Palm OS Developer Suite has extensive online help. For information on using third-party tools, refer to the documentation (printed or electronic, depending upon the tool) supplied with the tool.
Where to Go from Here
This chapter provided you only with a general outline of the issues involved in writing an application to run on Palm OS Cobalt. To learn the specifics, refer to the following resources:
- This book
The rest of this book explores some of the most basic Palm OS programming concepts. Among other things, the next three chapters cover:
- the way in which applications are started ("launched"),
- how applications can be instructed to perform a service on behalf of another,
- the means by which applications are informed of user actions, and the basic mechanism employed by Palm OS applications to process those actions,
- how applications can register for and receive notification of important operating system events.
- Exploring Palm OS: Memory, Databases, and Files
As the title implies, this book covers all aspects of the Palm OS memory system. This includes the way in which Palm Powered devices dedicate a portion of their memory to serve as what in a desktop computer would be secondary, or disk, storage. On the device, programs and data are stored in databases; these databases can either be structured, like a traditional computer database, or more free-form, like a traditional file. Palm OS doesn't provide a traditional file system except when working with "external" storage (which on a typical Palm OS device takes the form of an SD card or Memory Stick); this book shows you how to interact with these storage devices as well.
- Exploring Palm OS: User Interface
Nearly all Palm OS programs have some sort of user interface, and this book goes into great detail about how you create such an interface. This book covers the nuts-and-bolts of constructing and manipulating your user interface: for more general advice on how best to interact with the user, see Exploring Palm OS: User Interface Guidelines.
- Exploring Palm OS: System Management
This book discusses all of the "miscellaneous" system functions: threading, dates and times, floating point, alarms, features and preferences, and so on. It also covers hardware interactions: the real-time clock, expansion media, system boot and reset, battery power, and the like.
- Other books in the Exploring Palm OS series
The remaining books in the series provide more specialized information that might not be of interest to all Palm OS application developers. These books include:
- Exploring Palm OS: Text and Localization
- Exploring Palm OS: Input Services
- Exploring Palm OS: High-Level Communications
- Exploring Palm OS: Low-Level Communications
- Exploring Palm OS: Multimedia
- Exploring Palm OS: Telephony and SMS
- Exploring Palm OS: Security and Cryptography
- Exploring Palm OS: Creating a FEP
- Exploring Palm OS: Porting Applications to Palm OS Cobalt
- Exploring Palm OS: Palm OS File Formats
- Introduction to Palm OS Tools
- Palm OS Compiler Tools Guide
- Palm OS Compiler Reference
- Palm OS Debugger Guide
- Palm OS Resource Tools Guide
- Palm OS Simulator Guide
- Virtual Phone Guide
- Example applications
The Palm OS Cobalt SDK contains a number of sample applications that can be a valuable aid when you develop your own programs. The software development kit provides a royalty-free license that permits you to use any or all of the source code from the examples in your application.
- Conduit Development Kit and documentation
If you need to write a conduit for your application, see the documentation provided with the Conduit Development Kit.
- Training
PalmSource offers training in Palm OS programming. See the Training portion of the PalmSource website at http://www.palmos.com/dev/training/.
- PalmSource website
The PalmSource website is an invaluable source of information about PalmSource, the Palm OS, and Palm OS application development. From this website you can download SDKs, tools, and documentation. You can learn about the various device manufacturers and the devices they produce. And you can get help with your programming questions, either by consulting the PalmSource Knowledge Base or by posting a question to one of the many Internet forums dedicated to Palm OS programming. For all of this and more, go to http://www.palmos.com/dev/.
1. Palm has also reserved 'pqa '.