Programming for the Palm II

In an earlier article on Palm programming, "Programming

for the Palm", (October 2000, page 61), we talked about file types and

their internal structures. To recap, there are two types of "files" in

the Palm environment: a resource database, which is essentially the executable,

and a record database, which is the data required by a program. Both types have

some small but significant differences.

In this article we’ll take a look at some of the different

Palm programming alternatives and go about setting up the environment required

for one of them, before embarking on our first program.

In the beginning I didn’t really know the options available

in Palm programming. However, after some reading, I realized that there are

various options available. From command-line compilers to full-fledged IDEs, to

small "scriptable" languages that run on the Palm itself and others.

Languages from BASIC to C to Java and many other flavors are available and each

can be compiled on your desktop and installed on the Palm. The Palm also

supports BASIC, C, and Java. There are also a few RAD tools to quickly get you

up and running. However, none of these are well-developed themselves and have a

long way to go before you can start creating killer applications for the Palm

using these.

The most popular and powerful way of creating Palm

applications is using C and some Palm libraries. The PalmOS SDK is also

available at the Palm Developer Zone for free. All you need to do is register

and download it. Once that’s done, you can either use the commercial (and

expensive) CodeWarrior–an IDE for Palm development–or, like me, use the free

GNU C Compiler (GCC). The CD-ROM with this issue contains these, plus some other

tools. However, you may need to download some, as they are not distributable.

One of the biggest hurdles I faced was a lack of proper

documentation regarding the set up of GCC and the PalmOS SDK. Even most of the

information on the Web was pretty outdated. Since getting the configuration

right is essential to get started, let me walk you through the setup and what’s

required to get a functional environment. See the accompanying table for a list

of tools you’ll need and where you can find them.

Installation and configuration

On Windows, you first need to install CygWin. This is

available in two versions. A full install, which takes more space but doesn’t

require any further configuration and a smaller install, works fine. The only

thing missing in the smaller version is the make command. But this is available

separately on the CD and once the smaller version is installed, the EXE file can

simply be put into the H-i586-cygwin32\bin folder where you have installed

CygWin.

Next, install the PRC-Tools from the CD-ROM. Be sure to note

the location of this directory. After this is complete, install the PalmOS SDK.

By default, it installs into C:\PalmDev.

Run CygWin to be presented with a Bash shell (this is the

same one that Linux ships with). If you are not familiar with Unix or Linux

commands, brush up the basic ones from previous PC Quest issues. You won’t

need anything more than displaying the contents of a folder, changing

directories, etc. The advantage of this Bash shell over the one in Linux is that

it can coolly run Windows EXEs too. Anyway, make sure that your PATH contains

references to the make tool directory and the ones to the PRC-Tools\bin too.

Once this is done, you are ready to start programming.

A Palm program structure

Before we actually start writing our first program, there are

a few things one must understand about Palm programming. All Palm programs are

event-driven programs. Experienced Windows programmers will immediately

recognize this concept and, yes indeed, it’s very similar to what you already

know. For the others, here is a small and quick explanation. We’ll take a

detailed look into the structure next month.

An event-driven program is one that receives and responds to

certain "events" that occur. Events can be of many types. On the

Windows platform they can be mouse moves and clicks, windows opening and

closing, key presses and many more. On the Palm platform, events can be the

stylus move, tap, press of one of the standard buttons, graffiti input,

silkscreen button tap, applications or windows opening or closing and many

others. Events can also be processed at many different levels by the operating

system, application or a custom event handler. So, the Palm program checks if

any other handler has processed a particular event it receives, and, if not,

assigns a custom event handler to it, if the event is to be used in the

application. For example, if tapping a button in the application is to show a

message, the button tap event will have to be handled.

However, in our first program, we’ll not do any custom

event handling at all. Instead, we’ll let the PalmOS take care of all the

events for us. Our objective in the first program is only to get things going

and end up with a working application.

"Hello, world!"

From the eons of computer programming, the most popular

program to be created first has been the one which displays "Hello,

world!" to the programmer, thus signifying that his creation has truly been

born. So continuing this tradition, here’s the code for such a program for the

PalmOS platform. Save it as hello.c somewhere.

#include

UInt32 PilotMain (UInt16 cmd, MemPtr cmdPBP, UInt16

launchFlags)

{

EventType event;

if (cmd == sysAppLaunchCmd NormalLaunch)

{

// Display the message

WinDrawChars( "Hello, world!", 13, 55, 60 );

// Main event loop

do

{

// Wait for an event to arrive

EvtGetEvent( &event, evtWaitForever );

// Let the system handle the event

SysHandleEvent( &event );

// Process events till a StopEvent is recieved

} while (event.eType != appStopEvent);

}

// exit

return;

}

Pretty small program, is it not? And although the comments

are self-explanatory, let me walk you through the program.

#include

This is the main header file for the PalmOS SDK that lets you

access and use the APIs required to compile the program.

UInt32 PilotMain (UInt16 cmd, MemPtr cmdPBP, UInt16

launchFlags)

This is the function equivalent to main( ) in C and WinMain(

) in Windows SDK programming. This is the first function which is called when an

application is run. The parameters to this function are required and are sent by

the system when the application starts up. We’ll be using only the first

parameter in this program.

EventType event;

Here we define a variable called event of type EventType.

This type is declared in the PalmOS API and is part of the header above.

if (cmd == sysAppLaunchCmd NormalLaunch)

Here is where we use the first parameter sent to the

application in the variable cmd. This basically holds the type of request sent

to the application to start up. We simply check whether the value sent was one

for a normal application launch (using the #defined mnemonic sysApp

LaunchCmdNormal Launch). If it is so, we continue.

WinDrawChars( "Hello, world!", 13, 55, 60 );

This is a PalmOS API call that displays the string at the

location and intensity shown.

do

{

EvtGetEvent( &event, evtWaitForever );

SysHandleEvent( &event );

} while (event.eType != appStopEvent);

After we draw the string on the screen, we need to process

events that are sent to the application from the operating system. Events are

stored in an "event queue" in the order they are received. The

application starts processing this queue by first getting an event out of the

event queue, if required by waiting indefinitely (evtWaitForever). The event,

which is stored in the appropriately named variable, is then immediately sent to

the system for processing (SysHandleEvent). Just like typical government office

behavior! Anyway, this loop continues till the application receives an order to

stop (appStopEvent). The application returns control to the system after that.

As you can see, this small program itself has quite a few

things going on within it. For a list of all the start and stop codes, and API

function list, take a look at the PalmOS SDK reference at the Developer’s

Zone. However, this is not for the faint-hearted, as its more than 1,200 pages

long.

Compiling and testing

Now that your program is ready, you need to compile and run

it. But before that you need to do one more thing. In my previous article, I had

mentioned that every application has a unique Creator ID. This Creator ID is

what identifies different applications on the Palm, and not their name. So to

get a unique ID for any program you make, decide on a four-character string and

go to www.palm. com/dev/tech/palmos/creatorid. Enter the ID you have chosen. If

it has not already been registered and used, you can immediately register it

with them for free by giving the name and description of the application and

some other details. But for this exercise, use the CreatorID that has been

reserved for the "Hello, World!" program– WRLD.

To compile, enter the directory where hello.c exists and

issue the following commands.

m68k-palmos-gcc -O2 -c hello.c

m68k-palmos-gcc -o hello2 hello.o

These two commands compile the program, check for errors and

build a binary object of the C code.

build-prc hello.prc "Hello World" WRLD hello

This finally builds the PRC (or application) file for the

Palm, using the object binary called "hello", the CreatorID "WRLD"

and a descriptive name for the application as "Hello World".

To run the program, install it as you would normally on the

Palm and tap the "Hello World" icon. You should see a screen with just

the message written on it. Try tapping, writing or selecting anything. Nothing

will work, since the application has no event handlers of its own. Use any of

the normal buttons on the Palm to exit the application.

You can also download and use the PalmOS Emulator. This is a

program that lets you emulate the PalmOS environment on either Windows or Linux.

Detailed instructions are given within the archive downloadable from the

developer’s zone, so I shall not repeat them here.

That’s it for this time. Next month, we’ll take a look at

a much more detailed and complex application, which includes multiple forms,

alert messages, help text, menus, buttons, and more. So tighten your coding hats

and watch this space next month.

Vinod Unny is a

technology consultant at iSquare Technologies