3. Hello, World -- An Introduction To Palm OS Programming

It seems almost required that the first example in any programming tutorial be the infamous ``Hello, world.'' program. Once you have this program working, you know that you have at least a basic grasp of how to create, compile and install a Palm OS program.

One thing to take note of is that Palm OS programs are event-driven. Basicly, this means that unlike linear programs, (such as make, more, or pilot-xfer) Palm OS applications mostly wait for events, then process them in turn. In case you are not familiar with them, events can be any occurrence. Pen down & up, graffiti input, and alarms are all different events.

3.1 Getting Started

Program Source

This is the source for our ``Hello, world.'' program:

#include <System/SysAll.h>
#include <UI/UIAll.h>

// ---------------------------------------------------------------------
// PilotMain is called by the startup code and implements a simple event
// handling loop.
// ---------------------------------------------------------------------
DWord PilotMain( Word cmd, Ptr cmdPBP, Word launchFlags )
{
    EventType event;


    if (cmd == sysAppLaunchCmdNormalLaunch) {

        //  Display a string.
        WinDrawChars( "Hello, world!", 13, 55, 60 );

        //  Main event loop:
        do {
            //  Doze until an event arrives.
            EvtGetEvent( &event, evtWaitForever );

            //  System gets first chance to handle the event.
            SysHandleEvent( &event );

            //  Normally, we would do other event processing here.

        // Return from PilotMain when an appStopEvent is received.
        } while (event.eType != appStopEvent);
    }
    return;
}

Compilation

Assuming that the bin directory used by the prc-tools is in your default path, you have only to enter the following:

m68k-palmos-coff-gcc -O2 -g hello.c -o hello 
m68k-palmos-coff-obj-res hello
build-prc hello.prc "Hello, World" WRLD *.hello.grc

m68k-palmos-coff-gcc is the GCC cross-compiler built by prc-tools. m68k-palmos-coff-obj-res takes the program generated by m68k-palmos-coff-gcc and splits it up into the various sections that Palm OS expects an application to have. build-prc assembles the program sections, plus the information provided on its command-line to build the final Palm OS program.

Installation

Now, presuming that you have backed up your Palm OS device, you are ready to install hello.prc as follows:

pilot-xfer --port /dev/ttyS1 --install hello.prc

Now, press the HotSync button on your cradle.

Invoking the Program

When the HotSync is complete, you should find a program named ``Hello, World'' in the Applications Launcher with your other programs. When you select it, you should see ``Hello, World!'' in the middle of the Palm OS device's screen.

3.2 Dissection of A (Trivial) Program

Here, I want to explain the various parts of the ``Hello, World'' program.

SysAll.h -- Master System Include File

System/SysAll.h brings in many of the separate system include files. You may wish to look through some of these files. Pay particular attention to m68k-palmos-coff/include/PalmOS2/Common.h, as it contains the typedefs used throughout the Palm OS libraries.

UIAll.h -- Master User Interface Include File

UI/UIAll.h brings in many of the User Interface include files.

PilotMain() -- Application Main Function

Every Palm OS applications program contains a PilotMain() function. This takes the place of the main() function in a normal C program.

DWord PilotMain( Word cmd, Ptr cmdPBP, Word launchFlags )

Testing the Launch Code

The Launch Code is passed in via the cmd argument and tested against any Launch Code which the program is prepared to deal with. In ``Hello, World'', any action other than a normal program launch is ignored.

if (cmd == sysAppLaunchCmdNormalLaunch) {

Output

The WinDrawChars() function displays a text string at the specified screen coordinates.

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

Main Event Loop

The application will continue to run until it receives an appStopEvent, which is exactly what it sounds like.

//  Main event loop:
do {
        .
        .
        .
// Return from PilotMain when an appStopEvent is received.
} while (event.eType != appStopEvent);

Acquiring Events

The function EvtGetEvent changes its first argument as a side-effect. When it returns, that means that some event has occurred, which the operation system is reporting to the application.

EvtGetEvent( &event, evtWaitForever );

Processing Events

The application has full control over events that are passed along to it. However, most applications will want Palm OS to process most events. This is accomplished by passing the events back to system-provided event-processing functions.

SysHandleEvent() will process system events related to the buttons and Graffiti. Without this function call, Palm OS will never be able to process any button press event to figure out that another application needs to start, which means that appStopEvent will never appear on the even queue, which means that you will never be able to get out of the ``Hello, World'' program. In fact, the power button won't even function!

Go ahead and try this. Comment out the call to SysHandleEvent(), recompile and reinstall the program, and see what happens. Just make sure that you have a paper clip handy!

Hello, World Notes

You have probably noticed that this program does nothing with its events, other than passing them back to the operating system for processing. Later examples will be more exciting, I promise!