Developing Palm OS 3.0 Applications Part I: Interface Management 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 Developing Palm OS 3.0 Applications Part I: Interface Management Copyright © 1996 - 1998, 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 Palm III, 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: Metrowerks U.S.A. and international Metrowerks Corporation 2201 Donley Drive, Suite 310 Austin, TX 78758 U.S.A. Metrowerks Canada Metrowerks Inc. 1500 du College, Suite 300 Ville St-Laurent, QC Canada H4L 5G6 Metrowerks Mail order Voice: 1-800-377–5416 Fax: 1-512-873–4901 3Com (Palm Computing Subsidiary) U.S.A.: 1-800-881-7256 Canada: 800-891-6342 Mail Order elsewhere: 1-801-431-1536 Metrowerks World Wide Web http://www.metrowerks.com Palm Computing World Wide Web http://www.palm.com Registration information [email protected] Technical support [email protected] Sales, marketing, & licensing [email protected] CompuServe go Metrowerks Table of Contents About This Document. 23 Palm OS SDK Documentation . 23 What This Guide Contains . 24 Conventions Used in This Guide . 25 What’s New in Palm OS 3.0 . 26 General Information . 26 New Launch Codes. 27 Dynamic User Interface Objects . 27 Font Functions . 27 Progress Manager . 28 File Streaming API . 28 Sound Manager . 29 Exchange Manager . 29 IR Library . 29 Miscellaneous New Functions in 3.0 . 30 Existing Functions that Changed in 3.0 . 30 Documentation Revisions . 31 1 Developing Palm OS Applications . 33 Overview of Application Development . 33 Designing UI and Program Functionality . 34 Constructing UI Resources . 35 Using Managers and Filling Out the Program Logic. 36 Writing Robust Code . 37 Building, Debugging, and Testing . 40 Building the Application and Running it on the Palm Device. 40 Using Other Components of the SDK . 41 Internal Structure of an Application . 41 The ‘code’ #1 Resource . 42 The ‘pref’ #0 Resource . 42 The ‘code’ #0 and ‘date’ #0 Resources . 43 Naming Conventions . 43 Basic Hardware . 44 RAM and ROM . 44 Developing Palm OS 3.0 Applications, Part I v Table of Contents Modes of Operation . 44 Palm OS Connectivity. 45 Real-Time Clock and Timer . 46 Palm OS Device Screen and Sound Generation . 46 Palm OS Device Reset Switch . 47 Different Palm Computing Platform Devices . 48 Running Older Applications on the 3.0 Device . 49 Compiling Older Applications With SDK Version 3.0 . 49 Using OS Version 3.0 Features . 50 Running 3.0 Applications on an Older Device . 50 Retrieving the System Version Number . 51 Retrieving the ROM Serial Number . 51 2 Application Control Flow . 55 How Events Control an Application . 57 Basic Application Stages. 57 The Startup Routine . 58 The Event Loop . 61 The Stop Routine . 65 How Launch Codes Control an Application . 66 Parameter Block . 67 Launch Flags . 67 Launch Code Example . 68 Summary of All Launch Codes . 70 More About Launch Codes. 71 sysAppLaunchCmdAlarmTriggered . 72 sysAppLaunchCmdCountryChange . 72 sysAppLaunchCmdDisplayAlarm . 72 sysAppLaunchCmdExgAskUser . 72 sysAppLaunchCmdExgReceiveData . 74 sysAppLaunchCmdFind . 74 sysAppLaunchCmdGoto . 76 sysAppLaunchCmdInitDatabase . 77 sysAppLaunchCmdLookup . 78 sysAppLaunchCmdPanelCalledFromApp . 79 sysAppLaunchCmdReturnFromPanel . 80 vi Developing Palm OS 3.0 Applications, Part I Table of Contents sysAppLaunchCmdSaveData . 80 sysAppLaunchCmdSyncNotify . 80 sysAppLaunchCmdSystemLock . 81 sysAppLaunchCmdSystemReset . 81 sysAppLaunchCmdTimeChange . 82 More About Launch Flags . 82 Responding to Launch Codes . 83 Determining Status When Receiving Launch Code . 84 Predefined Launch Codes . 84 Creating Your Own Launch Codes . 84 3 Palm OS User Interface Resources. 85 Using Constructor to Work With Resources . 86 Creating Resources . 86 Changing Resources . 87 Project Resources . 88 Alerts . 89 Form Resource . 91 String Resource. 94 Menus and Menu Bars . 94 Menu Overview . 94 Creating a Menu . 95 Menu Bar and Menu Resources . 96 Menu User Interaction . 96 Event Flow for Menu Resource. 98 Catalog Resources . 98 Button Resource . 100 Check Box Resource. 103 Field Resource . 106 Form Bitmap Resource . 109 Gadget Resource . 110 Graffiti Shift Indicator Resource . 111 Label Resource . 112 List Resource. 113 Popup Trigger Resource . 115 Push Button Resource . 117 Developing Palm OS 3.0 Applications, Part I vii Table of Contents Repeating Button Resource. 120 Scrollbar Resource . 122 Selector Trigger Resource . 124 Table Resource . 126 4 Palm OS User Interface Objects . 127 A Note on the Rectangle Structure . 128 Control Objects. 128 Control Object Events. 129 Structure of a Control . 130 Associated Resources . 133 Control Functions . 133 Date and Time Objects. 134 Date and Time Functions . 134 Field Objects . 134 Field Object Events . 135 Structure of a Field . 136 Associated Resources . 139 Field Functions . 140 Form Objects. 142 Form Object Events. 142 Structure of a Form . 144 Associated Resource . 149 Form Functions . 149 Insertion Point Object . 151 Insertion Point Functions . 151 List Object . 152 List Object Events . 153 Structure of a List . 154 Associated Resources . 156 List Functions . 156 Menu Objects . 157 Menu Events . 158 Structure of a Menu . 158 Menu Functions . 162 Scrollbar Object. 162 viii Developing Palm OS 3.0 Applications, Part I Table of Contents Table Objects . 166 Table Event . 166 Structure of a Table . 166 Associated Resource . 169 Table Functions . 169 Window Objects . 171 Window Events . 171 Structure of a Window . 171 Window Functions . 173 Dynamic User Interface Objects. ..