1. Programming of Mobile and Handheld Devices Lecture 5: Programming for Palm OS Rob Pooley rjp@macs.hw.ac.uk

2. Programming conventions Each application has a PilotMain() function Palm OS applications are largely event-driven and so contain an event loop; –this event loop is only started in response to the normal launch code. Your application may –perform work outside the event loop in response to other launch codes or –define a different event loop for other codes.

3. More on conventions Most Palm OS applications contain a user interface made up of forms, which are analogous to windows in a desktop application the Palm OS approach is to –define the elements of the user interface separately and –merge these with the application code when compiling and linking the final application

4. More conventions All applications should use the memory and data management facilities provided by the system. Thus, you should refrain from creating and deleting objects with malloc or new Applications employ operating system services by calling Palm OS functions. “managers,” are groups of functions that work together to implement a feature usually defined by a type of resource which they “manage”. Managers are available to, for example, generate sounds, send alarms, perform network communication, and beam information through an infrared port.

5. API Naming Conventions Functions –Functions start with a capital letter. –All functions belonging to a particular manager start with a short prefix, such as “ Ctl ” for control functions or “ Ftr ” for functions that are part of the Feature Manager. Events –Events and other constants start with a lowercase letter. Structures –Structure elements start with a lowercase letter. Typedefs –Typedefs start with a capital letter and end with “Type” (for example, DateFormatType, found in DateTime.h ). Notifications –Notifications start with a prefix (most often, “ sys ”) followed by the word “ Notify.” For example, sysNotifyAppLaunchingEvent. Launch codes –Launch codes have a prefix followed by “ LaunchCmd,” as in; sysAppLaunchCmdNormalLaunch.Enumerations –Members of an enumerated type start with a lowercase prefix followed by a name starting with a capital letter, as follows: enum formObjects { frmFieldObj, frmControlObj, frmListObj, frmTableObj, frmBitmapObj, frmLineObj, frmFrameObj, frmRectangleObj, frmLabelObj, frmTitleObj, frmPopupObj, frmGraffitiStateObj, frmGadgetObj }; typedef enum formObjects FormObjectKind

6. Compatibility with Palm OS Integrate with the system software as follows: –Handle sysAppLaunchCmdNormalLaunch –Handle or ignore other application launch codes as appropriate –In the stop routine, tidy up and return memory an application should first flush all active records, then close the application's database, and finally save those aspects of the current state needed for startup. –Be sure your application uses the system preferences for numeric formats, date, time, and start day of week. –Don’t obscure shift indicators. In addition, follow these rules: –Store state information in the application preferences database, not in the application record database. –If your application uses the serial port, be sure to close the port when you no longer need it so that the HotSync application can use it. –Ensure that your application properly handles the global find. Generally, searches and sorts aren’t case sensitive. –If your application supports private records, be sure they are unavailable to the global find when they should be hidden. –Integrate with the Launcher application by providing an application name, two application icons, and a version string –Follow the guidelines detailed in Exploring Palm OS: User Interface Guidelines. –Ensure that your application properly handles system messages during and after synchronization. –Ensure that protected records and masked record contents are not displayed if the user has so indicated. –Ensure that your application uses a consistent default state when the user enters it: –If your application uses sounds, be sure it uses the Warning and Confirmation sounds properly.

7. Writing Robust Code Check assumptions. –You can write defensive code by making frequent use of the DbgOnlyFatalErrorIf() macro, which enables your debug builds to check assumptions. –You can keep more important checks in the release builds by using the ErrFatalErrorIf() function Avoid continual polling. –To conserve the battery, avoid continual polling. –If appropriate, take advantage of the keyUpEvent or the facilities for performing event-based pen tracking to avoid polling altogether

8. Writing Robust Code Avoid reading and writing to NULL (or low memory). –In Palm OS reading and writing to NULL will cause your application to crash. –When calling functions that allocate memory, at least make sure that the pointers they return are non-NULL. Check result codes when allocating memory. –Because various Palm Powered devices have larger or smaller amounts of available memory, it is always a good idea to check result codes carefully when allocating memory.

9. Writing Robust Code Avoid making assumptions about the screen. –The size and shape of the screen, the screen buffer, and the number of pixels per bit vary from one Palm Powered device to another. –the functions provided are optimized to make best use of the underlying hardware and to allow multiple applications and system services to share it Built-in applications can change. –The format and size of the preferences (and data) for the built-in applications is subject to change. –Write your code defensively, and consider disabling your application if it is run on an untested version of the OS

10. Uniquely Identifying Your Palm OS Application Each Palm OS application in fact, each Palm OS database is uniquely identified by a combination of its name and a four-byte creator ID. Each database on the Palm Powered device has a type as well as a creator ID. –The database type allows applications and the OS to distinguish among multiple databases with the same creator ID. Types and creator IDs are case-sensitive and are composed of four ASCII characters in the range 32-126. –Types and creator IDs consisting of all lowercase letters are reserved for use by PalmSource, so any type or creator ID that you choose must contain at least one uppercase letter, digit, or symbol

11. Header files and resources #include #include "AppDefs.h" PalmOS.h is the Palm OS API include file and is always needed. –As a system library header it is enclosed in angle brackets when it is included. The other file here is one which you create and place into the src subdirectory of your project. –It contains all the resource identifiers you will use to link to the resource definition file and defines a unique symbolic name for each of them. –I have used the name AppDefs.h for this file, but you can choose your own name. –As a programmer defined header file, it is enclosed in double quotes when it is included.

12. The files in a project

13. AppDefs.h #define MainForm 1000 #define MainGotoHistoryFormButton 1000 #define MainGotoMathsFormButton 1001 #define MainLabel1 1002 #define MainLabel2 1003 #define MainOKButton 1004 #define HistoryForm 1100 #define HistoryCorrectButton 1100 #define HistoryWrongButton 1101 #define HistoryLabel 1102 #define HistoryTextField 1103 #define MathsForm 1200 #define MathsCorrectButton 1200 #define MathsWrongButton 1201 #define MathsLabel 1202 #define MathsTextField 1203 #define WrongForm 1400 #define TryAgainButton 1402 #define CorrectForm 1300 #define AcceptCorrectButton 1302

14. GuessALot.xrd "Welcome to Guess a Lot." 1000 2 156 TRUE 0 "Guess a Lot" 1000 93 97 58 12 TRUE "History" FALSE STD_FONT STANDARD_BUTTON_FRAME

15. 1001 12 97 58 12 TRUE "Mathematics" FALSE STD_FONT STANDARD_BUTTON_FRAME 1003 33 31 TRUE STD_FONT "Welcome to Guess a Lot" 1002 33 57 TRUE STD_FONT "Please select a subject" 1004 61 127 36 12 TRUE "Exit" FALSE STD_FONT STANDARD_BUTTON_FRAME

16. Palm OS makefile ## ----------------------------------------------------------------------- # Palm OS Generic Makefile for Eclipse v1.0.0 # PalmOS4/68K # # Fill in this file to specify your project and the source that you want # to build, and the settings involved in the build. The makefile-engine.mk # will then do the hard work of the makefile and dependency handling. # # After starting a new project, please remember the following steps... #1. Add all sources and resources in SOURCES and RESOURCES #2. Review the other settings as needed. # ## ----------------------------------------------------------------------- SHELL = /bin/sh ## ----------------------------------------------------------------------- # Set up the artifact name, which is the root name of your project's output # without the extension. # # The PRC and/or static library name, the database name, and other file names # are based on the artifact name ## ----------------------------------------------------------------------- ARTIFACT_NAME =GuessaLotMore EMPTY = SPACE =$(EMPTY) $(EMPTY) ESCAPED_ARTIFACT_NAME = $(subst $(SPACE),\,$(ARTIFACT_NAME)) PRC_NAME = $(ESCAPED_ARTIFACT_NAME).prc LIB_NAME = $(ESCAPED_ARTIFACT_NAME).a ## ----------------------------------------------------------------------- # Sources and Resources # List all the sources (.c/.cpp) and resources (.xrd) in your project # Use project relative path names with forward slashes (src/code.cpp). # Please do not use spaces in directory names. # A note about XRD resource files: If you have existing.rsrc or.rcp files, # refer to the documentation for the GenerateXRD tool to convert them into # XRD files for use with all Palm OS SDKs. ## ----------------------------------------------------------------------- # TODO: Update all sources and resources SOURCES = src/AppMain.c RESOURCES = rsc/GuessaLot.xrd SLIB_DEF_FILE =