Structure of a Palm Application, Part 1

Chapter 5
Structure of an Application

Before you can write a Palm application, you need to know how it interacts with the OS and how it is organized. Prior to this discussion, we cover the standard terminology and naming conventions within the Palm OS. Once you know what the words mean, we can talk about the application and the OS.

We start with a discussion of how an application is structured to run on the Palm OS. You will learn that a Palm application is an event-driven system and that its routines are structured to handle various types of events. We will describe an application's life cycle--its starting, running, and closing. To help solidify your understanding of these points, we provide a simple application, OReilly Starter, which is a prototypical Palm application. We walk you through its organization (for example, its source files, utility files, and so on) and then show you the source code in its routines. While the application doesn't do much, it contains all of the standard routines and has the correct structure for any Palm application. You can use it as the starting point for your own work.

Typically, an application launches when a user opens it; you will learn how to handle this. We will also discuss other times the OS may access an application and what you need to do about it. These instances require you to structure your application so that it can provide information or launch as necessary. Lastly, there are some tricks you might want to add that allow shortcut access from within your application (for example, a hard button). Or, you might want to be a tyrant and take over the unit completely, denying access to other applications while your application is running.

Terminology

Like every operating system, the Palm OS has it own set of necessary terminology for you to learn. Much of it may be familiar to you already from other systems on which you have worked. We suggest that you skim through the list and concentrate on the items that are new to you. New and unique terms are listed first.

Form

An application form (what many people would think of as a window) that usually covers the entire screen (modal forms cover only the bottom part of the screen, however). A form optionally contains controls, text areas, and menus. In a Palm OS application there is only one active form allowed at a time. Chapter 8 covers forms in detail.

A rectangular area in which things like dialog boxes, forms, and menus are drawn by the application. The Window Manager makes sure that windows display properly relative to each other (for example, it has the ability to restore the old contents when a window is closed).

Database

A collection of persistent memory chunks. There are two kinds:

Resource

A piece of data stored in a resource database. Each resource is identified by a resource type and number. Note that a Palm application is simply a collection of resources. Chapter 8 covers resources in more detail.

Record

A memory chunk identified by a unique record ID located in a database. Applications typically store data in record databases.

Event

A data structure that describes things that happen in an application. These can be low-level hardware events such as a pen down, pen up, or hardware key press. They can also be higher-level events such as a character entry, a menu item selection, or a software button press.

The Palm OS is an event-driven system. Only one application is open at a time. When that application is running, it runs an event loop that retrieves events and continues to handle them until the user starts another application.

Main event loop

The main loop of execution in an application that repeatedly retrieves events, and then acts on them.

Launch code

A parameter passed to an application that specifies what the application should do when that particular launch code is executed. An application typically handles more than one launch code. This is the communication method used between the OS and a non-running application and between applications.

Menu

Menus are stored in resources grouped together into menu bars and are displayed when the user taps the menu area. See Chapter 11 for more details.

Menu bar

A collection of menus stored in a resource. Each form can have a menu bar associated with it.

Dialog box

A window containing controls that require the user to make a decision. In other words, the dialog box must be dismissed (usually by tapping on one of its buttons) before the application can continue.

Alert

A simple dialog box with only an icon, text, and buttons.

Palm OS Conventions

There are also a variety of Palm coding conventions that are useful to know. There are type conventions and standard naming practices for everything from functions to managers. It is worth getting a clearer idea of what these are before wading knee-deep into your first coding project. These are the ones you should learn.

Types

Here are the main types used by the Palm OS:

UInt32

An unsigned 32-bit integer.

Int32

A signed 32-bit integer.

UInt16

An unsigned 16-bit integer.

Int16

A signed 16-bit integer.

UInt8

An unsigned 8-bit integer.

Int8

A signed 8-bit integer.

Boolean

A 1-byte true or false value.

Char

A 1-byte character that will only work on systems with 1-byte encodings.

WChar

A 2-byte character suitable for all encodings (including for Japanese, Chinese, and so on).

Err

A 2-byte integer used for errors. The value errNone signifies no error.

Coord

A signed 2-byte integer used to represent a screen or window coordinate.

MemPtr

Specifies a (4-byte) pointer to an allocated chunk in memory.

MemHandle

A (4-byte) reference to a relocatable chunk of memory (see Chapter 6 for more details).

Function and Manager Naming Conventions

The Palm OS uses mixed-case for names, with an initial uppercase for functions and types. Constants and enumerations begin with lowercase letters. The following snippet of code shows the conventions in action (emphasis shows functions, types, and enumerations):

The Palm OS is divided into functional areas called managers. Each manager has its own header file (for example Form.h). Every routine in that manager usually begins with a manager abbreviation (for example: EvtGetEvent is part of the Event Manager, declared in Event.h; FrmGotoForm is part of the Form Manager, declared in Form.h). Table 5-1 contains example abbreviations.