Palm OS® Programmer’s Companion Volume I CONTRIBUTORS Written by Greg Wilson and Jean Ostrem Engineering contributions by Jesse Donaldson, Noah Gibbs, Lee Taylor, Danny Epstein, Peter Epstein, David Fedor, Roger Flores, Steve Lemke, Bob Ebert, Ken Krugler, Bruce Thompson, Tim Wiegman, Gavin Peacock, Ryan Robertson, and Waddah Kudaimi Copyright © 1996 - 2002, PalmSource, Inc. and its affiliates. All rights reserved. This documentation may be printed and copied solely for use in developing products for Palm OS® software. In addition, two (2) copies of this documentation may be made for archival and backup purposes. Except for the foregoing, no part of this documentation may be reproduced or transmitted in any form or by any means or used to make any derivative work (such as translation, transformation or adaptation) without express written consent from PalmSource, Inc. PalmSource, Inc. reserves the right to revise this documentation and to make changes in content from time to time without obligation on the part of PalmSource, Inc. to provide notification of such revision or changes. PALMSOURCE, INC. AND ITS SUPPLIERS MAKE NO REPRESENTATIONS OR WARRANTIES THAT THE DOCUMENTATION IS FREE OF ERRORS OR THAT THE DOCUMENTATION IS SUITABLE FOR YOUR USE. THE DOCUMENTATION IS PROVIDED ON AN “AS IS” BASIS. PALMSOURCE, INC. AND ITS SUPPLIERS MAKE NO WARRANTIES, TERMS OR CONDITIONS, EXPRESS OR IMPLIED, EITHER IN FACT OR BY OPERATION OF LAW, STATUTORY OR OTHERWISE, INCLUDING WARRANTIES, TERMS, OR CONDITIONS OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, AND SATISFACTORY QUALITY. TO THE FULL EXTENT ALLOWED BY LAW, PALMSOURCE, INC. ALSO EXCLUDES FOR ITSELF AND ITS SUPPLIERS ANY LIABILITY, WHETHER BASED IN CONTRACT OR TORT (INCLUDING NEGLIGENCE), FOR DIRECT, INCIDENTAL, CONSEQUENTIAL, INDIRECT, SPECIAL, OR PUNITIVE DAMAGES OF ANY KIND, OR FOR LOSS OF REVENUE OR PROFITS, LOSS OF BUSINESS, LOSS OF INFORMATION OR DATA, OR OTHER FINANCIAL LOSS ARISING OUT OF OR IN CONNECTION WITH THIS DOCUMENTATION, EVEN IF PALMSOURCE, INC. OR ITS SUPPLIERS HAVE BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. Palm OS, Palm Computing, HandFAX, HandSTAMP, HandWEB, Graffiti, HotSync, iMessenger, MultiMail, Palm.Net, PalmPak, PalmConnect, PalmGlove, PalmModem, PalmPoint, PalmPrint, and PalmSource are registered trademarks of PalmSource, Inc. or its affiliates. Palm, the Palm logo, MyPalm, PalmGear, PalmPix, PalmPower, AnyDay, EventClub, HandMAIL, the HotSync logo, PalmGlove, Palm Powered, the Palm trade dress, Smartcode, Simply Palm, ThinAir, WeSync, and Wireless Refresh are trademarks of PalmSource, Inc. or its affiliates. All other product and brand names may be trademarks or registered trademarks of their respective owners. IF THIS DOCUMENTATION IS PROVIDED ON A COMPACT DISC, THE OTHER SOFTWARE AND DOCUMENTATION ON THE COMPACT DISC ARE SUBJECT TO THE LICENSE AGREEMENT ACCOMPANYING THE COMPACT DISC. L Palm OS Programmer’s Companion, Volume I PalmSource, Inc. Document Number 3004-006 5470 Great America Pkwy. May 12, 2002 Santa Clara, CA 95054 For the latest version of this document, visit USA http://www.palmos.com/dev/support/docs/. www.palmos.com Document Number 3004-006 Table of Contents About This Document xiii Palm OS SDK Documentation . xiii What This Volume Contains . xiii Additional Resources . xv 1 Programming Palm OS in a Nutshell 1 Why Programming for Palm OS Is Different . 1 Screen Size . 2 Quick Turnaround Expected . 2 PC Connectivity . 3 Input Methods . 3 Power . 3 Memory . 4 File System . 4 Backward Compatibility . 4 Palm OS Programming Concepts . 4 API Naming Conventions . 6 Integrating Programs with the Palm OS Environment . 7 Writing Robust Code . 9 Assigning a Database Type and Creator ID . 11 Making Your Application Run on Different Devices . 12 Running New Applications on an Older Device . 13 Backward Compatibility with PalmOSGlue . 14 Compiling Older Applications with the Latest SDK . 14 Programming Tools . 15 Where to Go from Here . 16 2 Application Startup and Stop 19 Launch Codes and Launching an Application . 20 Responding to Launch Codes . 20 Responding to Normal Launch. 23 Responding to Other Launch Codes . 25 Launching Applications Programmatically . 27 Creating Your Own Launch Codes . 28 Palm OS Programmer’s Companion, Volume I iii Stopping an Application . 29 Notifications . 30 Registering for a Notification . 31 Writing a Notification Handler . 34 Sleep and Wake Notifications . 35 Helper Notifications . 38 When to Use the Helper API . 39 Requesting a Helper Service . 40 Implementing a Helper . 42 Launch Code Summary . 46 Notification Summary. 48 Launch and Notification Function Summary . 50 3 Event Loop 53 The Application Event Loop . 55 Low-Level Event Management . 58 The Graffiti Manager . 60 The Key Manager . 62 The Pen Manager. 62 The System Event Manager . 63 System Event Manager Summary . 66 4 User Interface 69 Palm OS Resource Summary . 70 Drawing on the Palm Powered Handheld . 72 The Draw State . 73 Drawing Functions . 74 High-Density Displays . 75 Forms, Windows, and Dialogs . 83 Alert Dialogs . 85 Progress Dialogs . 86 The Keyboard Dialog . 87 Offscreen Windows. 91 Controls . 92 Buttons . 92 Pop-Up Trigger . 93 iv Palm OS Programmer’s Companion, Volume I Selector Trigger . 94 Repeating Button. 95 Push Buttons . 96 Check Boxes . 97 Sliders and Feedback Sliders . 98 Fields . 102 Menus . 105 Checking Menu Visibility . 107 Dynamic Menus . 108 Menu Shortcuts . 109 Tables . 111 Table Event . 112 Lists . 112 Using Lists in Place of Tables. 114 Categories . 116 Initializing Categories in a Database . 117 Initializing the Category Pop-up Trigger. 119 Managing a Category Pop-up List . 120 Bitmaps . 123 Versions of Bitmap Support . 123 Bitmap Families . 130 Drawing a Bitmap . 135 Color Tables and Bitmaps . 137 Labels . 137 Scroll Bars . 137 Custom UI Objects (Gadgets). 140 Dynamic UI . 142 Dynamic User Interface Functions . 144 Color and Grayscale Support. 144 Indexed Versus Direct Color Display . 145 Color Table . 145 UI Color List. 147 Direct Color Functions . 149 Pixel Reading and Writing. 150 Direct Color Bitmaps . 150 Palm OS Programmer’s Companion, Volume I v Insertion Point . 153 Application Launcher . 153 Icons in the Launcher . 153 Application Version String. 154 The Default Application Category . 155 Opening the Launcher Programmatically . 156 Summary of User Interface API . 157 5 Memory 169 Introduction to Palm OS Memory Use . 169 Hardware Architecture . 169 PC Connectivity . 170 Memory Architecture . 171 Heap Overview . 175 The Memory Manager. 178 Memory Manager Structures. 178 Using the Memory Manager . 181 Achieving Optimum Performance . 184 Summary of Memory Management . 186 6 Files and Databases 189 The Data Manager . 189 Records and Databases . 190 Structure of a Database Header . 191 Using the Data Manager . 195 Data Manager Tips . 197 The Resource Manager . 198 Structure of a Resource Database Header . 199 Using the Resource Manager. 200 File Streaming Application Program Interface . 202 Using the File Streaming API . 202 Summary of Files and Databases . 203 7 Expansion 207 Expansion Support . 208 Primary vs. Secondary Storage . 208 vi Palm OS Programmer’s Companion, Volume I Expansion Slot . 209 Universal Connector . 209 Architectural Overview . 210 Slot Drivers . 211 File Systems . 212 VFS Manager . 212 Expansion Manager . 214 Standard Directories . 215 Applications on Cards. 216 Card Insertion and Removal . 218 Start.prc. 223 Checking for Expansion Cards . 224 Verifying Handheld Compatibility . 224 Checking for Mounted Volumes . 225 Enumerating Slots . 226 Determining a Card’s Capabilities . 227 Volume Operations . 228 Hidden Volumes . 229 Matching Volumes to Slots. ..