Resources and Event Loops

In

last month’s article on Palm programming we looked at writing a simple ‘Hello

World!’ program, the structure of the Palm application, and getting the GNU C

compiler working for developing Palm applications. In this article we’ll delve

deeper into the murky waters and understand what goes on within an application.

You may recall that every Palm application is actually a ‘resource’

database. That is, it’s made up of resources like buttons, menus, checkboxes,

text fields, radio buttons, pop-ups, bitmaps, and even code blocks.

When an application is started, many processes take place

before you see its first screen. The diagram below explains the process.

This

simplified version of the process shows the Application Startup routine, where

the initialization of most items required in the program is done. The

Application Startup then passes control to an Event Loop, which is one of the

most important functions of the program. It processes incoming events like a

button tap, menu selection, and Graffiti input and decides what needs to be done

with them. Many events can simply be sent off to the Palm’s system to be

handled. Other events that our application needs to process must be given a

valid custom handling function to use. This special event, signals a stop

request to the Event Loop, which in turn exits the loop and processes the

Application Stop routine.

Let’s look at the Event Loop in more detail. Everything you

do on your Palm generates an event, be it a simple tap, scratch, silkscreen, or

hard button press. Each of these events goes into an Event Queue. Events are

processed by the running application in the order they occur. So if you tap a

button and then scribble some Graffiti, the application will process them in the

same order. However, there are a lot of events that don’t need the application

to process them. For example, tapping the silkscreen Menu icon shows up the

application’s menu if it exists. This event is handled at the system level and

does not require the programmer to code the displaying and hiding of the menu in

the application. In fact, the programmer just needs to specify the menu ‘resource’

to display. We’ll talk more about this a little later.

If the event is not a system event, the onus passes back to

the application. For example, if your application has a button on the screen,

the system does not know what it has to do when the button is tapped. So you

need to write some code that does something at that time. This cycle is

explained in the diagram.

Creating resources

Let’s take a look at how resources are created for a Palm

application. You first need to create a Resource Definition File that contains

the names, types, and attributes of the resources required in the application.

This is saved as an RCP file in the application development folder for GCC.

Let look at a simple resource first.

FORM ID frmHello2 AT (0 0 160 160)

NOFRAME

USABLE

BEGIN

TITLE "Hello 2"

BUTTON "OK" ID btnOK AT (CENTER 115 37 12) USABLE

FRAME FONT 0

END

The above snippet creates a simple form that covers the

entire screen (0-160 pixels), has no frame, with the heading "Hello

2", and a single OK button on it. The positioning as well as it’s other

attributes, like the font to use and whether it has a frame or not, are also

specified.

One thing to remember about resources is that Palm

applications do not refer to the resources by their ‘names’. Instead, each

resource must have a unique resource id associated with it. For example, both

the form and the button above can’t be referred to by their given names–frmHello2

and btnOK–directly. These names are mnemonics to a resource id that’s

specified elsewhere, say, in a header file with #defines like the following:

#define frmHello2 1000

#define btnOK 1001

This header file is usually included in both the RCP file as

well as the main program C file so that consistency is maintained in referring

to resources.

However, creating resources is not as difficult as you think.

There are a lot of GUI-based front-ends that give you the look of a Palm screen,

and you can simply drag-drop and position resources and change their properties,

just like in modern RAD tools like Visual Basic. My favorite is the one called

Arbor PiBuilder. It’s available on this month’s CD. It will not only create

the RCP file for you but will also generate the header file you require while

giving you complete control over every aspect of the look of your application.

The large application

Now let’s create a slightly more involved application for

the Palm. The objective of this exercise is to utilize resources and create

custom event handlers for use in the Event Loop. Due to limitations in space, I’ll

not carry the complete code here. The program is available on the accompanying

CD with the complete set of source files required for it. But I will walk you

through the important parts of the program.

Let’s create a set of resources for the program. The

program needs to have a main full-screen form, a standard help tip screen, some

static text, a button and a menu with couple of options. One option will throw

up an alert box and another one a separate smaller form.

I used PiBuilder with some manual tweaking to get the file I

wanted. It’s called Hello2.RCP in the sample. Open it in either a text-editor

or a resource reader like PiBuilder or PilRC-GUI to see the different resources.

The file is divided into sections depending upon the type of resource being

specified. For example, the code

FORM ID Form1004 AT(0 0 160 160)

NOFRAME

SAVEBEHIND

USABLE

HELPID String1014

MENUID Menu1006

BEGIN

TITLE "Hello World 2.0"

BUTTON "Alert" ID Button1005 AT(10 118 37 12)

USABLE LEFTANCHOR FRAME FONT 0

LABEL "Test Application" ID Label1013 AT(5 29)

USABLE FONT 0

LABEL "Use the button, menus and help text" ID

Label1026 AT(5 45) USABLE FONT 0

FORMBITMAP AT(150 0) BITMAP Bitmap1029 USABLE

END

specifies a form named "Form1004" which is full

screen points to a String resource "String1014" for proving the help

tip and a menu resource "Menu1006". Other resources that it contains

like title, buttons on the form, labels, and bitmaps, are specified within the

BEGIN-END block. Similarly each of these resources also specify their own

attributes like the label text or button value. Each resource is also given a

unique name. The names are #defined in Hello2.H.

The Hello2.C file contains the complete program. Note that

this file includes the standard header PalmOS.h as well as the header for the

resources used above. I’ve also used forward declarations of the functions

being used so that the flow of the program is clearer.

The function PilotMain() (mentioned in my previous article)

is the first one to get executed. As you can see, as soon as the application

starts normally, it calls the function StartApplication(). This simple function

does nothing but informs the program that it needs to show the form called

"Form1004".

However, as explained earlier, a Palm program is event based.

So all that really happens, at this point, is that the program gets an event

informing it that a form is ready to be shown. The next step in the PilotMain()

creates the Event processing Loop–EventLoop(). This continues to process

events till an application stop event is encountered. Within the loop, it checks

whether the System or the Menu handler can process the event. If not, it checks

whether the event is of a new form getting loaded and, if so, assigns a ‘custom’

event handler for each form–frmMain EventH() for the main form and

frmAboutEventH() for the Aboutbox form. Finally if the event was none of the

above, it simply sends the event to the currently active form hoping that it’ll

take care of it as required.

Now in the case when the application is starting up, the load

event on the Main form, Form1004, triggers the Event Loop to assign the custom

handler to it. This in turn sends another event, which is for opening the form.

But this time the Event Loop lets the form handler take care of instead.

The form handler–frmAbout EventH –also checks the type of

events that it receives and processes it accordingly. By checking that the event

is for opening itself, it simply draws the form on the screen, including all the

resources contained within it. When a resource, like the button or menu, is

used, the corresponding event is triggered. This can include displaying an alert

by specifying which alert to show, or showing a different form altogether. If

the latter happens, the rest of the events will be sent to the event handler of

that form till it is closed. Remember that we do not need to code the display of

the menu pop-up and its items. This is taken care of by the Palm’s internal

menu handler. It is only the events that tapping a menu item generates that

require to be processed.

Compiling

Once all this is done, you will need to compile the resources

and the source code to get the PRC file. To compile resources, use the PILRC.EXE

(given with last month’s article). This will generate a few *.BIN files that

must also be included when you build you file using BUILD-PRC. The code on the

CD also includes a Makefile. Simply type "make" at the Cygwin prompt

in the directory where all the files exist and watch the PRC being created. You

can use this Makefile as a template for all your other Palm projects if you

wish. Makefiles can ease the task of compiling different parts separately and

also save you time by only compiling the modules that have changed after the

last compile.

Finalé

Well, although this has been a long series of articles, I’ve

only scratched the surface of Palm programming in them. There are a lot more

things that can be done on the Palm, like databases, tables, graphics, games,

etc. But in this series my intention was only to arouse your interest and to get

some of the basics cleared.

As a small bonus, the accompanying CD has another application

written by me, called ‘BOFH Excuses’. This is a small, fun and free program

that holds a large database of technical ‘excuses’ that a ‘Bastard

Operator From Hell’, like sysadmin, will love. You can browse through the

excuses and even mark the ones that you’ve already used!

This article was the last in the series of Palm programming.

I hope the series was as much learning and enjoyment for you as it was for me. I

will talk about more Palm-related stuff, including things from the ‘dark side’,

in a later issue of the magazine. Until then, here’s wishing you a prosperous

New Year and fun with your Palm.

Vinod Unny, is a

technology consultant at iSquare Technologies