Event Handling in a Spotlet

Spotlet Events

One of the first things you'll see in every KVM application is the use of a Spotlet. As the first example shows, this is how we bring up a base "window" on a Palm Pilot. While this in itself isn't very difficult, you often see a line like this:

Spotlet mySpotlet = (new Spotlet()).register(NO_EVENT_OPTIONS)

after it. So what the heck does the register method do?

First, register makes the Spotlet the focus of all events, and unregisters any previously registered Spotlet. Second it acts as a filter for what type of events it responds to.

This example shows the type of events you can watch for in a Spotlet. One of the first things you want to do with a Spotlet is to decide whether you want to catch key events from every possible key on the unit, or a subset.

If you use the register(WANT_SYSTEM_KEYS) method on your Spotlet, you catch all system keys on the unit. This includes:

Pen Down events
Pen Up events
Pen Move events
Text Entry using Graffiti
Pushing any of the hard buttons at the bottom of the unit
Touching the four icons to the sides of the Graffiti area or touching the "abc" or "123" areas within the Graffiti area

If the Spotlet was registered with register(NO_EVENT_OPTIONS), you only catch the following events:

Pen Down events
Pen Up events
Pen Move events
Text Entry using Graffiti
Tapping the Menu Icon

All other keys will perform their normal PalmOS function, with the exception of the "abc" and "123" areas in the Graffiti area, which now have no effect whatsoever. This allows you, for example, to exit the application and go directly to the Calculator function by tapping the Calculator Icon

The full source code of the example

Download the PalmPilot file EventHandling.prc for the EAv0.1 release

Items of Note in this program.

When you first run the program, a penUp event is generated as the application is initialzed.

The Spotlet.register(int) method uses the WANT_SYSTEM_KEYS option. The other option is commented out, but may be used instead.

    public static void main(String[] args) {
        EventHandling eh = new EventHandling();
  	eh.register(WANT_SYSTEM_KEYS);
//  	eh.register(NO_EVENT_OPTIONS);	    
    }

I played around with the penMove(int, int) method for several reasons. Basically, as the location would change from larger numbers to smaller numbers, the former wider text needs to get cleared, if you didn't clear it, when you went from (100, 100) to (1, 1) you would get (1, 1)100).
1. The first time I implemented it, I just called paint(), which produced noticible flicker as the entire screen was redrawn each time.
2. The second approach was to draw the the old string in the ERASE mode. This sounded like a clever idea, but again I still noticed a large amount of flicker
3. I finally just used a little trick of extending the text with several spaces, which worked to clear out any extra characters from the event before. Not elegant, but it worked very well.
The keyDown(int) method is basically a large case statement looking for system keys first, then converting anything else into a character. Note that some keys on the keyboard do not have predefined static values on Spotlet.