Palm OS® Programmer’s Companion Document Number 3004-002 Print Date 3/00 CONTRIBUTORS Written by Christopher Bey, Elly Freeman, and Jean Ostrem Production by <dot>PS document production services Engineering contributions by David Fedor, Roger Flores, Steve Lemke, Bob Ebert, Ken Krugler, Bruce Thompson, Jesse Donaldson, Tim Wiegman, Gavin Peacock, Ryan Robertson, and Waddah Kudaimi Copyright © 1996 - 2000, Palm, Inc. 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 documenta- tion may be made for archival and backup purposes. Except for the foregoing, no part of this documenta- tion 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 Palm, Inc. Palm, Inc. reserves the right to revise this documentation and to make changes in content from time to time without obligation on the part of Palm, Inc. to provide notification of such revision or changes. PALM, INC. MAKES NO REPRESENTATIONS OR WARRANTIES THAT THE DOCUMENTATION IS FREE OF ERRORS OR THAT THE DOCUMENTATION IS SUITABLE FOR YOUR USE. THE DOCUMEN- TATION IS PROVIDED ON AN “AS IS” BASIS. PALM, INC. MAKES 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, PALM,INC. ALSO EXCLUDES FOR ITSELF AND ITS SUP- PLIERS 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 DOCU- MENTATION, EVEN IF PALM, INC. HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. Palm Computing, Palm OS, Graffiti, HotSync, and Palm Modem are registered trademarks, and Palm III, Palm IIIe, Palm IIIx, Palm V, Palm Vx, Palm VII, Palm, More connected., Simply Palm, the Palm Comput- ing platform logo, Palm III logo, Palm IIIx logo, Palm V logo, and HotSync logo are trademarks of Palm, Inc. or its subsidiaries. All other product and brand names may be trademarks or registered trademarks of their respective owners. IF THIS DOCUMENTATION IS PROVIDED ON A COMPACT DISK, THE OTHER SOFTWARE AND DOCUMENTATION ON THE COMPACT DISK ARE SUBJECT TO THE LICENSE AGREEMENT AC- COMPANYING THE COMPACT DISK. Palm OS Programmer’s Companion Palm, Inc. Document Number 3004-002 5400 Bayfront Plaza March 16, 2000 Santa Clara, CA 95052 USA www.palm.com/devzone Document Number 3004-002 Table of Contents About This Document 11 Palm OS SDK Documentation . 11 What This Volume Contains . 11 Conventions Used in This Guide . 13 1 Programming Palm OS in a Nutshell 15 Why Programming for Palm OS Is Different . 15 Screen Size . 15 Quick Turnaround Expected . 16 PC Connectivity . 16 Input Methods . 17 Power . 17 Memory . 17 File System . 18 Backward Compatibility . 18 Palm OS Programming Concepts . 18 Programming Tools . 20 Where to Go From Here . 20 2 Good Design Practices 23 Designing Your Application . 24 Integrating Programs With the Palm OS Environment . 24 Naming Conventions . 27 Achieving Optimum Performance . 28 Assigning a Creator ID . 29 Working With Databases . 29 Writing Robust Code . 30 Avoiding Potential Pitfalls . 32 User Interface Guidelines . 33 Understanding the Palm OS UI Design Philosophy . 33 Creating a Palm OS User Interface . 36 Palm OS Resource Selection: List or Table?. 45 Localization Guidelines . 45 Making Your Application Run on Different Devices . 46 Palm OS Programmer’s Companion 3 Running New Applications on an Older Device . 47 Compiling Older Applications With The Latest SDK . 48 3 Application Startup and Stop 49 Launch Codes and Launching an Application . 49 Responding to Launch Codes . 50 Responding to Normal Launch. 53 Responding to Other Launch Codes . 57 Launching Applications Programmatically. 58 Creating Your Own Launch Codes . 60 Stopping an Application . 60 Launch Code Summary . 61 4 Event Loop 65 The Application Event Loop . 67 Low-Level Event Management . 71 Event Translation: Pen Strokes to Key Events. 71 Pen Queue Management . 72 Key Queue Management . 73 Auto-Off Control . 74 System Event Manager Summary . 75 5 User Interface 77 Palm OS Resource Summary . 78 Drawing on the Palm OS Device . 79 The Draw State . 80 Drawing Functions . 81 Forms, Windows, and Dialogs . 82 Alert Dialogs . 83 Progress Dialogs . 84 Controls . 86 Buttons . 86 Popup Trigger . 87 Selector Trigger . 88 Repeating Button. 89 Push Buttons . 90 4 Palm OS Programmer’s Companion Check Boxes . 91 Sliders and Feedback Sliders . 92 Fields . 97 Menus . 99 Dynamic Menus . 101 Menu Shortcuts . 102 Tables . 104 Table Event . 105 Lists . 105 Categories . 107 Bitmaps . 109 Labels . 112 Scroll Bars . 112 Custom UI Objects . 115 Dynamic UI . 118 Dynamic User Interface Functions . 119 Color and Grayscale Support. 120 Color Table . 120 UI Color List. 122 Insertion Point . 124 Text . 124 Working With Text As Strings . 125 Fonts in Palm OS 3.0 and Later . 126 Receiving User Input . 127 The Graffiti Manager . 127 The Key Manager . 129 The Pen Manager . 130 Application Launcher . 131 Summary of User Interface API. 132 6 Memory 147 Introduction to Palm OS Memory Use . 147 Hardware Architecture . 147 PC Connectivity . 148 Memory Architecture . 149 Palm OS Programmer’s Companion 5 Heap Overview . 153 The Memory Manager. 156 Memory Manager Structures. 156 Using the Memory Manager . 159 Optimizing Memory Manager Performance . 162 Summary of Memory Management . 163 7 Files and Databases 165 The Data Manager . 165 Records and Databases . 166 Structure of a Database Header . 167 Using the Data Manager . 169 The Resource Manager . 172 Structure of a Resource Database Header . 172 Using the Resource Manager. 173 File Streaming Application Program Interface . 175 Using the File Streaming API . 175 Summary of Files and Databases . 177 8 Palm System Features 181 Alarms . 181 Setting an Alarm . 182 Alarm Scenario . 184 Setting a Procedure Alarm. 185 Features . 187 The System Version Feature . 188 Application-Defined Features . 189 Using the Feature Manager . 189 Feature Memory . 190 Notifications . 192 Registering for a Notification . 193 Writing a Notification Handler . 196 Sleep and Wake Notifications . 198 Sound. 199 Synchronous and Asynchronous Sound . 201 Using the Sound Manager . 201 6 Palm OS Programmer’s Companion Sound Preferences Compatibility Information . 206 System Boot and Reset . 210 Soft Reset . 210 Soft Reset + Up Arrow . 211 Hard Reset . 211 System Reset Calls . 212 Hardware Interaction . 212 Palm OS Power Modes . 212 Guidelines for Application Developers . 214 Power Management Calls . 214 The Microkernel . 215 Retrieving the ROM Serial Number . 216 Time . 218 Using Real-Time Clock Functions. 219 Using System Ticks Functions . 219 Floating-Point . 220 Using Floating Point Arithmetic . 220 Using 1.0 Floating-Point Functionality . 221 Summary of System Features. 221 9 Serial Communication 225 Serial Hardware . 225 Byte Ordering . 226.