palm os programming

www.it-ebooks.info

201 West 103rd Street, Indianapolis, Indiana 46290

Palm OS

Programming

Glenn Bachmann

00 413x fm 10/2/02 4:10 PM Page i

www.it-ebooks.info

Palm OS Programming

Copyright  2003 by Sams Publishing

All rights reserved. No part of this book shall be reproduced, stored

in a retrieval system, or transmitted by any means, electronic,

mechanical, photocopying, recording, or otherwise, without

written permission from the publisher. No patent liability is

assumed with respect to the use of the information contained

herein. Although every precaution has been taken in the prepara￾tion of this book, the publisher and author assume no responsibil￾ity for errors or omissions. Nor is any liability assumed for damages

resulting from the use of the information contained herein.

International Standard Book Number: 0-672-32413-X

Library of Congress Catalog Card Number: 2002100932

Printed in the United States of America

First Printing: October 2002

05 04 03 02 4 3

2 1

Trademarks

All terms mentioned in this book that are known to be trademarks

or service marks have been appropriately capitalized. Sams

Publishing cannot attest to the accuracy of this information. Use of

a term in this book should not be regarded as affecting the validity

of any trademark or service mark.

Warning and Disclaimer

Every effort has been made to make this book as complete and as

accurate as possible, but no warranty or fitness is implied. The

information provided is on an “as is” basis. The authors and the

publisher shall have neither liability nor responsibility to any

person or entity with respect to any loss or damages arising from

the information contained in this book.

Associate Publisher

Michael Stephens

Acquisitions Editor

Michelle Newcomb

Development Editor

Mark Renfrow

Managing Editor

Charlotte Clapp

Project Editor

Matthew Purcell

Copy Editor

Kezia Endsley

Indexer

Larry Sweazy

Proofreader

Abby Vanhuss

Suzanne Thomas

Technical Editor

Jeff Pajor

Team Coordinator

Lynne Williams

Interior Designer

Gary Adair

Cover Designer

Alan Clements

Page Layout

Michelle Mitchell

Graphics

Steve Adams

Tammy Graham

Oliver Jackson

Laura Robbins

00 413x fm 10/2/02 4:10 PM Page ii

www.it-ebooks.info

Contents at a Glance

Introduction .................................................................................................1

Part I Getting Started with Palm Programming 5

1 Introduction to Palm Programming and CodeWarrior.......................... 7

2 Anatomy of a Palm Application...................................................... 17

3 Rapid Development Using POSE, the Palm OS Emulator..................... 43

4 Debugging Techniques for Palm Applications.................................... 55

5 Creating and Managing Resources................................................... 67

Part II Programming the Palm User Interface 75

6 Interacting with the User: Forms..................................................... 77

7 Form Elements ............................................................................ 97

8 Button Controls ......................................................................... 103

9 Labels and Fields ........................................................................ 121

10 Giving the Users a Choice: Lists and Pop-up Triggers ........................ 131

11 Tables ....................................................................................... 153

12 Menus ...................................................................................... 177

13 Drawing Graphics....................................................................... 193

14 Handling Pen Events................................................................... 213

15 Adding Color to Palm Applications ............................................... 225

Part III Memory, Databases, and Files 237

16 Palm OS Memory Management..................................................... 239

17 Understanding Palm OS Databases ................................................ 245

18 Palm Databases and Record Management ....................................... 255

19 Categories ................................................................................. 273

20 Expansion Memory Cards and the Virtual File System ...................... 299

Part IV Communications 329

21 Serial Communications ............................................................... 331

22 Infrared Communications: OBEX and Exchange Manager ................. 349

23 Using the Infrared Library............................................................ 365

00 413x fm 10/2/02 4:10 PM Page iii

www.it-ebooks.info

24 A Survey of Wireless Options for Palm Developers ........................... 377

25 Palm.NET and Web Clipping ........................................................ 387

26 Using TCP/IP and Net.lib............................................................. 403

Part V Advanced Topics 423

27 Overview of Conduits ................................................................. 425

28 Programming Palm OS Conduits ................................................... 431

29 Shared Libraries: Extending the Palm OS ........................................ 461

30 Other Advanced Project Types: Multi-Segment and Static Libraries...... 481

31 Saving Program State: Application Preferences ................................. 489

32 Palm OS 5 and ARM: Looking into the Future ................................. 495

Index ....................................................................................... 503

00 413x fm 10/2/02 4:10 PM Page iv

www.it-ebooks.info

Table of Contents

Introduction 1

Part I Getting Started with Palm Programming 5

1 Introduction to Palm Programming and CodeWarrior 7

The Palm Computing Platform......................................................... 9

What Is a Palm Application? .......................................................... 10

How Are Palm Applications Written?............................................... 11

CodeWarrior and Development Tool Choices.................................... 12

PRC-Tools ........................................................................... 12

Falch.net............................................................................. 13

AppForge ............................................................................ 13

NS Basic.............................................................................. 13

Satellite Forms ..................................................................... 13

What Tool Is Best for You? ............................................................. 13

Tools Used in This Book ................................................................ 14

The Palm SDK ............................................................................. 15

Summary.................................................................................... 15

2 Anatomy of a Palm Application 17

PilotMain and the Smallest Palm Program Ever ................................. 17

Launch Codes...................................................................... 18

Checking the Palm OS Version ............................................... 19

The Main Form............................................................................ 21

Events ................................................................................ 22

The Main Form Handler ........................................................ 25

Hello Palm! ................................................................................. 26

The Source Code .......................................................................... 27

Creating a CodeWarrior Project for “Hello Palm”............................... 37

Creating a GCC Project for “Hello Palm” ......................................... 39

Building and Running “Hello Palm”................................................ 40

Summary.................................................................................... 41

00 413x fm 10/2/02 4:10 PM Page v

www.it-ebooks.info

3 Rapid Development Using POSE, the Palm OS Emulator 43

Where to Get POSE ...................................................................... 44

ROM Images................................................................................ 44

Where to Get ROMs.............................................................. 45

The Different Kinds of ROMs.................................................. 46

Skins .......................................................................................... 46

Creating, Loading, and Saving POSE Sessions.................................... 47

Installing Applications and Databases .............................................. 49

Taking Screenshots ....................................................................... 49

Creating a Bound Copy of POSE ..................................................... 50

Advanced POSE Techniques ........................................................... 50

POSE Warnings and Error Messages ......................................... 51

Logging .............................................................................. 51

Profiling ............................................................................. 52

TCP/IP and Serial Communications Support ............................. 52

Gremlins............................................................................. 52

The OS 5 Simulator ...................................................................... 53

Summary.................................................................................... 54

4 Debugging Techniques for Palm Applications 55

Why Palm Debugging Is Different................................................... 56

Defensive Programming ................................................................ 56

Effective Debugging Techniques for the Palm.................................... 57

The Palm Error Manager........................................................ 57

FrmCustomAlert ................................................................... 58

Logging .............................................................................. 59

The CodeWarrior Debugger............................................................ 60

A Debugging Session............................................................. 60

Setting Breakpoints ............................................................... 61

Stepping Through Code......................................................... 62

Debugging to a Palm Device................................................... 62

Other Debugging Tools ................................................................. 63

Using Gremlins to Find Problems.................................................... 63

Summary.................................................................................... 64

5 Creating and Managing Resources 67

What Is a Palm Resource? .............................................................. 68

Why Use Constructor? .................................................................. 68

Why Use PilRC?........................................................................... 68

vi Palm OS Programming

00 413x fm 10/2/02 4:10 PM Page vi

www.it-ebooks.info

Creating a Resource Project File ...................................................... 69

Creating Resources in Constructor........................................... 69

What’s a Resource Fork? ........................................................ 70

Version-Control Considerations in Constructor ......................... 71

A Constructor Example: “Hello Palm” Revisited......................... 71

A PilRC Example: “Hello Palm” Revisited ................................. 72

Summary.................................................................................... 74

Part II Programming the Palm User Interface 75

6 Interacting with the User: Forms 77

The Palm User Interface ................................................................ 78

What Is a Form? .......................................................................... 79

Examples of Forms in the Built-in Palm Applications.................. 79

Programming with Forms .............................................................. 80

Alerts ................................................................................. 81

Custom Forms ..................................................................... 86

Using Forms to Capture User Input ................................................. 90

More Complex Forms: Event Handlers ............................................. 92

Summary.................................................................................... 95

7 Form Elements 97

What Kinds of Form Elements Are Available?.................................... 98

Buttons............................................................................... 98

Input Fields ......................................................................... 99

Labels................................................................................. 99

Lists ................................................................................... 99

Triggers ............................................................................. 100

Tables ............................................................................... 101

Custom Gadgets ......................................................................... 101

Summary .................................................................................. 102

8 Button Controls 103

What Is a Control Object? ........................................................... 103

Types of Control Objects...................................................... 104

What Is a Button?....................................................................... 105

Types of Buttons................................................................. 105

Guidelines for the Use of Buttons.................................................. 107

General Guidelines on Buttons ..................................................... 108

Contents vii

00 413x fm 10/2/02 4:10 PM Page vii

www.it-ebooks.info

Using Buttons in Your Application ................................................ 108

A Simple Survey Application ........................................................ 108

Grouped Push Buttons......................................................... 109

Repeating Buttons and the Arrow Increment ........................... 109

Initializing the Form ........................................................... 118

Trapping Control Events ...................................................... 119

Summary .................................................................................. 120

9 Labels and Fields 121

Form Labels ............................................................................... 122

Input Fields ............................................................................... 122

Using Constructor to Create Labels and Fields ................................. 123

Using Labels and Fields in Your Application.................................... 125

Just What the Doctor Ordered ...................................................... 126

Summary .................................................................................. 130

10 Giving the Users a Choice: Lists and Pop-up Triggers 131

Lists in the Palm Environment ..................................................... 132

Examples of Lists in Action on the Palm................................. 132

Pop-up Lists ....................................................................... 132

Guidelines for Using Lists in an Application.................................... 133

Creating List Resources ................................................................ 133

Usable .............................................................................. 134

Visible Items ...................................................................... 134

List Items .......................................................................... 134

Creating Pop-up List Resources ..................................................... 135

Adding List and Pop-up List Handling to Your Application................ 136

More Complex Handling—Drawing Your Own List................... 137

More Complex Handling—Trapping List Events ....................... 138

Pop-up List Handling .......................................................... 138

A Shopping List Revisited............................................................. 138

Summary .................................................................................. 151

11 Tables 153

What Is a Table?......................................................................... 153

Table Functionality ..................................................................... 154

When to Use Tables Instead of Lists ............................................... 154

Adding Tables to Your Program..................................................... 155

Table Initialization.............................................................. 156

Table View Management...................................................... 157

00 413x fm 10/2/02 4:10 PM Page viii

www.it-ebooks.info

Table Data Mapping ............................................................ 159

Table Drawing.................................................................... 161

Putting It All Together: FishTable .................................................. 164

Tables and Databases................................................................... 175

Summary .................................................................................. 176

12 Menus 177

What Is a Menu? ........................................................................ 178

Menus in Action on the Palm ............................................... 178

Menu Nomenclature ........................................................... 179

Guidelines for Menu Usage .......................................................... 180

Using Constructor to Create Menus ............................................... 181

Handling Menu Events in Your Application .................................... 183

Summary .................................................................................. 191

13 Drawing Graphics 193

The Palm Display ....................................................................... 193

Screen Sizes ....................................................................... 194

Color and Grayscale ............................................................ 194

Palm OS Graphics Primitives ........................................................ 195

Lines ................................................................................ 195

Fill Patterns ....................................................................... 196

Rectangles ......................................................................... 196

Drawing Text ..................................................................... 197

Bitmaps............................................................................. 197

The Palm OS Window Model........................................................ 197

What Is a Window?............................................................. 197

Creating a Window............................................................. 198

Multiple Windows .............................................................. 199

PalmDraw: A Graphics-Drawing Demonstration Program .................. 199

Setting Up for Multiple Windows .......................................... 207

The Line-Drawing and Rectangle-Drawing Windows................. 208

The Text-Drawing Window................................................... 209

The Bitmap-Drawing Window............................................... 210

Summary .................................................................................. 211

14 Handling Pen Events 213

What Is a Pen Event? .................................................................. 214

How Pen Events and Control Events Coexist................................... 214

Pen Events and Graffiti................................................................ 214

00 413x fm 10/2/02 4:10 PM Page ix

www.it-ebooks.info

x Palm OS Programming

Doodle: Creating a Pen-Drawing Program....................................... 215

Even More Fun: Tic-Tac-Toe.......................................................... 222

Summary .................................................................................. 224

15 Adding Color to Palm Applications 225

Color and Bits............................................................................ 226

Color and User Interface Elements................................................. 226

General User Interface Elements ............................................ 227

Menus .............................................................................. 227

Input Fields ....................................................................... 227

Forms and Dialogs .............................................................. 228

Alerts................................................................................ 228

RGB Values, the Palette, and the Color Table................................... 228

Setting the Color of Your User Interface Elements ............................ 228

Using Color with Drawing Routines............................................... 229

Letting Users Pick a Color............................................................ 230

Putting Colors to Work: The ColorTest Sample ............................... 231

Summary .................................................................................. 236

Part III Memory, Databases, and Files 237

16 Palm OS Memory Management 239

Overview of the Palm OS Memory Manager.................................... 240

Memory Cards versus Expansion Cards .................................. 240

Data Storage, Heap Size, and Dealing with Memory

Constraints ...................................................................... 240

The Persistence of Memory................................................... 242

Allocating and Using Memory ...................................................... 242

Memory Allocation Functions....................................................... 243

Handle Functions ............................................................... 243

Pointer Functions ............................................................... 243

Memory Manipulation ................................................................ 244

Summary .................................................................................. 244

17 Understanding Palm OS Databases 245

The Palm Database Model............................................................ 246

What Is a Database? ............................................................ 246

What Is a Record? ............................................................... 246

The Palm Data Manager .............................................................. 247

00 413x fm 10/2/02 4:10 PM Page x

www.it-ebooks.info

Using the Data Manager to Create and Manipulate Databases ............ 247

How Do I Create a Database? ................................................ 247

Using Databases ................................................................. 248

Browsing Palm Databases with DBBrowse ....................................... 249

Summary .................................................................................. 253

18 Palm Databases and Record Management 255

How Are Databases and Records Connected?................................... 255

Using the Data Manager with Records............................................ 256

Querying Database Records .......................................................... 257

Manipulating Database Records .................................................... 258

Creating a Record ............................................................... 258

Modifying a Record............................................................. 258

Deleting a Record ............................................................... 259

Getting Record Information ................................................. 259

Fish List: A Record Management Sample Application........................ 259

Summary .................................................................................. 272

19 Categories 273

What Is a Category?.................................................................... 273

Palm SDK Support for Categories .................................................. 275

How to Add Category Support to Your Application .......................... 275

Preparing Your Database for Categories................................... 275

Adding Category Awareness to Your Database Calls .................. 277

Supporting Categories in Your User Interface........................... 277

Adding Categories to the Fish List Application: What Kind of

Fish Was That?......................................................................... 278

Summary .................................................................................. 298

20 Expansion Memory Cards and the Virtual File System 299

A Brief History of Memory Storage on Palm-Powered Handhelds ........ 300

A Proliferation of Standards.......................................................... 301

Palm’s Initial Rollout................................................................... 302

Palm OS 4.0 and VFS, the Virtual File System .................................. 303

A Brief History of Expansion Support in Palm OS............................. 305

Enter VFS, the Virtual File System.................................................. 306

VFS and Developers .................................................................... 307

Volumes, Slots, and Cards .................................................... 307

Cards and Directories .......................................................... 308

Contents xi

00 413x fm 10/2/02 4:10 PM Page xi

www.it-ebooks.info

The VFS and Expansion Manager APIs.................................... 310

Enumerating Files and Folders .............................................. 311

Reading and Writing Files .................................................... 314

Copying Files ..................................................................... 315

VFSBrowser: A Simple Card Explorer Utility ............................ 315

Testing and Debugging a VFS Application ............................... 327

Summary .................................................................................. 328

Part IV Communications 329

21 Serial Communications 331

The Serial Port Hardware ............................................................. 332

The Serial Communications Software............................................. 332

Serial Manager Essentials ............................................................. 333

Opening the Port................................................................ 333

Closing the Port ................................................................. 334

SerGetSettings and SerSetSettings ..................................... 334

SerReceiveFlush ................................................................ 335

SerReceiveCheck ................................................................ 335

SerReceive ........................................................................ 336

SerReceiveWait.................................................................. 336

SerSend............................................................................. 337

SerSendWait ...................................................................... 337

PalmTalk: A Palm OS Serial Terminal Application............................. 337

Summary .................................................................................. 348

22 Infrared Communications: OBEX and Exchange Manager 349

What Is Exchange Manager?......................................................... 350

Client and Server Roles................................................................ 351

Using Exchange Manager............................................................. 352

A Sample Application Overview ............................................ 352

The Object Registration Model.............................................. 353

Data Structures................................................................... 354

Launch Codes .................................................................... 357

Receiving Objects ............................................................... 359

Sending Objects.................................................................. 360

Exchanging Databases ......................................................... 362

Targeting a Specific Application............................................. 362

The Send Paradigm—Beyond Infrared .................................... 362

Summary .................................................................................. 363

xii Palm OS Programming

00 413x fm 10/2/02 4:10 PM Page xii

www.it-ebooks.info

23 Using the Infrared Library 365

The IrDA Standard...................................................................... 366

Palm OS IR Capabilities ....................................................... 367

Implementing Infrared Connectivity in a Palm Application............... 369

IrDemo: Building a Palm OS IR Application .................................... 375

Summary .................................................................................. 375

24 A Survey of Wireless Options for Palm Developers 377

Options for Wireless Communication ............................................ 378

Short-Range Options ........................................................... 378

Wide Area Wireless Options.................................................. 381

The Developer’s Perspective.......................................................... 383

TCP/IP .............................................................................. 383

Web Clipping..................................................................... 384

Exchange Manager.............................................................. 384

Infrared Library .................................................................. 384

SMS and Telephony............................................................. 385

Summary .................................................................................. 385

25 Palm.Net and Web Clipping 387

The Palm Difference ................................................................... 388

The Problem with Wireless Internet Connectivity ............................ 388

Enter Web Clipping and Palm.Net................................................. 390

Palm.Net........................................................................... 390

Content Providers............................................................... 390

Palm Query Applications ..................................................... 391

The Developer Perspective ........................................................... 391

Integration with Existing Applications ................................... 391

iMessenger Integration ........................................................ 392

What Is a Web Clipping Application? ............................................ 392

Design Guidelines for PQAs.......................................................... 393

Size of Content .................................................................. 393

HTML............................................................................... 394

Images .............................................................................. 394

Hyperlinks......................................................................... 395

The Clipper History List....................................................... 395

Customizing the User’s Experience ........................................ 396

Launching Other Applications .............................................. 396

Contents xiii

00 413x fm 10/2/02 4:10 PM Page xiii

www.it-ebooks.info

Steps Involved in Creating a PQA.................................................. 396

A Sample PQA: Palm Programming Information Kiosk........................ 397

Summary .................................................................................. 401

26 Using TCP/IP and Net.lib 403

The Palm OS Network Stack ......................................................... 403

Connectivity Options and the Preferences Panel.............................. 405

The Net.lib Development Environment.......................................... 406

Using the Network Library ........................................................... 407

Loading and Opening Net.lib................................................ 407

Closing the Library ............................................................. 408

Data Structures and API Conventions..................................... 408

TCP Sockets—Streams.......................................................... 410

Domain Lookup and Connection .......................................... 411

Sending and Receiving Over a Socket Connection .................... 412

Servicing Multiple Connections—NetLibSelect....................... 414

Server Mode and NetLibSelect ............................................. 418

UDP Sockets—Datagrams ..................................................... 418

Creating UDP Sockets .......................................................... 419

Sending and Receiving......................................................... 419

Roadmap to Sample Applications .................................................. 421

Summary .................................................................................. 422

Part V Advanced Topics 423

27 Overview of Conduits 425

What Is a Conduit?..................................................................... 427

Data Mirroring ................................................................... 427

One Directional.................................................................. 427

Transaction Based ............................................................... 428

Backup.............................................................................. 428

How Does Hot-Sync Interact with Conduits?................................... 428

How to Obtain the Conduit SDK................................................... 429

Development Tools and Programming Environment ........................ 429

Other Conduit Development Options ............................................ 430

Summary .................................................................................. 430

xiv Palm OS Programming

00 413x fm 10/2/02 4:10 PM Page xiv

www.it-ebooks.info