Palm Pilot Development Tools

The PalmOS keeps a queue of events being handled by the
system. These events are sent to the current application in order
to execute the code to handle each event. An event is triggered
when a UI button is pressed, the Palm pen touches the screen
(penDownEvent) or when other operations occur. An application
should transfer any events it doesn't handle to the system. When
the event is handled, the PalmOS takes the next event in the queue
and passes it on to the application. The application can also put
events in the queue. Many PalmPilot functions cause all sorts of
events to be placed in the event queue. A list of all events and
what they do is in the official documentation for the Palm
Pilot.

PilotMain

The main procedure of a program is called PilotMain. When the
PalmOS calls PilotMain, it transfers a command to it. The PilotMain
procedure should find out what the command says. The command can
say, for example, that this is a normal launch of the application
(sysAppLaunchCmdNormalLaunch) or
that this is a command to find a string
(sysAppLaunchCmdfind). PilotMain
should ignore or respond to these commands in its code. An example
of an application that responds to the sysAppLaunchCmdfind is the
address book. Whenever we press the find button, the PalmOS sends
this command to all the applications. One application that will
accept this command is the address book—it starts searching for
the string we entered in its database.

EventLoop

To handle all events, we should use an event loop. An event
loop simply takes an event, handles it, then takes the next event
in the queue. If we do not want to handle a certain event, we can
send it to the PalmOS event handlers so it will be handled for
us.

Pilot API

To take advantage of all the functionality of the PalmOS,
there is well-documented API for your use. You should read the API
manual to see which kinds of events, functions and types of objects
exist in the PalmOS. Listing 2 is simple code that writes “Hello
World” on the Palm Pilot.

The first step toward running an application on the Palm is
to build the resources. As mentioned earlier, we can build the
resources using the command pilrc.

pilrc hw.rcp

To add the bitmap with ID 10 to the main form, I used a tool
that converts ppm files to Tbmpxxx.bin
resources. I used xv to convert
the format of peng.gif (found at
http://www.linux.org.il/)
to black-and-white ppm format. Then I used
ppmtoTbmp on the peng.ppm file,
and named the result Tbmp000a.bin. The 000a in the file name is the
32-bit hexadecimal value for 10. I needed to specify this value
because this is the bitmap ID I wrote in the pilrc resource file
for the main form. This tool was written by Ian Goldberg, and it
can be found at
http://www.pilotgear.com/.

The next step is to compile the C code. To do this, we use
the gcc m68-palmos-coff cross compiler, with the same flags as for
the normal Linux gcc:

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

The result of this command is an m68k COFF object file named
hello. The m68k COFF object file should be combined with the
resources just created using the pilrc program. To complete this
mission, we first use the obj-res
utility that splits the COFF file into the code and data resources,
and then use the build-prc utility to combine resources.

m68k-palmos-obj-res hello

This command will split the hello file into three resource files:
code0000.hello.grc, code0001.hello.grc and data0000.hello.grc. Now
we are ready for the final step of building the prc database.

build-prc hello.prc "hello" hwld *.grc *.bin

This command builds a prc application with a creatorID
hwld and type appl.

Testing the Application

Testing the application on your Palm Pilot is not such a good
idea. A bug might require us to reset the machine, and programs
can't be debugged with the normal tools. The best way to test our
just-created “Hello World” application is with a program that
will emulate the Palm Pilot from within our desktop. POSE,
available from
http://www.palm.com/ with
source code included, is a very good emulator. It can use a special
debug ROM, also available from that site. With the debug ROM, we
can get more debugging information on our application, which makes
finding errors much easier, and we can hook gdb to it in order to
debug with this well-known debugging tool. To install POSE, you
will need the FLTK X toolkit. All instructions come with the POSE
tar file.

There is one more emulator for X, called
xcopilot. In order to use your own
machine RAM or ROM, you can use the pilot-link package. The
pilot-link package gives you the ability to communicate with the
Palm Pilot from the serial port. There are some good utilities in
this package, available from
ftp://ryeham.ee.ryerson.ca/pub/PalmOS/.
Using the pilot-link utilities, we can also transfer databases from
our desktop to the Palm Pilot and from the Palm Pilot to the
desktop.

Figure 1

Figure 1 is how POSE looks with our
hello world application for the
Palm.