Tài liệu Alm os programming bible docx

Palm OS
®
Programming Bible
4676-7 FM.f.qc 10/16/00 9:59 AM Page i
4676-7 FM.f.qc 10/16/00 9:59 AM Page ii
Palm OS
®
Programming Bible
Lonnon R. Foster
IDG Books Worldwide, Inc.
An International Data Group Company
Foster City, CA ✦ Chicago, IL ✦ Indianapolis, IN ✦ New York, NY
4676-7 FM.f.qc 10/16/00 9:59 AM Page iii
Palm OS
®
Programming Bible
Published by
IDG Books Worldwide, Inc.
An International Data Group Company
919 E. Hillsdale Blvd., Suite 400
Foster City, CA 94404
www.idgbooks.com
(IDG Books Worldwide Web site)
Copyright © 2000 IDG Books Worldwide, Inc. All
rights reserved. No part of this book, including
interior design, cover design, and icons, may be
reproduced or transmitted in any form, by any means
(electronic, photocopying, recording, or otherwise)
without the prior written permission of the publisher.
ISBN: 0-7645-4676-7
Printed in the United States of America

10 9 8 7 6 5 4 3 2 1
1B/QW/RR/QQ/FC
Distributed in the United States by IDG Books
Worldwide, Inc.
Distributed by CDG Books Canada Inc. for Canada;
by Transworld Publishers Limited in the United
Kingdom; by IDG Norge Books for Norway; by IDG
Sweden Books for Sweden; by IDG Books Australia
Publishing Corporation Pty. Ltd. for Australia and
New Zealand; by TransQuest Publishers Pte Ltd. for
Singapore, Malaysia, Thailand, Indonesia, and Hong
Kong; by Gotop Information Inc. for Taiwan; by ICG
Muse, Inc. for Japan; by Intersoft for South Africa;
by Eyrolles for France; by International Thomson
Publishing for Germany, Austria, and Switzerland;
by Distribuidora Cuspide for Argentina; by LR
International for Brazil; by Galileo Libros for Chile;
by Ediciones ZETA S.C.R. Ltda. for Peru; by WS
Computer Publishing Corporation, Inc., for the
Philippines; by Contemporanea de Ediciones for
Venezuela; by Express Computer Distributors for
the Caribbean and West Indies; by Micronesia
Media Distributor, Inc. for Micronesia; by Chips
Computadoras S.A. de C.V. for Mexico; by Editorial
Norma de Panama S.A. for Panama; by American
Bookshops for Finland.
For general information on IDG Books Worldwide’s
books in the U.S., please call our Consumer Customer
Service department at 800-762-2974. For reseller
information, including discounts and premium

sales, please call our Reseller Customer Service
department at 800-434-3422.
For information on where to purchase IDG Books
Worldwide’s books outside the U.S., please contact
our International Sales department at 317-596-5530
or fax 317-572-4002.
For consumer information on foreign language
translations, please contact our Customer Service
department at 800-434-3422, fax 317-572-4002, or
e-mail
For information on licensing foreign or domestic
rights, please phone +1-650-653-7098.
For sales inquiries and special prices for bulk
quantities, please contact our Order Services
department at 800-434-3422 or write to the
address above.
For information on using IDG Books Worldwide’s
books in the classroom or for ordering examination
copies, please contact our Educational Sales
department at 800-434-2086 or fax 317-572-4005.
For press review copies, author interviews, or
other publicity information, please contact our
Public Relations department at 650-653-7000 or
fax 650-653-7500.
For authorization to photocopy items for
corporate, personal, or educational use, please
contact Copyright Clearance Center, 222 Rosewood
Drive, Danvers, MA 01923, or fax 978-750-4470.
Library of Congress Cataloging-in-Publication Data
Foster, Lonnon R., 1972-

Palm OS programming Bible / Lonnon R. Foster.
p. cm.
ISBN 0-7645-4676-7 (alk. paper)
1. Palm OS. 2. PalmPilot (Computer)--Programming.
I. Title.
QA76.76.O63 F685 2000
005.26'8--dc21 00-044954
LIMIT OF LIABILITY/DISCLAIMER OF W
ARRANTY: THE PUBLISHER AND AUTHOR HAVE USED THEIR
BEST EFFORTS IN PREPARING THIS BOOK. THE PUBLISHER AND AUTHOR MAKE NO REPRESENTATIONS
OR WARRANTIES WITH RESPECT TO THE ACCURACY OR COMPLETENESS OF THE CONTENTS OF THIS
BOOK AND SPECIFICALLY DISCLAIM ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS
FOR A PARTICULAR PURPOSE. THERE ARE NO WARRANTIES WHICH EXTEND BEYOND THE
DESCRIPTIONS CONTAINED IN THIS PARAGRAPH. NO WARRANTY MAY BE CREATED OR EXTENDED BY
SALES REPRESENTATIVES OR WRITTEN SALES MATERIALS. THE ACCURACY AND COMPLETENESS OF
THE INFORMATION PROVIDED HEREIN AND THE OPINIONS STATED HEREIN ARE NOT GUARANTEED OR
WARRANTED TO PRODUCE ANY PARTICULAR RESULTS, AND THE ADVICE AND STRATEGIES CONTAINED
HEREIN MAY NOT BE SUITABLE FOR EVERY INDIVIDUAL. NEITHER THE PUBLISHER NOR AUTHOR
SHALL BE LIABLE FOR ANY LOSS OF PROFIT OR ANY OTHER COMMERCIAL DAMAGES, INCLUDING BUT
NOT LIMITED TO SPECIAL, INCIDENTAL, CONSEQUENTIAL, OR OTHER DAMAGES.
Trademarks: All brand names and product names used in this book are trade names, service marks,
trademarks, or registered trademarks of their respective owners. IDG Books Worldwide is not associated
with any product or vendor mentioned in this book.
is a registered trademark or trademark under exclusive license
to IDG Books Worldwide, Inc. from International Data Group, Inc.
in the United States and/or other countries.
4676-7 FM.f.qc 10/16/00 9:59 AM Page iv
Eleventh Annual
Computer Press
Awards 1995

Tenth Annual
Computer Press
Awards 1994
Eighth Annual
Computer Press
Awards 1992
Ninth Annual
Computer Press
Awards 1993
IDG is the world’s leading IT media, research and exposition company. Founded in 1964, IDG had 1997 revenues of $2.05
billion and has more than 9,000 employees worldwide. IDG offers the widest range of media options that reach IT buyers
in 75 countries representing 95% of worldwide IT spending. IDG’s diverse product and services portfolio spans six key areas
including print publishing, online publishing, expositions and conferences, market research, education and training, and
global marketing services. More than 90 million people read one or more of IDG’s 290 magazines and newspapers, including
IDG’s leading global brands — Computerworld, PC World, Network World, Macworld and the Channel World family of
publications. IDG Books Worldwide is one of the fastest-growing computer book publishers in the world, with more than
700 titles in 36 languages. The “...For Dummies
®
” series alone has more than 50 million copies in print. IDG offers online
users the largest network of technology-specific Web sites around the world through IDG.net (), which
comprises more than 225 targeted Web sites in 55 countries worldwide. International Data Corporation (IDC) is the world’s
largest provider of information technology data, analysis and consulting, with research centers in over 41 countries and more
than 400 research analysts worldwide. IDG World Expo is a leading producer of more than 168 globally branded conferences
and expositions in 35 countries including E3 (Electronic Entertainment Expo), Macworld Expo, ComNet, Windows World
Expo, ICE (Internet Commerce Expo), Agenda, DEMO, and Spotlight. IDG’s training subsidiary, ExecuTrain, is the world’s
largest computer training company, with more than 230 locations worldwide and 785 training courses. IDG Marketing
Services helps industry-leading IT companies build international brand recognition by developing global integrated marketing
programs via IDG’s print, online and exposition products worldwide. Further information about the company can be found
at www.idg.com. 1/26/00
Welcome to the world of IDG Books Worldwide.

IDG Books Worldwide, Inc., is a subsidiary of International Data Group, the world’s largest publisher of
computer-related information and the leading global provider of information services on information technology.
IDG was founded more than 30 years ago by Patrick J. McGovern and now employs more than 9,000 people
worldwide. IDG publishes more than 290 computer publications in over 75 countries. More than 90 million
people read one or more IDG publications each month.
Launched in 1990, IDG Books Worldwide is today the #1 publisher of best-selling computer books in the
United States. We are proud to have received eight awards from the Computer Press Association in recognition
of editorial excellence and three from Computer Currents’ First Annual Readers’ Choice Awards. Our best-
selling ...For Dummies
®
series has more than 50 million copies in print with translations in 31 languages. IDG
Books Worldwide, through a joint venture with IDG’s Hi-Tech Beijing, became the first U.S. publisher to
publish a computer book in the People’s Republic of China. In record time, IDG Books Worldwide has become
the first choice for millions of readers around the world who want to learn how to better manage their
businesses.
Our mission is simple: Every one of our books is designed to bring extra value and skill-building instructions
to the reader. Our books are written by experts who understand and care about our readers. The knowledge
base of our editorial staff comes from years of experience in publishing, education, and journalism —
experience we use to produce books to carry us into the new millennium. In short, we care about books, so
we attract the best people. We devote special attention to details such as audience, interior design, use of
icons, and illustrations. And because we use an efficient process of authoring, editing, and desktop publishing
our books electronically, we can spend more time ensuring superior content and less time on the technicalities
of making books.
You can count on our commitment to deliver high-quality books at competitive prices on topics you want
to read about. At IDG Books Worldwide, we continue in the IDG tradition of delivering quality for more than
30 years. You’ll find no better book on a subject than one from IDG Books Worldwide.
John Kilcullen
Chairman and CEO
IDG Books Worldwide, Inc.
4676-7 FM.f.qc 10/16/00 9:59 AM Page v

Credits
Acquisitions Editors
John Osborn
Greg Croy
Project Editor
Eric Newman
Technical Editor
JB Parrett
Copy Editors
Mildred Sanchez
S. B. Kleinman
Permissions Editor
Jessica Montgomery
Media Dev. Manager
Laura Carpenter
Media Dev. Supervisor
Rich Graves
Senior Permissions Editor
Carmen Krikorian
Media Dev. Coordinator
Marisa Pearman
Media Development Specialists
Megan Decraene
Brock Bigard
Project Coordinators
Joe Shines
Danette Nurse
Graphics and Production Specialists
Robert Bihlmayer
Jude Levinson

Michael Lewis
Victor Pérez-Varela
Ramses Ramirez
Quality Control Technician
Dina F Quan
Illustrators
Rashell Smith
Karl Brandt
Gabriele McCann
Proofreading and Indexing
York Production Services
Cover Image
Evan Deerfield
About the Author
Lonnon R. Foster is a freelance programmer who has spent the past seven years cre-
ating desktop applications, database front ends, Web sites, communications software,
technical documentation, and handheld applications. He has been developing Palm
OS applications almost as long as the platform has existed, starting with his first Pilot
5000. Lonnon fills his sparse free time with tactical tabletop gaming, recreational Perl
coding, and reading everything he can get his hands on.
4676-7 FM.f.qc 10/16/00 9:59 AM Page vi
For Elisabeth, who believed from the very start that I could do it
4676-7 FM.f.qc 10/16/00 9:59 AM Page vii
4676-7 FM.f.qc 10/16/00 9:59 AM Page viii
Foreword
I
n 1992, Palm Computing (now Palm, Inc.) was founded. The rest is history. Of
course, there’s a lot more to it. Many good decisions were made, and many bad
designs were thrown out. Palm started as a software company intending to influence
existing handheld manufacturers with its easy-to-use software and synchronization

technologies. The company soon realized two things. The first was that the hard-
ware manufacturers didn’t seem to believe in Palm’s philosophy. The second was
that it was difficult to make a viable business just writing software for this small
market. Palm realized that its first take at this company was not the right one and
decided to become the master of its destiny. The name was Pilot. Palm changed the
focus of its business virtually overnight. This is a lot like in development, where you
find that the first take is rarely the best one. I have often gone back through my code
and discovered some wacky designs. Only then do I discover the best architectural
design, giving me fewer bugs and the best feature set. In Palm, this is known as the
sweet spot and it is a zone that few developers enter and fewer leave successfully.
However, Palm not only entered this zone, it now owns it. This accounts for most
of Palm’s success. There are more powerful devices out there (PocketPC), and there
are more connected ones (Cybiko). Yet all of those devices combined still do not
add up to the amount of devices that Palm has shipped. Why? Because Palm has
found the sweet spot, the spot where functionality and ease of use conflict, and
difficult decisions are made to remove functionality (something that even Microsoft
hasn’t realized). Other companies have discovered this zone and understand what
is necessary in the handheld market. That’s the reason why these very wise compa-
nies have licensed the Palm OS. Companies like Sony, Handspring, and Symbol have
all realized the importance of Palm’s philosophy, where ease of use and power are
not necessarily mutually exclusive, and where the end-user experience is always
top notch.
At this writing, there are more than 100,000 Palm OS developers. This development
community is as diverse as the world of computing: from high school kids writing
in Basic to skilled university researchers writing in C, from enterprise developers
writing in Java to commercial developers writing in C++. From Iceland to Argentina,
these developers have realized not only that Palm is the best-selling handheld in
the world but also that the Palm OS is an open operating system, intuitive to pro-
gram and very clearly documented. I don’t expect to see developers evangelize
the virtues of Palm OS

®
Programming Bible, but they should. Lonnon Foster has
proven that he understands not only the fundamentals of Palm OS programming
4676-7 FM.f.qc 10/16/00 9:59 AM Page ix
x
Foreword
but the sweet spot of writing as well. This book covers everything from building
forms and menus to programming sounds and color. The examples are complete
yet amazingly simple. Not only will you learn to program the Palm OS, you will
understand the philosophy that has made Palm successful, and in doing so, I
hope that you will be successful too.
Phillip B. Shoemaker
Director, Development Tools
Palm, Inc.
4676-7 FM.f.qc 10/16/00 9:59 AM Page x
Preface
T
he convenience, power, and ease of use of Palm OS handheld devices make
them attractive to a wide variety of users. Handheld devices running the Palm
OS have found their way into the shirt pockets of doctors, lawyers, sales personnel,
business professionals, and other segments of society not normally given to using
small electronic gadgetry. With more than 100,000 registered developers, the Palm
OS has also proven to be popular with software authors, which is where this book
comes in.
Palm OS
®
Programming Bible will show you how to create applications for Palm’s
popular line of handheld organizers, as well as third-party devices that also run the
Palm OS. In addition, this book covers creation of Web clipping applications for the
Palm VII/VIIx (and other wireless-equipped Palm OS handhelds) to allow wireless

connection to the Internet. You will also find material on writing conduit programs
to synchronize data between a Palm OS handheld and a desktop computer.
Whether you are a developer for a large organization that is integrating Palm OS
handhelds into its sales force or a hobbyist who wants to get the most from your
organizer, you will find this book to be a useful guide to creating software for the
Palm OS platform.
The primary focus of this book is Palm OS development in the C language, using
CodeWarrior for Palm Computing Platform or the GNU PRC-Tools as a development
environment. Other tools exist for developing Palm OS applications (and an overview
of other such tools is available in the appendixes), but these two environments are
popular with the largest developer audience, and they offer the most complete
access to the many features of the Palm OS and the handhelds that run it.
Who Should Read This Book
This book was written with the experienced C programmer in mind. If you know
nothing at all about Palm OS programming, this book will get you started with the
fundamentals, teaching you how the Palm OS works, showing you the tools avail-
able for Palm OS development, and providing you with tips to make your own
applications work seamlessly within Palm’s programming guidelines.
Even if you already have delved into the world of creating Palm OS applications,
you will find this book a useful resource, because it covers almost every aspect of
Palm OS development in depth. The Palm OS is very large, and this book can serve
as a guide to exploring those parts of the operating system that you have not yet
dealt with.
4676-7 FM.f.qc 10/16/00 9:59 AM Page xi
xii
Preface
If you wish to create Web clipping applications for the Palm VII/VIIx, you will
need to know the basics of HTML and Web page creation to make the Palm Query
Applications (PQAs) that reside on the handheld and provide a client-side connec-
tion to the Internet. To create the server side of a Web clipping application, you

will need to be familiar with some sort of system for creating dynamic Web
content, such as Perl CGI or Active Server Pages.
Conduit programming requires knowledge of C++, as well as a working knowledge
of how to create desktop applications for either Windows or the Mac OS.
How This Book Is Organized
This book is organized into seven parts, plus four appendixes.
Part I: Getting Started
This first part of the book discusses the philosophy behind the Palm OS and intro-
duces fundamental concepts behind the inner workings of the operating system.
Part II: Creating Palm OS Applications
The chapters in Part II cover the mechanics of making a Palm OS application. This
section begins with a tour of the tools for Palm OS programming, then gets you
off the ground with a simple “Hello, world” application and finally presents tools
and techniques for every programmer’s favorite part of writing an application:
debugging.
Part III: Programming the Palm OS
The third part of this book focuses on actually writing the code to make a Palm OS
application work. Starting with chapters on creating the resources that form the
structure of an application, this part continues by showing how to actually make
the program do something, from interacting with the user to manipulating text.
Part IV: Storing Information on the Handheld
Part IV shows how to store and retrieve application data. It starts with the big
picture, showing how to interact with databases, then moves in for a closer look
at the records that make up a database.
4676-7 FM.f.qc 10/16/00 9:59 AM Page xii
xiii
Preface
Part V: Communicating Outside the Handheld
The chapters in Part V cover the myriad methods a Palm OS handheld can use to
communicate with the outside world, including infrared beaming, serial communi-

cation, and wireless Web clipping.
Part VI: Synchronizing Data with the Desktop
Part VI introduces the concepts behind the HotSync Manager, which allows a Palm
OS handheld to synchronize its applications with desktop data sources. The section
continues by showing how to write a conduit to customize the interaction between
a Palm OS database and desktop applications.
Part VII: Advanced Programming Topics
In Part VII you will find various topics that do not come up as often as do the others
in Palm OS programming, including managing color, creating large applications, and
creating user interface elements dynamically while an application is running.
Appendixes
The final section of the book is devoted to four appendixes:
✦ Appendix A, “Palm OS API Quick Reference,” is a quick guide to the most
common functions, data structures, and constants used in the Palm OS,
including prototypes for Palm OS functions.
✦ Appendix B, “Finding Resources for Palm OS Development,” is a list of
helpful resources for Palm OS developers.
✦ Appendix C, “Developing in Other Environments,” is a survey of alternative
tools for Palm OS development.
✦ Appendix D, “What’s on the CD-ROM?” describes the contents of the
CD-ROM that accompanies this book, which features sample code and
applications from the book, as well as all the tools a developer needs to
get started with Palm OS development.
In addition, I’ve included a glossary at the end of the book.
4676-7 FM.f.qc 10/16/00 9:59 AM Page xiii
xiv
Preface
How to Approach This Book
Readers who are completely new to Palm OS development will get the most benefit
from this book by reading Parts I and II first to get a good handle on how the Palm

OS works and how to use CodeWarrior or the PRC-Tools. Then look at Part III to
learn what to do with those tools to make an actual application, and follow up with
Part IV to learn how to save and retrieve an application’s data. The other parts of
the book may be read in any order; pick a topic of interest, and start reading.
For readers who have already done some Palm OS development, Part I probably will
be material you already know. Part II can be useful if you use either CodeWarrior or
the PRC-Tools, and you want to see how the other set of tools works in comparison
with what you are using, and in particular, Chapter 5, “Debugging Your Program,”
contains useful tips for any Palm OS developer. Parts III and IV will serve as useful
references to parts of the operating system that you may or may not already be
familiar with, and later chapters introduce other parts of the Palm OS that are
not strictly required by most applications.
Developers interested in creating Web clipping applications can go straight to
Chapter 16, “Creating Web Clipping Applications.” Most Web clipping development
requires only a working knowledge of HTML, and if you run across any Palm OS–
specific concepts you are not familiar with, a quick look through Part I should
serve to resolve any confusion.
Anyone interested in creating conduits should first be familiar with the conceptual
information in Part I. After you understand the concepts behind the Palm OS, turn
to Part VI to learn how to hook the Palm OS up to a desktop computer.
Conventions Used in This Book
Each chapter in this book begins with a heads-up of the topics covered in the
chapter and ends with a summary of what you should have learned by reading
the chapter.
Throughout this book, you will find icons in the margins that highlight special or
important information. Keep an eye out for the following icons:
A Caution icon indicates a procedure that could potentially cause difficulty or even
data loss; pay careful attention to Caution icons to avoid common and not-so-
common programming pitfalls.
Cross-Reference icons point to additional information about a topic, which you can

find in other sections of the book.
Cross-
Reference
Caution
4676-7 FM.f.qc 10/16/00 9:59 AM Page xiv
xv
Preface
A Note icon highlights interesting or supplementary information and often contains
extra bits of technical information about a subject.
The On the CD-ROM icon is a pointer to information, tools, or programs available
on the CD-ROM that accompanies this book.
Tip icons draw attention to handy suggestions, helpful hints, and useful pieces of
advice.
In addition to the icons listed previously, the following typographical conventions
are used throughout the book:
✦ Code examples appear in a
fixed width font
.
✦ Other code elements, such as data structures and variable names, appear
in
fixed width
.
✦ File names and World Wide Web addresses (URLs) also appear in
fixed width
.
✦ Function and macro names are in bold.
✦ The first occurrence of an important term in a chapter is highlighted with
italic text. Italic is also used for placeholders — for example,
ICON <icon
file name>

, where
<icon file name>
represents the name of a bitmap file.
✦ A menu command is indicated in hierarchical order, with each menu com-
mand separated by an arrow. For example, File ➪ Open means to click the
File command on the menu bar, and then select Open.
✦ Keyboard shortcuts are indicated with the following syntax: Ctrl+C.
Tip
On the
CD-ROM
Note
What Is a Sidebar?
Topics in sidebars provide additional information. Sidebar text contains discussion that is
related to the main text of a chapter, but not vital to understanding the main text.
4676-7 FM.f.qc 10/16/00 9:59 AM Page xv
4676-7 FM.f.qc 10/16/00 9:59 AM Page xvi
Acknowledgments
F
ew books of this size and scope are ever the work of a single individual, and
this one is no exception. I owe a debt of gratitude to many people for their
help and encouragement in writing this book.
First and foremost, thanks to my acquisitions editors, John Osborn and Greg Croy,
as well as my agent, Neil Salkind, for giving me the opportunity to write this book.
Thanks also go to Erica Sadun, who had the whole idea in the first place.
I want to extend special thanks to Eric Newman, whose hard work as development
editor was an incalculable asset in creating this book. Not only did he help wrestle
the text of the book into a more focused and organized whole, he kept up the faith
even in the face of slipping deadlines and the author’s trip to England in the middle
of the writing. A Palm enthusiast himself, Eric also kept me abreast of happenings
in the Palm OS world that I would otherwise have missed during the busiest

months of writing.
In addition, my thanks go out to the book’s technical reviewer, JB Parrett, whose
expertise and passion for good user interface improved the quality of the book
immeasurably. I would also like to thank Mildred Sanchez and S. B. Kleinman for
their copyediting as well as apologize for any gross abuses of the English language
they were forced to endure.
A big thank you to the production team at IDG Books, including Gabriele McCann,
Linda Marousek, Danette Nurse, Ronald Terry, and Mary Jo Weis, whose efforts
behind the scenes made it possible for a random assortment of Word documents
and bitmap images to transform magically into the printed copy you now hold.
More thanks go to Jessica Montgomery, Lenora Chin Sell, and Carmen Krikorian,
the media production folks who secured legal permissions for third-party CD-ROM
content, and a very special thank you to Joe Kiempisty for his able assistance and
patience in getting my own source code onto the CD.
I owe a lot to Lisa Rathjens and Ryan Robertson of Palm. Lisa’s loan of time and soft-
ware helped produce much better CodeWarrior support in this book, and Ryan’s
explanation of how tables work and answers to random technical questions ensured
that some of the more confusing aspects of the Palm OS were made much clearer.
Thanks also go to Christine Ackerman and Neil Shepherd of Oracle, Ivan Phillips of
Pendragon Software, Ray Combs of PUMATECH, Dan Simon of Qualcomm, and Chris
Ciervo of Symbol.
4676-7 FM.f.qc 10/16/00 9:59 AM Page xvii
xviii
Acknowledgments
Special thanks go to Ken Martin, Gene Thompson, and Steve Feldon, whose com-
mentary as “beta testers” was very useful in making sure that I have not ignored
first-time Palm OS programmers in this volume. Steve also deserves my gratitude
for introducing me to handheld computing, first with his old Newton (which he
wouldn’t let me touch for fear of messing up the handwriting recognition), then
again with his Pilot 5000 (which he did let me touch, and convinced me that I

really needed to get one of my own).
An especially warm thank you goes out to the free software community, both for
producing the free Palm OS development tools that allowed me to get into Palm
development in the first place and for providing source code of working Palm OS
programs, which allowed me to learn the ropes of the Palm OS. In particular, I
thank Mitch Blevins, author of DiddleBug and other fine free software, for fabulous
source code to work from and general camaraderie between developers, and
John Marshall, maintainer of the PRC-Tools, for his able assistance in getting
the PRC-Tools up and running under GNU/Linux.
I also thank Garbage, Goodness, Guano Apes, and other bands whose names do not
begin with “G” (like Jethro Tull, Depeche Mode, and They Might Be Giants), for their
inspiring tunes, which were of great help during those really long chapters. In addi-
tion, my thanks go out to Nullsoft, makers of the Winamp MP3 player, whose fine
program allowed me to queue up hundreds of songs by the aforementioned bands
and blast them at obnoxious volumes.
Finally, I would like to offer my eternal thanks to Elisabeth (my wife), Constance
Maytum, John Hedtke, Alan Zander, both of my cats, and all my friends who put
up with alternating blank stares and manic technical babbling from me over the
course of this massive project.
4676-7 FM.f.qc 10/16/00 9:59 AM Page xviii
4676-7 FM.f.qc 10/16/00 9:59 AM Page xix
Contents at a Glance
Foreword . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ix
Preface. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xi
Acknowledgments. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xviii
Part I: Getting Started . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1
Chapter 1: Understanding the Palm Computing Platform . . . . . . . . . . . . . . . 3
Chapter 2: Understanding the Palm OS . . . . . . . . . . . . . . . . . . . . . . . . . 15
Part: II: Creating Palm OS Applications . . . . . . . . . . . . . . . . . . 41
Chapter 3: Introducing the Development Environments . . . . . . . . . . . . . . . 43

Chapter 4: Writing Your First Palm OS Application . . . . . . . . . . . . . . . . . . 67
Chapter 5: Debugging Your Program . . . . . . . . . . . . . . . . . . . . . . . . . . 97
Part III: Programming the Palm OS . . . . . . . . . . . . . . . . . . . . 131
Chapter 6: Creating and Understanding Resources . . . . . . . . . . . . . . . . . 133
Chapter 7: Building Forms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165
Chapter 8: Building Menus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 193
Chapter 9: Programming User Interface Elements . . . . . . . . . . . . . . . . . . 213
Chapter 10: Programming System Elements . . . . . . . . . . . . . . . . . . . . . 265
Chapter 11: Programming Tables. . . . . . . . . . . . . . . . . . . . . . . . . . . . 309
Part IV: Storing Information on the Handheld. . . . . . . . . . . . . . 371
Chapter 12: Storing and Retrieving Data . . . . . . . . . . . . . . . . . . . . . . . 373
Chapter 13: Manipulating Records . . . . . . . . . . . . . . . . . . . . . . . . . . . 403
Part V: Communicating Outside the Handheld . . . . . . . . . . . . . 469
Chapter 14: Beaming Data by Infrared. . . . . . . . . . . . . . . . . . . . . . . . . 471
Chapter 15: Using the Serial Port. . . . . . . . . . . . . . . . . . . . . . . . . . . . 507
Chapter 16: Creating Web Clipping Applications. . . . . . . . . . . . . . . . . . . 535
4676-7 FM.f.qc 10/16/00 9:59 AM Page xx
Part VI: Synchronizing Data with the Desktop. . . . . . . . . . . . . . 571
Chapter 17: Introducing Conduit Mechanics . . . . . . . . . . . . . . . . . . . . . 573
Chapter 18: Building Conduits . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 593
Part VII: Advanced Programming Topics . . . . . . . . . . . . . . . . . 657
Chapter 19: Programming in Color. . . . . . . . . . . . . . . . . . . . . . . . . . . 659
Chapter 20: Odds and Ends . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 673
Appendix A: Palm OS API Quick Reference . . . . . . . . . . . . . . . . . . . . . . 707
Appendix B: Finding Resources for Palm OS Development . . . . . . . . . . . . . 813
Appendix C: Developing in Other Environments . . . . . . . . . . . . . . . . . . . 821
Appendix D: What’s on the CD-ROM? . . . . . . . . . . . . . . . . . . . . . . . . . 829
Glossary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 837
Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 861
End-User License Agreement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 894

GNU General Public License . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 897
CD-ROM Installation Instructions . . . . . . . . . . . . . . . . . . . . . . . . . . . 904
4676-7 FM.f.qc 10/16/00 9:59 AM Page xxi
4676-7 FM.f.qc 10/16/00 9:59 AM Page xxii
Contents
Foreword . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ix
Preface. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xi
Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xviii
Part I: Getting Started 1
Chapter 1: Understanding the Palm Computing Platform . . . . . . . . 3
The Palm OS Philosophy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
Comparing Desktop and Handheld Application Design . . . . . . . . . . . . . 4
Expectation of Performance . . . . . . . . . . . . . . . . . . . . . . . . . 5
Limited Input Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
Small Screen Size . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
Battery and Processor Power . . . . . . . . . . . . . . . . . . . . . . . . 6
Limited Memory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
RAM as Permanent Storage. . . . . . . . . . . . . . . . . . . . . . . . . . 7
Connecting to the Desktop . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
Comparing Hardware Versions . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
Looking to the Future. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
Chapter 2: Understanding the Palm OS . . . . . . . . . . . . . . . . . . 15
Understanding a Palm OS Handheld’s Power Usage . . . . . . . . . . . . . . 15
Running a Palm OS Application . . . . . . . . . . . . . . . . . . . . . . . . . . 16
Responding to Launch Codes. . . . . . . . . . . . . . . . . . . . . . . . 17
Handling Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
Managing Memory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
Dynamic RAM. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
Storage RAM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
Using Resources. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23

Designing the User Interface. . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
Forms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
Alerts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
Menus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
Lists . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
Pop-up Triggers. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
Buttons . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
4676-7 FM.f.qc 10/16/00 9:59 AM Page xxiii
xxiv
Palm OS Programming Bible
Repeating Buttons . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
Selector Triggers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
Push Buttons . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
Check Boxes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
Labels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
Form Bitmaps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
Fields. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
Graffiti Shift Indicator . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
Scroll Bars. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
Gadgets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
Communicating with Other Devices . . . . . . . . . . . . . . . . . . . . . . . 35
Serial . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
TCP/IP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
Wireless . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
IrDA . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
Beaming . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
Comparing Palm OS Versions . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
Changes in Version 2.0. . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
Changes in Version 3.0. . . . . . . . . . . . . . . . . . . . . . . . . . . . 38

Changes in Version 3.1. . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
Changes in Version 3.2. . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
Changes in Version 3.3. . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
Changes in Version 3.5. . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
Part II: Creating Palm OS Applications 41
Chapter 3: Introducing the Development Environments . . . . . . . . 43
Using CodeWarrior for Palm OS . . . . . . . . . . . . . . . . . . . . . . . . . . 43
Familiarizing Yourself with the IDE. . . . . . . . . . . . . . . . . . . . . 45
Changing Target Settings . . . . . . . . . . . . . . . . . . . . . . . . . . 52
Compiling and Linking in CodeWarrior . . . . . . . . . . . . . . . . . . 56
Using the GNU PRC-Tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57
Compiling and Linking with the PRC-Tools . . . . . . . . . . . . . . . . 59
Automating Builds with Make. . . . . . . . . . . . . . . . . . . . . . . . 61
Chapter 4: Writing Your First Palm OS Application . . . . . . . . . . . 67
Looking at the Hello World User Interface . . . . . . . . . . . . . . . . . . . . 67
Walking Through the Hello World Code . . . . . . . . . . . . . . . . . . . . . 68
Including Header Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69
Entering the Application . . . . . . . . . . . . . . . . . . . . . . . . . . 71
Starting the Application . . . . . . . . . . . . . . . . . . . . . . . . . . . 73
Closing the Application . . . . . . . . . . . . . . . . . . . . . . . . . . . 73
Handling Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73
Setting Up Forms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76
Responding to Form Events. . . . . . . . . . . . . . . . . . . . . . . . . 77
xxivxxiv
4676-7 FM.f.qc 10/16/00 9:59 AM Page xxiv
xxv
Contents
Handling Menu Events. . . . . . . . . . . . . . . . . . . . . . . . . . . . 81
Displaying Alerts and Using the Text Field . . . . . . . . . . . . . . . . 83
Using Memory in the Palm OS. . . . . . . . . . . . . . . . . . . . . . . . . . . 85

Putting It All Together . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90
Chapter 5: Debugging Your Program . . . . . . . . . . . . . . . . . . . . 97
Using the Palm OS Emulator. . . . . . . . . . . . . . . . . . . . . . . . . . . . 97
Controlling POSE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100
Running POSE for the First Time . . . . . . . . . . . . . . . . . . . . . 102
Installing a ROM Image . . . . . . . . . . . . . . . . . . . . . . . . . . . 103
Installing Applications . . . . . . . . . . . . . . . . . . . . . . . . . . . 106
Saving and Restoring Configurations . . . . . . . . . . . . . . . . . . . 106
Adjusting POSE Settings . . . . . . . . . . . . . . . . . . . . . . . . . . 107
Handling Gremlins . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112
Emulating a HotSync Operation. . . . . . . . . . . . . . . . . . . . . . 115
Taking Screen Shots . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117
Handling Errors in POSE . . . . . . . . . . . . . . . . . . . . . . . . . . 118
Debugging at the Source Level. . . . . . . . . . . . . . . . . . . . . . . . . . 118
Debugging with CodeWarrior . . . . . . . . . . . . . . . . . . . . . . . 119
Debugging with GDB . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122
Resetting a Palm OS Handheld. . . . . . . . . . . . . . . . . . . . . . . . . . 125
Using Developer Graffiti Shortcuts . . . . . . . . . . . . . . . . . . . . . . . 125
Using the Palm OS Error Manager . . . . . . . . . . . . . . . . . . . . . . . . 127
Part III: Programming the Palm OS 131
Chapter 6: Creating and Understanding Resources . . . . . . . . . . 133
Following Palm OS User Interface Guidelines . . . . . . . . . . . . . . . . . 133
Making Fast Applications . . . . . . . . . . . . . . . . . . . . . . . . . 134
Highlighting Frequently Used Functions . . . . . . . . . . . . . . . . . 135
Designing for Ease of Use . . . . . . . . . . . . . . . . . . . . . . . . . 136
Maintaining Palm OS Style . . . . . . . . . . . . . . . . . . . . . . . . . 137
Creating Resources with Constructor. . . . . . . . . . . . . . . . . . . . . . 142
Exploring the Project Window. . . . . . . . . . . . . . . . . . . . . . . 143
Creating Catalog Resources . . . . . . . . . . . . . . . . . . . . . . . . 156
Creating Resources with PilRC. . . . . . . . . . . . . . . . . . . . . . . . . . 157

Creating Application Resources. . . . . . . . . . . . . . . . . . . . . . 158
Previewing the Interface in PilrcUI . . . . . . . . . . . . . . . . . . . . 163
Assigning Constants to Resources . . . . . . . . . . . . . . . . . . . . 163
Chapter 7: Building Forms . . . . . . . . . . . . . . . . . . . . . . . . . 165
Building Forms with Constructor . . . . . . . . . . . . . . . . . . . . . . . . 165
Setting Common Object Properties. . . . . . . . . . . . . . . . . . . . 167
Setting Individual Object Properties . . . . . . . . . . . . . . . . . . . 169
4676-7 FM.f.qc 10/16/00 9:59 AM Page xxv