LispMe UI support

There are currently 2 ways to write programs dealing with user interaction.

Using event

An event is represented as a list, whose first element is a symbol denoting the event type (e.g. key-down or frm-open) and whose other elements are the event parameters, different for each event type. All supported events are listed in the Catalog under the category UI event. Some PalmOS events are not translated this way, they're all represented by (#f) and should be ignored by your code.

The procedure event expects one parameter specifying whether it should wait for an event (true) or return immediately (false). In the latter case the return value is (timeout) when there's no event queued.

To avoid interference between LispMe's own event handling and your application (e.g. a pen tap in the output field would activate the output field event handling, which won't let your application see subsequent pen-moves and pen-ups), you can disable most controls and fields of LispMe's main dialog by calling (own-gui #t). In this case the fields are not drawn, too, so you won't see any output of write for example, until you enable them again by using the GUI controls menu command.

In spite of this, you would still have to use the drawing primitives to provide user feedback, so I think this approach is only feasible for very simple interactions like the ; Tic-Tac-Toe sample program.

The event handler approach

To create an application this way, you need two things:

• A resource database containing all the forms (dialogs), menus, bitmaps and strings needed.
• An event handler callback procedure, which gets called whenever an event is available. Of course, this procedure is written in Scheme and LispMe provides the glue between the PalmOS API/event model and the Scheme world.

General

• Text fields
• all kind of controls (buttons, pushbuttons, checkboxes, triggers)
• lists and popup lists
• bitmaps and labels
• scrollbars
• menus
• raw pen and Graffiti input

Names for UI functions and events are generally chosen like the corresponding ones from the original Palm API but have been adapted to Scheme's spelling style.

Creating the resources

• PilRC is a PC-based resource compiler written by Wes Cherry.
• Metroworks Codewarrior for the Pilot includes a graphical design tool called Constructor for forms etc.
• Individeo created a resource editor running on the Pilot itself.

I registered the creator ids fbU0 upto fbU9, which you should use for your LispMe resources.

Using PilRC and PRCTools, a typical makefile for a resource DB looks like this:

SHELL=sh
APPID     = fbU0
APPTYPE   = Rsrc
ICONTEXT  = "demo"

demo.prc: demo.rcp
	pilrc demo.rcp .
	# Create ICON IDs 9000 and 9001 instead of 1000 ann 1001  
	mv tAIB03e9.bin tAIB2329.bin
	mv tAIB03e8.bin tAIB2328.bin
	build-prc -t $(APPTYPE) demo.prc $(ICONTEXT) $(APPID) *.bin

all:    demo.prc

One exception to this rule is when you want to create custom icons for the starter application. See here for details.

Opening and closing forms

• popup a nested form over the current active form by frm-popup, like the Palm API FrmPopupForm() Additionally, the continuation of the frm-popup call is stored and will be re-activated when the event handler of the nested dialog executes frm-return.
• close and replace the current active form by calling frm-goto, like the Palm API FrmGotoForm(). The current event handler is abandoned and no continuation is saved.

You can't replace LispMe's main form by frm-goto, so the first form in your interactive LispMe program must be invoked by frm-popup. The maximum form nesting depth is 6. Have a look at this sample program.

The event handler

An event handler should return a boolean value indicating if the event has been handled (true) or should be passed on to the next handler (false).

While the event handler is running, the Pilot won't respond to any user action (not even the off button!), so there's the danger that an infinite loop in a handler locks your Pilot and you'd have to reset it. To avoid this, there's a watchdog timer which aborts an event handler after a time interval configurable in the Preferences Dialog.

Now for the fun stuff separating Scheme from lower-level languages: Just like any other closure in Scheme, an event handler is called in the environment in effect when its lambda abstraction has been executed. Thus you can write a higher-order function returning event handlers whose state is kept in the enclosing environment and you can have several instances of the same dialog (but with different values) in an object-oriented fashion.

Or, you can concatenate several event handling procedures using higher-order combiners, e.g. to include common handling code for a particular menu into many different dialogs.

Or create powerful macros to generate event handlers...

One last warning:Don't try to call a continuation created in an event handler when the associated form has been closed already. The PalmOS forms are not part of the continuation context and won't exist anymore. Same for leaving an event handler by an outward continuation. Generally, don't jump from one event handler to another via continuations (but jumping is perfectly safe within the dynamic context of a single event handler).

Associated language elements