This guide is for anyone interested in learning how to use Ujinn Markup Language (UJML) to easily develop and deploy applications to major phones, PDAs, computer platforms, and embedded devices.

Most of this guide is a tutorial which explains how to write a simple game application. Each step in the tutorial introduces one or more UJML concepts in the context of developing the game. Additionally, the guide provides general tips regarding the concepts discussed.

Value of UJML

UJML allows developers to deploy applications that support a rich user experience to a broader audience than any other technology.

Rich User Experience for Small Devices

The designers used a minimalist approach to UJML to keep the UIE Player tiny, as small as 30 KB on some Java-enabled devices, and to keep the language simple to learn and use. Yet, UJML can be used to develop applications that provide a rich user experience.

Easy to Learn

UJML is an XML-based programming markup language that supports a subset of ECMA Script; also called JavaScript.

Example: “Hello World!”

Below are examples of an application that display the text “Hello World” on the device screen. The examples are written in UJML, Java (J2ME/MIDP), and C++ (BREW). Symbian, Palm OS, and Pocket PC versions are not shown because they are similar in complexity to the BREW example. HTML and WML samples are also not shown because they are similar to UJML in terms of their simplicity.

This comparison illustrates the simplicity of UJML compared to other programming languages available for mobile devices. Not only does a given task require less code, but the language concepts needed to learn, understand, and remember are simpler and more concise.

UJML Version:

<?xml version="1.0" encoding="UTF-8"?>

<!DOCTYPE ujml PUBLIC "-//UIEVOLUTION//DTD UJML 1.1//EN" "ujml.dtd">

<ujml>

<label>

<text>Hello world</text>

</label>

</display>

</application>

</ujml>

J2ME/MIDP Version:

import javax.microedition.midlet.*;

import javax.microedition.lcdui.*;

public class HelloWorld extends MIDlet implements CommandListener

{

private Command exitCommand; // The exit command

private Display display; // The display for this MIDlet

public HelloWorld()

{

display = Display.getDisplay(this);

exitCommand = new Command("Exit", Command.SCREEN, 2);

}

public void startApp()

{

TextBox t = new TextBox("", "Hello World", 256, 0);

t.addCommand(exitCommand);

t.setCommandListener(this);

display.setCurrent(t);

}

public void pauseApp()

{

}

public void destroyApp(boolean unconditional)

{

}

public void commandAction(Command c, Displayable s)

{

if (c == exitCommand)

{

destroyApp(false);

notifyDestroyed();

}

BREW Version:

#include "AEEModGen.h" // Module interface definitions

#include "AEEAppGen.h" // Applet interface definitions

#include "AEEShell.h" // Shell interface definitions

#include "AEEDisp.h" // Display interface defintions

#include "helloworld.bid" // applet class ID

#include "AEEFile.h" // AEEFile Services

static boolean HelloWorld_HandleEvent(IApplet * pi, AEEEvent eCode, uint16 wParam, uint32 dwParam);

int AEEClsCreateInstance(AEECLSID ClsId,IShell * pIShell,IModule * po,void ** ppObj)

{

*ppObj = NULL;

if(ClsId == AEECLSID_HELLOWORLD)

{

if(AEEApplet_New(sizeof(AEEApplet), ClsId, pIShell,po,(IApplet**)ppObj,

(AEEHANDLER)HelloWorld_HandleEvent,NULL) == TRUE)

{

return (AEE_SUCCESS);

}

return (EFAILED);

}

static boolean HelloWorld_HandleEvent(IApplet * pi, AEEEvent eCode, uint16 wParam, uint32 dwParam)

{

AEEDeviceInfo di;

AECHAR szBuf[] = {'H','e','l','l','o',' ','W','o', 'r', 'l', 'd', '\0'};

AEEApplet * pMe = (AEEApplet*)pi;

switch (eCode)

{

case EVT_APP_START:

ISHELL_GetDeviceInfo (pMe->m_pIShell, &di);

IDISPLAY_ClearScreen (pMe->m_pIDisplay);

IDISPLAY_DrawText(pMe->m_pIDisplay, AEE_FONT_BOLD, szBuf, -1, 0, 0, 0, IDF_ALIGN_CENTER | IDF_ALIGN_MIDDLE);

IDISPLAY_Update (pMe->m_pIDisplay);

return(TRUE);

case EVT_APP_STOP:

return TRUE;

default:

break;

}

return FALSE;

}

Easy to Deploy to Many Platforms

The UIE Player is available for the following platforms:

· Java

o J2ME/MIDP (AT&T, Sprint)

o J2ME/DoJa (DoCoMo 504i phones)

o Personal Java

o J2SE (Applet/Application)

· BREW (Verizon, All-Tel, KDDI)

· Danger Hiptop

· Palm OS 3.5 and greater

· Pocket PC

· Symbian

· Win32 ActiveX

· Game Boy Advance (prototype)

Supports Client/Server Applications

All aspects of application and resource loading use URLs, so the programming model of UJML is designed to make it easy to create dynamic client/server networked applications as well as standalone preinstalled applications. The UIE Player supports both http and file URL schemes as well as relative URLs.

Secure

UJML applications are interpreted by the UIE Player, which protects the device from faulty or malicious applications; an application that “crashes” is simply unloaded by the UIE Player. This "sandbox" protects UJML applications from each other, and also limits the damage a malicious application can inflict on a device.

By default, UJML applications are not able to access a device’s features like the file system, phone book, and phone dialer. For custom UIE Players that allow access to device features and resources, the UIE Player configuration allows for flexible security policies that can limit access to resources to trusted UJML applications or partitions. The UIE Player uses a simple URL-based security policy similar to cookie security in HTML/HTTP browsers.

Supports a “No Installation” Model

The UIE Player can use a device’s local storage as a cache of applications so that the user never has to manage application installation on his or her device. The UIE Player simply fetches applications that are not in the cache from the network. When the player needs more space in the cache it discards the least recently used application.

This model reduces device operational cost since applications are maintained and deployed using a server, rather than requiring explicit application management on the device. It also allows application updates to be deployed transparently to users because the update is deployed to the server and the devices simply load the updated version next time the user runs the application.

UJML Architecture

UJML is an XML-based markup language that adheres to the UJML DTD. The language describes screen contents in terms of visual states. States also contain blocks of executable code which control how the player transitions between states.

UJML is rendered on the device using a small application called the UIE Player, the moral equivalent of an HTML browser. The term ‘player’ is used instead of ‘browser’ because UJML applications are active and dynamic, as opposed to HTML which consists of mostly static pages that are browsed. UJML is more akin to Dynamic HTML (DHTML) which supports scripting to add active and dynamic components to static HTML.

Unlike most other markup language browsers, the UIE Player does not directly render UJML text files. In order to maximize performance and minimize resource usage (CPU and memory), a UJML text file must be compiled into a byte code file which the UIE Player can render. The compiler compiles UJML into an efficient executable format, thus compressing the raw UJML text file to a much smaller size, efficient for transmitting over costly and low bandwidth wireless networks.

Static vs. Dynamic

The compiler can generate precompiled UJML files (called UJBC files) offline, or it can be invoked on-the-fly on a server. The next two diagrams show the components involved in developing and deploying UJML applications via these two methods; the first is precompiled and preloaded on the device and the second is dynamically compiled on a server in response to a request from the device. Of course, there are many variations possible between these two extremes.

Diagram: Precompiled Deployment

Diagram: Dynamic Compilation Deployment

In order to support both of these deployment models, the UIE Player supports the http and file URL schemes.

Like HTML browsers, the UIE Player supports the notion of history so that UJML applications can support the notion of “going back” to the previous application. Applications are added to the history stack in the order they are started using the _run() function. A running application removes itself from the stack, causing the previously loaded application to be restarted using the _unload() function. The specification and configuration for the URL of the application to start when the UIE Player is started on a device is platform-dependent and is documented in the Application Deployment section later in this document.

Partitions

A UJML application may consist of multiple partitions, much like a Web site may consist of multiple HTML pages. The main, or parent, partition of an application is the one that is loaded using the _run() function. Child partitions are loaded and unloaded using the _link() and _unlink() functions. This function naming convention is borrowed from the world of binary executable applications and DLLs. Depending on their usage, UJML partitions can have the functional characteristics of both HTML pages and binary DLLs. _link()’ed partitions are not added to the history stack. Instead, they are children of their parent partition and are unloaded when the parent is unloaded.

Only the current application on the top of the history stack and its linked partitions consume memory resources. Once an application is not on top of the history stack, all memory resources for that application are freed and made available to the new current application.

Tip: While an application is being loaded to the top of the history stack, as the result of the _run() function being called, the current application consumes memory resources until the new application is finished loading. So, it is important to ensure that neither the previous application nor the new application consume so much memory that both will not fit in memory at the same time.

One way to avoid this situation is to use an intermediate “loader application” that uses very little memory. See the “AppSplash.ujml” example later in this document for an example.

The following diagram shows the UIE Player’s history stack after the following has occurred:

1. The player was started with the default application “App 1”. This placed “App 1” at the bottom, location 0, of the history stack.

2. “App 1” ran “App 2” which added “App 2” to the top of the history stack, location 1.

3. “App 2” linked partition “Part A”.

4. “App 1” is shown in gray because it is not physically loaded in memory at this point.

After “App 2” calls the _unload() function to unload itself, the player reloads “App 1” and the history stack and memory usage looks like the diagram below:

On most devices, the UIE Player is able to cache UJML files locally to avoid refetching them using the network.

Also, on many platforms, the UIE Player supports local persistent storage in the form of property bags. This allows applications to store small amounts of data on the device in order to preserve some aspects of their state.

Application Development

In the following sections, we’ll explore many of the features of UJML as we develop the game Ujinn[1]. The game is based on Samegame and has the following basic specification:

Application: ujinn

Goal:

Maximize score while removing as many of the boxes from the grid as possible.

Game moves:

The player can select a box to remove if that box has at least one adjacent box of

the same color. The adjacent box must be directly above, below, left or right of

the selected box.

Scoring:

Each time a group is cleared we add (n) * (n - 1) where 'n' is the number of

boxes in the cleared group.

At the end of the game the penalty for remaining boxes is the number of remaining

boxes, or the player is given a bonus of (mScore / 4) if they cleared all the boxes.

The following screen shots illustrate the game layout and operation.

After the player selects the current box (upper left), the yellow box and the “connected” 2 yellow boxes to the right are cleared.

SDK

Each section below uses many UJML examples, all of which lead to the development of the game Ujinn. The UJML examples are contained in separate files that accompany this document. The reader is encouraged to install the SDK and run the examples in the SDK.

Installation

Follow these steps to install the UIE SDK:

1. Install Java(TM) 2 Platform Standard Edition (J2SE).

Sun Microsystems' J2SE can be found at java.sun.com/j2se. Download and install the J2SE Software Development Kit using the instructions on Sun's Web site.

2. Set the JAVA_HOME environment variable to the J2SE SDK installation's root directory; the default is C:\j2sdk1.4.1_01. For information on setting environment variables refer to this page.

3. Run the UIE SDK installation program.

Download the UIE SDK from www.uievolution.com.

Application

A minimal UJML application is defined as:

<?xml version="1.0" encoding="UTF-8"?>

<!DOCTYPE ujml PUBLIC "-//UIEVOLUTION//DTD UJML 1.2//EN" "ujml.dtd">

<ujml>

</application>

</ujml>

File: Application.ujml

To run this application in the UIE SDK Debugger, follow these steps:

1. Start the debugger. Use the “Start UIE Debugger” program in the Start à Programs à UIEvolution SDK program group.

2. In the Select Application dialog box:

a. Enter the file path to the Application.ujml file. If you extracted the Inside UJML ZIP file to D:\My Documents\Inside UJML, the URL to enter is file:///D:\My Documents\Inside UJML\UJML\Application.ujml (you can also use the Browse button to locate the file).

b. Select the Flip Phone, MIDP (136x140) skin.

c. Click OK.

3. Click the Run button on the toolbar.

4. The device emulator shows:

Display

Ujinn is a grid-based game so we need to display some boxes in a grid. We also want to display some game statistics like the current score, level, etc. at the top of the screen.

The simplest way to display something on the screen is to put it in a <display> element. The example below draws the text “Score” and a box:

<?xml version="1.0" encoding="UTF-8"?>

<!DOCTYPE ujml PUBLIC "-//UIEVOLUTION//DTD UJML 1.2//EN" "ujml.dtd">

<ujml>

<label>

<text>Score</text>

<fg>&_COLOR_BLUE;</fg>

</label>

<box>

<fg>&_COLOR_RED;</fg>

<bg>&_COLOR_GREEN;</bg>

</box>

</display>

</application>

</ujml>

File: Display.ujml

Running the above Display.ujml in the SDK debugger yields the following in the emulator:

This example uses the default <display> element which is intended for static backgrounds because there is no way to update the contents of the default <display>.

States

For dynamic display elements, UJML allows the programmer to define additional <display> elements that can be controlled (displayed, updated, hidden) programmatically by changing the values of state variables; called state transitions.

A UJML state associates one or more <display> elements to the values that a variable can contain. For example, since a boolean variable can have two values it can be in one of two states, true or false. In UJML it is possible to define <display> elements for each of these values, or states.

In the example below, the boolean state variable sBox has a single <display> element defined for the state value true. When sBox is set to true, the box is displayed on the screen; when it is set to false, since there is no <display> defined for the value false, the box is hidden.

<?xml version="1.0" encoding="UTF-8"?>

<!DOCTYPE ujml PUBLIC "-//UIEVOLUTION//DTD UJML 1.2//EN" "ujml.dtd">

<ujml>

<state-variables>

<state-var name="sBox" type="boolean"/>

</state-variables>

sBox = true;

</script>

<box>

<fg>&_COLOR_RED;</fg>

<bg>&_COLOR_GREEN;</bg>

</box>

</display>

</transition>

</state>

</states>

</application>

</ujml>

File: DisplayState.ujml

The above example displays:

The example below changes the previous Display.ujml application to use separate <display> elements for the text and the box; this allows the application to control them independently by setting the corresponding state variables to either true or false to show or hide the items:

<?xml version="1.0" encoding="UTF-8"?>

<!DOCTYPE ujml PUBLIC "-//UIEVOLUTION//DTD UJML 1.2//EN" "ujml.dtd">

<ujml>

<state-variables>

<state-var name="sScore" type="boolean"/>

<state-var name="sBox" type="boolean"/>

</state-variables>

sScore = true;

sBox = true;

</script>

<label>

<text>Score</text>

<fg>&_COLOR_BLUE;</fg>

</label>

</display>

</transition>

</state>

<box>

<fg>&_COLOR_RED;</fg>

<bg>&_COLOR_GREEN;</bg>

</box>

</display>

</transition>

</state>

</states>

</application>

</ujml>

File: DisplayStates.ujml

The single most important thing to remember about UJML and states is:

The only way to change the display is by changing the values of state variables that have <display> elements associated with them.

Setting a state variable to a value that it already contains will not affect the display. The value must change to change the display[2]. This means that integer state variables are more powerful than boolean variables because a boolean state variable can realistically only have one visible <display> if having the choice of hiding the item is needed; the value true is used to show it and the value false is used to hide it.

Z-order

The <display> elements are drawn on the display with a z-order, back-to-front layering, which matches the order the <display> elements appear in the UJML source file. The default <display> is in the background, lowest in z-order, and the last <display> in the file is in the foreground, highest in z-order[3].

The following example adds two more boxes and a background to DisplayStates.ujml. It also shows how to create and use arrays in UJML; we’ve changed sBox from a simple boolean variable to a boolean array with three elements, one for each box we want to display. Finally, the program shows how ARGB (alpha, red, green, blue) values can be specified for the colors of visual elements.

<?xml version="1.0" encoding="UTF-8"?>

<!DOCTYPE ujml PUBLIC "-//UIEVOLUTION//DTD UJML 1.2//EN" "ujml.dtd">

<ujml>

<state-variables>

<state-var name="sScore" type="boolean"/>

<state-var name="sBox" type="boolean" size="3"/>

</state-variables>

sScore = true;

sBox[ 0 ] = true;

sBox[ 1 ] = true;

sBox[ 2 ] = true;

</script>

<display>

<box>

<width>136</width>

<height>140</height>

</box>

</display>

<label>

<text>Score</text>

<fg>&_COLOR_BLUE;</fg>

</label>

</display>

</transition>

</state>

<box>

<fg>0xffcccccc</fg>

<bg>0xffcccccc</bg>

</box>

</display>

</transition>

</state>

<box>

</box>

</display>

</transition>

</state>

<box>

</box>

</display>

</transition>

</state>

</states>

</application>

</ujml>

File: DisplayZOrder.ujml

The program displays the following:

Application Logic

So far we’ve discussed how to display things on the screen and hinted at how programming logic is expressed in UJML using the <script> element in the above examples. UJML supports variables, arithmetic expressions, logical/boolean expressions, string expressions, control flow statements, functions, and events.

Variables

We’ve already seen how to declare and use state variables. Since there is a certain amount of internal overhead for state variables to support state transitions, UJML also supports simple variables which have no states associated with them. Both state variables and simple variables can be used in expressions and executable statements in the same way as variables are used in any other programming language.

The example below adds variables for the score value and box colors. It shows how to use XML entity definitions for declaring constant values and how to use variables and constants in display elements.

<?xml version="1.0" encoding="UTF-8"?>

<!DOCTYPE ujml PUBLIC "-//UIEVOLUTION//DTD UJML 1.2//EN" "ujml.dtd" [

<!ENTITY MAX_BOXES "3">

<!ENTITY BOX_WIDTH "30">

<!ENTITY BOX_HEIGHT "50">

<ujml>

<state-variables>

<state-var name="sScore" type="boolean"/>

<state-var name="sBox" type="boolean" size="&MAX_BOXES;"/>

</state-variables>

<variables>

<var name="mScore" type="int"/>

<var name="mBox" type="int" size="&MAX_BOXES;"/>

</variables>

mScore = 0;

sScore = true;

mBox[ 0 ] = 0xffcccccc;

sBox[ 0 ] = true;

mBox[ 1 ] = 0xff999999;

sBox[ 1 ] = true;

mBox[ 2 ] = 0xff666666;

sBox[ 2 ] = true;

</script>

<box>

</box>

</display>

<label>

<text><eval>mScore</eval></text>

<fg>&_COLOR_BLUE;</fg>

</label>

</display>

</transition>

</state>

<box>

<width>&BOX_WIDTH;</width>

<height>&BOX_HEIGHT;</height>

</box>

</display>

</transition>

</state>

<box>

<width>&BOX_WIDTH;</width>

<height>&BOX_HEIGHT;</height>

</box>

</display>

</transition>

</state>

<box>

<width>&BOX_WIDTH;</width>

<height>&BOX_HEIGHT;</height>

</box>

</display>

</transition>

</state>

</states>

</application>

</ujml>

File: Variables.ujml

The resulting display:

Script

UJML supports two scripting languages for evaluating expressions and controlling application flow. The previous examples have used UJML’s subset of ECMAScript (JavaScript). JavaScript is contained in the <script> element. Anyone that is a familiar with programming languages like C, C++, Java, or JavaScript will most likely prefer to use JavaScript in UJML applications.

UJML also supports UJMLscript which has the same capabilities as JavaScript but retains the XML syntax. UJMLscript is contained in the <execute> element. Developers that are unfamiliar with the above languages may find UJMLscript easier to learn initially but may find JavaScript easier later when the programming logic of the applications becomes more complex. This is because UJMLscript is verbose and difficult to read when doing complex calculations or program control flow.

Except for the following example that shows equivalent JavaScript and UJMLscript, this document uses JavaScript in all examples.

The following example is the UJMLscript equivalent of the previous Variables.ujml example:

<?xml version="1.0" encoding="UTF-8"?>

<!DOCTYPE ujml PUBLIC "-//UIEVOLUTION//DTD UJML 1.2//EN" "ujml.dtd" [

<!ENTITY MAX_BOXES "3">

<!ENTITY BOX_WIDTH "30">

<!ENTITY BOX_HEIGHT "50">

<ujml>

<state-variables>

<state-var name="sScore" type="boolean"/>

<state-var name="sBox" type="boolean" size="&MAX_BOXES;"/>

</state-variables>

</variables>

<execute>

<set var="mScore">0</set>

<set-state var="sScore">true</set-state>

<set var="mBox">

<index>0</index>

<val>0xffcccccc</val>

</set>

<set-state var="sBox">

<index>0</index>

<val>true</val>

</set-state>

<set var="mBox">

<index>1</index>

<val>0xff999999</val>

</set>

<set-state var="sBox">

<index>1</index>

<val>true</val>

</set-state>

<set var="mBox">

<index>2</index>

<val>0xff666666</val>

</set>

<set-state var="sBox">

<index>2</index>

<val>true</val>

</set-state>

</execute>

<box>

</box>

</display>

<label>

<text>

<ref var="mScore"/>

</text>

<fg>&_COLOR_BLUE;</fg>

</label>

</display>

</transition>

</state>

<box>

<width>&BOX_WIDTH;</width>

<height>&BOX_HEIGHT;</height>

<fg>

<ref var="mBox">

<index>0</index>

</ref>

</fg>

<bg>

<ref var="mBox">

<index>0</index>

</ref>

</bg>

</box>

</display>

</transition>

</state>

<box>

<width>&BOX_WIDTH;</width>

<height>&BOX_HEIGHT;</height>

<fg>

<ref var="mBox">

<index>1</index>

</ref>

</fg>

<bg>

<ref var="mBox">

<index>1</index>

</ref>

</bg>

</box>

</display>

</transition>

</state>

<box>

<width>&BOX_WIDTH;</width>

<height>&BOX_HEIGHT;</height>

<fg>

<ref var="mBox">

<index>2</index>

</ref>

</fg>

<bg>

<ref var="mBox">

<index>2</index>

</ref>

</bg>

</box>

</display>

</transition>

</state>

</states>

</application>

</ujml>

File: UJMLscript.ujml

Expressions

UJML supports most common mathematical, logical, and string operators. An expression can appear both in script as well as the UJML element content for elements that allow values or variable references. In this case, the expression must either be UJMLscript or a JavaScript expression within an <eval> element. However, expressions may not appear in UJML element attribute values because, in UJML, all attribute values are static constants.

The following are examples of valid and invalid uses of expressions:

Valid

Invalid

x = y * 3;

</script>

<box>

</box>

Functions

Many utility functions are built into UJML; applications can also define their own functions.

The example below uses expressions and several built-in functions to dynamically lay out the screen so that it will scale to the current device’s screen size. The example also shows how to use a default state to define an identical state for all the elements of an array state variable.

<?xml version="1.0" encoding="UTF-8"?>

<!DOCTYPE ujml PUBLIC "-//UIEVOLUTION//DTD UJML 1.2//EN" "ujml.dtd" [

<!ENTITY MAX_BOXES "3">

<ujml>

<state-variables>

<state-var name="sScore" type="boolean"/>

<state-var name="sBox" type="boolean" size="&MAX_BOXES;"/>

</state-variables>

</variables>

mTextHeight = _text_height( 0, 0, 0 );

mScrWidth = _getIntProperty( &_PROPERTY_INT_SCREEN_WIDTH; );

mScrHeight = _getIntProperty( &_PROPERTY_INT_SCREEN_HEIGHT; );

mBoxWidth = mScrWidth / &MAX_BOXES;;

mBoxHeight = mScrHeight - mTextHeight;

mScore = 0;

sScore = true;

mBox[ 0 ] = 0xffcccccc;

sBox[ 0 ] = true;

mBox[ 1 ] = 0xff999999;

sBox[ 1 ] = true;

mBox[ 2 ] = 0xff666666;

sBox[ 2 ] = true;

</script>

<box>

<width> <eval>mScrWidth</eval> </width>

<height> <eval>mScrHeight</eval> </height>

<fg>&_COLOR_BLACK;</fg>

<bg>&_COLOR_BLACK;</bg>

</box>

</display>

<label>

<text> <eval>mScore</eval> </text>

<fg>&_COLOR_YELLOW;</fg>

</label>

</display>

</transition>

</state>

Below we define a single default state for all the elements in the array state variable sBox. The main purpose of using a default state is to reduce the amount of UJML code that needs to be written when all the states for the array are identical[4].

<box>

<x> <eval>_state_index() * mBoxWidth</eval> </x>

<y> <eval>mTextHeight</eval> </y>

<width> <eval>mBoxWidth</eval> </width>

<height> <eval>mBoxHeight</eval> </height>

<fg> <eval>mBox[ _state_index() ]</eval> </fg>

<bg> <eval>mBox[ _state_index() ]</eval> </bg>

</box>

</display>

</transition>

</state>

</states>

</application>

</ujml>

File: Functions.ujml

The display on several device skins in the emulator looks like these screen shots:

It is generally a good idea to write applications that automatically scale to the device screen. While it may be difficult or unnecessary to develop an application that looks good on both a vertical screen format and horizontal screen format, many phones have screens in the same format but with differing sizes. So, making the application look good on the same screen format (like vertical phone screens) and within the wide screen size variances possible is a good goal so that the application can be distributed to as many devices as possible with little or no modifications.

Control Flow

Following the fundamental minimalist approach to UJML, it supports only the if and while control flow constructs; switch and for are not supported.

The example below uses a while loop to display all the boxes in an array. A function is used to calculate the x location of each box:

<?xml version="1.0" encoding="UTF-8"?>

<!DOCTYPE ujml PUBLIC "-//UIEVOLUTION//DTD UJML 1.2//EN" "ujml.dtd" [

<!ENTITY MAX_BOXES "3">

<ujml>

<state-variables>

<state-var name="sScore" type="boolean"/>

<state-var name="sBox" type="boolean" size="&MAX_BOXES;"/>

</state-variables>

</variables>

<functions>

<function name="getX" type="int">

<parameters>

<var name="box" type="int"/>

</parameters>

<variables>

<var name="x" type="int"/>

</variables>

<script>

x = box * mBoxWidth;

</script>

<return>

<eval>x</eval>

</return>

</function>

</functions>

mTextHeight = _text_height( 0, 0, 0 );

mScrWidth = _getIntProperty( &_PROPERTY_INT_SCREEN_WIDTH; );

mScrHeight = _getIntProperty( &_PROPERTY_INT_SCREEN_HEIGHT; );

mBoxWidth = mScrWidth / &MAX_BOXES;;

mBoxHeight = mScrHeight - mTextHeight;

mScore = 0;

sScore = true;

mBox[ 0 ] = 0xffcccccc;

mBox[ 1 ] = 0xff999999;

mBox[ 2 ] = 0xff666666;

while (i < &MAX_BOXES;)

{

sBox[ i ] = true;

i = i + 1;

}

</script>

<box>

<width> <eval>mScrWidth</eval> </width>

<height> <eval>mScrHeight</eval> </height>

<fg>&_COLOR_BLACK;</fg>

<bg>&_COLOR_BLACK;</bg>

</box>

</display>

<label>

<text> <eval>mScore</eval> </text>

<fg>&_COLOR_YELLOW;</fg>

</label>

</display>

</transition>

</state>

<box>

<x><eval>getX( _state_index() )</eval></x>

<y> <eval>mTextHeight</eval> </y>

<width> <eval>mBoxWidth</eval> </width>

<height> <eval>mBoxHeight</eval> </height>

<fg> <eval>mBox[ _state_index() ]</eval> </fg>

<bg> <eval>mBox[ _state_index() ]</eval> </bg>

</box>

</display>

</transition>

</state>

</states>

</application>

</ujml>

Events

User actions and system status changes are communicated to a UJML application using events.

The following example adds an event handler when the F1 function key is pressed by the user. The handler unloads the application when F1 is pressed.

<?xml version="1.0" encoding="UTF-8"?>

<!DOCTYPE ujml PUBLIC "-//UIEVOLUTION//DTD UJML 1.2//EN" "ujml.dtd" [

<!ENTITY MAX_BOXES "3">

<ujml>

<state-variables>

…

</state-variables>

…

</variables>

…

</script>

<box>

<width> <eval>mScrWidth</eval> </width>

<height> <eval>mScrHeight</eval> </height>

<fg>&_COLOR_BLACK;</fg>

<bg>&_COLOR_BLACK;</bg>

</box>

<fn>

<text>Back</text>

<event name="onselect">

<accelerators>

<key>F1</key>

</accelerators>

<script>

_unload();

</script>

</event>

</fn>

</display>

…

</states>

</application>

</ujml>

File: Events.ujml

Tip: Always use the F1 key for Back functionality because this behavior is required by some platforms, like BREW, and it fits well with the overall user experience of many devices since most phones have the notion of Back or Clear buttons and Sony’s CLIE PDAs also have a Back button.

Events may only be associated with visual element in a <display> element.

Tip: To create event handlers when a visible visual element is not desired, use an empty or transparent <box> element.

States

In additions to defining <display> elements, states can define application logic to be executed when the state becomes active (the state variable changes to the specified value in the <transition> element).

The following example displays a message box and uses a delayed script to hide the box after five seconds.

<?xml version="1.0" encoding="UTF-8"?>

<!DOCTYPE ujml PUBLIC "-//UIEVOLUTION//DTD UJML 1.2//EN" "ujml.dtd" [

<!ENTITY MAX_BOXES "3">

<ujml>

<state-variables>

…

<state-var name="sMessageBox" type="boolean"/>

</state-variables>

…

</variables>

…

sMessageBox = true;

</script>

…

</display>

…

When the state variable sMessageBox is set to true, the transition below is executed by the UIE Player. First, the <display> element is processed and added to the UIE Player’s internal “display list” which it uses to paint the screen. Next, the <script> element is processed; however, since it follows a <delay> element, instead of executing the <script> element, the UIE Player adds the element to a queue so that it will be executed after a five second delay.

<state var="sMessageBox">

<transition value="true">

<display>

<multi-label>

<text>This is a message box.</text>

<x>10</x>

<y>30</y>

<width><eval>mScrWidth - 20</eval></width>

<height><eval>mScrHeight - 60</eval></height>

<fg>&_COLOR_LIME;</fg>

<bg>&_COLOR_MAROON;</bg>

</multi-label>

</display>

<delay>5000</delay>

<script>

sMessageBox = false;

</script>

</transition>

</state>

</states>

</application>

</ujml>

File: ScriptStates.ujml

Common reasons for using script in a state:

· Delayed logic

· Timer-based logic

· Animation

Templates

Because the Ujinn game uses an 8x8 grid for the game play area, we need to update our sample application to use a two-dimensional state variable array. We also introduce a color map array which is used for the game piece colors; later, we’ll initialize it based on whether or not the device supports color or grayscale.

The changes to our application are shown in bold below:

<?xml version="1.0" encoding="UTF-8"?>

<!DOCTYPE ujml PUBLIC "-//UIEVOLUTION//DTD UJML 1.2//EN" "ujml.dtd" [

<!ENTITY MAX_ROWS "8">

<!ENTITY MAX_COLS "8">

<!ENTITY MAX_COLORS "4">

<ujml>

<state-variables>

<state-var name="sBoxes" type="boolean" size="&MAX_ROWS;,&MAX_COLS;"/>

…

</state-variables>

<var name="mColorMap" type="int" size="&MAX_COLORS;"/>

<var name="r" type="int"/>

<var name="c" type="int"/>

…

</variables>

…

mColorMap[ 0 ] = 0xffcccccc;

mColorMap[ 1 ] = 0xff999999;

mColorMap[ 2 ] = 0xff666666;

mColorMap[ 3 ] = 0xff333333;

while (r < &MAX_ROWS;)

{

c = 0;

while (c < &MAX_COLS;)

{

mBoxes[ r ][ c ] = mColorMap[ (r + c) % &MAX_COLORS; ];

sBoxes[ r ][ c ] = true;

c = c + 1;

}

r = r + 1;

}

</script>

…

</display>

…

<box>

<x> <eval>_state_index(1) * mBoxWidth</eval> </x>

<y>

<eval>mTextHeight + (_state_index(0) * mBoxHeight)</eval>

</y>

<width> <eval>mBoxWidth</eval> </width>

<height> <eval>mBoxHeight</eval> </height>

<fg>

<eval>mBoxes[ _state_index(0) ][ _state_index(1) ]</eval>

</fg>

<bg>

<eval>mBoxes[ _state_index(0) ][ _state_index(1) ]</eval>

</bg>

</box>

</display>

</transition>

</state>

…

</states>

</application>

</ujml>

file: ArrayStates.ujml

This program displays the following:

The UIE SDK Debugger provides important information regarding network traffic for an application; it also can emulate network client/server latency and data transfer bandwidths. Notice that the debugger shows the application's data transfer size in the Requests tab. Also notice that our sample application has grown in size after changing it to an 8x8 grid.

The reason for the size increase is because the application now has 61 additional display states. This may be a bit surprising since the default state appears insignificant:

<box>

<x> <eval>_state_index(1) * mBoxWidth</eval> </x>

<y>

<eval>mTextHeight + (_state_index(0) * mBoxHeight)</eval>

</y>

<width> <eval>mBoxWidth</eval> </width>

<height> <eval>mBoxHeight</eval> </height>

<fg>

<eval>mBoxes[ _state_index(0) ][ _state_index(1) ]</eval>

</fg>

<bg>

<eval>mBoxes[ _state_index(0) ][ _state_index(1) ]</eval>

</bg>

</box>

</display>

</transition>

</state>

However, a default state is just shorthand that allows the developer to use a single simple syntax to define an array of identical states, one for each state variable array element. So, this innocent-looking default state expands to 64 individual states when compiled. Hence, the increased size of the file.

UJML provides a way to define a display template which can be referenced from a display state and expanded on the UIE Player. This is not only useful for our particular situation where we want to minimize the size of the application, but it can also be used to define reusable sections of display elements.

The example below converts our application to use a template for each grid display state:

<?xml version="1.0" encoding="UTF-8"?>

<!DOCTYPE ujml PUBLIC "-//UIEVOLUTION//DTD UJML 1.2//EN" "ujml.dtd" [

…

<ujml>

<state-variables>

…

</variables>

<templates>

<template name="tBox">

<display>

<box>

<x> <eval>c * mBoxWidth</eval> </x>

<y> <eval>mTextHeight + (r * mBoxHeight)</eval> </y>

<width> <eval>mBoxWidth</eval> </width>

<height> <eval>mBoxHeight</eval> </height>

<fg>

<eval>mBoxes[ r ][ c ]</eval>

</fg>

<bg>

<eval>mBoxes[ r ][ c ]</eval>

</bg>

</box>

</display>

</template>

</templates>

…

</script>

…

</display>

…

<expand template="tBox"/>

</display>

</transition>

</state>

…

</states>

</application>

</ujml>

file: Templates.ujml

Notice the size reduction as a result of using a template:

As before, there are still 64 display states, but now each state simply references the template which generates much less byte code compared to the inline display elements used in the previous example.

Tip: Templates can only reference global variables so caution must be taken to ensure the global variable values are in sync with the state transitions when using templates. One way is to show/hide display states that use templates using a function rather than directly setting the state variable. This function can set up the global variables used by the template before setting the state variable to a value that makes the display state visible. This technique will be used later as we develop the Ujinn game.

Ujinn

We now have many of the basic UJML building blocks that we need to implement the Ujinn game. So, let’s build our game.

Grid Initialization

The Ujinn grid is a randomly arranged set of colors. The first step is to update our sample application to initialize the grid.

<?xml version="1.0" encoding="UTF-8"?>

<!DOCTYPE ujml PUBLIC "-//UIEVOLUTION//DTD UJML 1.2//EN" "../ujml.dtd" [

<!ENTITY and "&&">

<!ENTITY SCORE_ITEM_FG "&_COLOR_WHITE;">

<!ENTITY SCORE_ITEM_BG "0xff000066">

<!ENTITY MAX_ROWS "8">

<!ENTITY MAX_COLS "8">

<!ENTITY MAX_COLORS "4">

<!ENTITY CLEARING_COLOR "&_COLOR_WHITE;">

<!ENTITY CLEARED_COLOR "&_COLOR_TRANSPARENT;">

<ujml>

<state-variables>

<state-var name="sBoxes" type="boolean" size="&MAX_ROWS;,&MAX_COLS;"/>

</state-variables>

</variables>

</parameters>

mColorMap[ entry ][ 0 ] = color1;

mColorMap[ entry ][ 1 ] = color2;

</script>

</function>

if (_getBooleanProperty( &_PROPERTY_BOOLEAN_COLOR_CAPABLE; ))

{

setColorMapEntry( 0, 0xffff0000, 0xffdd0000 );

setColorMapEntry( 1, 0xff00ff00, 0xff00dd00);

setColorMapEntry( 2, 0xff0000ff, 0xff0000dd);

setColorMapEntry( 3, 0xffffff00, 0xffdddd00);

}

else

{

setColorMapEntry( 0, 0xff000000, 0xffcccccc);

setColorMapEntry( 1, 0xff555555, 0xffcccccc);

setColorMapEntry( 2, 0xffaaaaaa, 0xffcccccc);

setColorMapEntry( 3, 0xffdddddd, 0xffcccccc);

}

</script>

</function>

</variables>

gSeed = _srand( 101 );

while (col < &MAX_COLS;)

{

row = 0;

while (row < &MAX_ROWS;)

{

mBoxes[row][col][0] = mColorMap[ gSeed % &MAX_COLORS; ][0];

mBoxes[row][col][1] = mColorMap[ gSeed % &MAX_COLORS; ][1];

tBoxRow = row;

tBoxCol = col;

sBoxes[ tBoxRow ][ tBoxCol ] = true;

gSeed = _srand( gSeed );

row = row + 1;

}

col = col + 1;

}

</script>

</function>

</functions>

<box>

<x> <eval>tBoxCol * mBoxWidth</eval> </x>

<y> <eval>tBoxRow * mBoxHeight + mTextHeight</eval> </y>

<width> <eval>mBoxWidth</eval> </width>

<height> <eval>mBoxHeight</eval> </height>

<fg> <eval>mBoxes[ tBoxRow ][ tBoxCol ][ 1 ]</eval> </fg>

<bg> <eval>mBoxes[ tBoxRow ][ tBoxCol ][ 0 ]</eval> </bg>

<box>

<x> <eval>mBoxWidth / 4</eval> </x>

<y> <eval>mBoxHeight / 4</eval> </y>

<width> <eval>mBoxWidth / 2</eval> </width>

<height> <eval>mBoxHeight / 2</eval> </height>

<fg> <eval>mBoxes[ tBoxRow ][ tBoxCol ][ 1 ]</eval> </fg>

<bg> <eval>mBoxes[ tBoxRow ][ tBoxCol ][ 1 ]</eval> </bg>

</box>

</display>

</template>

</templates>

mTextHeight = _text_height( 0, 0, 0 );

mScrWidth = _getIntProperty( &_PROPERTY_INT_SCREEN_WIDTH; );

mScrHeight = _getIntProperty( &_PROPERTY_INT_SCREEN_HEIGHT; );

mBoxWidth = mScrWidth / &MAX_COLS;;

mBoxHeight = (mScrHeight - mTextHeight) / &MAX_ROWS;;

setupColorMap();

start();

</script>

<box>

<width> <eval>mScrWidth</eval> </width>

<height> <eval>mScrHeight</eval> </height>

<fg>&_COLOR_BLACK;</fg>

<bg>&_COLOR_BLACK;</bg>

</box>

<fn>

_unload();

</script>

</event>

</fn>

</display>

</display>

</transition>

</state>

</states>

</application>

</ujml>

File: ujinn1.ujml

Notice that we now use a random number generator to choose a color for each box. Also, the colors are kept in a color map which is initialized based on whether or not the device supports color. The boxes are now drawn using two boxes with slightly different shades of the same color; this helps to make the boxes more visible, especially for slightly color-blind users.

The start() function does the work of initializing the box colors and setting the box state to true to make each box visible. While using a function for updating the display is a workable approach, it can cause delays that exceed the user’s patience. For example, running ujinn1.ujml on some phones initializes the screen very slowly.[RA1]

The reason for the delay is that the UIE Player only updates the screen when it is idle; which means no UJML code is executing. Therefore, as long as the start() function is executing, all the state transitions that update the display are not visible to the user until the function is finished.

Periodic Screen Updates in a Loop

A simple way to update the screen while the grid is being initialized is to implement the start() function using states with <delay> elements that later force the application to idle for a moment so that the UIE Player can update the screen.

Let’s rewrite the start() function to use states and update the screen after each column is initialized. This gives the user more immediate visual feedback to show that something useful is happening and progress is being made.

…

<ujml>

<state-variables>

<state-var name="sBoxes" type="boolean" size="&MAX_ROWS;,&MAX_COLS;"/>

<state-var name="sStart" type="boolean"/>

</state-variables>

…

<var name="gCol" type="int"/>

</variables>

…

</functions>

…

</templates>

…

gSeed = _srand( 101 );

gCol = 0;

sStart = true;

</script>

…

</display>

…

<state var="sStart">

<transition value="true">

<delay>20</delay>

</variables>

row = 0;

while (row < &MAX_ROWS;)

{

mBoxes[row][gCol][0] = mColorMap[ gSeed % &MAX_COLORS; ][0];

mBoxes[row][gCol][1] = mColorMap[ gSeed % &MAX_COLORS; ][1];

tBoxRow = row;

tBoxCol = gCol;

sBoxes[ tBoxRow ][ tBoxCol ] = true;

gSeed = _srand( gSeed );

row = row + 1;

}

gCol = gCol + 1;

We execute the “sStart == true” transition for each column. Once gCol is equal to MAX_COLS, sStart is set to false and we terminate the loop.

_clear_state( sStart );

sStart = gCol < &MAX_COLS;;

</script>

</transition>

</state>

</states>

</application>

</ujml>

File: ujinn2.ujml

In the revised Ujinn, we’ve removed the start() function and moved the initialization loop into a state, sStart. The outer loop for each column is now controlled using a global gCol variable which is used at the end of the state script to determine if we should transition to the true case again; this will happen for each column less than MAX_COLS. The key thing to notice is how a small delay is used to force the screen to be refreshed, because it forces the UIE Player to idle.

Tip: Use the <delay> element in long loops to update the screen periodically.

Cursor

The user needs a way to interact with the game. Phones typically have a direction pad and a Fire or Select button. PDAs tend to be more stylus-oriented. In the revision of Ujinn below, we add a cursor and stylus input to the game.

…

<ujml>

<state-variables>

…

<state-var name="sCursor" type="boolean"/>

</state-variables>

…

<var name="mCursorCol" type="int"/>

<var name="mCursorRow" type="int"/>

</variables>

…

<function name="setCursor" type="void">

</parameters>

mCursorRow = row;

mCursorCol = col;

sCursor = false;

sCursor = true;

</script>

</function>

</functions>

…

…

<state var="sCursor">

The first box captures stylus taps. The event handler converts the stylus location to a box location and moves the cursor to the box.

<box>

<y> <eval>mTextHeight</eval> </y>

<width> <eval>mBoxWidth * &MAX_COLS;</eval> </width>

<height> <eval>mBoxHeight * &MAX_ROWS;</eval> </height>

<fg>&_COLOR_TRANSPARENT;</fg>

<bg>&_COLOR_TRANSPARENT;</bg>

setCursor(

_getIntProperty( &_VALUE_INT_ONSELECT_Y_REL; ) /

mBoxHeight,

_getIntProperty( &_VALUE_INT_ONSELECT_X_REL; ) /

mBoxWidth );

</script>

</event>

</box>

<box>

<x>

<eval>mCursorCol * mBoxWidth + mBoxWidth / 2 - 2</eval>

</x>

<y>

<eval>(mCursorRow * mBoxHeight) + mTextHeight + 2</eval>

</y>

<height> <eval>mBoxHeight - 4</eval> </height>

</box>

<box>

<x> <eval>mCursorCol * mBoxWidth + 2</eval> </x>

<y>

<eval>(mCursorRow * mBoxHeight) + mTextHeight +

mBoxHeight / 2 - 2</eval>

</y>

<width> <eval>mBoxWidth - 4</eval> </width>

setCursor( mCursorRow, (mCursorCol + &MAX_COLS; - 1)

% &MAX_COLS; );

</script>

</event>

</box>

<box>

<x>

<eval>mCursorCol * mBoxWidth + mBoxWidth / 2 - 2</eval>

</x>

<y>

<eval>(mCursorRow * mBoxHeight) + mTextHeight +

mBoxHeight / 2 - 2</eval>

</y>

<bg> <eval>mBoxes[ mCursorRow ][ mCursorCol ][1]</eval></bg>

<accelerators> <key>RIGHT</key> </accelerators>

setCursor( mCursorRow, (mCursorCol+1) % &MAX_COLS; );

</script>

</event>

</box>

<box>

if (mCursorRow == 0)

{

setCursor( &MAX_ROWS; - 1,

(mCursorCol + &MAX_COLS; - 1) %

&MAX_COLS; );

}

else

{

setCursor( mCursorRow - 1, mCursorCol );

}

</script>

</event>

</box>

<box>

if (mCursorRow == (&MAX_ROWS; - 1))

{

setCursor( 0, (mCursorCol + 1) % &MAX_COLS; );

}

else

{

setCursor( mCursorRow + 1, mCursorCol );

}

</script>

</event>

</box>

<box>

<x> <eval>mCursorCol * mBoxWidth</eval> </x>

<y> <eval>(mCursorRow * mBoxHeight) + mTextHeight</eval> </y>

<width> <eval>mBoxWidth</eval> </width>

<height> <eval>mBoxHeight</eval> </height>

<fg>&_COLOR_TRANSPARENT;</fg>

<bg>&_COLOR_TRANSPARENT;</bg>

</box>

</display>

</transition>

</state>

…

</state>

</states>

</application>

</ujml>

File: ujinn3.ujml

Adding the cursor requires adding a new state variable, sCursor, to control the visibility of the cursor and the associated display elements. We also add event handlers for Up, Down, Left, and Right key presses. Finally, we add an event handler for the stylus which converts the x and y coordinates of a stylus tap to the corresponding box in the game grid.

The revised Ujinn game now displays a cursor in the upper left corner of the grid. On both phones and PDAs, the left, right, up, and down buttons move the cursor. On a PDA, tapping on a box will cause the cursor to move to the box.

Removing Boxes

Once the user can select a box, the next step is to allow the user to remove groups, starting with the box selected by the cursor. The application searches adjacent boxes to see if they are the same color as the box under the cursor. Once no more adjacent matches can be found, the group is deleted and the screen is redrawn.

<?xml version="1.0" encoding="UTF-8"?>

<!DOCTYPE ujml PUBLIC "-//UIEVOLUTION//DTD UJML 1.4//EN" "ujml.dtd" [

<!ENTITY and "&&">

<!ENTITY SCORE_ITEM_FG "&_COLOR_WHITE;">

<!ENTITY SCORE_ITEM_BG "0xff000066">

<!ENTITY MAX_ROWS "8">

<!ENTITY MAX_COLS "8">

<!ENTITY MAX_COLORS "4">

<!ENTITY CLEARING_COLOR "&_COLOR_WHITE;">

<!ENTITY CLEARED_COLOR "&_COLOR_TRANSPARENT;">

<ujml>

<state-machines>

<include file="ujlib/stack.ujml" state-machine="IntStack"/>

/state-machines>

<state-variables>

…

<state-var name="sDelayedRemoveBoxes" type="boolean"/>

<state-var name="sDelayedSelectBox" type="boolean"/>

<state-var name="sRemoveColumns" type="boolean"/>

</state-variables>

</variables>

…

</parameters>

if (color == mBoxes[ row ][ col ][ 0 ])

{

IntStack.push( row );

IntStack.push( col );

}

</script>

</function>

…

</parameters>

</variables>

if ((mBoxes[row][col][0] != &CLEARING_COLOR;) &and;

(mBoxes[row][col][0] != &CLEARED_COLOR;))

{

selectedColor = mBoxes[ row ][ col ][ 0 ];

selectedInnerColor = mBoxes[ row ][ col ][ 1 ];

IntStack.push( row );

IntStack.push( col );

while (IntStack.size() > 0)

{

col = IntStack.pop();

row = IntStack.pop();

mBoxes[ row ][ col ][ 0 ] = &CLEARING_COLOR;;

mBoxes[ row ][ col ][ 1 ] = &CLEARING_COLOR;;

repaintBox( row, col );

numBoxesToBeRemoved = numBoxesToBeRemoved + 1;

mRemoveBoxesFromColumn[ col ] = true;

<!-- Now check neighboring boxes to see if they are the same

color -->

if (row > 0)

{

checkBoxColor( row - 1, col, selectedColor );

}

if (col > 0)

{

checkBoxColor( row, col - 1, selectedColor );

}

if (row < (&MAX_ROWS; - 1))

{

checkBoxColor( row + 1, col, selectedColor );

}

if (col < (&MAX_COLS; - 1))

{

checkBoxColor( row, col + 1, selectedColor );

}

<!-- Make sure the user selected a box that had neighbors of

the same color -->

if (numBoxesToBeRemoved > 1)

{

<!-- user selected a valid box, remove the marked boxes after

a slight delay -->

<!-- to show the user some feedback on which boxes are being

deleted -->

sDelayedRemoveBoxes = true;

}

else

{

<!-- user selected a box that has no neighbors of the same

color so back out -->

mBoxes[ row ][ col ][ 0 ] = selectedColor;

mBoxes[ row ][ col ][ 1 ] = selectedInnerColor;

repaintBox( row, col );

}

</script>

</function>

</variables>

sCursor = false;

mNumBoxesCleared = 0;

gAvailCol = &MAX_COLS;;

col = &MAX_COLS; - 1;

<!-- for each column, check to see if we've marked it as having boxes

to remove -->

while (col > -1)

{

if (mRemoveBoxesFromColumn[ col ])

{

topBox = &MAX_ROWS; - mNumBoxesInColumn[ col ];

row = topBox;

while (row < &MAX_ROWS;)

{

if (mBoxes[ row ][ col ][ 0 ] == &CLEARING_COLOR;)

{

mNumBoxesCleared = mNumBoxesCleared + 1;

mBoxes[ row ][ col ][ 0 ] = &CLEARED_COLOR;;

mBoxes[ row ][ col ][ 1 ] = &CLEARED_COLOR;;

repaintBox( row, col );

availRow = row;

mNumBoxesInColumn[col] = mNumBoxesInColumn[col] - 1;

}

row = row + 1;

}

row = &MAX_COLS; - 1;

row = availRow - 1;

topBox = topBox - 1;

while (row > topBox)

{

if (mBoxes[ row ][ col ][ 0 ] != &CLEARED_COLOR;)

{

mBoxes[ availRow ][col][0] = mBoxes[row][col][ 0 ];

mBoxes[ availRow ][col][1] = mBoxes[row][col][ 1 ];

mBoxes[ row ][ col ][ 0 ] = &CLEARED_COLOR;;

mBoxes[ row ][ col ][ 1 ] = &CLEARED_COLOR;;

repaintBox( row, col );

repaintBox( availRow, col );

availRow = availRow - 1;

}

row = row - 1;

}

mRemoveBoxesFromColumn[ col ] = false;

if (mNumBoxesInColumn[ col ] == 0)

{

gAvailCol = col;

}

col = col - 1;

}

<!-- if there are empty columns, remove them; if gAvailCol is

less than &MAX_COLS;, then -->

gCol = gAvailCol;

sRemoveColumns = gCol < &MAX_COLS;;

</script>

</function>

</parameters>

</variables>

while (row < &MAX_ROWS;)

{

mBoxes[ row ][ toCol ][ 0 ] = mBoxes[ row ][ fromCol ][ 0 ];

mBoxes[ row ][ toCol ][ 1 ] = mBoxes[ row ][ fromCol ][ 1 ];

mBoxes[ row ][ fromCol ][ 0 ] = &CLEARED_COLOR;;

mBoxes[ row ][ fromCol ][ 1 ] = &CLEARED_COLOR;;

repaintBox( row, fromCol );

repaintBox( row, toCol );

row = row + 1;

}

mNumBoxesInColumn[ toCol ] = mNumBoxesInColumn[ fromCol ];

mNumBoxesInColumn[ fromCol ] = 0;

</script>

</function>

…

</functions>

<box>

<x> <eval>tBoxCol * mBoxWidth</eval> </x>

<y> <eval>tBoxRow * mBoxHeight + mTextHeight</eval> </y>

<width> <eval>mBoxWidth</eval> </width>

<height> <eval>mBoxHeight</eval> </height>

<fg> <eval>mBoxes[ tBoxRow ][ tBoxCol ][ 1 ]</eval> </fg>

<bg> <eval>mBoxes[ tBoxRow ][ tBoxCol ][ 0 ]</eval> </bg>

<box>

<x> <eval>mBoxWidth / 4</eval> </x>

<y> <eval>mBoxHeight / 4</eval> </y>

<width> <eval>mBoxWidth / 2</eval> </width>

<height> <eval>mBoxHeight / 2</eval> </height>

<fg> <eval>mBoxes[ tBoxRow ][ tBoxCol ][ 1 ]</eval> </fg>

<bg> <eval>mBoxes[ tBoxRow ][ tBoxCol ][ 1 ]</eval> </bg>

</box>

</display>

</template>

</templates>

…

</script>

…

</display>

selectBox( mCursorRow, mCursorCol );

sDelayedSelectBox = false;

</script>

</transition>

</state>

</display>

</transition>

</state>

<box>

<y> <eval>mTextHeight</eval> </y>

<width> <eval>mBoxWidth * &MAX_COLS;</eval> </width>

<height> <eval>mBoxHeight * &MAX_ROWS;</eval> </height>

<fg>&_COLOR_TRANSPARENT;</fg>

<bg>&_COLOR_TRANSPARENT;</bg>

setCursor( _getIntProperty( &_VALUE_INT_ONSELECT_Y_REL; ) / mBoxHeight,

_getIntProperty( &_VALUE_INT_ONSELECT_X_REL; ) / mBoxWidth );

sDelayedSelectBox = true;

</script>

</event>

</box>

<box>

<x> <eval>mCursorCol * mBoxWidth + mBoxWidth / 2 - 2</eval>

</x>

<y> <eval>(mCursorRow * mBoxHeight) + mTextHeight + 2</eval>

</y>

<height> <eval>mBoxHeight - 4</eval> </height>

selectBox( mCursorRow, mCursorCol );

</script>

</event>

</box>

<box>

<x> <eval>mCursorCol * mBoxWidth + 2</eval> </x>

<y> <eval>(mCursorRow * mBoxHeight) + mTextHeight +

mBoxHeight / 2 - 2</eval> </y>

<width> <eval>mBoxWidth - 4</eval> </width>

setCursor( mCursorRow,

(mCursorCol+&MAX_COLS;-1) % &MAX_COLS; );

</script>

</event>

</box>

<box>

<x> <eval>mCursorCol * mBoxWidth + mBoxWidth / 2 - 2</eval>

</x>

<y> <eval>(mCursorRow * mBoxHeight) + mTextHeight +

mBoxHeight / 2 - 2</eval> </y>

<bg>

<eval>mBoxes[ mCursorRow ][ mCursorCol ][ 1 ]</eval>

</bg>

<accelerators> <key>RIGHT</key> </accelerators>

setCursor( mCursorRow, (mCursorCol + 1) % &MAX_COLS; );

</script>

</event>

</box>

<box>

if (mCursorRow == 0)

{

setCursor( &MAX_ROWS; - 1,

(mCursorCol + &MAX_COLS; - 1) %

&MAX_COLS; );

}

else

{

setCursor( mCursorRow - 1, mCursorCol );

}

</script>

</event>

</box>

<box>

if (mCursorRow == (&MAX_ROWS; - 1))

{

setCursor( 0, (mCursorCol + 1) % &MAX_COLS; );

}

else

{

setCursor( mCursorRow + 1, mCursorCol );

}

</script>

</event>

</box>

<box>

<x> <eval>mCursorCol * mBoxWidth</eval> </x>

<y> <eval>(mCursorRow * mBoxHeight) + mTextHeight</eval> </y>

<width> <eval>mBoxWidth</eval> </width>

<height> <eval>mBoxHeight</eval> </height>

<fg>&_COLOR_TRANSPARENT;</fg>

<bg>&_COLOR_TRANSPARENT;</bg>

selectBox( mCursorRow, mCursorCol );

</script>

</event>

</box>

</display>

</transition>

</state>

sDelayedRemoveBoxes = false;

removeBoxes();

</script>

</transition>

</state>

<delay>

<eval>gRemoveColumnsDelay</eval>

</delay>

gRemoveColumnsDelay = 0;

if (mNumBoxesInColumn[ gCol ] > 0)

{

<!-- this column is not empty so move it to the empty

available column -->

moveColumn( gCol, gAvailCol );

gAvailCol = gAvailCol + 1;

gRemoveColumnsDelay = 200;

}

gCol = gCol + 1;

_clear_state( sRemoveColumns );

sRemoveColumns = gCol < &MAX_COLS;;

</script>

</transition>

sCursor = true;

gRemoveColumnsDelay = 0;

_clear_state( sRemoveColumns );

</script>

</transition>

</state>

…

</state>

</states>

</application>

</ujml>

File: ujinn4.ujml

Now the user can clear groups:

The implementation of removing boxes is straightforward logic so it is left to the reader to view it in the source UJML in ujinn4.ujml. Some UJML specifics include further use of delayed states to provide animated user feedback as the group of boxes is removed and the columns are shifted to the left. Also, the program uses a simple stack which is implemented as a reusable UJML fragment; discussed in the next section.

Reusable Stack

Given that a central theme and goal of UJML is to allow developers to implement an application once and deploy it to many platforms, it follows that developing reusable UJML “components” is an important topic in the context of code reuse and redeployment.

Although the current version, 1.4, of UJML does not directly support the development of reusable components like Java classes and COM objects, it does allow the developer quite a bit of flexibility for reusing UJML efficiently using the <state-machine> element[5].

The <state-machine> and <include> elements are discussed later in this document.

Below is the <state-machine> that defines a simple reusable stack, as used by Ujinn.

<?xml version="1.0" encoding="UTF-8"?>

<!DOCTYPE ujml PUBLIC "-//UIEVOLUTION//DTD UJML 1.4//EN" "../ujml.dtd" [

<!ENTITY % include SYSTEM "include.ujmc">

%include;

<ujml>

<state-machine name="IntStack" access="export">

</variables>

</parameters>

mItems[ mTop ] = item;

mTop = mTop + 1;

</script>

</return>

</function>

</variables>

if (mTop > 0)

{

mTop = mTop - 1;

item = mItems[ mTop ];

}

</script>

</return>

</function>

</return>

</function>

</functions>

</state-machine>

</state-machines>

</partition>

</ujml>

File: ujlib/stack.ujml

Score Display

Now we add the ability to update the score at the top of the screen.

…

<ujml>

<state-variables>

…

<state-var name="sScores" type="boolean"/>

<state-var name="sDelayedUpdateScores" type="boolean"/>

</state-variables>

…

…

</variables>

…

sDelayedUpdateScores = true;

</script>

</function>

…

</variables>

while (col < &MAX_COLS;)

{

repaintColumn( col );

col = col + 1;

}

updateScores();

</script>

</function>

…

mBoxWidth = mScrWidth / &MAX_COLS;;

mBoxHeight = (mScrHeight - mTextHeight) / &MAX_ROWS;;

mNumBoxes = &MAX_ROWS; * &MAX_COLS;;

mScore = 0;

mTotalBoxesCleared = 0;

mLevelNumber = 1;

mCursorRow = 0;

mCursorCol = 0;

sCursor = false;

sCursor = true;

</script>

</function>

mScore = 0;

mHighScore = 0;

updateScores();

</script>

</function>

…

</functions>

…

sScores = false;

sScores = true;

sDelayedUpdateScores = false;

</script>

</transition>

</state>

<box>

<width> <eval>mScrWidth</eval> </width>

<height> <eval>mTextHeight</eval> </height>

<fg>&SCORE_ITEM_BG;</fg>

<bg>&SCORE_ITEM_BG;</bg>

<label>

<text>

<eval>mScore</eval>

<eval>mHighScore</eval>

<eval>mLevelNumber</eval>

<eval>mTotalBoxesCleared</eval>

<eval>mNumBoxes</eval>

</strcat>

</text>

<fg>&SCORE_ITEM_FG;</fg>

</label>

</box>

</display>

</transition>

</state>

…

…

</transition>

mScore = mScore + (mNumBoxesCleared * (mNumBoxesCleared - 1));

mTotalBoxesCleared = mTotalBoxesCleared + mNumBoxesCleared;

updateScores();

sCursor = true;

gRemoveColumnsDelay = 0;

_clear_state( sRemoveColumns );

</script>

</transition>

</state>

…

</states>

</application>

</ujml>

File: ujinn5.ujml

Notice that the function updateScores() simply sets the sDelayedUpdatesScores state variable to true. This state transition uses a <delay> element to defer the actual score update. This is done to avoid repainting two independent sections of the screen at the same time because doing so can dramatically slow down the screen repainting process on slow devices.

The UIE Player attempts to repaint the smallest part of the screen that has become invalid due to display states being added or removed from the state machine. The UIE Player coalesces invalid screen regions into one invalid region. So, if two areas of the screen are far from each other, the UIE Player will repaint the rectangular section of the screen that contains both regions; thus repainting much more than is necessary. By using delays, the application can force the two regions to be repainted independently and the resulting performance increase can be dramatic; especially for grid-based games like Ujinn where an overly-large invalid screen rectangle can cause many display states to be repainted.

Tip: Use the <delay> element to show spatially disjointed display states independently.

Endgame Checking

The changes below check for when the grid is either cleared completely or when there are no more groups to clear.

…

<ujml>

<state-variables>

…

<state-var name="sGameOver" type="boolean"/>

<state-var name="sDelayedEndGameCheck" type="boolean"/>

<state-var name="sMessage" type="boolean"/>

</state-variables>

…

…

…

</transition>

mScore = mScore + (mNumBoxesCleared * (mNumBoxesCleared - 1));

mTotalBoxesCleared = mTotalBoxesCleared + mNumBoxesCleared;

sDelayedEndGameCheck = true;

gRemoveColumnsDelay = 0;

_clear_state( sRemoveColumns );

</script>

</transition>

</state>

</variables>

if (mTotalBoxesCleared == mNumBoxes)

{

mScore = mScore + (mScore / 4);

mMessage = _strcat( "Level cleared!

Bonus: ", _strcat( mScore / 4, "." ) );

sMessage = true;

if (mScore > mHighScore)

{

mHighScore = mScore;

}

fGameOver = true;

}

else

{

if (!areBoxesRemovable())

{

mScore = mScore - (mNumBoxes - mTotalBoxesCleared);

mMessage = _strcat( "No more moves.

Penalty: ", _strcat( mNumBoxes - mTotalBoxesCleared, "." ) );

sMessage = true;

if (mScore > mHighScore)

{

mHighScore = mScore;

}

fGameOver = true;

}

updateScores();

sCursor = false;

sCursor = true;

sDelayedEndGameCheck = false;

sGameOver = fGameOver;

</script>

</transition>

</state>

sCursor = false;

</script>

</transition>

</state>

<multi-label>

<text><eval>mMessage</eval> </text>

<width><eval>mScrWidth - 20</eval> </width>

<height><eval>mScrHeight - 20</eval></height>

<bg>&_COLOR_WHITE;</bg>

sMessage = false;

start();

</script>

</event>

</multi-label>

</display>

</transition>

</state>

</states>

</application>

</ujml>

File: ujinn6.ujml

Menus

At this point, the basic Ujinn game is complete. However, the game can be augmented by giving the user options to: play a different level, change the grid size, change the number of colors, or replay the same level.

We now add a main menu and an options editor dialog box to allow the user to specify the various options described above. Since menus are likely to be useful in other applications, we’ll implement them as a reusable UJML <state-machine> as defined below.

<?xml version="1.0" encoding="UTF-8"?>

<!DOCTYPE ujml PUBLIC "-//UIEVOLUTION//DTD UJML 1.4//EN" "../ujml.dtd" [

<!ENTITY % include SYSTEM "include.ujmc">

%include;

<!ENTITY HIGHLIGHT_VISIBLE "-1">

<!ENTITY HIGHLIGHT_FIRE_SELECT_EVENT "-2">

<!ENTITY MENU_MAX_ITEMS "6">

<ujml>

<state-machines>

<state-machine name="Menu" access="export">

<state-variables>

<state-var name="sMenu" type="boolean"/>

<state-var name="sHighlight" type="int"/>

<state-var name="sMenuItems" type="boolean" size="&MENU_MAX_ITEMS;"/>

</state-variables>

</variables>

</parameters>

mCurItem = item;

mCurItemOffsetY = mCurItem * mItemHeight;

Event.setParam( 0, mCommands[ mCurItem ] );

Event.fireEventNow( &EVENT_SELECTING;, mHandler );

_clear_state( sHighlight );

sHighlight = &HIGHLIGHT_FIRE_SELECT_EVENT;;

</script>

</function>

_clear_state( sHighlight );

sHighlight = &HIGHLIGHT_VISIBLE;;

</script>

</function>

</parameters>

mCurItem = (mCurItem + delta + mNumItems) % mNumItems;

mCurItemOffsetY = mCurItem * mItemHeight;

Event.setParam( 0, mCommands[ mCurItem ] );

Event.fireEventNow( &EVENT_HIGHLIGHTING;, mHandler );

Highlight_show();

Event.setParam( 0, mCommands[ mCurItem ] );

Event.fireEvent( &EVENT_HIGHLIGHTED;, mHandler);

</script>

</function>

</parameters>

mAttributes[ attribute ] = color;

</script>

</function>

</parameters>

</variables>

if (attribute &_GTE; 0)

{

retval = mAttributes[ attribute ];

}

else if (attribute == &MENU_ATTR_X;)

{

retval = mX - mAttributes[ &MENU_ATTR_BORDER_THICKNESS; ];

}

else if (attribute == &MENU_ATTR_Y;)

{

retval = mY - mAttributes[ &MENU_ATTR_BORDER_THICKNESS; ];

}

else if (attribute == &MENU_ATTR_WIDTH;)

{

retval = mWidth + mAttributes[ &MENU_ATTR_BORDER_THICKNESS; ] * 2;

}

else if (attribute == &MENU_ATTR_HEIGHT;)

{

retval = mItemHeight * mNumItems +

mAttributes[ &MENU_ATTR_BORDER_THICKNESS; ] * 2;

}

</script>

<eval>retval</eval>

</return>

</function>

</parameters>

</variables>

_clear_state( sMenu );

sMenu = visible;

if (visible)

{

while (item < mNumItems)

{

Event.setParam( 0, mCommands[ mCurItem ] );

Event.fireEventNow( &EVENT_PAINTING;, mHandler );

mItemIndex = item;

_clear_state( sMenuItems[ item ] );

sMenuItems[ item ] = true;

item = item + 1;

}

Highlight_show();

}

else

{

while (item < mNumItems)

{

_clear_state( sMenuItems[ item ] );

item = item + 1;

}

_clear_state( sHighlight );

}

</script>

</function>

<eval>sMenu</eval>

</return>

</function>

mX = (mScrWidth - mWidth) / 2;

mY = (mScrHeight - mNumItems * mItemHeight) / 2;

</script>

</function>

</parameters>

setVisible( false );

mScrWidth = _getIntProperty( &_PROPERTY_INT_SCREEN_WIDTH; );

mScrHeight = _getIntProperty( &_PROPERTY_INT_SCREEN_HEIGHT; );

mHandler = handler;

mWidth = 0;

mItemHeight = _text_height( 0, 0, 0 );

mNumItems = 0;

mCurItemOffsetY = 0;

mCurItem = 0;

setAttribute( &MENU_ATTR_ITEM_FG;, &_COLOR_BLACK; );

setAttribute( &MENU_ATTR_ITEM_BG;, &_COLOR_WHITE; );

setAttribute( &MENU_ATTR_BORDER;, &_COLOR_GRAY; );

setAttribute( &MENU_ATTR_BG;, &_COLOR_BLACK; );

setAttribute( &MENU_ATTR_HIGHLIGHT_FG;, &_COLOR_WHITE; );

setAttribute( &MENU_ATTR_HIGHLIGHT_BG;, 0xff9999ff );

setAttribute( &MENU_ATTR_SELECTED_FG;, &_COLOR_WHITE; );

setAttribute( &MENU_ATTR_SELECTED_BG;, 0xff6666cc );

mX = 3;

mY = mX;

setAttribute( &MENU_ATTR_BORDER_THICKNESS;, mX );

</script>

</function>

</parameters>

mCaptions[ mNumItems ] = caption;

mCommands[ mNumItems ] = command;

mNumItems = mNumItems + 1;

mWidth = _max( mWidth, _text_width( caption, 0, 0, 0 ) + 8 );

</script>

<eval>mNumItems - 1</eval>

</return>

</function>

</parameters>

<index>

</index>

</set>

<index>

</index>

</set>

</execute>

</function>

</parameters>

mCurItem = id % mNumItems;

mCurItemOffsetY = mCurItem * mItemHeight;

Event.setParam( 0, mCommands[ mCurItem ] );

Event.fireEventNow( &EVENT_HIGHLIGHTING;, mHandler );

if (getVisible())

{

Highlight_show();

}

Event.setParam( 0, mCommands[ mCurItem ] );

Event.fireEvent( &EVENT_HIGHLIGHTED;, mHandler );

</script>

</function>

</parameters>

mX = x + mAttributes[ &MENU_ATTR_BORDER_THICKNESS; ];

mY = y + mAttributes[ &MENU_ATTR_BORDER_THICKNESS; ];

</script>

</function>

</functions>

<label>

<text>

<eval>mCaptions[ mItemIndex ]</eval>

</text>

<fg>

<eval>mAttributes[ &MENU_ATTR_ITEM_FG; ]</eval>

</fg>

</label>

</display>

</template>

</templates>

<!-- catch all unwanted events, especially clicking outside the

boundary of the menu -->

<box>

<width><eval>mScrWidth</eval></width>

<height><eval>mScrHeight</eval></height>

<fg>&_COLOR_TRANSPARENT;</fg>

<bg>&_COLOR_TRANSPARENT;</bg>

<key>RIGHT</key>

</accelerators>

</script>

</event>

</box>

<box>

<x>

<eval>mX - mAttributes[ &MENU_ATTR_BORDER_THICKNESS; ]</eval>

</x>

<y>

<eval>mY - mAttributes[ &MENU_ATTR_BORDER_THICKNESS; ]</eval>

</y>

<width>

<eval>mWidth + 2 * mAttributes[ &MENU_ATTR_BORDER_THICKNESS; ]</eval>

</width>

<eval>(mItemHeight * mNumItems) + 2 * mAttributes[ &MENU_ATTR_BORDER_THICKNESS; ]</eval>

</height>

<fg>

<eval>mAttributes[ &MENU_ATTR_BORDER; ]</eval>

</fg>

<bg>

<eval>mAttributes[ &MENU_ATTR_BG; ]</eval>

</bg>

<box>

<x>

<eval>mAttributes[ &MENU_ATTR_BORDER_THICKNESS; ]</eval>

</x>

<y>

<eval>mAttributes[ &MENU_ATTR_BORDER_THICKNESS; ]</eval>

</y>

<width>

<eval>mWidth</eval>

</width>

<eval>(mItemHeight * mNumItems)</eval>

</height>

<fg>

<eval>mAttributes[ &MENU_ATTR_ITEM_BG; ]</eval>

</fg>

<bg>

<eval>mAttributes[ &MENU_ATTR_ITEM_BG; ]</eval>

</bg>

</box>

</display>

</transition>

</state>

<box>

<x>

</x>

<y>

<eval>mY + _state_index() * mItemHeight</eval>

</y>

<width>

<eval>mWidth</eval>

</width>

<eval>mItemHeight</eval>

</height>

<fg>&_COLOR_TRANSPARENT;</fg>

<bg>

<eval>mAttributes[ &MENU_ATTR_ITEM_BG; ]</eval>

</bg>

selectItem( _state_index() );

</script>

</event>

</box>

</display>

</transition>

</state>

<box>

<x>

</x>

<y>

<eval>mY + mCurItemOffsetY</eval>

</y>

<width>

<eval>mWidth</eval>

</width>

<eval>mItemHeight</eval>

</height>

<fg>

<eval>mAttributes[ &MENU_ATTR_HIGHLIGHT_BG; ]</eval>

</fg>

<bg>

<eval>mAttributes[ &MENU_ATTR_HIGHLIGHT_BG; ]</eval>

</bg>

</accelerators>

<eval>selectItem( mCurItem )</eval>

</execute>

</event>

<label>

<text>

<eval>mCaptions[ mCurItem ]</eval>

</text>

<fg>

<eval>mAttributes[ &MENU_ATTR_HIGHLIGHT_FG; ]</eval>

</fg>

</label>

</box>

<box>

</accelerators>

<eval>Highlight_move( 1 )</eval>

</execute>

</event>

</box>

<box>

</accelerators>

<eval>Highlight_move( 0 - 1 )</eval>

</execute>

</event>

</box>

<box>

<key>

<eval>mCurItem + 1</eval>

</key>

</accelerators>

<eval>selectItem( mCurItem )</eval>

</execute>

</event>

</box>

</display>

</transition>

<box>

<x>

</x>

<y>

<eval>mY + mCurItemOffsetY</eval>

</y>

<width>

<eval>mWidth</eval>

</width>

<eval>mItemHeight</eval>

</height>

<fg>

<eval>mAttributes[ &MENU_ATTR_SELECTED_BG; ]</eval>

</fg>

<bg>

<eval>mAttributes[ &MENU_ATTR_SELECTED_BG; ]</eval>

</bg>

<label>

<text>

<eval>mCaptions[ mCurItem ]</eval>

</text>

<fg>

<eval>mAttributes[ &MENU_ATTR_SELECTED_FG; ]</eval>

</fg>

</label>

</box>

</display>

Event.setParam( 0, mCommands[ mCurItem ] );

Event.fireEvent( &EVENT_SELECTED;, mHandler );

</script>

</transition>

</state>

</states>

</state-machine>

</state-machines>

</partition>

</ujml>

File: menu.ujml

Now, let’s incorporate the menu into Ujinn.

<?xml version="1.0" encoding="UTF-8"?>

<!DOCTYPE ujml PUBLIC "-//UIEVOLUTION//DTD UJML 1.4//EN" "ujml.dtd" [

<!ENTITY % include SYSTEM "ujlib/include.ujmc">

%include;

<!ENTITY SCORE_ITEM_FG "&_COLOR_WHITE;">

<!ENTITY SCORE_ITEM_BG "0xff000066">

<!ENTITY MAX_ROWS "8">

<!ENTITY MAX_COLS "8">

<!ENTITY MAX_COLORS "16">

<!ENTITY CLEARING_COLOR "&_COLOR_WHITE;">

<!ENTITY CLEARED_COLOR "&_COLOR_TRANSPARENT;">

<!ENTITY POPUP_HIDDEN "-1">

<!ENTITY POPUP_NULL "0">

<!ENTITY POPUP_MAIN_MENU "1">

<!ENTITY POPUP_MESSAGE "4">

<!ENTITY MENU_NEW "Next Level">

<!ENTITY MENU_RESTART "Replay Level">

<!ENTITY MENU_DONE "Done">

<!ENTITY ON_START "1">

<!ENTITY ON_NEXT_LEVEL "2">

<!ENTITY ON_GOTO_MENU "3">

<!ENTITY ON_NULL "4">

<!ENTITY ON_RESTART "5">

<ujml>

<state-machines>

</state-machines>

<state-variables>

<state-var name="sFnKeys" type="boolean"/>

<state-var name="sBoxes" type="boolean" size="&MAX_ROWS;,&MAX_COLS;"/>

<state-var name="sCursor" type="boolean"/>

<state-var name="sPopup" type="int"/>

<state-var name="sScores" type="boolean"/>

<state-var name="sDelayedUpdateScores" type="boolean"/>

<state-var name="sDelayedRemoveBoxes" type="boolean"/>

<state-var name="sDelayedSelectBox" type="boolean"/>

<state-var name="sRemoveColumns" type="boolean"/>

<state-var name="sStart" type="boolean"/>

<state-var name="sRestart" type="boolean"/>

<state-var name="sGameOver" type="boolean"/>

<state-var name="sDelayedEndGameCheck" type="boolean"/>

</state-variables>

</variables>

</variables>

temp = sPopup;

sPopup = &POPUP_HIDDEN;;

sPopup = temp;

</script>

</function>

…

</functions>

…

</templates>

…

</script>

…

</display>

<fn>

<text>Options</text>

<key>POUND</key>

</accelerators>

</variables>

temp = sPopup;

sPopup = &POPUP_HIDDEN;;

if (temp == &POPUP_MAIN_MENU;)

{

sPopup = &POPUP_NULL;;

}

else if (temp == &POPUP_NULL;)

{

sPopup = &POPUP_MAIN_MENU;;

}

else

{

start();

}

</script>

</event>

</fn>

</display>

</transition>

</state>

…

Menu.setVisible( false );

</script>

</transition>

Menu.initialize( "menu" );

Menu.add( "&MENU_NEW;", &ON_NEXT_LEVEL; );

Menu.add( "&MENU_RESTART;", &ON_RESTART; );

Menu.add( "&MENU_DONE;", &ON_NULL; );

Menu.center();

Menu.setVisible( true );

</script>

</transition>

<box>

<x>

</x>

<y>

</y>

<width>

<eval>mScrWidth - 4</eval>

</width>

<eval>mScrHeight - 4</eval>

</height>

<bg>&_COLOR_DARKGRAY;</bg>

<multi-label>

<text>

</text>

<width>

<eval>mScrWidth - 8</eval>

</width>

<eval>_max( mScrHeight - (mTextHeight * 2) - 4, mTextHeight * 2 )</eval>

</height>

<fg>&_COLOR_WHITE;</fg>

<bg>&_COLOR_DARKGRAY;</bg>

</multi-label>

</box>

</display>

Menu.initialize( "menu" );

Menu.add( "&MENU_RESTART;", &ON_RESTART; );

Menu.add( "&MENU_NEW;", &ON_NEXT_LEVEL; );

Menu.center();

Menu.setVisible( true );

</script>

</transition>

</state>

<state var="Event.sEvent" index="&EVENT_SELECTED;">

<transition value="menu">

<variables>

<var name="command" type="int"/>

</variables>

<script>

Menu.setVisible( false );

command = Event.getParam( 0 );

if (command == &ON_GOTO_MENU;)

{

sPopup = &POPUP_MAIN_MENU;;

}

else if (command == &ON_START;)

{

start();

}

else if (command == &ON_RESTART;)

{

restart();

}

else if (command == &ON_NEXT_LEVEL;)

{

mScore = 0;

mHighScore = 0;

mLevelNumber = mLevelNumber + 1;

start();

}

else if (command == &ON_NULL;)

{

sPopup = &POPUP_NULL;;

}

</script>

</transition>

</state>

…

</variables>

if (mTotalBoxesCleared == mNumBoxes)

{

mScore = mScore + (mScore / 4);

mMessage = _strcat( "Level cleared!

Bonus: ", _strcat( mScore / 4, "." ) );

sPopup = &POPUP_MESSAGE;;

if (mScore > mHighScore)

{

mHighScore = mScore;

}

fGameOver = true;

}

else

{

if (!areBoxesRemovable())

{

mScore = mScore - (mNumBoxes - mTotalBoxesCleared);

mMessage = _strcat( "No moves.

Penalty: ", _strcat( mNumBoxes - mTotalBoxesCleared, "." ) );

sPopup = &POPUP_MESSAGE;;

if (mScore > mHighScore)

{

mHighScore = mScore;

}

fGameOver = true;

}

updateScores();

sCursor = false;

sCursor = true;

sDelayedEndGameCheck = false;

sGameOver = fGameOver;

</script>

</transition>

</state>

…

</states>

<!—menu goes on top of z-order à

<state-machines>

</state-machines>

</application>

</ujml>

File: ujinn7.ujml

Busy Cursor

On slow devices, the screen repaint at the start of a level can take a while so we’ll add a busy cursor to be displayed when the application is likely to take a few seconds to perform a task.

Since the busy cursor will likely be used in other applications, we’ll implement it as a reusable <state-machine>.

<?xml version="1.0" encoding="UTF-8"?>

<!DOCTYPE ujml PUBLIC "-//UIEVOLUTION//DTD UJML 1.4//EN" "../ujml.dtd" [

<!ENTITY % include SYSTEM "include.ujmc">

%include;

<!ENTITY BUSY_FACE "0xff0000ff">

<!ENTITY BUSY_HANDS "0xff00ffff">

<!ENTITY BUSY_BG "0xfff000066">

<!ENTITY BUSY_BORDER "2">

<!ENTITY BUSY_HAND_THICKNESS "4">

<!ENTITY BUSY_ANIMATE_FRAME_CNT "4">

<ujml>

<state-machines>

<state-machine name="Busy" access="export">

<state-variables>

<state-var name="sAnimate" type="boolean"/>

<state-var name="sAnimateTick" type="boolean"/>

</state-variables>

</variables>

</parameters>

<eval>(mScrWidth - _text_width( text, 0, 0, 0 )) / 2</eval>

</return>

</function>

mScrWidth = _getIntProperty( &_PROPERTY_INT_SCREEN_WIDTH; );

mScrHeight = _getIntProperty( &_PROPERTY_INT_SCREEN_HEIGHT; );

mTextHeight = _text_height( 0, 0, 0 );

mSize = _max( _min( mScrWidth, mScrHeight ) / &BUSY_HAND_THICKNESS;, 40 );

mX = (mScrWidth - mSize) / 2;

mY = (mScrHeight - mSize) / 2;

mLittleHandX[ 0 ] = mX + mSize / 2 - &BUSY_HAND_THICKNESS; / 2;

mLittleHandY[ 0 ] = mY + mSize / 2;

mLittleHandWidth[ 0 ] = mSize / 2 - &BUSY_HAND_THICKNESS; * 2;

mLittleHandHeight[ 0 ] = &BUSY_HAND_THICKNESS;;

mBigHandX[ 0 ] = mX + mSize / 2 - &BUSY_HAND_THICKNESS; / 2;

mBigHandY[ 0 ] = mY + &BUSY_HAND_THICKNESS;;

mBigHandWidth[ 0 ] = &BUSY_HAND_THICKNESS;;

mBigHandHeight[ 0 ] = mSize / 2;

mLittleHandX[ 1 ] = mX + mSize / 2 - &BUSY_HAND_THICKNESS; / 2;

mLittleHandY[ 1 ] = mY + mSize / 2;

mLittleHandWidth[ 1 ] = mSize / 2 - &BUSY_HAND_THICKNESS; * 2;

mLittleHandHeight[ 1 ] = &BUSY_HAND_THICKNESS;;

mBigHandX[ 1 ] = mX + mSize / 2 - &BUSY_HAND_THICKNESS; / 2;

mBigHandY[ 1 ] = mY + mSize / 2;

mBigHandWidth[ 1 ] = mSize / 2 - &BUSY_HAND_THICKNESS;;

mBigHandHeight[ 1 ] = &BUSY_HAND_THICKNESS;;

mLittleHandX[ 2 ] = mX + mSize / 2 - &BUSY_HAND_THICKNESS; / 2;

mLittleHandY[ 2 ] = mY + mSize / 2;

mLittleHandWidth[ 2 ] = mSize / 2 - &BUSY_HAND_THICKNESS; * 2;

mLittleHandHeight[ 2 ] = &BUSY_HAND_THICKNESS;;

mBigHandX[ 2 ] = mX + mSize / 2 - &BUSY_HAND_THICKNESS; / 2;

mBigHandY[ 2 ] = mY + mSize / 2;

mBigHandWidth[ 2 ] = &BUSY_HAND_THICKNESS;;

mBigHandHeight[ 2 ] = mSize / 2 - &BUSY_HAND_THICKNESS;;

mLittleHandX[ 3 ] = mX + mSize / 2 - &BUSY_HAND_THICKNESS; / 2;

mLittleHandY[ 3 ] = mY + mSize / 2;

mLittleHandWidth[ 3 ] = mSize / 2 - &BUSY_HAND_THICKNESS; * 2;

mLittleHandHeight[ 3 ] = &BUSY_HAND_THICKNESS;;

mBigHandX[ 3 ] = mX + &BUSY_HAND_THICKNESS;;

mBigHandY[ 3 ] = mY + mSize / 2;

mBigHandWidth[ 3 ] = mSize / 2 - &BUSY_HAND_THICKNESS;;

mBigHandHeight[ 3 ] = &BUSY_HAND_THICKNESS;;

</script>

</function>

mAnimateFrame = 0;

sAnimate = true;

</script>

</function>

sAnimate = false;

</script>

</function>

</functions>

<box>

<x>

<eval>mX - &BUSY_BORDER;</eval>

</x>

<y>

<eval>mY - &BUSY_BORDER;</eval>

</y>

<width>

<eval>mSize + &BUSY_BORDER; * 2</eval>

</width>

<eval>mSize + &BUSY_BORDER; * 2</eval>

</height>

<oval>

<x>

<eval>&BUSY_BORDER;</eval>

</x>

<y>

<eval>&BUSY_BORDER;</eval>

</y>

<width>

<eval>mSize</eval>

</width>

<eval>mSize</eval>

</height>

</oval>

</box>

</display>

sAnimateTick = true;

</script>

</transition>

sAnimateTick = false;

</script>

</transition>

</state>

<box>

<x>

<eval>mLittleHandX[ mAnimateFrame ]</eval>

</x>

<y>

<eval>mLittleHandY[ mAnimateFrame ]</eval>

</y>

<width>

<eval>mLittleHandWidth[ mAnimateFrame ]</eval>

</width>

<eval>mLittleHandHeight[ mAnimateFrame ]</eval>

</height>

<fg>&BUSY_HANDS;</fg>

<bg>&BUSY_HANDS;</bg>

</box>

<box>

<x>

<eval>mBigHandX[ mAnimateFrame ]</eval>

</x>

<y>

<eval>mBigHandY[ mAnimateFrame ]</eval>

</y>

<width>

<eval>mBigHandWidth[ mAnimateFrame ]</eval>

</width>

<eval>mBigHandHeight[ mAnimateFrame ]</eval>

</height>

<fg>&BUSY_HANDS;</fg>

<bg>&BUSY_HANDS;</bg>

</box>

</display>

mAnimateFrame = (mAnimateFrame + 1) % &BUSY_ANIMATE_FRAME_CNT;;

_clear_state( sAnimateTick );

sAnimateTick = sAnimate;

</script>

</transition>

</state>

</states>

</state-machine>

</state-machines>

</partition>

</ujml>

File: busy.ujml

Below, we incorporate the busy cursor into Ujinn. Note that since there is already some animation happening on the screen, we will not use the animation effect of the busy cursor.

<?xml version="1.0" encoding="UTF-8"?>

<!DOCTYPE ujml PUBLIC "-//UIEVOLUTION//DTD UJML 1.4//EN" "ujml.dtd" [

<!ENTITY % include SYSTEM "ujlib/include.ujmc">

%include;

...

<!ENTITY POPUP_BUSY "5">

...

<ujml>

<state-machines>

...

</state-machines>

<state-variables>

...

</state-variables>

...

</variables>

...

sPopup = &POPUP_BUSY;;

gSeed = _srand( mLevelNumber * 101 );

gCol = 0;

gRow = 0;

sStart = true;

</script>

</function>

sPopup = &POPUP_BUSY;;

gCol = 0;

gRow = 0;

sRestart = true;

</script>

</function>

...

</functions>

...

</templates>

...

Busy.initialize();

start();

</script>

...

</display>

...

Busy.hide();

Menu.setVisible( false );

</script>

</transition>

<transition value="&POPUP_BUSY;">

<script>

Busy.show();

sFnKeys = false;

sCursor = false;

Menu.setVisible( false );

</script>

</transition>

...

</state>

...

</states>

<state-machines>

<include file="ujlib/busy.ujml" state-machine="Busy"/>

</state-machines>

</application>

</ujml>

File: ujinn8.ujml

Resuming a Game

As a general rule, an application should save its state. If a user exits the application and later returns to the application, it can appear in the same state as when the user exited. This also applies when the device is turned off, or closed in the case of flip phones; many flip phones terminate the application when they are closed.

In Ujinn, the game state is saved using a property bag. When the game is resumed, it uses the property bag to reinitialize internal variables so that it returns to the same state as when it was exited.

<?xml version="1.0" encoding="UTF-8"?>

<!DOCTYPE ujml PUBLIC "-//UIEVOLUTION//DTD UJML 1.4//EN" "ujml.dtd" [

...

<!ENTITY PROP_BAG_NAME "Ujinn.Properties">

<!ENTITY PROP_VERSION "1">

<!ENTITY PROP_VERSION_MINOR "0">

<!ENTITY PROP_STATUS_SAVED "10">

<!ENTITY PROP_STATUS_NOT_SAVED "11">

<!ENTITY PROP_KEY_VERSION "0">

<!ENTITY PROP_KEY_STATUS "1">

<!ENTITY PROP_KEY_VERSION_MINOR "2">

<!ENTITY PROP_KEY_mNumRows "3">

<!ENTITY PROP_KEY_mNumCols "4">

<!ENTITY PROP_KEY_mNumColors "5">

<!ENTITY PROP_KEY_mScore "6">

<!ENTITY PROP_KEY_mHighScore "7">

<!ENTITY PROP_KEY_mTotalBoxesCleared "8">

<!ENTITY PROP_KEY_mLevelNumber "10">

<!ENTITY PROP_KEY_mCursorCol "11">

<!ENTITY PROP_KEY_mCursorRow "12">

<!ENTITY PROP_KEY_sGameOver "13">

<!ENTITY PROP_KEY_mNumBoxesInColumn "">

<!ENTITY PROP_KEY_mColumnHasRemovableBoxes "">

<!ENTITY PROP_KEY_mSavedColumnHasRemovableBoxes "">

<!ENTITY PROP_KEY_mBoxes "17">

<!ENTITY PROP_KEY_mSavedBoxes "">

<ujml>

<state-machines>

...

</state-machines>

<state-variables>

...

<state-var name="sStartup" type="boolean"/>

<state-var name="sUnload" type="boolean"/>

<state-var name="sResume" type="boolean"/>

<state-var name="sRestart" type="boolean"/>

</state-variables>

...

</variables>

...

</parameters>

</variables>

if (_isSupported( &_X_PROPERTY_BAG; ))

{

rc = _x_loadBag( bag );

}

</script>

</return>

</function>

</variables>

if (loadBag( "&PROP_BAG_NAME;" ))

{

i = _x_getBagInt( "&PROP_BAG_NAME;", &PROP_KEY_VERSION;, -1 );

if (i < 1)

{

_x_setBagInt( "&PROP_BAG_NAME;", &PROP_KEY_VERSION;, &PROP_VERSION; );

_x_setBagInt( "&PROP_BAG_NAME;", &PROP_KEY_VERSION_MINOR;, &PROP_VERSION_MINOR; );

_x_setBagInt( "&PROP_BAG_NAME;", &PROP_KEY_STATUS;, &PROP_STATUS_NOT_SAVED; );

_x_storeBag( "&PROP_BAG_NAME;" );

}

else

{

fSaved = ( _x_getBagInt( "&PROP_BAG_NAME;", &PROP_KEY_STATUS;, -1 ) == &PROP_STATUS_SAVED;);

}

_x_closeBag( "&PROP_BAG_NAME;" );

}

</script>

<eval>fSaved</eval>

</return>

</function>

</variables>

if (loadBag( "&PROP_BAG_NAME;" ))

{

_x_setBagInt( "&PROP_BAG_NAME;", &PROP_KEY_STATUS;, &PROP_STATUS_NOT_SAVED; );

_x_setBagInt( "&PROP_BAG_NAME;", &PROP_KEY_mNumRows;, mNumRows );

_x_setBagInt( "&PROP_BAG_NAME;", &PROP_KEY_mNumCols;, mNumCols );

_x_setBagInt( "&PROP_BAG_NAME;", &PROP_KEY_mNumColors;, mNumColors );

_x_setBagInt( "&PROP_BAG_NAME;", &PROP_KEY_mScore;, mScore );

_x_setBagInt( "&PROP_BAG_NAME;", &PROP_KEY_mHighScore;, mHighScore );

_x_setBagInt( "&PROP_BAG_NAME;", &PROP_KEY_mTotalBoxesCleared;, mTotalBoxesCleared );

_x_setBagInt( "&PROP_BAG_NAME;", &PROP_KEY_mLevelNumber;, mLevelNumber );

_x_setBagInt( "&PROP_BAG_NAME;", &PROP_KEY_mCursorCol;, mCursorCol );

_x_setBagInt( "&PROP_BAG_NAME;", &PROP_KEY_mCursorRow;, mCursorRow );

_x_setBagBoolean( "&PROP_BAG_NAME;", &PROP_KEY_sGameOver;, sGameOver );

i = &PROP_KEY_sGameOver; + 1;

while (col < &MAX_COLS;)

{

_x_setBagInt( "&PROP_BAG_NAME;", i, mNumBoxesInColumn[ col ] );

i = i + 1;

_x_setBagBoolean( "&PROP_BAG_NAME;", i, mColumnHasRemovableBoxes[ col ] );

i = i + 1;

_x_setBagBoolean( "&PROP_BAG_NAME;", i, mSavedColumnHasRemovableBoxes[ col ] );

i = i + 1;

row = 0;

while (row < &MAX_ROWS;)

{

_x_setBagInt( "&PROP_BAG_NAME;", i, mBoxes[ row ][ col ][ 0 ] );

i = i + 1;

_x_setBagInt( "&PROP_BAG_NAME;", i, mBoxes[ row ][ col ][ 1 ] );

i = i + 1;

_x_setBagInt( "&PROP_BAG_NAME;", i, mSavedBoxes[ row ][ col ][ 0 ] );

i = i + 1;

_x_setBagInt( "&PROP_BAG_NAME;", i, mSavedBoxes[ row ][ col ][ 1 ] );

i = i + 1;

row = row + 1;

}

col = col + 1;

}

_x_setBagInt( "&PROP_BAG_NAME;", &PROP_KEY_STATUS;, &PROP_STATUS_SAVED; );

_x_storeBag( "&PROP_BAG_NAME;" );

_x_closeBag( "&PROP_BAG_NAME;" );

}

</script>

</function>

</variables>

if (loadBag( "&PROP_BAG_NAME;" ))

{

mNumRows = _x_getBagInt( "&PROP_BAG_NAME;", &PROP_KEY_mNumRows; );

mNumCols = _x_getBagInt( "&PROP_BAG_NAME;", &PROP_KEY_mNumCols; );

mNumColors = _x_getBagInt( "&PROP_BAG_NAME;", &PROP_KEY_mNumColors; );

mScore = _x_getBagInt( "&PROP_BAG_NAME;", &PROP_KEY_mScore; );

mHighScore = _x_getBagInt( "&PROP_BAG_NAME;", &PROP_KEY_mHighScore; );

mTotalBoxesCleared = _x_getBagInt( "&PROP_BAG_NAME;", &PROP_KEY_mTotalBoxesCleared; );

mLevelNumber = _x_getBagInt( "&PROP_BAG_NAME;", &PROP_KEY_mLevelNumber; );

mCursorCol = _x_getBagInt( "&PROP_BAG_NAME;", &PROP_KEY_mCursorCol; );

mCursorRow = _x_getBagInt( "&PROP_BAG_NAME;", &PROP_KEY_mCursorRow; );

mBoxWidth = mScrWidth / mNumCols;

mBoxHeight = (mScrHeight - mTextHeight) / mNumRows;

mNumBoxes = mNumRows * mNumCols;

gSeed = _srand( mLevelNumber * 101 );

gI = &PROP_KEY_sGameOver; + 1;

gCol = 0;

gRow = 0;

sResume = true;

}

</script>

</function>

</functions>

...

</templates>

...

Busy.initialize();

sPopup = &POPUP_BUSY;;

sStartup = true;

</script>

<box>

<width>

<eval>mScrWidth</eval>

</width>

<eval>mScrHeight</eval>

</height>

<fg>&_COLOR_BLACK;</fg>

<bg>&_COLOR_BLACK;</bg>

</box>

<fn>

</accelerators>

Busy.show();

sUnload = true;

</script>

</event>

</fn>

</display>

if (canResumeGame())

{

resumeGame();

}

else

{

start();

}

</script>

</transition>

</state>

...

</variables>

mNumBoxesInColumn[ gCol ] = _x_getBagInt( "&PROP_BAG_NAME;", gI );

gI = gI + 1;

mColumnHasRemovableBoxes[ gCol ] = _x_getBagBoolean( "&PROP_BAG_NAME;", gI );

gI = gI + 1;

mSavedColumnHasRemovableBoxes[ gCol ] = _x_getBagBoolean( "&PROP_BAG_NAME;", gI );

gI = gI + 1;

row = 0;

while (row < &MAX_ROWS;)

{

mBoxes[ row ][ gCol ][ 0 ] = _x_getBagInt( "&PROP_BAG_NAME;", gI );

gI = gI + 1;

mBoxes[ row ][ gCol ][ 1 ] = _x_getBagInt( "&PROP_BAG_NAME;", gI );

gI = gI + 1;

mSavedBoxes[ row ][ gCol ][ 0 ] = _x_getBagInt( "&PROP_BAG_NAME;", gI );

gI = gI + 1;

mSavedBoxes[ row ][ gCol ][ 1 ] = _x_getBagInt( "&PROP_BAG_NAME;", gI );

gI = gI + 1;

row = row + 1;

}

repaintColumn( gCol );

gCol = gCol + 1;

_clear_state( sResume );

sResume = gCol < &MAX_COLS;;

</script>

</transition>

sGameOver = _x_getBagBoolean( "&PROP_BAG_NAME;", &PROP_KEY_sGameOver; );

_x_closeBag( "&PROP_BAG_NAME;" );

repaint();

if (sGameOver)

{

sResume = false;

if (mTotalBoxesCleared == mNumBoxes)

{

mMessage = _strcat( "Level cleared!

Bonus: ", _strcat( mScore / 4, "." ) );

}

else

{

mMessage = _strcat( "No moves.

Penalty: ", _strcat( mNumBoxes - mTotalBoxesCleared, "." ) );

}

sPopup = &POPUP_MESSAGE;;

}

else

{

sFnKeys = true;

sCursor = true;

sPopup = &POPUP_NULL;;

}

</script>

</transition>

</state>

saveGame();

_unload();

</script>

</transition>

</state>

</states>

<state-machines>

</state-machines>

</application>

</ujml>

File: ujinn9.ujml

Tip: Property bags are not supported on resource-limited platforms that require the minimal Java player (DoJa). So, it is important to use the _isSupported() function to determine if property bags are supported by the platform. If data persistence is required the application can save its data to a server and refetch it when it is resumed.

One way to do this is to use two partitions for data saving and fetching: one uses property bags which allow the application to save and fetch the data quickly, and the other partition uses a server. The application then loads the appropriate data fetching partition depending on whether property bags are supported on the device or not.

Localization

An application can determine a device's locale using the _getStringProperty() function. Below, we move all of Ujinn’s locale-specific data, namely strings, into separate partitions—one for each locale.

<?xml version="1.0" encoding="UTF-8"?>

<!DOCTYPE ujml PUBLIC "-//UIEVOLUTION//DTD UJML 1.4//EN" "ujml.dtd" [

<!ENTITY % include SYSTEM "ujlib/include.ujmc">

%include;

<!ENTITY % ujinn SYSTEM "ujinn.ujmc">

%ujinn;

...

<ujml>

<state-machines>

...

</state-machines>

<state-variables>

...

<state-var name="sLocaleLoaded" type="boolean" access="export"/>

<state-var name="sBg" type="boolean"/>

</state-variables>

...

<var name="mStrings" type="string" size="&LOCALE_MAX_STRINGS;" access="export"/>

</variables>

...

</functions>

...

</templates>

_link( "Locale", _strcat( _substring( _getStringProperty( &_PROPERTY_STRING_LOCALE; ), 0, 2 ), "/Locale.ujbc" ) );

...

Busy.initialize();

sPopup = &POPUP_BUSY;;

</script>

<box>

<width>

<eval>mScrWidth</eval>

</width>

<eval>mScrHeight</eval>

</height>

<fg>&_COLOR_BLACK;</fg>

<bg>&_COLOR_BLACK;</bg>

</box>

</display>

<fn>

<text>

<eval>mStrings[ &LOCALE_STR_BACK; ]</eval>

</text>

</accelerators>

sUnload = true;

</script>

</event>

</fn>

</display>

</transition>

</state>

<state var="sLocaleLoaded">

<transition value="true">

<script>

sBg = true;

sStartup = true;

</script>

</transition>

</state>

...

<fn>

<text>

<eval>mStrings[ &LOCALE_STR_OPTIONS; ]</eval>

</text>

...

</fn>

</display>

</transition>

</state>

...

...

Menu.initialize( "menu" );

Menu.add( mStrings[ &LOCALE_STR_MENU_NEW; ], &ON_NEXT_LEVEL; );

Menu.add( mStrings[ &LOCALE_STR_MENU_RESTART; ], &ON_RESTART; );

Menu.add( mStrings[ &LOCALE_STR_MENU_DONE; ], &ON_NULL; );

Menu.center();

Menu.setVisible( true );

</script>

</transition>

<box>

<x>

</x>

<y>

</y>

<width>

<eval>mScrWidth - 4</eval>

</width>

<eval>mScrHeight - 4</eval>

</height>

<bg>&_COLOR_DARKGRAY;</bg>

<multi-label>

<text>

</text>

<width>

<eval>mScrWidth - 8</eval>

</width>

<eval>_max( mScrHeight - (mTextHeight * 2) - 4, mTextHeight * 2 )</eval>

</height>

<fg>&_COLOR_WHITE;</fg>

<bg>&_COLOR_DARKGRAY;</bg>

</multi-label>

</box>

</display>

Menu.initialize( "menu" );

Menu.add( mStrings[ &LOCALE_STR_MENU_RESTART; ], &ON_RESTART; );

Menu.add( mStrings[ &LOCALE_STR_MENU_NEW; ], &ON_NEXT_LEVEL; );

Menu.center();

Menu.setVisible( true );

</script>

</transition>

</state>

...

</variables>

if (mTotalBoxesCleared == mNumBoxes)

{

mScore = mScore + (mScore / 4);

mMessage = _strcat( mStrings[ &LOCALE_STR_LEVEL_CLEARED; ], mScore / 4 );

sPopup = &POPUP_MESSAGE;;

if (mScore > mHighScore)

{

mHighScore = mScore;

}

fGameOver = true;

}

else

{

if (!areBoxesRemovable())

{

mScore = mScore - (mNumBoxes - mTotalBoxesCleared);

mMessage = _strcat( mStrings[ &LOCALE_STR_NO_MOVES_PENALTY; ], mNumBoxes - mTotalBoxesCleared );

sPopup = &POPUP_MESSAGE;;

if (mScore > mHighScore)

{

mHighScore = mScore;

}

fGameOver = true;

}

updateScores();

sCursor = false;

sCursor = true;

sDelayedEndGameCheck = false;

sGameOver = fGameOver;

</script>

</transition>

</state>

...

...

sGameOver = _x_getBagBoolean( "&PROP_BAG_NAME;", &PROP_KEY_sGameOver; );

_x_closeBag( "&PROP_BAG_NAME;" );

repaint();

if (sGameOver)

{

sResume = false;

if (mTotalBoxesCleared == mNumBoxes)

{

mMessage = _strcat( mStrings[ &LOCALE_STR_LEVEL_CLEARED; ], mScore / 4 );

}

else

{

mMessage = _strcat( mStrings[ &LOCALE_STR_NO_MOVES_PENALTY; ], mNumBoxes - mTotalBoxesCleared );

}

sPopup = &POPUP_MESSAGE;;

}

else

{

sFnKeys = true;

sCursor = true;

sPopup = &POPUP_NULL;;

}

</script>

</transition>

</state>

saveGame();

_unload();

</script>

</transition>

</state>

</states>

<state-machines>

</state-machines>

</application>

</ujml>

File: ujinn10.ujml

Below is the external entity file that defines a constant for each string stored in mStrings. This file is shared by Ujinn and the locale partitions.

<?xml version="1.0" encoding="UTF-8"?>

<!ENTITY LOCALE_STR_MENU_NEW "0">

<!ENTITY LOCALE_STR_MENU_RESTART "1">

<!ENTITY LOCALE_STR_MENU_SETTINGS "2">

<!ENTITY LOCALE_STR_MENU_DONE "3">

<!ENTITY LOCALE_STR_OPTIONS_LEVEL "4">

<!ENTITY LOCALE_STR_OPTIONS_COLS "5">

<!ENTITY LOCALE_STR_OPTIONS_ROWS "6">

<!ENTITY LOCALE_STR_OPTIONS_COLORS "7">

<!ENTITY LOCALE_STR_BACK "8">

<!ENTITY LOCALE_STR_OPTIONS "9">

<!ENTITY LOCALE_STR_NO_MOVES "10">

<!ENTITY LOCALE_STR_LEVEL_CLEARED "11">

<!ENTITY LOCALE_STR_NO_MOVES_PENALTY "12">

<!ENTITY LOCALE_MAX_STRINGS "13">

File: ujinn.ujmc

Below are the English and Japanese locale partitions.

<?xml version="1.0" encoding="UTF-16"?>

<!DOCTYPE ujml PUBLIC "-//UIEVOLUTION//DTD UJML 1.2//EN" "../ujml.dtd" [

<!ENTITY % ujinn SYSTEM "../ujinn.ujmc">

%ujinn;

<ujml>

<state-variables>

<state-var name="sLocaleLoaded" type="boolean" access="import"/>

</state-variables>

</variables>

mStrings[ &LOCALE_STR_MENU_NEW; ] = "Next Level";

mStrings[ &LOCALE_STR_MENU_RESTART; ] = "Replay Level";

mStrings[ &LOCALE_STR_MENU_SETTINGS; ] = "Settings";

mStrings[ &LOCALE_STR_MENU_DONE; ] = "Done";

mStrings[ &LOCALE_STR_OPTIONS_LEVEL; ] = "Level";

mStrings[ &LOCALE_STR_OPTIONS_COLS; ] = "Columns";

mStrings[ &LOCALE_STR_OPTIONS_ROWS; ] = "Rows";

mStrings[ &LOCALE_STR_OPTIONS_COLORS; ] = "Colors";

mStrings[ &LOCALE_STR_BACK; ] = "Back";

mStrings[ &LOCALE_STR_OPTIONS; ] = "Options";

mStrings[ &LOCALE_STR_NO_MOVES; ] = "No moves.";

mStrings[ &LOCALE_STR_LEVEL_CLEARED; ] = "Level cleared! Bonus: ";

mStrings[ &LOCALE_STR_NO_MOVES_PENALTY; ] = "No moves. Penalty: ";

sLocaleLoaded = true;

</script>

</application>

</ujml>

File: en/Locale.ujml

<!DOCTYPE ujml PUBLIC "-//UIEVOLUTION//DTD UJML 1.2//EN" "../ujml.dtd" [

<!ENTITY % ujinn SYSTEM "../ujinn.ujmc">

%ujinn;

<ujml>

<state-variables>

<state-var name="sLocaleLoaded" type="boolean" access="import"/>

</state-variables>

<var name="mStrings" type="string" size="&LOCALE_MAX_STRINGS;"

access="import"/>

</variables>

mStrings[ &LOCALE_STR_MENU_NEW; ] = "次のレベル";

mStrings[ &LOCALE_STR_MENU_RESTART; ] = "リプレイ";

mStrings[ &LOCALE_STR_MENU_SETTINGS; ] = "設定";

mStrings[ &LOCALE_STR_MENU_DONE; ] = "済み";

mStrings[ &LOCALE_STR_OPTIONS_LEVEL; ] = "レベル";

mStrings[ &LOCALE_STR_OPTIONS_COLS; ] = "行";

mStrings[ &LOCALE_STR_OPTIONS_ROWS; ] = "列";

mStrings[ &LOCALE_STR_OPTIONS_COLORS; ] = "色";

mStrings[ &LOCALE_STR_BACK; ] = "戻る";

mStrings[ &LOCALE_STR_OPTIONS; ] = "オプション";

mStrings[ &LOCALE_STR_NO_MOVES; ] = "手詰まり.";

mStrings[ &LOCALE_STR_LEVEL_CLEARED; ] = "レベルクリア！ボーナス: ";

mStrings[ &LOCALE_STR_NO_MOVES_PENALTY; ] = "手詰まり. 減点: ";

sLocaleLoaded = true;

</script>

</application>

</ujml>

File: ja/Locale.ujml

Using the SDK Debugger, you can select a locale to test the application in both English and Japanese. Use the Tools à Select menu to display the appropriate dialog box to change the locale:

Animation

Effective use of animation is important to achieve a rich user experience.

There are two ways to implement animation in UJML: the fixed-timer method and the maximum-frame-rate method. The fixed-timer method is appropriate when a sequence of objects needs to be displayed in a particular order with particular intervals; the maximum-frame-rate method is appropriate when a set of objects needs to be moved as smoothly as possible.

The first example displays a character walking from right to left across the screen using fixed-timer animation. It has two state variables, sBoy and sTick. The integer state variable sBoy has two <display> blocks, one for the value 0, and another for the value 1 which display and respectively at the position specified by the variable mPos. The boolean state variable sTick has a <delay> element which executes the <script> element 250 milliseconds after sTick turns to true. The <script> block calls the function processTick(), which moves the position of the character by changing the variable mPos, alternates the state variable sBoy, and resets the state variable sTick to true until the character reaches the left edge of the screen. As a result, the function processTick() will be called every 250 milliseconds until the character reaches the left edge and animates the character from right to left.

<?xml version="1.0" encoding="UTF-8"?>

<!DOCTYPE ujml PUBLIC "-//UIEVOLUTION//DTD UJML 1.2//EN" "../ujml.dtd" [

<!ENTITY MSEC_FRAME "250">

<!ENTITY BOYW "20">

<!ENTITY BOYH "24">

<!ENTITY SBOY_L0 "0">

<!ENTITY SBOY_L1 "1">

<!ENTITY IMAGE_URL "<image-url>boy</image-url>">

<ujml>

<state-variables>

<state-var name="sTick" type="boolean" />

<state-var name="sBoy" type="int" />

</state-variables>

</variables>

if (mPosX>-&BOYW;) {

mPosX = mPosX-&BOYW;/4;

sBoy = (1-sBoy);

sTick = false;

sTick = true;

}

</script>

</function>

</functions>

mScrWidth = _getIntProperty(&_PROPERTY_INT_SCREEN_WIDTH;);

mScrHeight = _getIntProperty(&_PROPERTY_INT_SCREEN_HEIGHT;);

mPosX = mScrWidth;

sBoy = &SBOY_L0; ;

sTick = true;

</script>

<delay>&MSEC_FRAME;</delay>

</transition>

</state>

<image>

<url>&IMAGE_URL;</url>

<x><eval>mPosX</eval></x>

<y><eval>mScrHeight/2</eval></y>

</image>

</display>

</transition>

<image>

<url>&IMAGE_URL;</url>

<src-y>&BOYH;</src-y>

<x><eval>mPosX</eval></x>

<y><eval>mScrHeight/2</eval></y>

</image>

</display>

</transition>

</state>

</states>

</application>

</ujml>

File: walk.ujml

Here is the result:

The second example turns the first example above into an interactive application, which allows the user to control the character's movement.

In addition to sTick and sBoy, this application has the third state variable sInput, which enables user input. The state variable sInput has a single <display> element for the state value true, which has four dummy <box> elements, which processes direction keys—Up, Down, Left, and Right keys. When one of those direction keys is pressed, the function moveBoy() is called with an appropriate set of parameters. The function moveBoy() changes the state variable sBoy so that the image faces the correct direction, stores the direction in mDX and mDY, then resets the state variable sTick to true to start the animation.

Note that it changes the state variable sInput to false in moveBoy() and keeps it false until the end of the animation cycle. This is important to prevent it from reentering an animation in the middle of animation, which is a very common mistake made by novice programmers.

The state variable sBoy has eight <display> elements instead of two, to display two alternative images for each direction.

The state variable sTick is identical to the previous example, but the function processTick() is slightly different to support four different directions, and stops after it displays two alternative images.

<?xml version="1.0" encoding="UTF-8"?>

<!DOCTYPE ujml PUBLIC "-//UIEVOLUTION//DTD UJML 1.2//EN" "../ujml.dtd" [

<!ENTITY MSEC_FRAME "100">

<!ENTITY BOYW "20">

<!ENTITY BOYH "24">

<!ENTITY SBOY_L0 "0">

<!ENTITY SBOY_L1 "1">

<!ENTITY SBOY_R0 "2">

<!ENTITY SBOY_R1 "3">

<!ENTITY SBOY_U0 "4">

<!ENTITY SBOY_U1 "5">

<!ENTITY SBOY_D0 "6">

<!ENTITY SBOY_D1 "7">

<!ENTITY IMAGE_URL "<image-url>boy</image-url>">

<ujml>

<state-variables>

<state-var name="sTick" type="boolean"/>

<state-var name="sBoy" type="int"/>

<state-var name="sInput" type="boolean"/>

</state-variables>

</variables>

mPosX = mPosX + mDX;

mPosY = mPosY + mDY;

sBoy = (sBoy /2 *2) + 1 - (sBoy % 2);

if (_eq(sBoy % 2,1)) {

sTick = false;

sTick = true;

} else {

sInput = true;

}

</script>

</function>

</parameters>

sBoy = state;

if (fMove) {

mDX = (dx * &BOYW;)/2;

mDY = (dy * &BOYH;)/2;

sInput = false;

sTick = false;

sTick = true;

}

</script>

</function>

</functions>

mScrWidth = _getIntProperty(&_PROPERTY_INT_SCREEN_WIDTH;);

mScrHeight = _getIntProperty(&_PROPERTY_INT_SCREEN_HEIGHT;);

mPosX = (mScrWidth-&BOYW;)/2;

mPosY = (mScrHeight-&BOYH;)/2;

sBoy = &SBOY_L0; ;

sInput = true;

</script>

<delay>&MSEC_FRAME;</delay>

</transition>

</state>

<box>

</accelerators>

moveBoy(-1, 0, &SBOY_L0;, _gt(mPosX-&BOYW;, -1));

</script>

</event>

</box>

<box>

<key>RIGHT</key>

</accelerators>

moveBoy(1, 0, &SBOY_R0;, _lt(mPosX+&BOYW;*2, mScrWidth));

</script>

</event>

</box>

<box>

</accelerators>

moveBoy(0, -1, &SBOY_U0;, _gt(mPosY-&BOYH;, -1));

</script>

</event>

</box>

<box>

</accelerators>

moveBoy(0, 1, &SBOY_D0;, _lt(mPosY+&BOYH;*2, mScrHeight));

</script>

</event>

</box>

</display>

</transition>

</state>

<image>

<url>&IMAGE_URL;</url>

<x><eval>mPosX</eval></x>

<y><eval>mPosY</eval></y>

</image>

</display>

</transition>

<image>

<url>&IMAGE_URL;</url>

<src-y>&BOYH;</src-y>

<x><eval>mPosX</eval></x>

<y><eval>mPosY</eval></y>

</image>

</display>

</transition>

<image>

<url>&IMAGE_URL;</url>

<src-x>&BOYW;</src-x>

<x><eval>mPosX</eval></x>

<y><eval>mPosY</eval></y>

</image>

</display>

</transition>

<image>

<url>&IMAGE_URL;</url>

<src-x>&BOYW;</src-x>

<src-y>&BOYH;</src-y>

<x><eval>mPosX</eval></x>

<y><eval>mPosY</eval></y>

</image>

</display>

</transition>

<image>

<url>&IMAGE_URL;</url>

<src-x><eval>&BOYW;*2</eval></src-x>

<x><eval>mPosX</eval></x>

<y><eval>mPosY</eval></y>

</image>

</display>

</transition>

<image>

<url>&IMAGE_URL;</url>

<src-x><eval>&BOYW;*2</eval></src-x>

<src-y>&BOYH;</src-y>

<x><eval>mPosX</eval></x>

<y><eval>mPosY</eval></y>

</image>

</display>

</transition>

<image>

<url>&IMAGE_URL;</url>

<src-x><eval>&BOYW;*3</eval></src-x>

<x><eval>mPosX</eval></x>

<y><eval>mPosY</eval></y>

</image>

</display>

</transition>

<image>

<url>&IMAGE_URL;</url>

<src-x><eval>&BOYW;*3</eval></src-x>

<src-y>&BOYH;</src-y>

<x><eval>mPosX</eval></x>

<y><eval>mPosY</eval></y>

</image>

</display>

</transition>

</state>

</states>

</application>

</ujml>

File: walk2.ujml

The result looks like this:

The third example demonstrates how to smoothly animate an object (such as an image or text) from one location to another using the maximum-frame-rate animation technique. In this case, we do not use a fixed <delay> timer like the above examples because it is difficult to pick a single frame-rate that generates reasonable results on all devices. If the device cannot handle all the instructions within the specified amount of time, the animation becomes very slow and jerky. On the other hand, choosing a large delay to make it possible to run it on low-end devices degrades animation quality on high-end devices.

In this situation, the maximum-frame-rate method is appropriate. It simply puts a minimum delay (such as 20 milliseconds) between frames, and adjusts the location of the object based on the actual “elapsed” time. Animations implemented with this method automatically move at the maximum possible frame-rate on each target device.

The function processTick() in this example calculates the elapsed time, mElapsedTime, and determines the location of the object, mPos, based on it. For each frame, the state variable sImage will be reset to true, displaying an image at the position specified by the variable mPos.

<?xml version="1.0" encoding="UTF-8"?>

<!DOCTYPE ujml PUBLIC "-//UIEVOLUTION//DTD UJML 1.2//EN" "../ujml.dtd" [

<!ENTITY MSEC_DELAY "20">

<!ENTITY MSEC_TOTAL "2000">

<!ENTITY IMAGEW "118">

<!ENTITY IMAGEH "100">

<ujml>

<state-variables>

<state-var name="sTick" type="boolean" />

<state-var name="sImage" type="boolean" />

</state-variables>

</variables>

</variables>

sTick = false;

mElapsedTime = _msec()-mStartTime;

if (_lt(mElapsedTime, &MSEC_TOTAL;)) {

mPos = mScrHeight-mElapsedTime*(mScrHeight-mOffsetY)/&MSEC_TOTAL;;

sTick = true;

} else {

mPos = mOffsetY;

}

sImage = false;

sImage = true;

</script>

</function>

</functions>

mScrWidth = _getIntProperty(&_PROPERTY_INT_SCREEN_WIDTH;);

mScrHeight = _getIntProperty(&_PROPERTY_INT_SCREEN_HEIGHT;);

mOffsetX = (mScrWidth-&IMAGEW;)/2;

mOffsetY = (mScrHeight-&IMAGEH;)/2;

mStartTime = _msec();

sTick = true;

</script>

<delay>&MSEC_DELAY;</delay>

</transition>

</state>

<image>

<url><image-url>splash</image-url></url>

<x><eval>mOffsetX</eval></x>

<width>&IMAGEW;</width>

<height>&IMAGEH;</height>

</image>

</display>

</transition>

</state>

</states>

</application>

</ujml>

File: splash.ujml

Here is the result:

Animating more than one object using this method is also possible. See the example below. In this case, each display block of the state variable array sImage[] will be redrawn for each processTick() call.

<?xml version="1.0" encoding="UTF-8"?>

<!DOCTYPE ujml PUBLIC "-//UIEVOLUTION//DTD UJML 1.2//EN" "../ujml.dtd" [

<!ENTITY MSEC_DELAY "20">

<!ENTITY MSEC_TOTAL "2000">

<!ENTITY IMAGEW "118">

<!ENTITY IMAGEH "100">

<!ENTITY IMAGEC "10">

<!ENTITY SLICEH "10">

<ujml>

<state-variables>

<state-var name="sTick" type="boolean" />

<state-var name="sImages" type="boolean" size="&IMAGEC;" />

</state-variables>

</variables>

</variables>

sTick = false;

mElapsedTime = _msec()-mStartTime;

if (_lt(mElapsedTime, &MSEC_TOTAL;)) {

mPos = mElapsedTime*(mScrWidth-mOffsetX)/&MSEC_TOTAL;;

sTick = true;

} else {

mPos = mScrWidth-mOffsetX;

}

i=0;

while(_lt(i,&IMAGEC;)) {

sImages[i] = false;

sImages[i] = true;

i = i+1;

}

</script>

</function>

</functions>

mScrWidth = _getIntProperty(&_PROPERTY_INT_SCREEN_WIDTH;);

mScrHeight = _getIntProperty(&_PROPERTY_INT_SCREEN_HEIGHT;);

mOffsetX = (mScrWidth-&IMAGEW;)/2;

mOffsetY = (mScrHeight-&IMAGEH;)/2;

mStartTime = _msec();

sTick = true;

</script>

<delay>&MSEC_DELAY;</delay>

</transition>

</state>

<image>

<url><image-url>splash</image-url></url>

<src-y><eval>_state_index(0)*&SLICEH;</eval></src-y>

<x><eval>mOffsetX+(mScrWidth-mOffsetX-mPos)*((_state_index(0)%2)*2-1)</eval></x>

<y><eval>mOffsetY+_state_index(0)*&SLICEH;</eval></y>

<width>&IMAGEW;</width>

<height>&SLICEH;</height>

</image>

</display>

</transition>

</state>

</states>

</application>

</ujml>

File: splash2.ujml

Reusable Components

A UJML program isn’t really a single state machine; it is an environment where multiple dependent state machines can function and interact. In many cases, the program has several sets of related state variables, variables, functions, and templates where each set implements a higher level state machine, for example, a button. The <state-machine> element defines an encapsulation of these related elements so that it is easier to develop and reuse them as a unit.

A <state-machine> is more like a service API than an object-oriented class. A <state-machine> cannot be instantiated like a class. Once it is included (using <include> or linked (using _link()) into an application, it becomes an encapsulated service API to the application. While it is possible to include or link a <state-machine> multiple times in an application, simultaneously, each instance is a complete copy of all the byte code and memory needed by the UIE Player to execute the <state-machine>. Unlike an object-oriented class where each instance shares the code that implements the class initializers and member functions, state machines do not share such resources; they are more like a macro expansion or a linked library.

This does not preclude a <state-machine> from sharing member functions by managing its own notion of an instance. As with other non-object-oriented APIs, a <state-machine> can expose the notion of a handle which it uses internally to keep track of an instance. With this model, each member function takes at least one parameter for the instance handle.

A RecordSet service might have member functions that look like this:

· handle ß RecordSet.Open(name)

· RecordSet.Seek(handle, offset)

· RecordSet.Read(handle)

· RecordSet.Close(handle)

<state-machine>

This element defines a UJML state machine.

Syntax:

<state-machine name=”{string}” [access=”import | export”]/>

[<state-machines>…</state-machines>]

[<state-variables>…</state-variables>]

[<variables>…</variables>]

[<functions>…</functions>]

[<templates>…</templates>]

[<states>]…[</states>]

[<state-machines>…</state-machines>]

</state-machine>

All variables, functions, and templates are, by default, private to the state-machine. This allows a state machine to be fully encapsulated. However, they can be declared public using the attribute visibility="public". The attribute values public and private are new attribute values that are valid only in the context of a <state-machine>.

If access=export is specified for the state machine, then all public members are exported. If access=import is specified, then only public members may be declared in the state machine and a parent or ancestor partition must export the state machine.

The only way that an application can access or directly affect the state of a state machine is by calling the state machine's public members. The syntax for calling state machine functions is:

{state-machine-name}.{function-name}([function-arguments]])

{state-machine-name}.{member-name} = value

Examples:

slides.init();

slides.show( 0 );

grid.repaint()

grid.mVariable = 33;

If a state machine needs to be initialized, it must define a public function that can be called by the application to initialize it. For example, myStateMachine.init().

A state-machine's z-order is defined by its location in the <application> or <paritition>; bottom to top.

Examples:

“Slide Viewer” Example:

<ujml>

<state-machines>

<state-machine name=”slides”/>

<state-variables>

<state-var name=”self” type=”int”/>

</state-variables>

</variables>

<function name=”showPage” type=”void”

visiblity =”public”>

</parameters>

field1 = fld1;

field2 = fld2;

self = pg;

</script>

</function>

</functions>

…

</display>

…

</script>

</transition>

…

</display>

…

</script>

</transition>

</state>

</states>

</state-machine>

Ignoring the private/public functions feature, the equivalent of the above state machine written in “standard” UJML is as follows:

<ujml>

<state-variables>

<state-var name=”slides” type=”int”/>

</state-variables>

</variables>

</parameters>

field1 = fld1;

field2 = fld2;

slides = pg;

</script>

</function>

</functions>

</transition>

</transition>

</state>

</ states>

Grid example:

<state-machine name=”grid”>

<state-variables>

<state-var name=”self” type=”int” size=”10,10”>

</state-variables>

…

</parameters>

…

self[ x ][ y ] = 0;

</script>

</function>

</functions>

…

…

</script>

To use either one of the above:

slides.showPage( 0, “fred flintstone”, 31 );

grid.show( 0, 10, … );

<include>

Allows a state machine defined in one UJML file to be included in another UJML file, for example, including file A within file B.. The contents of the state machine definition text from file A replace the <include> tag in the file that contains the <include>.

Examples:

File (slides.ujml)

<ujml>

<state-machines>

<state-machine name=”slides” >

…

</state-machine>

</state-machines>

…

</partition>

</ujml>

File including above file:

<ujml>

<state-machines>

</state-machines>

…

slides.showPage( 0, “fred flintstone”, 31 );

…

</partition>

</ujml>

The above example includes the slides state machine into the application; the example below imports it instead, which allows the slides state machine to be in its own partition and available for reuse by other partitions.

File slidesinc.ujml:

<ujml>

<state-machines>

<state-machine name=”slides” access=”import”/>

<functions name=”showPage” type=”void”

visibility=”public”>

</parameters>

</function>

</functions>

</state-machine>

</state-machines>

< partition >

</ujml>

The application file:

<ujml>

<state-machines>

</state-machines>

…

slides.showPage( 0, “fred flintstone”, 31 );

…

</partition>

</ujml>

It is assumed that a parent partition linked “slides.ujbc”, which then linked the above partition.

Examples

Most of the following examples can be found in the ujml/ujlib folder.

If you want to link them (using the _link() function) into your applications, use ujml/ujlib/include.ujml in your <include> elements; <include file=”ujlib/include.ujml” state-machine=”Busy”/>.

If you want to include them directly, use each example’s source file; for example, to include the Busy state machine: <include file=”ujlib/busy.ujml” state-machine=”Busy”/>.

Example usage for these state machines can be found in the applications in ujml/samples folder.

Busy

<state-machine name="Busy" access="import">

</functions>

</state-machine>

Button

<state-machine name="Button" access="import">

</parameters>

</function>

</parameters>

</function>

</parameters>

</function>

</parameters>

</function>

</parameters>

</function>

</parameters>

</function>

</parameters>

</function>

</parameters>

</function>

</parameters>

</function>

</functions>

</state-machine>

Edit

<state-machine name="Edit" access="import">

</function>

</parameters>

</function>

</parameters>

</function>

</parameters>

</function>

</parameters>

</function>

</parameters>

</function>

</parameters>

</function>

</parameters>

</function>

</parameters>

</function>

</functions>

</state-machine>

Event

<state-machine name="Event" access="import">

<state-variables>

<state-var name="sEvent" type="string"

size="&EVENT_MAX_EVENTS;" visibility="public"/>

</state-variables>

</parameters>

</function>

</parameters>

</function>

</parameters>

</function>

</parameters>

</function>

</functions>

</state-machine>

Focus

<state-machine name="Focus" access="import">

</parameters>

</function>

</parameters>

</function>

</parameters>

</function>

</function>

</function>

</parameters>

</function>

</functions>

</state-machine>

FunctionKey

<state-machine name="FunctionKey" access="import">

</parameters>

</function>

</parameters>

</function>

</parameters>

</function>

</parameters>

</function>

</functions>

</state-machine>

Image

<state-machine name="Image" access="import">

</function>

</function>

</parameters>

</function>

</parameters>

</function>

</parameters>

</function>

</parameters>

</function>

</parameters>

</function>

</parameters>

</function>

</parameters>

</function>

</parameters>

</function>

</parameters>

</function>

</parameters>

</function>

</functions>

</state-machine>

Label

<state-machine name="Label" access="import">

</function>

</parameters>

</function>

</parameters>

</function>

</parameters>

</function>

</parameters>

</function>

</parameters>

</function>

</parameters>

</function>

</parameters>

</function>

</parameters>

</function>

</functions>

</state-machine>

Linker

<state-machine name="Linker" access="import">

</variables>

</parameters>

</function>

</parameters>

</function>

</functions>

</state-machine>

RecordSet

<state-machine name="RecordSet" access="import">

<state-variables>

<state-var name="sData"

type="int"

size="&MAX_OPEN_RECORDSETS;"

visibility="public"/>

</state-variables>

<var name="mFields" type="string"

size="&MAX_OPEN_RECORDSETS;,&MAX_FIELDS_PER_RECORD;"

visibility="public"/>

<var name="mNumRecs"

type="int"

size="&MAX_OPEN_RECORDSETS;"

visibility="public"/>

</variables>

</parameters>

</function>

</parameters>

</function>

</parameters>

</function>

</parameters>

</function>

</parameters>

</function>

</parameters>

</function>

</parameters>

</function>

</parameters>

</function>

</parameters>

</function>

</functions>

</state-machine>

ScrollBar

<state-machine name="ScrollBar">

</parameters>

</function>

</parameters>

</function>

</parameters>

</function>

</parameters>

</function>

</functions>

</state-machine>

Stack

<state-machine name="StringStack" access="import">

</parameters>

</function>

</functions>

</state-machine>

<state-machine name="IntStack" access="import">

</parameters>

</function>

</functions>

</state-machine>

TextBox

<state-machine name="TextBox" access="import">

</parameters>

</function>

</functions>

</state-machine>

List

<state-machine name="List" access="import">

</parameters>

</function>

</parameters>

</function>

</parameters>

</function>

</functions>

</state-machine>

Message Box

In this chapter, we will learn how to use the partition mechanism of UJML as a way to develop a reusable message box component. A partition is equivalent to a class in C++ or Java, but there is a significant difference: partitions are always explicitly loaded and unloaded, instead of implicitly linked like C++ or Java classes. This “explicit linking” makes it possible to run UJML applications under very restricted memory environments. The trade-off is that developers must pay attention to the “lifetime” of partitions and make sure that unnecessary partitions don’t' use precious system resources.

As an example, we have created a message box partition, which displays a specified message and a set of specified buttons and lets the user select one of them.

Interface

Just like any other programming language, each reusable component has a well-defined interface. In the case of a UJML partition, its interface consists of imported variables and imported functions. See the definition of the interface of message box below.

</variables>

</parameters>

</function>

</functions>

In this example, the partition will import the message text (mMessage), the number of buttons (mItemCount), and the label of each button (mLabel[]) as variables, and the “on select” notification callback as a function.

Notice that there is no “displayMessageBox” API. This is because a typical UJML application is a single-purpose module and almost always has a default execution block and a default display block, which will be implicitly executed and displayed. In this case, the default execution initializes local variables, and the default display block displays the message box.

Parent Application

First, examine the source code of a sample UJML application that uses this message box partition.

<?xml version="1.0" encoding="UTF-8"?>

<!DOCTYPE ujml PUBLIC "-//UIEVOLUTION//DTD UJML 1.2//EN" "../ujml.dtd" [

<!ENTITY ITEM_MAX "6">

<ujml>

<state-variables>

<state-var name="sHideMessageBox" type="boolean"/>

</state-variables>

</variables>

</parameters>

<!-- Hide the message box after a delay

(so that the user can see the "selected" state) -->

sHideMessageBox = true;

</script>

</function>

</functions>

mMessage = "Please select Yes or No and click the FIRE button.";

mLabel[0] = "Yes";

mLabel[1] = "No";

mItemCount = 2;

_link("MessageBox", "messagebox.ujbc");

</script>

<eval>_unlink("MessageBox")</eval>

</execute>

</transition>

</state>

</states>

</application>

</ujml>

Look at the top-level <script> block and notice that it initializes a set of variables (which are all marked “export”), and call a system function _link(), loading the message box partition. This is the essence of the code you need to write when using this message box partition. The system call _link() will load the specified partition in memory and execute its default execution block.

When the user selects one of the buttons (in this case, “yes” or “no”), the partition notifies the parent of the selection by calling the onSelect function with the index to the button (in this case, “0” or “1”).

The application can then use this information in deciding whether to unload the partition because it is no longer necessary. [RA2] In this example, the parent application unloads it asynchronously (with a 0.25 second delay) by setting a state variable “sHideMessageBox” (instead of the partition notifies after a certain delay and let the parent call the _unlink() function immediately) so that the parent can immediately start some operation (such as loading another partition) while the user sees the result of the selection (highlighted button).

Next, let’s see the source code of the “message box” partition.

Message Box Partition

First, let’s see the portion related to the default execution block and default display block.

</variables>

…

mCellHeight = &TEXTH; + &GAP; * 2;

mOffsetX = (&SCREENW;-&CELLW;) / 2;

mOffsetY = (&SCREENH;-mCellHeight * mItemCount) / 2

+&TEXTH;*2 + &GAP;*2;

mFocus = 0;

setItemState(0,&STATE_FOCUS;);

mCur = 0;

while(_lt(mCur+1, mItemCount)) {

setItemState(mCur+1,&STATE_NORMAL;);

}

sFocus = true;

</script>

<box>

<width>

<eval>&SCREENW;</eval>

</width>

<eval>&SCREENH;</eval>

</height>

<fg>&_COLOR_TRANSPARENT;</fg>

<bg>&COLOR_BACKGROUND;</bg>

</box>

<box>

<width><eval>&SCREENW;-&GAP;*2</eval></width>

<height><eval>&TEXTH;*4+&GAP;*2+&GAP;*2</eval></height>

<fg>&_COLOR_TRANSPARENT;</fg>

<bg>&COLOR_BUTTONB;</bg>

<multi-label>

<text><eval>mMessage</eval></text>

<width><eval>&SCREENW;-&GAP;*4</eval></width>

<height><eval>&TEXTH;*4</eval></height>

</multi-label>

</box>

</display>

The default execution block (see the <script> block) initializes three variables, mCellHeight, mOffsetX and mOffsetY based on the size of default font and the screen size. These variables will be used when the partition lays out the display elements appropriately for the device (instead of giving a fixed screen coordinate). Ignore the rest of the execution block (gray text) for now.

The default display block (see the <display> block), paints the background (the first <box> block), draws the box surrounding the message (the second <box> block), and the message itself (the <multi-label> block). Notice that some parameters are calculated dynamically, which is necessary to lay these elements out appropriately.

If the default display block is the only block displayable, the user will see a screen like this:

Now, let’s look at the section we have ignored (grayed text) along with some related code.

<state-variables>

<state-var name="sFocus" type="boolean"/>

<state-var name="sItems" type="int" size="&ITEM_MAX;" />

</state-variables>

…

</variables>

…

…

</parameters>

mCur = i;

sItems[i] = s;

</script>

</function>

…

</functions>

…

mFocus = 0;

setItemState(0,&STATE_FOCUS;);

while(_lt(mCur+1, mItemCount)) {

setItemState(mCur+1,&STATE_NORMAL;);

}

sFocus = true;

</script>

First, it initializes mFocus with a value of 0, which indicates the index of the selected item. This means that this message box always sets the focus on the first button (if you need to specify it from the parent, turn it into an imported variable and initialize it in the parent). Then, it calls a local function, setItemState() for each button, passing STATE_FOCUS for the first button and STATE_NORMAL for the rest. The setItemState() updates the mCur, and set the specified state value to the specified index of state variable sItems[], which makes each button visible with an appropriate state (see below). Lastly, it sets the state variable sFocus to true to enable user input (see below).

First look at the display blocks associated with the state variable sItems[].

<transition value="&STATE_NORMAL;">

<box>

<x><eval>mOffsetX</eval></x>

<y><eval>mOffsetY+(mCellHeight+&GAP;)*mCur</eval></y>

</box>

</display>

</transition>

<transition value="&STATE_FOCUS;">

<box>

<x><eval>mOffsetX</eval></x>

<y><eval>mOffsetY+(mCellHeight+&GAP;)*mCur</eval></y>

</box>

</display>

</transition>

<transition value="&STATE_SELECTED;">

<box>

<x><eval>mOffsetX</eval></x>

<y><eval>mOffsetY+(mCellHeight+&GAP;)*mCur</eval></y>

</box>

</display>

</transition>

</state>

The ”*” as the index parameter of <state> tag indicates that each button state has exactly the same set of display blocks. Each button can take one of three states, NORMAL, FOCUS, and SELECTED. The image below shows how the “Yes” button will be displayed in these three states.

Notice that those display blocks use three templates, “tItem”, tSelectedItem,” and “tFocus”. Here is the code for these templates:

<template name="tItem">

<box>

<width>&CELLW;</width>

<height><eval>mCellHeight</eval></height>

<fg>&_COLOR_TRANSPARENT;</fg>

<bg>&COLOR_BUTTONB;</bg>

<label>

<text><eval>mLabel[mCur]</eval></text>

<x><eval>(&CELLW; - _text_width(mLabel[mCur],0,0,0))/2</eval></x>

<fg>&COLOR_BUTTONF;</fg>

</label>

</box>

</display>

</template>

<template name="tItemSelected">

<box>

<width>&CELLW;</width>

<height><eval>mCellHeight</eval></height>

<fg>&_COLOR_TRANSPARENT;</fg>

<bg>&COLOR_BUTTONF;</bg>

<label>

<text><eval>mLabel[mCur]</eval></text>

<x><eval>(&CELLW; - _text_width(mLabel[mCur],0,0,0))/2</eval></x>

<fg>&COLOR_BUTTONB;</fg>

</label>

</box>

</display>

</template>

<template name="tFocus">

<box>

<width>&CELLW;</width>

<height><eval>mCellHeight</eval></height>

<fg>&COLOR_BUTTONF;</fg>

<bg>&_COLOR_TRANSPARENT;</bg>

<box>

<width><eval>&CELLW;+2</eval></width>

<height><eval>mCellHeight+2</eval></height>

<fg>&COLOR_BUTTONF;</fg>

<bg>&_COLOR_TRANSPARENT;</bg>

</box>

</display>

</template>

</templates>

The template “tItem” draws the button label (specified in mCur) in normal color, and the template “tSelectedItem” in reversed color. The template “tFocus” draws the focus rectangle.

As described above, setting “tFocus” to true enables user input. See the code below.

</parameters>

setItemState(mFocus, &STATE_NORMAL;);

mFocus = _min(mItemCount-1, _max(mFocus+d,0));

setItemState(mFocus, &STATE_FOCUS;);

</script>

</function>

…

<box>

<key>UP</key>

</accelerators>

moveFocus(-1);

</script>

</event>

</box>

<box>

<key>DOWN</key>

</accelerators>

moveFocus(1);

</script>

</event>

</box>

<box>

<key>FIRE</key>

</accelerators>

setItemState(mFocus, &STATE_SELECTED;);

sFocus = false;

onSelect(mFocus);

</script>

</event>

</box>

</display>

</transition>

</state>

Notice that the display block of “sFocus=true” has three non-displaying <box> elements (invisible because the size is not specified), whose sole purposes are input handling. When the Up key is pressed, it calls a local function moveFocus with a value of -1. When the Down key is pressed, it calls a local function moveFocus with a value of 1. When the Fire key is pressed, it changes the state of the currently focused button to Selected, disables the input (so that the user can’t operate while the parent is performing an asynchronous operation), and notifies the parent of the selection by calling the imported function, onSelect.

By the way, here is a set of entities (this is equivalent to #define in C/C++).

<?xml version="1.0" encoding="UTF-8"?>

<!DOCTYPE ujml PUBLIC "-//UIEVOLUTION//DTD UJML 1.2//EN" "../ujml.dtd" [

<!ENTITY ITEM_MAX "6">

<!ENTITY CELLW "80">

<!ENTITY GAP "2">

<!ENTITY STATE_NORMAL "0">

<!ENTITY STATE_FOCUS "1">

<!ENTITY STATE_SELECTED "2">

<!ENTITY COLOR_BACKGROUND "0xffcccccc">

<!ENTITY COLOR_BUTTONB "0xffffffff">

<!ENTITY COLOR_BUTTONF "0xff000099">

<!ENTITY SCREENW "_getIntProperty(&_PROPERTY_INT_SCREEN_WIDTH;)">

<!ENTITY SCREENH "_getIntProperty(&_PROPERTY_INT_SCREEN_HEIGHT;)">

<!ENTITY TEXTH "_text_height(0,0,0)">

[1] UJML is an acronym for Ujinn Markup Language. The name is credited to the founder’s oldest son and it was originally intended to be used as the name for the company. But, the name UIEvolution stuck for the company name but Ujinn stuck for the language name. The use of the name Ujinn for the game is basically the author’s way of reusing the name Ujinn for some thing fun because Ujinn is Japanese for “Happy Genie”. The author is a sucker for self-referential systems and sentences J.

[2] Actually, it is possible to change the display without changing the value of the state variable by using the _clear_state() function.

[3] The _link() function can also be used to control z-order, but at a partition level, rather than at a <display> element level. Refer to the _link() function reference section on how to use the z-order parameter.

[4] Currently, the use of default states has no beneficial effect on the compiled byte code size because the compiler simply expands the single default state into multiple states, one for each array element. In the future, the use of default states may also reduce the byte code size by allowing the UIE Player to do the expansion rather than having the compiler do it.

[5] A future, extended version of UJML will support reusable objects written in UJML, Java, or C++.

Date	Version	Author	Comments
March 2003	1.2	Pete Stoppani	Initial version
Summer 2003	1.2.1	Satoshi Nakajima	1. Added Animation section 2. Added Message Box section
March 2004	1.4	Pete Stoppani	1. 2. 3. 4.