1 Programming Palm OS in a Nutshell

This chapter is the place to start if you're new to Palm programming. It summarizes what's unique about writing applications for Palm Computing^® platform 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
  
  
• Programming Tools
  
  
• Where to Go From Here
  

Read this chapter for a high-level introduction to Palm 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. Writing applications for handhelds, specifically Palm Computing platform devices, is a bit different from writing desktop applications because the Palm Computing platform device is designed differently than a desktop computer. Also, users simply interact with the device differently than they do desktop computers.

This section describes how these differences affect the design of a Palm OS^® application.

Screen Size

The Palm OS device's screen is only 160x160 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 section "User Interface Guidelines" in the chapter "Good Design Practices" for more detailed guidelines on designing the user interface.

Note that screen sizes of future Palm OS devices may vary.

Quick Turnaround Expected

On a PC, users don't mind waiting a few seconds while an application loads because they plan to use the application for an extended amount of time.

By contrast, the average Palm user uses a Palm application 15 to 20 times per day for much briefer periods of time, usually just a few seconds. Speed is therefore a critical design objective for hand-held organizers 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. (Also consider that the Palm OS does not provide a wait cursor.)

To maximize performance, the user interface should minimize navigation between windows, opening of dialog boxes, 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 (MemoPad, Address Book, etc.). These guidelines are summarized in the chapter "Good Design Practices" in this book.

PC Connectivity

PC connectivity is an integral component of the Palm Computing platform device. The device comes with a cradle 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 with 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 must 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 hand-held device. To write a conduit, you use the Conduit SDK, which provides its own documentation.

Input Methods

Handheld users don't have a keyboard or mouse. Users enter data into the device using a pen. They can either write Graffiti^® strokes or use the keyboard dialog provided on the device.

While Graffiti strokes and the keyboard dialog 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.

Power

The Palm Computing platform device runs on batteries and thus does not have the same processing power as a desktop PC. It is intended as a satellite viewer for corresponding desktop applications.

If your application needs to perform a computationally intensive task, you should implement that task in the desktop application instead of the device application.

Memory

The Palm OS device has limited heap space and storage space. Different versions of the device have between 512K and 8MB total of dynamic memory and storage available. The device does not have a disk drive or PCMCIA support.

Because of the limited space and power, optimization is critical. To make your application as fast and efficient as possible, optimize for heap space first, speed second, code size third.

File System

Because of the limited storage space, and to make synchronization with the desktop computer more efficient, 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.

Backward Compatibility

Different versions of the Palm Computing platform device are available, and each runs a different version of the Palm OS. Users are not expected to upgrade their versions of the Palm OS as rapidly as they would an operating system on a desktop computer. Updates to the OS are designed in such a way that you can easily maintain backward compatibility with previous versions of the OS, and thus, your application is available to more users. See "Making Your Application Run on Different Devices" in the chapter "Good Design Practices" for details.

Palm OS Programming Concepts

Palm OS applications are generally single-threaded, event-driven programs. Only one program runs 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 to main in C programs. To launch an application, the system calls PilotMain 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 3, "Application Startup and Stop.")

  
  
• Palm OS is an event-based operating system, so Palm OS applications 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 4, "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 Chapter 5, "User Interface.")
  
  
• All applications should use the memory and data management facilities provided by the system. (See Chapter 6, "Memory." and Chapter 7, "Files and Databases.")
  
  
• You implement an application's features 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 Table of Contents of this guide.

  
  

  ---

  
  IMPORTANT: The ANSI C libraries are not part of the Palm development platform. In many cases, you can perform the same function using a Palm OS API call as you can with a call to a ANSI C function. For example, the Palm OS provides a string manager that performs many of the string functions you'd expect to be able to perform in an ANSI C program. If you do use a standard C function, the code for the function is linked into your application and results in a bigger executable.
  

  ---

  
  

Programming Tools

Several tools are available that help you build, test, and debug Palm OS applications. The most widely used tool is the CodeWarrior Interactive Development Environment (IDE) from 3Com^® Corporation. Documentation for the CodeWarrior IDE is provided with CodeWarrior. (See http://www.palm.com for information about other development tools.)

As with most applications, the user interface is generally stored in one or more resource files. You use the Palm OS Constructor to create these resources. To learn how, refer to the Constructor documentation.

To debug and test your application, there are several tools available:

• The CodeWarrior Debugger handles source-level debugging. You can use it with an application running on the Palm OS device, or you can use it in conjunction with one of the other debugging tools below.
  
  
• The Palm OS Emulator (POSE) tests your application on the desktop computer before downloading it onto the device.
  
  
• On the Macintosh, you can build a Simulator version of your application to test it. This is a standalone Mac OS application that runs your Palm OS application on a Macintosh computer.
  
  
• The Palm Debugger is an assembly-level tool. You can also use it to enter commands directly to the Palm device.
  

The book Palm OS Programming Development Tools Guide describes the Palm-provided debugging tools available on your development platform. For CodeWarrior Debugger documentation, refer to the CodeWarrior CD.

Where to Go From Here

This chapter provided you only with a general outline of the issues involved in writing a Palm OS application. To learn the specifics, refer to the following resources:

• This book
  

  The rest of this book provides details on how to implement common application features using the Palm OS SDK. If you're new to Palm OS programming, you need to read the next three chapters to learn the principles of Palm OS application and UI design, how to implement the main function, and how to implement the standard event loop. The remaining chapters you can read on an as-needed basis.

  
  
• Example applications
  

  The actual source code for the applications on the Palm OS device is included as examples on your SDK CD. The code can be a valuable aid when you develop your own program. 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.

  
  
• Palm OS Programming Development Tools Guide
  

  The Palm OS Programming Development Tools Guide provides more details on using the tools to debug programs. (You might also be interested in the "Debugging Strategies" chapter in this book, which describes programmatic debugging solutions.)

  
  
• Palm OS SDK Reference
  

  The reference book provides the details on all of the public data structures and API calls.

  
  
• Conduit Development Kits and documentation
  

  If you need to write a conduit for your application, see the documentation provided with the Conduit Development Kits.