You are previewing Palm Programming: The Developer's Guide.
O'Reilly logo
Palm Programming: The Developer's Guide

Book Description

PalmPilot's popularity is growing and with over a million units sold, the Palm OS dominates the hand-held market. Wired has astutely described Palm's position in a recent article: "On its way to becoming the bestselling hand-held computer of all time, the 3Com PalmPilot has spawned an intense, emotional, and fanatical developer following not seen since the glory days of the Mac." (Wired, 20 Feb. 98). Palm Programming should be eagerly accepted by programmers because the authors worked closely with Palm to ensure that the book is tailored exactly to the needs of the ever-growing group of Palm developers. As nothing but some piecemeal documentation exists currently, this book provides a much needed solution to the Palm developers. In fact, Palm uses this book as their official developer's guide and will be using it in the future as a key part of their training materials for developers. There are currently no books on Palm programming (and we know of none that are planned). The only way to learn is by using the reference material published by Palm (available freely on their Web site), the tutorial they provide, or various Palm programming FAQs compiled by third parties. Palm Programming shows intermediate to experienced C programmers how to build a Palm application from the ground up. Using an easy-to- understand tutorial approach, this book gives readers everything necessary to create a wide range of Palm applications and conduits, from simple scripts through full-blown applications, and in the process provides thorough coverage of Palm programming. It includes a CD-ROM (Macintosh and Windows compatible) with the full source code to the examples in the book, a trial version of Palm's Software Development Kit, and third-party developer tools, including Metrowerks' CodeWarrior Lite programming kit. Outline Part 1: Overview of Palm OS and devices Chapter 1: The Palm Solution Chapter 2: Developing for Palm OS Chapter 3: Designing a solution Part 2: Programming for the handheld Chapter 4: Structure of an Application Chapter 5: Forms and Form Objects Chapter 6: Databases Chapter 7: Menus Chapter 8: Extras Chapter 9: Communications Chapter 10: Debugging Part 3: Programming for the desktop: conduits Chapter 11: Getting started with conduits Chapter 12: Uploading and Downloading Data Chapter 13: Two-way Syncing Appendix: Where to go from here

Table of Contents

  1. Palm Programming: The Developer’s Guide
    1. Foreword
    2. Foreword
    3. Preface
      1. The Palm Phenomenon
      2. Who This Book Is For—C Programmers
        1. Do You Need to Know C++?
        2. Do You Need to Be a Desktop Expert to Write a Conduit?
        3. Which Flavor Conduit Do You Want—C++ or Java?
      3. What This Book Is About and How to Read It
        1. The Breakdown of the Chapters
        2. How to Read This Book
          1. The skip-through approach
          2. The cover-to-cover method
          3. The in-front-of-a-computer approach
      4. What’s in a Name—Is It a Pilot or a Palm?
      5. Conventions Used in This Book
      6. How to Contact Us
      7. Versions of Things
      8. Whom We Need to Thank
    4. I. Palm—Why It Works and How to Program It
      1. 1. The Palm Solution
        1. Why Palm Succeeded Where So Many Failed
          1. No One Would Make a Good Enough Device
          2. Palm Device Size and Weight
          3. Palm Device Cost
          4. Palm Device Features
          5. What Palm OS Devices Don’t Have and Why
            1. A keyboard
            2. Text recognition software
            3. An industry-standard PC card slot
          6. Palm-Sized PCs—Are They Palm Killers?
        2. Designing Applications for Palm Devices
          1. Essential Design Elements
            1. Designing for a small screen size
            2. Limit text input on the handheld
            3. Seamlessly sync
            4. Make the application small
            5. Make the application fast
          2. User Interface Guidelines
        3. Elements in a Palm Application
          1. The Two-Part Solution
          2. HotSync Overview
        4. Summary
      2. 2. Development Environments and Languages
        1. Overview
          1. Overview of the OS
            1. Memory
            2. Resources
            3. Events
            4. Forms and controls
            5. Communications
            6. Palm 3.0 OS features
            7. Miscellaneous
          2. Overview of Conduits
        2. Handheld Development
          1. CodeWarrior for Palm OS
            1. Developing on the Macintosh
            2. Developing on Windows
          2. GCC
            1. What is in GNU PalmPilot SDK
            2. Where to get GCC
          3. Tools Directly from Palm Computing
        3. Alternative Development Environments
          1. Assembler SDK (ASDK)
          2. Jump
          3. CASL
        4. High-Level Forms Development
          1. Pendragon Forms
          2. Satellite Forms
          3. Handheld Development Recommendations
            1. Developing using Mac OS
            2. Developing using Unix
            3. Developing using Windows
            4. The choice for rapid prototyping, fast development, and great usability
            5. Switching platforms
            6. Switching development environments
        5. Conduit Development
          1. What Is a Conduit?
          2. Using C/C++
          3. Using Java
        6. Conclusion
      3. 3. Designing a Solution
        1. User Interface Elements in an Application
          1. Alerts
          2. Forms
          3. Menus, Menu Items, and Menubars
          4. Tables and Lists
          5. Miscellaneous User Interface Elements
        2. General Design of a Palm Application
          1. General Optimization
        3. How the Sample Applications Are Useful
        4. User Interface of the Sales Application
          1. The Sales Application Customer List
            1. The customer list
            2. New Customer
          2. Beam All Customers
          3. The Customer Order Form
            1. Creating an order
            2. Modifying an item in an order
            3. Deleting an item in an order
          4. Changing Customer Information
            1. The Customer Details
            2. The Item Details
          5. Deleting the Customer
          6. Beaming the Customer
          7. Edit and Options Menus
        5. Developing a Prototype
          1. Clarify the Flow of Events
          2. The Start Screen
        6. Design Tradeoffs in the Sample Application
          1. Adding Items to an Order
          2. Where to Put Customer Information
            1. Creating a new customer
            2. Beaming a list of customers
            3. Deleting a customer
        7. Designing for a Small Screen
        8. Designing the Databases
        9. Designing the Conduit
          1. Processor-Intensive Tasks
          2. Design of the Sales Application Conduit
        10. Design Summary
    5. II. Designing Palm Applications
      1. 4. Structure of an Application
        1. Terminology
        2. A Simple Application
          1. What the Application Does
          2. The Hello World Source Code
          3. A Code Walkthrough of Hello World
            1. The #include files
            2. The main routine: PilotMain
            3. The startup routine: StartApplication
            4. The closing routine: StopApplication
            5. The main event loop
            6. Handling events with EvtGetEvent
            7. The event queue and application event loop
            8. SysHandleEvent
            9. MenuHandleEvent
            10. ApplicationHandleEvent
            11. Callbacks in GCC
            12. FrmDispatchEvent
          4. Hello World Summary
        3. Scenarios
        4. Memory Is Extremely Limited
          1. The Dynamic Heap
          2. Memory API
        5. Other Times Your Application Is Called
          1. Launch Codes
          2. Launch Flags
          3. A Few Scenarios
        6. Summary
      2. 5. Forms and Form Objects
        1. Resources
          1. Creating Resources in Constructor
            1. Use constants rather than raw resource IDs
            2. Using constants for your resources
          2. Creating Resources in PilRC
            1. The pretty points of PilRC
            2. PilRC example
            3. Using constants for your resources
          3. Reading Resources
          4. Writing Resources
        2. Forms
          1. Alerts
            1. Customizing an alert
            2. Alert example
            3. Tips on creating alerts
          2. Modal Dialogs
            1. Modal form template
            2. Modal form example
            3. A tip for modal forms
            4. Modal form sizes
            5. Help for modal forms
        3. Form Objects
          1. Dealing with Form Objects in Your Form Event
            1. Events generated by a successful tap
            2. Events generated by repeated taps
            3. Events generated by the start of a tap
            4. Events generated by the end of an unsuccessful tap
          2. Getting an Object from a Form
            1. Types of form object pointers
            2. Code example
            3. Error checking
          3. Form Object “Gotchas”
          4. Specific Form Objects
          5. Label Objects
            1. Changing the text of a label
            2. Problems with labels longer than the resource specification
          6. Gadget Objects
            1. What the gadget is responsible for
            2. A sample gadget
          7. List Objects
            1. Sample that displays a specific list item
            2. Custom versus noncustom lists
          8. Pop-up Trigger Objects
          9. Text Objects
            1. Setting text in a field
            2. Modifying text in a field
            3. Getting text from a field
            4. Other aspects of a field that require attention
            5. Field “gotchas”
          10. Scrollbar Objects
            1. Scrollbar coding requirements
            2. Updating the scrollbar based on the insertion point
            3. Updating the scrollbar when the number of lines changes
            4. Updating the display when the scrollbar moves
            5. Updating the display when the scroll buttons are used
            6. Scrolling a full page
        4. Resources, Forms, and Form Objects in the Sales Application
          1. Alerts
          2. Delete Customer
          3. Edit Customer
          4. Item Details
          5. Customers Form
          6. Switching Forms
      3. 6. Databases
        1. Overview of Databases and Records
          1. Write-Protected Memory
          2. Palm 3.0 OS Heap Changes
          3. Where Databases Are Stored
          4. How Records Are Stored Versus How They Are Referenced
        2. Creating, Opening, and Closing Databases
          1. Creating a Database
            1. Create your database in your StartApplication routine
            2. Creating a database from an image
          2. Opening a Database
          3. Closing a Database
          4. Creating the Application Info Block in a Database
        3. Working with Records
          1. Finding a Record
            1. Finding a record given a unique ID
            2. Finding a record given a key
          2. Creating a New Record
            1. Adding at the beginning of the database
            2. Adding at the end of the database
            3. Adding in sort order
          3. Reading from a Record
          4. Modifying a Record
          5. Handling Secret Records
          6. Iterating Through the Records in a Database or Category
          7. Sorting the Records in a Database
          8. Deleting a Record
          9. Dealing with Large Records
            1. File streaming
            2. Multiple chunks in a separate database
          10. Editing a Record in Place
            1. Initialize the field with the handle
            2. Cleanup once the editing is finished
        4. Examining Databases in the Sales Sample
          1. Defining the Sales Databases
          2. Reading and Writing the Customer
          3. Reading and Writing Products
          4. Working with Orders
          5. Opening, Creating, and Closing the Sales Databases
          6. Initializing the Sales Databases
            1. Initializing the customer database
            2. Initializing the product database
            3. The comparison routine for sorting
            4. Initializing the orders database
          7. Adding Records
          8. The Customers Form
          9. Editing Customers
          10. The Order Form
            1. Looking up a product
            2. Editing an item
            3. Deleting an item
            4. Adding a new item
            5. Finishing an order record
          11. The Item Form
      4. 7. Menus
        1. Menu User Interface
          1. Common Menu Shortcuts
          2. Arranging Menus
          3. Standard Menu Items
            1. Edit menu
            2. About application
          4. Applications Can Have Multiple Sets of Menus
        2. Menu Resources
          1. The .PRC file
          2. Using PilRC
          3. Using Constructor
            1. How Constructor creates menus
            2. How Constructor creates MENU resources
            3. Two problems with menus
            4. Creating your menus textually with PalmRez
          4. Associating Menubars with Forms
            1. Specifying the menubar of a form in Constructor
            2. Specifying the menubar of a form in PilRC
        3. Application Code for Menus
          1. MenuHandleEvent
          2. MyFormHandleEvent
          3. MyFormHandleMenuEvent
          4. Handling Items in the Edit Menu
          5. The About Menu
          6. Menu Erase Status
          7. Handling Unusable Menu Items
            1. A good time to remove a menu item
            2. Tools for implementing duplicate menus
          8. A Procedure for Handling Common Menu Items
        4. Adding Menus to the Sample Application
          1. The Menubars
          2. Menu Definitions
          3. Handling Common Menus
          4. Checking the OS Version Number
          5. The Customers Form
      5. 8. Extras
        1. Tables
          1. An Overview of Tables
            1. Scrolling in tables
            2. Adjusting width and height
            3. Data types in tables
              1. Display-only data types
              2. Edit and display data types
              3. Display-only data types
              4. Editable data types
            4. Initializing tables
          2. Simple Table Sample
            1. Initialization of the simple table sample
            2. Column 1—handling numbers
            3. Column 2—a checkbox
            4. Column 3—a label
            5. Column 4—a date
            6. Column 6—a pop-up trigger
            7. Columns 0, 5, and 7—handling text
            8. Column 8—handling custom content
            9. Displaying the columns
            10. Custom load routines
            11. Custom save routine
            12. Custom draw routine
            13. Handling a table event
        2. Tables in the Sample Application
          1. Tables with Editable Numeric Values
            1. Initialization
            2. Refreshing the form
            3. Displaying the quantity and product data
            4. Dynamically adjusting number fields
            5. Deallocating number fields
            6. Adding product names
            7. Adding scrolling support
            8. The table event handler
            9. Handling taps
            10. Handling key events
            11. Handling numeric cell selection
        3. Find
          1. Overview of Find
            1. The objectives of Find
          2. A Walkthrough of Finding Items
            1. The application’s response to a Find request
            2. Handling a Find request with multiple databases
            3. Navigating to a found item
            4. Displaying a found item from a running application
            5. Displaying a found item from a closed application
          3. Find in the Sales Application
            1. Handling the Find request
            2. Searching for matching strings
            3. Displaying the found item
        4. Beaming
          1. Beaming and the Exchange Manager
          2. How Beaming Works
          3. Programming Tips
            1. Optimization tips
            2. Debugging tips
            3. General tips
          4. Step-by-Step Implementation Checklist
            1. Determine data interchange format
            2. Add beam user interface
            3. Send an entry
            4. Receive an entry
            5. Display received item
            6. Send an entire category
            7. Receive an entire category
            8. Test all possibilities
          5. Sales Application
            1. Sending a single customer
            2. Receiving a record
            3. Sending all customers
            4. Receiving all customers
        5. Barcodes
          1. Handling Scanning in an Application
          2. A Scanning Sample
            1. Starting up the application
            2. The application shutdown
            3. Event handling
      6. 9. Communications
        1. Serial
          1. Tips for Using the Serial Manager
          2. Sample Serial Application
            1. Features of the sample application
            2. The GPS device
            3. The NMEA protocol
            4. The sample application serial code
        2. TCP/IP
          1. Network API
          2. Tips for Using TCP/IP
          3. Sample Network Application
            1. The sample on Linux
            2. The Linux main program
            3. Linux include files and global definitions
            4. Sending the mail
            5. Connecting to the server
            6. Getting a port
            7. Reading data character by character
            8. Sending data character by character
            9. Testing the Linux application
            10. Porting the Linux application to Palm OS
          4. TCP/IP Summary
      7. 10. Debugging Palm Applications
        1. Using POSE
          1. Major Advantages to POSE
          2. Future POSE Features
          3. Minor Disadvantages to POSE
          4. Cross-Platform Capabilities
          5. Mac OS-Specific Commands
          6. Windows-Specific Commands
        2. Device Reset
        3. Graffiti Shortcut Characters
        4. Source-Level Debugging with CodeWarrior
          1. Choosing a Target
            1. Using POSE
            2. Using a handheld
          2. Debugging Commands
          3. Console Window
        5. Source-Level Debugging with GNU PalmPilot SDK
        6. Using Simulator on Mac OS
        7. Gremlins
          1. Gremlins and Gadgets
          2. Using Gremlins Repeatedly
          3. Other Advice
    6. III. Designing Conduits
      1. 11. Getting Started with Conduits
        1. Overview of Conduits
          1. What Does a Conduit Do?
          2. Conduit Development on Windows
            1. CDK 3.0
            2. Using Visual C++
            3. Using Java
          3. Conduit Development on Macintosh
          4. Required Elements in a Minimal Conduit
        2. Registering and Unregistering a Conduit
          1. The Old, Ugly Way
          2. The New, Sleek Way
          3. CDK 3.0—Information Needed to Register
            1. Required conduit entries
            2. Optional entries
            3. Java-only entries
          4. Registering and Unregistering Manually Using CondCfg
          5. Automatically Installing and Uninstalling a Conduit
            1. Installing the conduit
            2. ConduitInstall.exe
            3. Automatically uninstalling a conduit
            4. ConduitDeinstall.exe
          6. Finding the Correct Conduit Manager DLL
            1. The solution to finding CondMgr.DLL
            2. Implementing the solution
            3. The elements in our installation
        3. Conduit Entry Points
          1. Required Entry Points
          2. Optional Entry Points
        4. The HotSync Log
          1. LogAddEntry
          2. LogAddEntry(logString, activity, timestamp)
          3. LogAddFormattedEntry
        5. When the HotSync Button Gets Pressed
        6. Using the Backup Conduit
          1. Applications That Might Use the Backup Conduit
          2. Using System Prefs Instead
          3. Setting the Backup Bit for a Database
        7. Creating a Minimal Sales Conduit
          1. Code for the Sales Conduit
            1. Adding GetConduitName
            2. Adding GetConduitVersion
            3. Adding OpenConduit
            4. Adding ConfigureConduit
            5. DLL doings
            6. Adding GetConduitInfo
          2. Registering the Conduit
          3. Testing
            1. Proving ChangeConduit works
            2. Seeing the conduit in the HotSync log
            3. Setting the conduit to Do Nothing
      2. 12. Uploading and Downloading Data with a Conduit
        1. Conduit Requirements
        2. Where to Store Data
        3. Creating, Opening, and Closing Databases
          1. Creating a Database
          2. Opening a Database
          3. Closing the Database
        4. Downloading to the Handheld
          1. Deleting Existing Records
          2. Writing Records
          3. Writing the AppInfo Block
        5. Uploading to the Desktop
          1. Finding the Number of Records
          2. Reading Records
            1. Iterating through each record stopping only for altered ones
            2. Looking up exact records via unique record ID
            3. Iterating through the records of a database from beginning to end
            4. The CRawRecordInfo class
          3. Reading the AppInfo Block
          4. Deleted/Archived Records
            1. Archiving records
            2. Deleting records
        6. When the HotSync Button Gets Pressed
        7. Portability Issues
          1. Byte Ordering
          2. Structure Packing
        8. The Sales Conduit
          1. Format Used to Store Data on the Desktop
          2. Modifying OpenConduit
          3. General Code
            1. Database defines
            2. Globals
            3. Data structures
          4. Downloading to the Handheld
            1. Downloading customers
            2. Downloading products
          5. Uploading to the Desktop
            1. Uploading orders
            2. Uploading customers
      3. 13. Two-Way Syncing
        1. The Logic of Syncing
          1. Fast Sync
            1. Examine the desktop data
            2. Examine the handheld data
            3. Examine the local data
            4. Dispose of the old data
            5. Write local database to desktop database
          2. Thorny Comparisons—Changes to the Same Records on Both Platforms
            1. A record is deleted on one database and modified on the other
            2. A record is archived on one database and changed on the other
            3. A record is archived on one database and deleted on the other
            4. A record is changed on one database and changed differently on the other
            5. A record is changed on one database and changed identically on the other
          3. Slow Sync
        2. The Conduit Classes
          1. The Classes and Their Responsibilities
          2. CBaseConduitMonitor
            1. CreateTable
            2. ConstructRecord
            3. SetArchiveFileExt
            4. LogRecordData
            5. LogApplicationName
            6. CBaseConduitMonitor data member
          3. CBaseTable
            1. Functions you must override
            2. CBaseTable functions you can’t override, but wish you could
          4. CBaseSchema
            1. Functions you must override
            2. CBaseSchema data members
          5. CBaseRecord
            1. Functions you must override
            2. Useful functions
            3. CBaseRecord data members
          6. CDTLinkConverter
            1. Functions you must override
        3. Sales Conduit Sample Based on the Classes
          1. CSalesConduitMonitor—Copying the Class
            1. A virtual conundrum
            2. Code we wish you never had to see
          2. CSalesConduitMonitor
            1. CSalesConduitMonitor Class Definition
            2. CSalesConduitMonitor constructor
            3. Functions that require overriding
            4. The two category routines
            5. Modifying EngageStandard
          3. CBaseTable—Copying the Class
            1. The problem—virtual reality beats nonvirtual reality
            2. The CBaseTable code you have to copy
            3. CSalesTable
            4. Class definition
            5. CSalesTable constructor
            6. CSalesTable functions
            7. SaveTo
            8. WriteRecord
            9. ReplaceTabs
            10. OpenFrom
            11. ReadCustomer
          4. CSalesSchema
            1. Constants
            2. CSalesSchema class definition
            3. CSalesSchema functions
          5. CSalesRecord
            1. CSalesRecord class definition
            2. Class constructor
            3. CSalesRecord functions
            4. Getting the customer ID
            5. Setting the customer ID
            6. Assigning one record to another
            7. Comparing one record to another
          6. CSalesDTLinkConverter
            1. CSalesDTLinkConverter class definition
            2. CSalesDTLinkConverter constructor
            3. Converting to Palm record format
            4. Converting to CBaseRecord format
          7. The DLL
            1. DLL OpenConduit
            2. DLL class definition
            3. Initializing function
            4. Exit function
            5. DLL resources
          8. Testing the Conduit
        4. Generic Conduit
          1. Advantages of Using Generic Conduit
          2. Disadvantages of Using Generic Conduit
          3. Solution to the Disadvantages
          4. Generic Conduit Classes
            1. CPalmRecord
            2. CDbManager
            3. CHHMgr
            4. CPcMgr
            5. CArchiveDatabase
            6. CBackupMgr
            7. CPLogging
            8. CSynchronizer
        5. Sales Conduit Based on Generic Conduit
          1. CSalesPCMgr
            1. CSalesPCMgr constructor
            2. StoreDB function
            3. WriteRecord
            4. Retrieving a database
            5. Reading customer information
          2. CSalesSynchronizer
            1. Class definition
            2. Creating a CSalesPcMgr class
            3. The constructor
            4. Modifying perform to add uploading and downloading products and orders
          3. Creating the Conduit
      4. 14. Debugging Conduits
        1. HotSync Flags
          1. Running HotSync in Verbose Mode with -v
          2. A Different Verbose Mode with -L1
          3. A Different Verbose Mode with Packets Using -L2
          4. Quick-Connect Mode
          5. Rebuilding the Registry
        2. Source-Level Debugging
          1. Building a Debug Version
          2. Running a Debug Version
          3. Setting Breakpoints
        3. Avoiding Timeouts While Debugging
          1. Auto-off Timeout
          2. HotSync Timeout
            1. Opening the secret handheld option
            2. The secret alert
        4. Conduit Problems You Might Have
          1. When an Installed Conduit Doesn’t Run
            1. A mismatched HotSync and conduit
            2. The DLL isn’t where it’s supposed to be
          2. When the Handheld Crashes After Syncing
        5. Test with POSE
        6. Turn Off Other Conduits During Testing
        7. Use the Log, Luke
      5. A. Where to Go From Here
        1. Palm Programming Book Web Site
        2. The Official Palm Developer Site
          1. Getting Your Application Creator ID
          2. Developer Technical Support
          3. Other Developer Support
          4. Platinum Certification
        3. Palm Programming Mailing Lists
        4. Third-Party Palm Programming Resources
        5. Third-Party Palm Programming FAQ
        6. RoadCoders, Handheld Developers
        7. PalmCentral
        8. Journals and Magazines
          1. PalmPower Online Magazine
          2. Handheld Systems Journal
    7. Index
    8. Colophon