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