Lesson 4b: State variables and transitions

In the previous sublesson, I mentioned state variables and that they may be used to display visual elements. This is a simplification of their purpose, but in regards to displays, state variables are the only way to update the display.

I find that thinking of applications as a series of screens helps me understand the concept behind state variables. On mobile phones, this is very obvious. You press the menu button to show the menu (a screen), you select an item from the menu and it loads a different part of the application (another screen). Any of the menu items may lead to any number of other screens. One screen, in other words, may have many different screen transitions.

In a typical programming language, you'd set up an object's member variables (color=red, size=10, etc) and then call a method which then performs some processing based upon the updated object state. A state is defined in this situation by its defining characteristics (variables) and its behavior is defined by the results of the execution (method). To change state, the program must explicitly call the state transition with the correct variables. If the input parameters are incorrect, the program may behave in an undefined manner.

UJML introduces the concept of state variables. They are different from normal variables because they have special knowledge about their internal values. When a state variable's value changes, it reacts by executing a script defined for that particular value. This leads to two fundamental properties of state variables:

1) State variables may be any type except for reference data types.
2) State variable execution scripts can be called implicitly by the UIE Player.

The second property is the more interesting of the two. By simply changing the value of a state variable, the specified script is executed.

State variables are declared as follows:

<ujml>
   <application>
      <state-variables>
         <state-var name="sPaintScreen" type="boolean" />
      </state-variables>
   </application>
</ujml>

The state variable is scoped to the entire application block, so it may be accessed anywhere from within the block. It is also possible to define state variables that have more restricted scope, but I'll try to cover that later when I discuss state machines.

When a state variable is updated, it transitions to a new state. This is called a state transition. A state transition may contain a display routine, audio routine, script routine, or a resource definition. It may also use a variable declaration to provide any necessary local variables to the script.

This is an example of a simple state transition that displays an image.

<state var="sPaintScreen">
   <transition value="true">
      <display>
         <image>
            <url>http://photos1.blogger.com/img/158/8299/320/050923_003L1.jpg</url>
            <x>0</x>
            <y>0</x>
            <width>240</width>
            <height>320</height>
         </image>
      </display>
   </transition>
</state>

This state transition will display the specified image on the screen when the 'sPaintScreen' state variable is set to "true". When 'sPaintScreen' is set to "false", anything specified in the "true" transition will be deleted. In short, "true" shows the image, and "false" hides the image.

Now, to paint the image to the screen, the application's script just sets the sPaintScreen state variable to true.

<ujml>
   <application>
      <state-variables>
         <state-var name="sPaintScreen" type="boolean" />
      </state-variables>
      <script>
         // Paint the image
         sPaintScreen = true;
      </script>
      <states>
         <state var="sPaintScreen">
            <transition value="true">
               <display>
                  <image>
                     <url>http://photos1.blogger.com/img/158/8299/320/050923_003L1.jpg</url>
                     <x>0</x>
                     <y>0</y>
                     <width>240</width>
                     <height>320</height>
                  </image>
               </display>
            </transition>
         </state>
      </states>
   </application>
</ujml>

The code above does essentially the same thing as the code in the previous lesson. The difference is that this version separates the painting of the image from the application display. When a visual element is included directly in the application's display, it remains on the screen at the lowest Z-order. By moving the visual element into a state transition display, it can be shown and erased from the display programmatically.

We previously used function key accelerators to handle user interactions. If we use the same technique here, we can update the display in response to user key presses.

<fn>
   <text>Update Display</text>
   <event name="onselect">
      <accelerators>
         <key>F1</key>
      </accelerators>
      <script>
         // flip flop the boolean value
         sPaintScreen = !sPaintScreen;
      </script>
   </event>
</fn>

This key handler will either show or erase the image on the screen when the user presses the F1 key. The program we have been working on is now interactive!

<ujml>
   <application>
      <state-variables>
         <state-var name="sPaintScreen" type="boolean" />
      </state-variables>
      <script>
         // Paint the image
         sPaintScreen = true;
      </script>
      <display>
         <fn>
            <text>Update Display</text>
            <event name="onselect">
               <accelerators>
                  <key>F1</key>
               </accelerators>
               <script>
                  // flip flop the boolean value
                  sPaintScreen = !sPaintScreen;
               </script>
            </event>
         </fn>
      </display>
      <states>
         <state var="sPaintScreen">
            <transition value="true">
               <display>
                  <image>
                     <url>http://photos1.blogger.com/img/158/8299/320/050923_003L1.jpg</url>
                     <x>0</x>
                     <y>0</y>
                     <width>240</width>
                     <height>320</height>
                  </image>
               </display>
            </transition>
         </state>
      </states>
   </application>
</ujml>

Briefly, the above code declares a state variable called 'sPaintScreen'. The sPaintScreen variable is set to 'true' which puts the sPaintScreen=true state transition into the queue. The display is updated with the F1 key bound to the 'onselect' event. The pending state transition is executed and the image is shown on the screen. When the user presses the F1 key, sPaintScreen is set to 'false' which then erases any visual elements specified in 'true'. Since there is no explicit 'false' transition, no special handling is performed. If the user presses the F1 key again, sPaintScreen is set to 'true' which puts the image back on the screen.

Try the code and play with it for a little while. Investigate adding an event handler into the sPaintScreen=true state transition. Doing so will allow you to change the text of the F1 key accelerator.

Next time I will cover using the resources tag to manage the handling of images.

Lesson 4a: Displaying images

By now you're probably wondering when I'm going to get to the good stuff, you know, like showing pictures and stuff. Well, let's get to it.

First, it is important to understand that images are resources. This means that once they are loaded they stay loaded only while they are needed. Once a resource is loaded, though, it is available immediately to any code that needs it. It's a very powerful idiom, and we will explore using images as resources in the second half of this lesson.

Images are defined by the <image> tag. You tell the player which file to load by providing it with a URL. URLs are merely the URI-format location of the file on disk or internet. UJML treats URLs as relative addresses to the location of the executing UJML program. The exception is when you specify a complete URI with either an http:// or file:/// or other URI header.

I'll use the graphic located at http://photos1.blogger.com/img/158/8299/320/050923_003L1.jpg as the sample image for this lesson.

If you just specify an image with the URL, the image will be displayed at 0,0 (or the top-left corner of the screen). Unfortunately, it will also be displayed with a width of 0,0 which means that it won't be visible at all. This is a common theme in UJML: the default values are typically 0, so it's important to set them correctly. DO NOT RELY ON UJML TO SET DEFAULTS.

I'm not so interested in displaying the image somewhere in the middle of the screen, so for the time being I'm not going to change the x,y offsets. However it is important that I change the width and height properties so that the image is properly displayed. The image is 240 pixels wide and 320 pixels high.

I specify the image as follows:

<image>
   <url>http://photos1.blogger.com/img/158/8299/320/050923_003L1.jpg</url>
   <width>240</width>
   <height>320</height>
</image>

Logically it follows that since this is part of the display it should go into the display tag of our application. The simplified code follows:

<ujml>
   <application>
      <display>
         <image>
            <url>http://photos1.blogger.com/img/158/8299/320/050923_003L1.jpg</url>
            <width>240</width>
            <height>320</height>
         </image>
      </display>
   </application>
</ujml>

Now, like the original Hello World program from Lesson 1, we have created a program that can display the data we wish to show the user.

One important aspect of this is that visual elements like images and labels can be stacked on one another. This is called Z-order. Items specified first will be displayed first, so each item drawn after that will be layered on top of it. You can think of this like a stack of visual elements where the last item drawn is on top of the stack while the first item drawn is all the way at the bottom and possibly even covered up by elements above it.

Let's say we wanted to write Hello World on top of the image we just drew. All that's necessary is to add a label to the display area.

<ujml>
   <application>
      <display>
         <image>
            <url>http://photos1.blogger.com/img/158/8299/320/050923_003L1.jpg</url>
            <width>240</width>
            <height>320</height>
         </image>
         <label>
            <text>Hello World!</text>
         </label>
      </display>
   </application>
</ujml>

Now, since the label is drawn after the image it is shown on top. If the order was reversed, the label would be invisible because the image would completely cover it up.

Next time I will discuss state variables and using them to display elements.

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.

Sidenote: My UJML Editor

If you're using the UIEvolution SDK, you know that it's based on Eclipse, the open-source, extensible, all-singing, all-dancing, IDE. It's really great, and the UIEvolution engineers worked hard to integrate the IDE with the UJML language and compiler/debugger stack.

However, plain vanilla UIE IDE is pretty harsh to write UJML in. Because the language is based on XML, there are just a ton of tags that need to be written and the IDE doesn't help at all when composing a program.

To help that, I've heard that some programmers use an Eclipse extension called XML Buddy which provides some XML-language assistance. I tried it and couldn't make heads or tails of it. Others swear by it.

Personally, I use Visual C++ (or VC#) Express to compose my programs. It does automatic ENTITY checking, auto-closes XML tags, and is freely available from Microsoft with only online registration being required. There are things that I wish it did better. I wish it would read the UJML DTD and automatically provide a list of valid tags for the current tagnode. I wish it didn't leak memory like there's no tomorrow (it eats up to 380MB of RAM sometimes, and it takes up to 10 minutes to close).

What you use is up to you. The SDK comes with a decent IDE which can be extended. MS provides a free IDE which has a lot of niceties built in. Whatever you feel comfortable with is what you should use. Except for Notepad. Do yourself a favor and try something (anything) else.