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 152

  Resetting 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 202

  Summary 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 359

  Setting 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 470

  Record 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 618

  Registering 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 705

  Retrieving 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