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

2. Lecture 3 Programming on Palm OS Mobile and Handheld Applications2 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. Lecture 3 Programming on Palm OS Mobile and Handheld Applications3 Typical PilotMain UInt32 PilotMain (UInt16 cmd, void *cmdPBP, UInt16 launchFlags) { UInt32 error = StartQuizApp(); if(error) return error; QuizAppEventLoop(); EndQuizApp(); return errNone; }

4. Lecture 3 Programming on Palm OS Mobile and Handheld Applications4 Simple Start Application static UInt16 StartQuizApp(void) { UInt16 error = 0; FrmGotoForm(MainForm); return errNone; }

5. Lecture 3 Programming on Palm OS Mobile and Handheld Applications5 Event loop static void QuizAppEventLoop(void) { Err error; EventType event; do { EvtGetEvent(&event, evtWaitForever); if (! SysHandleEvent(&event)) if (! MenuHandleEvent(0, &event, &error)) if (! AppHandleEvent(&event)) FrmDispatchEvent(&event); } while (event.eType != appStopEvent);

6. Lecture 3 Programming on Palm OS Mobile and Handheld Applications6 EndQuizApp static void EndQuizApp(void) { FrmCloseAllForms( ); }

7. Lecture 3 Programming on Palm OS Mobile and Handheld Applications7 Event handlers and related functions An application should define and attach event handlers to any resources which require them. In this example there is an event handler for each form which is used. When AppHandleEvent is called it can detect events which request the loading of a new form and set the appropriate event handler for that form. An event handler is a function which is automatically called, by FrmDispatchEvent, when a particular form is active. In this way we set up some of the logic of our application. In our application there are several types of form, each created using the Resource Editor tool in the Developer Suite and each with its own buttons. We make the Id of each form distinct. It is not strictly necessary for resources of different types to have different Ids.

8. Lecture 3 Programming on Palm OS Mobile and Handheld Applications8 Typical AppHandleEvent static Boolean AppHandleEvent(EventPtr event) { UInt16 formId; FormPtr form; if (event->eType == frmLoadEvent) { // Load the form resource. formId = event->data.frmLoad.formID; form = FrmInitForm(formId); ErrFatalDisplayIf(!form, "Can't initialize form"); FrmSetActiveForm(form); switch (formId) { case MainForm: FrmSetEventHandler(form, MainFormHandleEvent); break; case HistoryForm: FrmSetEventHandler(form, HistoryFormHandleEvent); break; case MathsForm: FrmSetEventHandler(form, MathsFormHandleEvent); break; case WrongForm: FrmSetEventHandler(form, WrongFormHandleEvent); break; case CorrectForm: FrmSetEventHandler(form, CorrectFormHandleEvent); break; default: ErrFatalDisplay("Invalid Form Load Event"); break; } return true; } else return false; }

9. Lecture 3 Programming on Palm OS Mobile and Handheld Applications9 FrmDispatchEvent - pseudocode Boolean FrmDispatchEvent(EventType *event) { Boolean handled = result of calling Form's event handler; if (handled) return true; else return FrmHandleEvent(event); } FrmDispatchEvent is written to allow the application to interpret events such as button presses if they are meaningful to this application. This is done by calling an event handler which is installed within the current form. If that fails, it passes these on to the system’s FrmHandleEvent.

10. Lecture 3 Programming on Palm OS Mobile and Handheld Applications10 Example of an event handler Boolean WrongFormHandleEvent(EventPtr event) { Boolean handled = false; FormPtr form; switch (event->eType) { case frmOpenEvent: form = FrmGetActiveForm(); FrmDrawForm(form); handled = true; break; case ctlSelectEvent: switch (event->data.ctlSelect.controlID) { case TryAgainButton: FrmGotoForm(MainForm); handled = true; break; default: ErrFatalDisplay("Mysterious Wrong Form Button Event"); handled = false; break; } break; case frmCloseEvent: MainFormDeinit(FrmGetActiveForm()); handled = false; break; default: } return handled; }

11. Lecture 3 Programming on Palm OS Mobile and Handheld Applications11 More on conventions Most Palm OS applications contain a user interface made up of forms, which are analogous to windows in a desktop application Only one form is normally visible at a time 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

12. Lecture 3 Programming on Palm OS Mobile and Handheld Applications12 More conventions All applications should use the memory and data management facilities provided by the system. 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, for example, to generate sounds, send alarms, perform network communication, and beam information through an infrared port.

13. Lecture 3 Programming on Palm OS Mobile and Handheld Applications13 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.

14. Lecture 3 Programming on Palm OS Mobile and Handheld Applications14 Writing Robust Code Check assumptions. Avoid continual polling. Avoid reading and writing to NULL (or low memory). Check result codes when allocating memory. Avoid making assumptions about the screen. Built-in applications can change.

15. Lecture 3 Programming on Palm OS Mobile and Handheld Applications15 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

16. Lecture 3 Programming on Palm OS Mobile and Handheld Applications16 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 (subfolder) 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.

17. Lecture 3 Programming on Palm OS Mobile and Handheld Applications17 The files in a project

18. Lecture 3 Programming on Palm OS Mobile and Handheld Applications18 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

19. Lecture 3 Programming on Palm OS Mobile and Handheld Applications19 Excerpt from 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

20. Lecture 3 Programming on Palm OS Mobile and Handheld Applications20 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 =

21. Lecture 3 Programming on Palm OS Mobile and Handheld Applications21 Palm UI and other Resources Palm OS applications are built using two main input files and a software development environment which combines and links the outputs from these. –See www.palmos.com/dev/support/docs/dev_suite/PalmOSDevSuite/Tools_Overview.html We have seen the first of these input files – the source code, written in C or C++. The second defines the structures available in the application, such as GUI screens and buttons. It is written as an XRD resource file, which is structured as an XML file.

22. Lecture 3 Programming on Palm OS Mobile and Handheld Applications22 Process for Building Palm OS 68K Applications PalmOS.h AppResources.h C source file Application Resource description file app.xrd

23. Lecture 3 Programming on Palm OS Mobile and Handheld Applications23 Building Palm OS 68K applications Palm OS Developer Suite includes PRC-Tools. PRC-Tools includes patched versions of the GNU packages gcc, binutils, gdb, and various post-linker tools. Create a 68K C/C++ Project for your source code. You can choose either a standard make project or a managed make project. Create your C/C++ source files using the C/C++ editor provided. Create your application's XML resource definition (XRD) files either by using Palm OS Resource Editor or by editing the XML file using a text editor. Build your project. From Developer Suite, select Build Project or Rebuild Project to build your 68K application.

24. Lecture 3 Programming on Palm OS Mobile and Handheld Applications24 Testing and running Test your application by running it on Palm OS Emulator, Palm OS Simulator, or a Palm Powered™ device. From Palm OS Developer Suite, select Run > Run to open the Run dialog box, and use the Target tab to select the run target for your application. Debug your application, using the debugger integrated with Palm OS Developer Suite. From Palm OS Developer Suite, select Run > Debug to open the Debug dialog box, and use the Target tab to select the debug target for your application.

25. Lecture 3 Programming on Palm OS Mobile and Handheld Applications25 Creating resource (XRD) files The following sequence takes you through the steps required to create the XRD file It starts from the Palm OS project environment It creates a new XRD file using the Palm OS graphical resource builder Remember that this does not create the corresponding C header file automatically You have to edit a suitable.h file with the correct #define directives

26. Lecture 3 Programming on Palm OS Mobile and Handheld Applications26 Opening the resource editor

27. Lecture 3 Programming on Palm OS Mobile and Handheld Applications27

28. Lecture 3 Programming on Palm OS Mobile and Handheld Applications28

29. Lecture 3 Programming on Palm OS Mobile and Handheld Applications29

30. Lecture 3 Programming on Palm OS Mobile and Handheld Applications30 Select new resource from the edit menu

31. Lecture 3 Programming on Palm OS Mobile and Handheld Applications31

32. Lecture 3 Programming on Palm OS Mobile and Handheld Applications32

33. Lecture 3 Programming on Palm OS Mobile and Handheld Applications33

34. Lecture 3 Programming on Palm OS Mobile and Handheld Applications34