Lesson 3: Elementary events

At this point, we've familiarized ourselves with the UIE SDK and have a vague understanding of what the heck is going on.

Briefly, the steps we've covered so far are 1) Write some UJML code, 2) Open the IDE, 3) Compile the UJML code, and 4) Run our Hello World program. That's not really a lot.

The first thing we probably want to do now that we've got those basics covered, is figure out how we are going to allow users to actually shut off the program. If you've read through the automatically generated Hello World example from the SDK, you already know, and you can probably skip this lesson.

For those of you still with me, let's jump in and see what UJML provides.

On any mobile phone, you'll typically have a set of buttons above the numeric keypad. There is the directional pad which provides a means of entering UP, DOWN, LEFT, and RIGHT. It usually has a button in the middle which sends a command named FIRE to whatever application is currently active. Then surrounding the directional pad, there are two to four more buttons. Starting on the top-left, these are F1, (top-right) F2, (bottom-left) F3, and (bottom-right) F4. The UIPlayer can support up to F10, but most ports only support F1 and F2. This is unfortunate on Japanese phones because F1-F4 are almost universal here.

Let's tie the keypress of one of the F-buttons to an event and have it execute some code. In English, that means that when someone presses a button, something happens on the device. I would like to start with adding "Exit Program" functionality to the Hello World application. The F2 key is as good a place as any to put this.

To implement this type of functionality, UJML provides the <fn> tag. And fn contains a text label and an event handler. These are cleverly given the tags <text> and <event>.

<fn>
   <text>Exit Program</text>
   <event name="onSelect">
      <accelerators>
         <key>F2</key>
      </accelerators>
      <script>
         _unload();
      </script>
   </event>
</fn>

What I have done there is specified a new function key with the text "Exit Program". It will be tied to an event called "onSelect" and will be fired by the key F2. When the onSelect event is fired, the script will be executed. The _unload() function causes the program to unload itself from the application stack.

The event "onSelect" occurs when a button is pressed. That action "selects" the key and fires that event. Only one event handler can fire per event, so the handler with the highest Z-order will handle the event. If the top-most handler does not implement a handler, the event is passed down through the Z-order to each remaining handler. If no one handles an event (like if you press a key in the original Hello World application) then no script will be executed.

So the action that I've defined is that when the user presses the F2 (top-right) key, the program will call _unload() and exit.

Since a function key goes on the screen, it belongs in the <display> tag hierarchy. In fact, all events require <display> tags because in UJML only Visual Elements can receive user events. This will become clearer later when we tire other events to other visual elements.

Combining this code with the original Hello World code we get the following program:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE ujml PUBLIC "-//UIEVOLUTION//DTD UJML 1.5//EN" "http://www.uievolution.com/dtd/ujml-1.5.dtd">
<ujml>
   <application>
      <display>
         <label>
            <text>Hello UJML!</text>
         </label>
         <fn>
            <text>Exit Program</text>
            <event name="onSelect">
               <accelerators>
                  <key>F2</key>
               </accelerators>
               <script>
                  _unload();
               </script>
            </event>
         </fn>
      </display>
   </application>
</ujml>

If you run it in the IDE, you should now have a button on the bottom right of the screen that says "Exit Program". Open up the Runtime tab in the debugger and you can see the _unload() function get called whenever you press the F2 button.

If you're thinking what I'm thinking, you're probably wondering why the program isn't exiting. Well, the reason for that is that the emulator is designed to restart the original program after the program exits. So what you're seeing is actually the emulator closing the program then restarting it. The screen doesn't have any repainting to do, so it just looks like it's not shutting down. Don't worry, it is calling _unload() correctly. It just doesn't have anywhere to go once it calls it.

Try other function keys and see how they work. Take a look at your own cell phone and see how other applications use the function keys. See whether they are static or dynamic, what sorts of functions you can execute from them, etc. From a programmer perspective, function keys are absolutely essential to creating usable user interfaces.