Wrox Professional Palm OS Programming Apr 2005 ISBN 076457373X pdf
Professional Palm OS ®
Programming
Professional Palm OS
®
Programming Lonnon R. Foster and Glenn Bachmann
®
Professional Palm OS Programming
Published by Wiley Publishing, Inc. 10475 Crosspoint Boulevard Indianapolis, IN 46256 Copyright © 2005 by Wiley Publishing, Inc., Indianapolis, Indiana Published simultaneously in Canada
ISBN-13: 978-0-7645-7373-6
ISBN-10: 0-7645-7373-X Manufactured in the United States of America 10 9 8 7 6 5 4 3 2 1
1B/QU/QU/QV/IN No part of this publication may be reproduced, stored in a retrieval system or transmitted in any form or by any means, electronic, mechanical, photocopying, recording, scanning or otherwise, except as permitted under Sections 107 or 108 of the 1976 United States Copyright Act, without either the prior written permission of the Publisher, or authorization through payment of the appropriate per-copy fee to the Copyright Clearance Center, 222 Rosewood Drive, Danvers, MA 01923, (978) 750-8400, fax (978) 750-4744. Requests to the Publisher for permission should be addressed to the Legal Department, Wiley Publishing, Inc., 10475 Crosspoint Blvd., Indianapolis, IN 46256, (317) 572-3447, fax (317) 572-4355, E-Mail: brandreview@wiley.com.
LIMIT OF LIABILITY/DISCLAIMER OF WARRANTY: THE PUBLISHER AND THE AUTHOR MAKE NO REP- RESENTATIONS OR WARRANTIES WITH RESPECT TO THE ACCURACY OR COMPLETENESS OF THE CON- TENTS OF THIS WORK AND SPECIFICALLY DISCLAIM ALL WARRANTIES, INCLUDING WITHOUT LIMITATION, WARRANTIES OF FITNESS FOR A PARTICULAR PURPOSE. NO WARRANTY MAY BE CRE- ATED OR EXTENDED BY SALES OR PROMOTIONAL MATERIALS. THE ADVICE AND STRATEGIES CON- TAINED HEREIN MAY NOT BE SUITABLE FOR EVERY SITUATION. THIS WORK IS SOLD WITH THE UNDERSTANDING THAT THE PUBLISHER IS NOT ENGAGED IN RENDERING LEGAL, ACCOUNTING, OR OTHER PROFESSIONAL SERVICES. IF PROFESSIONAL ASSISTANCE IS REQUIRED, THE SERVICES OF A COMPETENT PROFESSIONAL PERSON SHOULD BE SOUGHT. NEITHER THE PUBLISHER NOR THE AUTHOR SHALL BE LIABLE FOR DAMAGES ARISING HEREFROM. THE FACT THAT AN ORGANIZATION OR WEBSITE IS REFERRED TO IN THIS WORK AS A CITATION AND/OR A POTENTIAL SOURCE OF FUR- THER INFORMATION DOES NOT MEAN THAT THE AUTHOR OR THE PUBLISHER ENDORSES THE INFOR- MATION THE ORGANIZATION OR WEBSITE MAY PROVIDE OR RECOMMENDATIONS IT MAY MAKE.
FURTHER, READERS SHOULD BE AWARE THAT INTERNET WEBSITES LISTED IN THIS WORK MAY HAVE CHANGED OR DISAPPEARED BETWEEN WHEN THIS WORK WAS WRITTEN AND WHEN IT IS READ. For general information on our other products and services or to obtain technical support, please contact our Cus- tomer Care Department within the U.S. at (800) 762-2974, outside the U.S. at (317) 572-3993 or fax (317) 572-4002. Wiley also publishes its books in a variety of electronic formats. Some content that appears in print may not be available in electronic books. Library of Congress Cataloging-in-Publication Data Foster, Lonnon R., 1972- Professional Palm OS programming / Lonnon R. Foster & Glenn Bachmann. p. cm. Includes index.
ISBN 0-7645-7373-X (pbk.) 1. Palm OS. 2. Pocket computers. I. Bachmann, Glenn. II. Title. QA76.76.O63F597185 2005 004.16—dc22
2005000594
Trademarks: Wiley, the Wiley Publishing logo and related trade dress are trademarks or registered trademarks of
John Wiley & Sons, Inc. and/or its affiliates in the United States and other countries, and may not be used without written permission. Palm OS is a trademark or registered trademark of PalmSource, Inc. All other trademarks are the property of their respective owners. Wiley Publishing, Inc., is not associated with any product or vendor men- tioned in this book.
About the Authors Lonnon R. Foster
is a programmer and writer who has spent the past nine years creating desktop appli- cations, database front ends, Web sites, communications software, technical documentation, and hand- held applications. He has been developing Palm OS applications almost as long as the platform has existed, starting with his first Pilot 5000 and progressing to more complicated wireless software for Symbol’s 1700 series. Lonnon fills his sparse free time with tactical tabletop gaming, recreational Perl coding, and reading everything he can get his hands on.
Glenn Bachmann
is a noted author of several books and articles on Palm OS programming and mobile computing. Glenn is also president and founder of Bachmann Software, a leading provider of wireless file management, networking, backup, and printing software products for Palm OS, Pocket PC, and www.bachmannsoft-
Symbian handheld computing platforms. Founded in 1994, Bachmann Software ( ware.com
) has established itself as a leading contributor to the mobile and wireless economy through its utility software products and partnerships with many of the key companies in the mobile computing arena. Bachmann’s PrintBoy, FilePoint, Mobile Backup, and Mobile Utilities are among the best-selling software utilities for handhelds and smartphones.
First and foremost I thank my acquisitions editor, Chris Webb, for remembering me from our previous collaborations and providing me with the opportunity to participate in writing this book. I also thank
my development editor, Eileen Bien Calabro, who bore the difficult task of keeping the book on track with
just the right amount of poking and prodding to the author.I also thank Lonnon Foster for creating the phenomenally successful Palm OS Programming Bible, the second edition of which is the predecessor and foundation of this book. Through Lonnon’s clear and
concise writing style and attention to detail, he has helped programmers around the world become Palm
OS programmers.There are so many people in the Palm OS developer community—at PalmSource, palmOne, and other software companies—who continue to be the heroes of our little mobile computing industry. These fine folks are responsible for the fantastic handhelds, smartphones, operating systems, and software applica- tions that make it such a delight to participate in and contribute to the success of the Palm Economy. My hat goes off to you all. Thanks are also due to the team at Bachmann Software, truly the finest and most dedicated people I have ever worked with.
Finally, I thank my wife for supporting me in my never-ending adventures in growing a software com- pany. I also thank my three wonderful children, who seem to have grown up under the impression that it is entirely normal for their father to possess 58 different handhelds.
Credits
Executive Editor Chris Webb Development Editor Eileen Bien Calabro Technical Reviewer JB Parrett Copy Editors Stefan Gruenwedel Nancy Rapoport Vice President & Executive Group Publisher Richard Swadley Vice President and Publisher Joseph B. Wikert Project Coordinator Erin Smith
Graphics and Production Specialists April Farling Carrie A. Foster Lauren Goddard Denny Hager Joyce Haughey Jennifer Heleine Lynsey Osborn Julie Trippetti Quality Control Technicians Laura Albert Amanda Briggs John Greenough Leeann Harney Carl William Pierce Brian H. Walls Proofreading and Indexing TECHBOOKS Production Services
In loving memory of Robert B. Hyslop (1909–2002)
Contents
Introduction xxiii
1 The Palm OS Success Story
1 Comparing Desktop and Handheld Application Design
2 Diversity of Handheld Form Factors
3 Expectation of Performance
3 Limited Input Methods
3 Small Screen Size
4 Processing Power
5 Battery Life
5 Limited Memory
5 RAM as Permanent Data Storage
5 Designing Applications for Smartphones and Other Wireless Devices
6 Many Connection Types
6 Connection Speed
7 Mobile-User Expectations
7 Connection Reliability
7 Connecting to the Desktop
8 Comparing Palm OS Handheld Devices
9 Looking to the Future
10 Summary
10 Chapter 2: Understanding the Palm OS
11 Understanding a Palm OS Handheld’s Power Usage
11 Running Under Different Processors
12 Using Programming Protein
13 Running a Palm OS Application
14 Understanding the Palm OS Garnet Kernel
14 Understanding the Palm OS Cobalt Kernel
15 Responding to Launch Codes
16 Handling Events
16 xii Contents
Using Resources
38 Data Exchange
31 Maintaining Palm OS Style
32 Communicating with Other Devices
37 Serial
37 TCP/IP
37 Bluetooth
38 Telephony
38 IrDA
39 Comparing Palm OS Versions
29 Highlighting Frequently Used Features
39 Changes in Version 2.0
40 Changes in Version 3.0
40 Changes in Version 3.1
40 Changes in Version 3.2
41 Changes in Version 3.3
41 Changes in Version 3.5
41 Changes in Version 4.0
42 Changes in Version 5.0
30 Designing for Ease of Use
28 Making Fast Applications
17 Designing an Application’s User Interface
22 Selector Triggers
17 Forms
18 Alerts
18 Menus
19 Tables
20 Lists
21 Pop-up Triggers
21 Buttons
22 Repeating Buttons
23 Push Buttons
27 Following Palm OS User Interface Guidelines
23 Check Boxes
23 Sliders
24 Labels
24 Form Bitmaps
25 Fields
25 Graffiti Shift Indicator
26 Scroll Bars
26 Gadgets
42
Contents Changes in Palm OS Garnet
42 Changes in Palm OS Cobalt
42 Summary
43 Chapter 3: Introducing the Development Tools
45 Using CodeWarrior for Palm OS
46 Familiarizing Yourself with the IDE
47 Changing Target Settings
58 Compiling and Linking in CodeWarrior
61 Using the Palm OS Development Suite (PODS)
62 Familiarizing Yourself with the Eclipse Workbench
63 Changing Project Settings
73 Compiling and Linking in the Eclipse Workbench
74 Summary
75 Chapter 4: Writing Your First Palm OS Application
77 Creating Hello World 1
78 Including Header Files
78 Entering the Application
79 Starting the Application
81 Closing the Application
82 Handling Events
82 Setting Up Forms
85 Responding to Form Events
87 Creating Hello World 2
89 Defining Resource Constants
90 Responding to Form Events
91 Handling Menu Events
93 Displaying Alerts and Using the Text Field
95 Putting It All Together
97 Understanding Changes in Palm OS Header Files 111 Summary 114
115 Using Palm OS Emulator (POSE)
115 Controlling POSE
118 Running POSE for the First Time 120 Installing a ROM Image 121 Installing Applications 122 Saving and Restoring Configurations 123
Contents
xiv
Chapter 7: Building Forms and Menus 169
Displaying Multiple Records in List View 190 Displaying an Individual Book in Record View 191
179 Individual Form and Form Object Properties 181
179 Common Form Object Properties
Building Forms with Palm OS Resource Editor 176 Building Menus with Palm OS Resource Editor 178 Understanding Form Object Properties
Sharing Menus Between Menu Bars 175
Building Forms with Constructor 169 Building Menus with Constructor 172
Summary 168
Adjusting Emulator Settings 123 Handling Gremlins 126 Emulating a HotSync Operation 130 Emulating Expansion Cards 132 Capturing Screenshots 133 Handling Errors in the Emulator 133
Creating Resources with the Palm OS Resource Editor 163 Creating and Editing Application Resources 165
Exploring the Project Window 153
Chapter 6: Creating and Understanding Resources 151
Following Palm OS User Interface Guidelines 151 Creating Resources with Constructor 152Resetting a Palm OS Handheld 145 Using Developer Graffiti Shortcuts 146 Using the Palm OS Error Manager 147 Summary 148
Debugging with CodeWarrior 140 Debugging with PODS 143
Debugging at the Source Level 140
Starting the Simulator 134 Loading a ROM Image 135 Installing Applications and Data 136 Running Gremlins 136 Viewing Databases, Memory, and Events 137 Saving and Loading a Storage Snapshot 139
Using Palm OS Simulator 134
Introducing Librarian, a Sample Application 190
Contents Editing a Record in Edit View
Setting a Handle for a Text Field 227 Modifying a Text Field 228 Retrieving Text from a Field 229 Setting Field Focus 230 Setting Field Attributes 231
Managing Memory 255
Chapter 9: Managing Memory 255
Summary 253
Hiding Menu Items 247 Programming the Command Toolbar 248
Programming Menus 247
Retrieving List Data 241 Manipulating Lists 242 Programming Dynamic Lists 243 Handling Pop-up Lists 245
Programming Lists and Pop-up Lists 241
Programming Extended Gadgets 239
Programming Gadgets 232
Programming Fields 226
192 Examining Librarian’s Menus 194
221 Selecting Colors 225
220 Selecting Dates and Times
219 Programming Selector Triggers
Programming Check Boxes and Push Buttons 219 Handling Control Groups
Handling Form Object Events 211 Retrieving an Object Pointer 213 Hiding and Showing Form Objects 215
Programming Objects on Forms 210
Displaying a Modal Dialog Box with FrmPopupForm 206 Updating a Form 208
Switching to a New Form 203 Displaying a Modal Dialog Box with FrmDoDialog 203
Chapter 8: Programming User Interface Elements 199
Programming Alerts 199 Programming Forms 202Summary 197
Palm OS Garnet Memory Architecture 255 Palm OS Cobalt Memory Architecture 259 xvi Contents
Using Dynamic Memory in Palm OS Garnet 261 Using Dynamic Memory in Palm OS Cobalt 264 Summary 265
Reacting to Low Battery Conditions 306
Setting the Transfer Mode 326 Setting Foreground, Background, and Text Colors 327
Drawing Graphics and Text 326
Understanding Windows 312 Creating Offscreen Windows 316 Saving and Restoring the Draw State 318 Determining and Setting Color Depth 319 Using Color Tables 323 Translating RGB to Index Values 325
Managing the Drawing Surface 312
Chapter 11: Programming Graphics 311
Identifying the Device 306 Using the Clipboard 307 Summary 310
Generating Random Numbers 302 Managing Power 304
267 Determining the Operating System Version
Calling the System Application Launcher 298 Launching Applications Directly 299 Sending Launch Codes Globally 302 Creating Your Own Launch Codes 302
Looking Up Phone Numbers 297 Launching Applications 298
Understanding Application Button Presses 294 Overriding Hardware Application Buttons 294
Handling Pen Events 289 Handling Key Events 292
Using Font Functions 273 Using String Functions 284 Using Character Macros 285
Manipulating Text 273
268 Checking Individual Features 271
Drawing Pixels 328
Contents
Drawing Lines 328 Drawing Rectangles 329 Drawing Text 332 Drawing Bitmaps 333 Using Color Bitmaps 334 Coloring the User Interface 335
Programming High-Resolution Displays 339
Using the High-Density Display Feature Set 340 Detecting Available Screen Densities 341 Setting and Retrieving the Coordinate System 342
Translating Between Coordinate Systems 343
Using the Palm OS Cobalt Graphics Model 343
Chapter 12: Programming Multimedia 349
Understanding Sound Manager 349
Playing Simple Sound 350 Playing Sampled Sound 352
Summary 347
Session Objects 353 Working with Sources and Destinations 354 Components of a Playback Session 354 Sample Source Code for Playback 356
Summary 357
Chapter 13: Programming Alarms and Time 359
Setting Alarms 359Setting an Alarm 360 Responding to Alarms 362 Responding to Other Launch Codes 366
Manipulating Time Values 367
Retrieving and Setting Time Values 368 Converting Time Values 369 Altering Time Values 371
Following User Date and Time Preferences 371 Getting the User’s Attention 374
What Is a Graphics Context? 344 Understanding Paths 344 Alpha Blending and Anti-Aliasing 344 How Drawing Works in a Graphics Context 345
Understanding Multimedia Services 353 xviii Contents
Requesting Attention 376 Responding to the Attention Manager 379 Managing Attention Attempts 384 Preventing the Attention Indicator from Appearing 384
Summary 385
Chapter 14: Programming Tables 387
Creating a Simple Table 388
Understanding How Tables Work 388 Initializing a Table 392 Handling Table Events 409 Hiding Rows and Columns 410
Creating More Complex Tables 414
Connecting a Table to Data 415 Scrolling Tables 440 Handling Table Text Fields 461
Summary 468
Chapter 15: Storing and Retrieving Data 469
Understanding Palm OS Databases 469 Understanding Non-Schema Databases 470Record Databases 471 Resource Databases 473 Working with Non-Schema Databases 473 Working with Extended Databases 488 Working with Schema Databases 488
Storing Application Preferences 492 Reading and Setting System Preferences 496
Using Feature Memory 497 Summary 498
Chapter 16: Manipulating Records 501
Working with Non-Schema Database Records 501
Looking at Records in the Librarian Sample Application 502 Comparing Records 507 Finding Records 513 Creating Records 514 Deleting Records 518 Reading Records 520 Modifying Records 520
Contents
Changing Database Structures Between Versions 531 Sorting Records 536 Retrieving and Modifying Record Information 537
Categorizing Records 538 Implementing Private Records 548 Deleting All Private Records 549 Resizing Records 549
Working with Schema Database Records 549 Working with Cursors
550 Implementing the Global Find Facility
555 Handling sysAppLaunchCmdSaveData
556 Handling sysAppLaunchCmdFind 557 Handling sysAppLaunchCmdGoto 561
Summary 564
567 Understanding the Expansion Manager
567 Understanding Secondary Storage 568
Organizing Files and Directories 569 Running Applications from Secondary Storage 570
Using the Virtual File System 571
Verifying Presence of the VFS Manager 572 Detecting Card Insertion and Removal 572 Retrieving a Volume Reference 576 Getting and Setting Volume Labels 579 Finding Volume Information 580 Creating Directories 581 Handling VFS Manager Errors Gracefully 585 Creating Files 586 Deleting Files and Directories 589 Opening and Closing Files 593 Retrieving and Setting File Information 595 Reading Data from Files 598 Positioning a File Pointer 603 Writing Data to Files 607 Finding Files 610 Retrieving Default File Locations 613 Dealing with Palm OS Databases 614 Moving Palm OS Databases 615
Summary 615 xx Contents
Chapter 18: Sharing Data Through the Exchange Manager 617
Using the Exchange Manager 618Registering a Data Type 621 Sending Data 626 Customizing the Data Acceptance Dialog Box 649
Receiving Data 654 Displaying Beamed Records 666 Debugging Beaming 666 Sending Applications and Databases 667 Receiving Databases 670
Summary 671
Chapter 19: Using the Serial Port 673
Understanding Palm OS Serial Communications 673 Using the Serial Manager 675
Using the New Serial Manager 677 Using the Old Serial Manager 698
Summary 701
Chapter 20: Communicating Over a Network 703
Understanding TCP/IP Networking 704 Programming the Palm OS Garnet Net Library 705Retrieving a Net Library Reference 707 Opening the Net Library 707 Resolving Hostnames and Addresses 708 Finding a Service Port 713 Opening a Socket 715 Connecting a Socket 716 Sending and Receiving Data 717 Disconnecting a Socket 720 Closing a Socket 721 Closing the Net Library 721
Using the Palm OS Cobalt Berkeley Sockets APIs 722 Learning More About Sockets
722 Advantages of Using Sockets with Palm OS Cobalt 723 Summary 724
Chapter 21: Learning Conduit Basics 725
Understanding Conduits 726
Stepping Through the HotSync Process 727
Contents Designing Conduits
Implementing GetConduitInfo 751 Implementing GetConduitName 753 Implementing GetConduitVersion 754 Implementing OpenConduit 754 Implementing Configuration Entry Points 757
Summary 812
Registering and Unregistering a Conduit 804 Opening and Closing Handheld Databases 804 Iterating Over Database Records 807 Reading and Writing Records 810 Deleting Records 811 Maintaining a Connection 811
Using the Sync Manager API 803
Following MFC Conduit Flow of Control 790 Implementing a Monitor Class 791 Implementing a Table Class 792 Implementing a Schema Class 795 Implementing a Record Class 796 Implementing a Link Converter Class 800
Using the Palm MFC Base Classes 789
Following Generic Conduit Flow of Control 767 Describing the Desktop Record Format 768 Implementing Storage and Retrieval 770 Converting Data to and from CPalmRecord 779 Synching the Application Info Block 789
Implementing Conduit Entry Points 750
729 Choosing a Development Path
744 Choosing a Handheld Application 745 Selecting a Data Transfer Type 746 Selecting Conduit Features 747 Confirming Class and File Names 748
743 Selecting a Conduit Type
743 Using the Conduit Wizard
Logging Actions in the HotSync Log 738 Summary 741
732 Creating Automatic Conduit Installations 735
731 Installing Conduits Manually
730 Installing Conduits
Using the Generic Conduit Base Classes 766
Chapter 23: Programming Navigation Hardware 813 Programming the palmOne 5-Way Navigation Button 813 Object Focus and Application Focus
xxii Contents
814 Understanding Tab Order 814 Handling Navigation Events 814 Detecting the Presence of 5-Way Navigation Buttons 815
Designing Your Forms for 5-Way Navigation 816
Programming the Sony Jog Dial 816
Understanding JogAssist 819 Working Around JogAssist 820
Summary 826
Chapter 24: Odds and Ends 827
Creating Large Applications in Palm OS Garnet 827 Breaking the 32K Barrier
828 Segmenting Applications in Palm OS Garnet 830 Adding Custom Fonts to Palm OS Garnet Applications 835
Creating a Custom Font 836
Creating a User Interface Dynamically 839 Localizing Applications 843
Using the Text and International Managers 843
Using the File Streaming API 850
Opening File Streams 851 Closing File Streams 854 Retrieving File Stream Errors 854 Deleting File Streams 855 Setting Position in a File Stream 855 Reading and Writing File Stream Data 856
Summary 858 Glossary 859 Index 885
Introduction
The convenience, power, and ease of use of Palm OS handheld devices make them attractive to a wide variety of users. More than 35 million Palm Powered handheld devices 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 320,000 registered developers and 20,000 third-party applications, Palm OS also has proven to be popular with software authors, which is where this book comes in.
®
Professional Palm OS Programming is written for the present and future developers of Palm OS applica-
tions. It is designed to help both aspiring and experienced handheld developers master the ins and outs of creating a full-fledged Palm OS handheld application. Whether you are a developer for a large organization that is integrating Palm Powered 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.
What This Book Covers
Professional Palm OS Programming shows you how to create applications that run on handhelds and
smartphones from palmOne, Sony, Kyocera, Samsung, and other licensees of Palm OS.This book specifically covers both Palm OS Garnet and the new Palm OS Cobalt, representing the next- generation operating system for Palm OS developers. As of this writing, Palm OS Cobalt 6.1 is complete; however, Palm OS Cobalt–based handhelds have yet to ship. Furthermore, PalmSource Palm OS Cobalt development tools are being updated. Accordingly, the book focuses on Palm OS Garnet as the standard handheld operating system and supplements those chapters with Palm OS Cobalt–specific information where the introduction of Palm OS Cobalt tools, APIs, and concepts is appropriate.
The primary focus of this book is Palm OS development in the C language, using CodeWarrior for Palm OS Platform, or PalmSource’s PODS as a development environment. Other tools exist for developing Palm OS applications, but these environments are popular with the largest developer audience and offer the most complete access to the many features of Palm OS and the handhelds that run it. Introduction
Whom This Book Is For
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 Palm OS works, showing you the tools available for Palm OS development, and providing you with tips to make your own applications work seamlessly within PalmSource’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. Palm OS is multifaceted, and this book can serve as a guide to exploring those parts of the operating system that you have not yet dealt with.
If you wish to create applications that make use of TCP/IP communications options on appropriately equipped wireless Palm Powered handhelds, you will need to know the basics of socket programming and TCP/IP protocols. Similarly, although this book covers how to perform serial communications on Palm OS, it will not teach you the basics of serial communications.
Conduit programming is a very complex topic and uses a completely different set of tools from those used for handheld programming. This book provides a basic overview of conduits, as well as a descrip- tion of the tools used to create them. An in-depth discussion of conduit programming would require a book in itself, so that subject is beyond the scope of this volume. For those who are interested in con- duits, conduit programming requires solid knowledge of C++, as well as a working knowledge of creat- ing desktop applications for either Windows or Mac OS. Palm’s Conduit Development Kit (CDK) provides tools for writing conduits in Java and Visual Basic (or any other COM-compliant language), but this book focuses on C++ conduit development.
How This Book Is Structured
Each chapter in this book focuses on a specific area of Palm OS programming. The first eight chapters, essential reading for programmers new to the Palm OS, introduce readers to the operating system itself, the development tools, and the basics of creating a simple application. It is critical that new Palm OS programmers master the information and concepts presented in these chapters before moving on to more advanced material. Once the earlier chapter concepts are mastered, for the most part each of the remaining chapters is self- contained and can be read as a topic unto itself. The following is an overview of what is covered in each chapter:
❑
Chapter 1, “The Palm OS Success Story, ” introduces the Palm OS platform and discusses design issues that are generally important for any Palm OS programmer to understand. ❑
Chapter 2, “Understanding the Palm OS” covers the operating system in more depth, including a historical overview of Palm OS versions up to and including Palm OS Garnet and Palm OS Cobalt. ❑
Chapter 3, “Introducing the Development Tools,” provides an introduction to using Metrowerks CodeWarrior and PalmSource’s PODS to create and work with Palm OS programming projects.
xxiv
Introduction
❑
Chapter 4, “Writing Your First Palm OS Application,” walks you through the basics of a simple Palm OS application. ❑
Chapter 5, “Debugging Your Program,” discusses Palm OS Emulator and Palm Simulator, as well as the debugging tools available in both CodeWarrior and PODS. ❑
Chapter 6, “Creating and Understanding Resources,” covers the creation of project resources with Metrowerks’ Constructor and PalmSource’s Palm OS Resource Editor. ❑
Chapter 7, “Building Forms and Menus,” describes how to design forms and menus that make up the primary user interface for most Palm OS applications. ❑
Chapter 8, “Programming User Interface Elements,” teaches you how to incorporate resources such as forms, menus, and alerts into your source code. ❑
Chapter 9, “Managing Memory,” discusses how memory is managed on Palm OS Garnet and Palm OS Cobalt and provides information on how to allocate and use memory in your applica- tion. ❑
Chapter 10, “Programming System Elements,” covers system topics such as operating system version checking, fonts, events, and the Clipboard. ❑
Chapter 11, “Programming Graphics,” describes how to draw on the device display using the Palm OS Garnet and Palm OS Cobalt windowing and graphics models. ❑
Chapter 12, “Programming Multimedia,” covers how to use beeps and sounds within your application, as well as how to make use of media playback and recording functionality. ❑
Chapter 13, “Programming Alarms and Time,” discusses the Palm OS time and date facilities, using alarms, and the attention manager ❑
Chapter 14, “Programming Tables,” describes how to incorporate tables to display rows and columns of data within your applications user interface. ❑
Chapter 15, “Storing and Retrieving Data,” introduces the Palm OS Database Manager and also covers Palm OS Cobalt Schema databases. ❑
Chapter 16, “Manipulating Records,” builds on Chapter 15 by examining the programming APIs used to work with database records. ❑
Chapter 17, “Using Secondary Storage,” describes how to enhance your application to read and write data stored on memory expansion cards. ❑
Chapter 18, “Sharing Data Through the Exchange Manager,” covers the Palm OS Exchange Manager. ❑
Chapter 19, “Using the Serial Port,” introduces the Serial Manager as a method for program- ming serial communications on Palm OS handhelds. ❑
Chapter 20, “Communicating Over a Network,” covers the TCP/IP implementation on Palm OS Garnet and Palm OS Cobalt. ❑
Chapter 21, “Learning Conduit Basics,” introduces the concept of conduits as a method of exchanging and synchronizing data between the handheld and desktop through HotSync. Introduction
❑
Chapter 22, “Building Conduits,” builds on Chapter 21 by examining the tools used to build conduits. ❑
Chapter 23, “Programming Navigation Hardware,” discusses how to program your application to work correctly with five-way navigation buttons and scroll wheels. ❑
Chapter 24, “Odds and Ends,” covers a variety of miscellaneous Palm OS programming topics, including large projects, segmentation, custom fonts, localization, and file streaming. How to Approach This Book Readers who are completely new to Palm OS development will benefit most by first reading Chapters
1–8 in their entirety. These chapters provide an excellent introduction to Palm OS, the development tools, setting up your first projects, and creating a basic application. Following these chapters, you should at least review Chapters 9, 15, and 16 to get an idea of how storage and memory work. After that, the other chapters can generally be read in any order, based on specific topics of interest to the reader.
For readers who have already done some Palm OS development, the first eight chapters form a good review. However, they are also an essential read if you plan to work with PODS and Palm OS Cobalt. The new and updated chapters on graphics, memory management, networking, database storage, and multimedia will also serve as useful references as well as introductions to how these topics are handled differently under Palm OS Cobalt than in Palm OS Garnet. Anyone interested in creating conduits can obtain a high-level overview of this complex topic from Chapters 21 and 22. Developers who wish to delve right into conduit programming are advised to obtain the most current version of the Conduit Development Kit, available from PalmSource’s Web site. The CDK remains the best reference available on this topic.
What’s New in This Edition?
Since the publication of the second edition of Palm OS Programming Bible, PalmSource, formerly the Palm OS subsidiary of Palm, Inc., has released updates to Palm OS 5, now known as Palm OS Garnet. PalmSource has also introduced a brand new version of the operating system, known as Palm OS Cobalt. In conjunction with these advances in the operating system, PalmSource for the first time released its very own suite of tools for developing Palm OS applications, known as PODS.
In terms of devices, besides the inexorable march forward in improvements to the screen display and memory capacity, the past year has seen the growth of the smartphone as a tremendously important handheld device that represents the convergence of voice, wireless data, and traditional handheld applications.
Professional Palm OS Programming is a brand new Wrox Pro book that builds on Palm OS Programming
Bible , Second Edition to cover new capabilities and changes for developers of Palm OS Garnet and Palm
OS Cobalt applications. In addition to the considerable material provided from Palm OS Programming
Bible on programming for Palm OS, the following new topics in Palm OS programming are specifically
covered in this book:
xxvi
Introduction
❑ Changes to the Palm OS platform and operating system, including Palm OS Garnet and Palm OS Cobalt
❑ New and updated coverage of Palm OS development tools, including Metrowerks’ CodeWarrior 9.3 and the new PODS from PalmSource
❑ Creating and working with resources using the latest resource editors from PalmSource ❑ Debugging Palm OS Garnet and Palm OS Cobalt programs from within the PODS integrated debugger ❑ The new Palm OS Cobalt graphics model ❑ Working with the new Palm OS Cobalt Schema databases ❑ Programming the five-way navigator buttons found on most new handhelds ❑ New multimedia functionality for audio and video recording and playback
What You Need to Use This Book
To make the best use of this book, you should obtain at least one Palm OS handheld. Just about any rea- sonable modern device from palmOne, Sony, or other handheld vendor should do, although the Palm OS Garnet discussions will make more sense to you if you are working with a Palm OS 5.x–based color device. palmOne’s Tungsten series is a good choice if you are looking to purchase a handheld at this time.
It is possible to learn Palm OS programming without a handheld, but there is nothing like working with an actual device to gain the best understanding of what it is like to create software for handhelds. You will also need access to a computer that is capable of running either Metrowerks’ CodeWarrior or PalmSource’s PODS development tools. For information on minimum computer requirements, please visit www.metrowerks.com or www.palmsource.com .
Conventions
To help you get the most from the text and keep track of what’s happening, we’ve used a number of typographic conventions throughout the book.
Tips, hints, tricks, and asides to the current discussion are offset and placed in italics like this.
As for styles in the text: ❑ We highlight new terms and important words when we introduce them.
❑ We show keyboard strokes like this: Ctrl-A.
Boxes like this one hold important, not-to-be-forgotten information that is directly relevant to the accompanying text. Introduction
❑ We show most filenames, URLs, functions, classes, objects, and code within the text like so: persistence.properties . ❑ We present code in two different ways: In code examples we highlight new and important code with a gray background.
The gray highlighting is not used for code that’s less important in the present context, or has been shown before.
Note that depending on the topic, in some cases code listings are presented for both Palm OS Garnet and Palm OS Cobalt.
Errata
We make every effort to ensure that there are no errors in the text or in the code. However, no one is perfect and mistakes do occur. If you find an error in one of our books, like a spelling mistake or faulty piece of code, we would be very grateful for your feedback. By sending in errata you may save another reader hours of frustration, and at the same time you will be helping us provide even higher quality information. To find the errata page for this book, go to www.wrox.com and locate the title using the Search box or one of the title lists. Then, on the book details page, click the Book Errata link. On this page you can view all errata that has been submitted for this book and posted by Wrox editors. A complete book list, includ- ing links to each book’s errata, is also available at www.wrox.com/misc-pages/booklist.shtml .
If you don’t spot “your” error on the Book Errata page, go to www.wrox.com/contact/techsupport.shtml and complete the form there to send us the error you have found. We’ll check the information and, if appropriate, post a message to the book’s errata page and fix the problem in subsequent editions of the book.
p2p.wrox.com
For author and peer discussion, join the P2P forums at p2p.wrox.com . The forums are a Web-based sys- tem for you to post messages relating to Wrox books and related technologies and to interact with other readers and technology users. The forums offer a subscription feature to e-mail you topics of interest of your choosing when new posts are made to the forums. Wrox authors, editors, other industry experts, and your fellow readers are present on these forums. At http://p2p.wrox.com you will find a number of different forums that will help you not only as you read this book, but also as you develop your own applications. To join the forums, just follow these steps:
1. Go to p2p.wrox.com and click the Register link.
2. Read the terms of use and click Agree. xxviii
Introduction
3. Complete the required information to join as well as any optional information you wish to provide and click Submit.
4. You will receive an e-mail with information describing how to verify your account and complete
the joining process.You can read messages in the forums without joining P2P, but you must join in order to post your own messages.
Once you join, you can post new messages and respond to messages other users post. You can read mes- sages at any time on the Web. If you would like to have new messages from a particular forum e-mailed to you, click the Subscribe to This Forum icon by the forum name in the forum listing. Be sure to read the P2P FAQs for answers to questions about how the forum software works as well as many common questions specific to P2P and Wrox books. To read the FAQs, click the FAQ link on any P2P page.
The Palm OS Success Stor y
Since the release of the Pilot 1000 in 1996, devices running Palm OS have become synonymous with the term “handheld computer.” Through the years, the designers of Palm OS have consis- tently been able to combine just the right mix of features to make a personal digital assistant (PDA) that is easy to integrate into almost any user’s lifestyle. Designing an application that takes advantage of the strengths of the Palm OS platform requires an understanding of not only how the platform works but also why it was designed the way it was. This chapter explains some of the thinking that has made the Palm OS platform so successful. It also points out important design considerations for developers of handheld applications. Finally, it provides an overview of the increasingly diverse world of Palm OS devices and the array of hardware capabilities they encompass.
The Palm OS Success Stor y
How has Palm OS maintained its position as the leader in handheld platforms, even in the face of capable challengers such as Microsoft Windows Mobile and Symbian OS? One could debate the pros and cons of these and other worthy contenders for the title of “best handheld operating system” but the truth is that Palm OS continues to achieve a magic combina- tion of simplicity and extensibility that attracts device manufacturers, developers, and users to the platform. This success is all the more impressive when you consider that Palm OS has remained the leader throughout a period of time when the definition of a “PDA” has expanded from a simple personal organizer to a robust application platform — all the way through to the present time when it is becoming increasingly difficult to find a handheld that does not play music, take pictures, play games, or double as your cell phone.
Chapter 1
What makes Palm OS a great platform for so many developers and handheld users? There are many rea- sons, but these are among the most important: ❑ Palm OS is small, fast, and efficient. Rather than suffer inevitable bloat as new features are added to the latest handhelds, Palm OS remains true to its core values and instead offers exten- sibility to its licensees, enabling them to build devices that add advanced features to the core operating system. ❑ Palm OS is easy to use. Devices that use Palm OS allow users to perform common tasks with a minimum of dialog boxes, menus, and screen navigation. Many common tasks are accomplished with a single button press or stylus tap. ❑ Palm OS allows simple and fast desktop synchronization. The Palm OS HotSync design enables one-button synchronization of data between the desktop and handheld. Despite having years to learn from Palm OS, other platforms have yet to approach the simplicity and ease of use that Palm OS HotSync offers. ❑ Palm OS embraces diversity. The number and diversity of licensees is a testament to how well the designers of Palm OS enable handheld manufacturers to adapt it to a wide variety of tasks, from multimedia to wireless communications. This is in direct contrast to other platforms, where devices tend to be fairly similar in form and function. Palm hit upon a perfect combination of these factors with its first device, and it has resisted the tempta- tion to cram marginally useful features into new Palm devices. Intelligent selection of such features has fashioned these devices into handy tools instead of merely expensive toys.
Comparing Desktop and Handheld Application Design
There are significant differences between a desktop computer and a handheld device — enough differ- ences that designing a handheld application must be approached differently from designing a desktop application. Many elements must be kept in mind when designing a Palm OS application:
❑ Diversity of handheld form factors ❑ Expectation of performance ❑ Limited input methods ❑ Small screen size ❑ Processing power ❑ Battery life ❑ Limited memory ❑ RAM as permanent data storage
2
The Palm OS Success Story