Palm OS Programmer's Companion (Preliminary)
Total Page:16
File Type:pdf, Size:1020Kb
Palm OS Programmer’s Companion (Preliminary) Navigate this online document as follows: To see bookmarks, Command-7 (Mac OS) type: Ctrl-7 (Windows) To navigate, any blue hypertext link click on: any Table of Contents entry any Index entry arrows in the toolbar Palm OS Programmer’s Companion (Preliminary) Copyright © 1996 - 1999, 3Com Corporation or its subsidiaries (“3Com”). All rights reserved. This docu- mentation may be printed and copied solely for use in developing products for the Palm Computing plat- form. 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 3Com. 3Com reserves the right to revise this documentation and to make changes in content from time to time without obligation on the part of 3Com to provide notification of such revision or changes. 3COM MAKES 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. 3COM MAKES NO WARRANTIES, TERMS OR CONDITIONS, EXPRESS OR IM- PLIED, 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, 3COM ALSO EXCLUDES FOR ITSELF AND ITS SUPPLI- ERS 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 3COM HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. 3Com, the 3Com logo, HotSync, Palm Computing, and Graffiti are registered trademarks, and iMessenger, Palm III, Palm IIIx, Palm V, Palm VII, Palm.Net, Palm OS, and the Palm Computing Platform logo are trademarks of 3Com Corporation or its subsidiaries. Microsoft and Windows are registered trademarks of Microsoft Corporation. Other brand and product names may be registered trademarks or trademarks of their respective holders. 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. Contact Information: 3Com (Palm Computing Subsidiary) 5400 Bayfront Plaza P.O. Box 58007 Santa Clara, CA. 95052-8007 U.S.A. 3Com (Palm Computing Subsidiary) U.S.A.: 1-800-881-7256 Mail Order Canada: 1-800-891-6342 elsewhere: 801-431-1536 Web: http://www.palm.com Palm Computing World Wide Web Web: http://www.palm.com Developer Technical support Web: http://www.palm.com/devzone/ Developer Mailing Lists Web: http://LS.palm.com Solution Provider Program Web: http://www.palm.com/spp/ (developer services and hardware discounts) Metrowerks World Wide Web Web: http://www.metrowerks.com Table of Contents About This Document 13 Palm OS SDK Documentation . 13 What This Volume Contains . 13 Conventions Used in This Guide . 15 1 Programming Palm OS in a Nutshell 17 Why Programming for Palm OS Is Different . 17 Screen Size . 17 Quick Turnaround Expected . 18 PC Connectivity . 18 Input Methods . 19 Power . 19 Memory . 19 File System . 20 Backward Compatibility . 20 Palm OS Programming Concepts . 20 Programming Tools . 22 Where to Go From Here . 22 2 Good Design Practices 25 Designing Your Application . 26 Integrating Programs With the Palm OS Environment . 26 Naming Conventions . 29 Achieving Optimum Performance . 30 Assigning a Creator ID . 31 Working With Databases . 31 Writing Robust Code . 32 Avoiding Potential Pitfalls . 34 User Interface Guidelines . 35 Understanding the Palm OS UI Design Philosophy . 35 Creating a Palm OS User Interface . 38 Palm OS Resource Selection: List or Table?. 46 Localization Guidelines . 46 Making Your Application Run on Different Devices . 47 Palm OS Programmer’s Companion (Preliminary) 5 Running New Applications on an Older Device . 48 Compiling Older Applications With The Latest SDK . 49 3 Application Startup and Stop 51 Launch Codes and Launching an Application . 51 Responding to Launch Codes . 52 Responding to Normal Launch. 55 Responding to Other Launch Codes . 58 Launching Applications Programmatically . 59 Creating Your Own Launch Codes . 60 Stopping an Application . 60 Launch Code Summary . 62 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 . 74 5 User Interface 77 Palm OS Resource Summary . 78 Drawing on the Palm OS Device . 79 Forms, Windows, and Dialogs . 79 Alert Dialogs . 81 Progress Dialogs . 82 Controls . 84 Buttons . 84 Popup Trigger . 85 Selector Trigger . 86 Repeating Button. 87 Push Buttons . 88 Check Boxes . 89 Fields . 90 6 Palm OS Programmer’s Companion (Preliminary) Menus . 93 Tables . 95 Table Event . 95 Lists . 96 Labels . 98 Scroll Bars . 98 Custom UI Objects . 100 Dynamic UI . 100 Dynamic User Interface Functions . 101 Insertion Point . 102 Text . 102 Working With Text As Strings . 102 Fonts in Palm OS 3.0 and Later . 104 Receiving User Input . 105 The Graffiti Manager . 105 The Key Manager . 107 The Pen Manager. 108 Application Launcher . 108 Summary of User Interface API . 110 6 Memory 123 Introduction to Memory Use on Palm OS . 123 Hardware Architecture . 123 PC Connectivity . 124 Memory Architecture . 125 Heap Overview . 129 The Memory Manager. 131 Memory Manager Structures. 132 Using the Memory Manager . 135 Summary of Memory Management . 138 7 Files and Databases 141 The Data Manager . 141 Records and Databases . 142 Structure of a Database Header. 143 Using the Data Manager . 145 Palm OS Programmer’s Companion (Preliminary) 7 The Resource Manager . 148 Structure of a Resource Database Header . 148 Using the Resource Manager. 149 File Streaming Application Program Interface . 151 Using the File Streaming API . 151 Summary of Files and Databases . 153 8 Palm System Features 157 Alarms . 157 Setting an Alarm . 158 Alarm Scenario . 160 Setting a Procedure Alarm . 161 Features . 163 The System Version Feature . 164 Application-Defined Features . 165 Using the Feature Manager . 165 Feature Memory . 166 Sound . 167 Synchronous and Asynchronous Sound . 169 Using the Sound Manager . 169 Sound Preferences Compatibility Information . 174 System Boot and Reset . 178 Soft Reset . 178 Soft Reset + Up Arrow . 178 Hard Reset . 179 System Reset Calls . 179 Hardware Interaction . 180 Palm OS Power Modes . 180 Guidelines for Application Developers . 181 Power Management Calls . 182 The Microkernel . 183 Retrieving the ROM Serial Number . 184 Time . 185 Using Real-Time Clock Functions. 186 Using System Ticks Functions . 186 8 Palm OS Programmer’s Companion (Preliminary) Floating-Point . 187 Using Floating Point Arithmetic . 187 Using 1.0 Floating-Point Functionality . 188 Summary of System Features. 188 9 Serial Communication 191 Serial Hardware . 191 Byte Ordering . 192 Serial Communications Architecture Hierarchy . 192 The Serial Manager . 194 Using the Serial Manager . 195 The New Serial Manager . 198 Checking for the New Serial Manager. 199 What's New About the New Serial Manager . 200 About the New Serial Manager. 200 Using the New Serial Manager . 202 New Serial Manager Example . 205 Writing a Serial or Virtual Device Driver. 208 The Connection Manager . 211 The Serial Link Protocol . 212 SLP Packet Structures . 212 Transmitting an SLP Packet . 215 Receiving an SLP Packet . 215 The Serial Link Manager. ..