Programming of Mobile and Handheld
Devices
Lecture 3: Programming for Palm OS
Rob Pooley
rjp@macs.hw.ac.uk
Lecture 3 Programming
on Palm OS
Mobile and Handheld Applications
1
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.
Lecture 3 Programming
on Palm OS
Mobile and Handheld Applications
2
Typical PilotMain
UInt32 PilotMain (UInt16 cmd, void *cmdPBP,
UInt16 launchFlags)
{
UInt32 error = StartQuizApp();
if(error) return error;
QuizAppEventLoop();
EndQuizApp();
return errNone;
}
Lecture 3 Programming
on Palm OS
Mobile and Handheld Applications
3
Simple Start Application
static UInt16 StartQuizApp(void)
{
UInt16 error = 0;
FrmGotoForm(MainForm);
return errNone;
}
Lecture 3 Programming
on Palm OS
Mobile and Handheld Applications
4
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);
Lecture 3 Programming
on Palm OS
Mobile and Handheld Applications
5
EndQuizApp
static void EndQuizApp(void)
{
FrmCloseAllForms( );
}
Lecture 3 Programming
on Palm OS
Mobile and Handheld Applications
6
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.
Lecture 3 Programming
on Palm OS
Mobile and Handheld Applications
7
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);
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;
switch (formId) {
case MainForm:
FrmSetEventHandler(form,
MainFormHandleEvent);
break;
case HistoryForm:
FrmSetEventHandler(form,
HistoryFormHandleEvent);
break;
}
Lecture 3 Programming
on Palm OS
Mobile and Handheld Applications
8
FrmDispatchEvent - pseudocode
Boolean
FrmDispatchEvent(EventType
*event)
{
Boolean handled = result of
calling Form's event handler;
if (handled) return true;
else return
FrmHandleEvent(event);
}
Lecture 3 Programming
on Palm OS
• 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.
Mobile and Handheld Applications
9
Example of an event handler
Boolean WrongFormHandleEvent(EventPtr
event)
{
Boolean handled = false;
FormPtr form;
switch (event->eType)
{
case frmOpenEvent:
default:
ErrFatalDisplay("Mysterious Wrong Form
Button Event");
handled = false;
break;
}
break;
form = FrmGetActiveForm();
FrmDrawForm(form);
handled = true;
break;
case frmCloseEvent:
MainFormDeinit(FrmGetActiveForm());
handled = false;
break;
case ctlSelectEvent:
switch (event->data.ctlSelect.controlID) {
case TryAgainButton:
FrmGotoForm(MainForm);
handled = true;
break;
Lecture 3 Programming
on Palm OS
default:
}
return handled;
}
Mobile and Handheld Applications
10
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
Lecture 3 Programming
on Palm OS
Mobile and Handheld Applications
11
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.
Lecture 3 Programming
on Palm OS
Mobile and Handheld Applications
12
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.
Lecture 3 Programming
on Palm OS
Mobile and Handheld Applications
13
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.
Lecture 3 Programming
on Palm OS
Mobile and Handheld Applications
14
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
Lecture 3 Programming
on Palm OS
Mobile and Handheld Applications
15
Header files and resources
#include <PalmOS.h>
#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.
Lecture 3 Programming
on Palm OS
Mobile and Handheld Applications
16
The files in a project
Lecture 3 Programming
on Palm OS
Mobile and Handheld Applications
17
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
Lecture 3 Programming
on Palm OS
Mobile and Handheld Applications
18
Excerpt from GuessALot.xrd
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<PALMOS_RESOURCE_FILE>
<FORM_RESOURCE RESOURCE_ID="1000">
<COMMENT_TEXT> "Welcome to Guess a Lot." </COMMENT_TEXT>
<FORM_ID> 1000 </FORM_ID>
<BOUNDS>
<LEFT> 2 </LEFT>
<TOP> 2 </TOP>
<WIDTH> 156 </WIDTH>
<HEIGHT> 156 </HEIGHT>
</BOUNDS>
<USABLE> TRUE </USABLE>
<MODAL> TRUE </MODAL>
<SAVE_BEHIND> TRUE </SAVE_BEHIND>
<HELP_ID> 0 </HELP_ID>
<MENU_ID> 0 </MENU_ID>
<DEFAULT_BUTTON> 0 </DEFAULT_BUTTON>
<FORM_OBJECTS>
<FORM_TITLE>
<TEXT> "Guess a Lot" </TEXT>
</FORM_TITLE>
<FORM_BUTTON>
<ID> 1000 </ID>
<BOUNDS>
<LEFT> 93 </LEFT>
<TOP> 97 </TOP>
<WIDTH> 58 </WIDTH>
<HEIGHT> 12 </HEIGHT>
</BOUNDS>
<USABLE> TRUE </USABLE>
<ENABLED> TRUE </ENABLED>
<TEXT> "History" </TEXT>
<LEFT_ANCHOR> FALSE </LEFT_ANCHOR>
<FONT_ID> STD_FONT </FONT_ID>
<BUTTON_FRAME> STANDARD_BUTTON_FRAME </BUTTON_FRAME>
</FORM_BUTTON>
Lecture 3 Programming
on Palm OS
Mobile and Handheld Applications
19
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 =
Lecture 3 Programming
on Palm OS
Mobile and Handheld Applications
20
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.
Lecture 3 Programming
on Palm OS
Mobile and Handheld Applications
21
Process for Building Palm OS 68K
Applications
AppResources.h
PalmOS.h
C source file
Resource
description file
app.xrd
Application
Lecture 3 Programming
on Palm OS
Mobile and Handheld Applications
22
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.
Lecture 3 Programming
on Palm OS
Mobile and Handheld Applications
23
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.
Lecture 3 Programming
on Palm OS
Mobile and Handheld Applications
24
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
Lecture 3 Programming
on Palm OS
Mobile and Handheld Applications
25
Opening the resource editor
Lecture 3 Programming
on Palm OS
Mobile and Handheld Applications
26
Lecture 3 Programming
on Palm OS
Mobile and Handheld Applications
27
Lecture 3 Programming
on Palm OS
Mobile and Handheld Applications
28
Lecture 3 Programming
on Palm OS
Mobile and Handheld Applications
29
Select new resource from the edit menu
Lecture 3 Programming
on Palm OS
Mobile and Handheld Applications
30
Lecture 3 Programming
on Palm OS
Mobile and Handheld Applications
31
Lecture 3 Programming
on Palm OS
Mobile and Handheld Applications
32
Lecture 3 Programming
on Palm OS
Mobile and Handheld Applications
33
Lecture 3 Programming
on Palm OS
Mobile and Handheld Applications
34