About This Document

Palm OS SDK Documentation

What This Volume Contains

Additional Resources

1 Programming Palm OS in a Nutshell

Why Programming for Palm OS Is Different

Screen Size

Quick Turnaround Expected

PC Connectivity

Input Methods

Power

Memory

File System

Backward Compatibility

Palm OS Programming Concepts

API Naming Conventions

Integrating Programs with the Palm OS Environment

Writing Robust Code

Assigning a Database Type and Creator ID

Making Your Application Run on Different Devices

Running New Applications on an Older Device

Backward Compatibility with PalmOSGlue

Compiling Older Applications with the Latest SDK

Programming Tools

Palm OS Developer Suite

CodeWarrior

Palm OS Emulator

Palm OS Simulator

Where to Go from Here

2 Application Startup and Stop

Launch Codes and Launching an Application

Responding to Launch Codes

Responding to Normal Launch

Responding to Other Launch Codes

Launching Applications Programmatically

Creating Your Own Launch Codes

Stopping an Application

Notifications

Registering for a Notification

Writing a Notification Handler

Sleep and Wake Notifications

Helper Notifications

When to Use the Helper API

Requesting a Helper Service

Implementing a Helper

Socket Notifications

Launch Code Summary

Notification Summary

Launch and Notification Function Summary

3 Event Loop

The Application Event Loop

Low-Level Event Management

The Graffiti Manager

The Key Manager

The Pen Manager

The System Event Manager

Creating and Handling Custom Events

Custom Events and the Palm OS Event Queue

System Event Manager Summary

4 User Interface

Palm OS Resource Summary

Drawing on the Palm Powered Handheld

The Draw State

Drawing Functions

High-Density Displays

Forms, Windows, and Dialogs

Alert Dialogs

Progress Dialogs

The Keyboard Dialog

Offscreen Windows

Controls

Buttons

Pop-Up Trigger

Selector Trigger

Repeating Button

Push Buttons

Check Boxes

Sliders and Feedback Sliders

Fields

Menus

Checking Menu Visibility

Dynamic Menus

Menu Shortcuts

Tables

Table Event

Lists

Using Lists in Place of Tables

Categories

Initializing Categories in a Database

Initializing the Category Pop-up Trigger

Managing a Category Pop-up List

Bitmaps

Versions of Bitmap Support

Bitmap Families

Drawing a Bitmap

Color Tables and Bitmaps

Labels

Scroll Bars

Custom UI Objects (Gadgets)

Dynamic UI

Dynamic User Interface Functions

Color and Grayscale Support

Indexed Versus Direct Color Display

Color Table

UI Color List

Direct Color Functions

Pixel Reading and Writing

Direct Color Bitmaps

Insertion Point

Application Launcher

Icons in the Launcher

Application Version String

The Default Application Category

Opening the Launcher Programmatically

Summary of User Interface API

5 Memory

Introduction to Palm OS Memory Use

Hardware Architecture

PC Connectivity

Memory Architecture

Heap Overview

The Memory Manager

Memory Manager Structures

Using the Memory Manager

Achieving Optimum Performance

Summary of Memory Management

6 Files and Databases

The Data Manager

Records and Databases

Structure of a Database Header

Using the Data Manager

Automatic Database Backup and Restore

Data Manager Tips

The Resource Manager

Structure of a Resource Database Header

Using the Resource Manager

File Streaming Application Program Interface

Using the File Streaming API

Summary of Files and Databases

7 Expansion

Expansion Support

Primary vs. Secondary Storage

Expansion Slot

Universal Connector

Architectural Overview

Slot Drivers

File Systems

VFS Manager

Expansion Manager

Standard Directories

Applications on Cards

Card Insertion and Removal

Start.prc

Checking for Expansion Cards

Verifying Handheld Compatibility

Checking for Mounted Volumes

Enumerating Slots

Determining a Card's Capabilities

Volume Operations

Hidden Volumes

Matching Volumes to Slots

Naming Volumes

File Operations

Common Operations

Naming Files

Working with Palm Databases

Directory Operations

Directory Paths

Common Operations

Enumerating the Files in a Directory

Determining the Default Directory for a Particular File Type

Default Directories Registered at Initialization

Custom Calls

Custom I/O

Debugging

Summary of Expansion and VFS Managers

8 Text

Text Manager and International Manager

Characters

Declaring Character Variables

Using Character Constants

Missing and Invalid Characters

Retrieving a Character's Attributes

Virtual Characters

Retrieving the Character Encoding

Strings

Manipulating Strings

Performing String Pointer Manipulation

Truncating Displayed Text

Comparing Strings

Global Find

Dynamically Creating String Content

Using the StrVPrintF Function

Fonts

Built-in Fonts

Selecting Which Font to Use

Fonts for High-Density Displays

Setting the Font Programmatically

Obtaining Font Information

Creating Custom Fonts

Summary of Text API

9 Applications and the Dynamic Input Area

The Dynamic Input Area Feature

Size Constraints

Input Area Policy

Setting the Input Area Policy

Enabling the Input Trigger

Setting an Input Area State

Resizing a Form

Hiding and Showing the Control Bar

Pen Input Manager Compatibility

New sysFtrNumInputAreaFlags Support

Additional winDisplayChangedEvent

Restoration of Input Trigger State

New pinInputAreaUser Input Area State

New Stat... Functions

New Support for Changing Display Orientation

10 Attentions and Alarms

Getting the User's Attention

The Role of the Attention Manager

Attention Manager Operation

Getting the User's Attention

Attentions and Alarms

Detecting and Updating Pending Attentions

Detecting Device Capabilities

Controlling the Attention Indicator

Alarms

Setting an Alarm

Alarm Scenario

Setting a Procedure Alarm

Summary of Attentions and Alarms

11 Palm System Support

Features

The System Version Feature

Application-Defined Features

Using the Feature Manager

Feature Memory

Preferences

Accessing System Preferences

Setting System Preferences

Setting Application-Specific Preferences

Sound

Simple Sound

Sampled Sound

Simple vs Sampled

Sound Preferences

Standard MIDI Files

Creating a Sound Stream

System Boot and Reset

Soft Reset

Soft Reset + Up Arrow

Hard Reset

System Reset Calls

Hardware Interaction

Palm OS Power Modes

Guidelines for Application Developers

Power Management Calls

The Microkernel

Retrieving the ROM Serial Number

Time

Using Real-Time Clock Functions

Using System Ticks Functions

Floating-Point

Summary of System Features

12 Localized Applications

Localization Guidelines

Using Overlays to Localize Resources

Dates

Numbers

Obtaining Locale Information

Notes on the Japanese Implementation

Japanese Character Encoding

Japanese Character Input

The Calculator Button

Displaying Japanese Strings on UI Objects

Displaying Error Messages

Chinese Fonts

Summary of Localization

13 Security

Certificate Manager

Certificate Store Operations

Certificate Verification and Parsing

Certificate Backup and Restore

14 Palm OS Garnet ARM Programming

Understanding Palm OS Garnet and ARM

Palm Application Compatibility Environment

Using ARM-Native Subroutines

Calling ARM-Native Subroutines

Writing ARM-Native Subroutines

Isolate the Performance-Critical Area in Your 68K Application

Convert the ARM-Native Subroutine to Take One Argument

Handle 68K and ARM Technical Differences

Test the ARM-Native Subroutine

Build the ARM-Native Subroutine

Embed the ARM Code in a 68K Application

Calling Palm OS Functions From ARM Code

Calling a Trap

Calling a Function Using a Function Pointer

Overview of Sample Files

ARM-Native Subroutine Sample Files

Windows DLL Sample Files

15 Debugging Strategies

Displaying Development Errors

Using the Error Manager Macros

The Try-and-Catch Mechanism

Using the Try and Catch Mechanism

Using the ARM Debug Nub

Activating the ARM Debugger Nub

Register with Palm OS Debugger

Summary of Debugging API

16 Standard IO Applications

Creating a Standard IO Application

Creating a Standard IO Provider Application

Summary of Standard IO