INTRO SPECS TUTORIALS RESOURCES TOOLS ABOUT US CONTACT US
 
 

UIML 2
• Tutorials

UIML 1
• Tutorial 1
• Tutorial 2

UIML 1 Tutorial 1:

This very simple interface will illustrate some of the basic concepts of UIML design. Some of these concepts include:

    1. UIML language elements and structure.

    2. Separation of structure, style and content.

    3. Content keys and their usefulness.

Note to the Reader:

This tutorial assumes that you are familier with Java AWT component names, attributes and layout. For further information on available AWT components and attributes see the "Attribute Dictionary".

First we want to design the dialog. We assume that it is a simple and informative. The dialog states a fact and is accompanied by an acknowledgement button. We want it to look something like this.

The Dialog Box has three interface objects: the box (a Frame), the message, and the acknowledgement button. We want to put the message and button inside the dialog and arrange them vertically.

The first thing we need to do is create the structure of the dialog. This is done with a user interface (UI) description. UI descriptions look very much like HTML, except that the tags are different. The UI description for this example looks like this:

<UIML>
<HEAD>
   <AUTHOR>Stephen Williams</AUTHOR>
   <DATE>December 3, 1997</DATE>
   <VERSION>1.0</VERSION>
</HEAD>
<APP CLASS="App" NAME="DialogApp">
   <GROUP CLASS="Dialog" NAME="PrintFinishedDialog">
      <ELEM CLASS="DialogMessage" NAME="PrintFinishedMsg"/>
      <ELEM CLASS="DialogButton" NAME="OKButton"/>
   </GROUP>
</APP>
<DEFINE NAME="OKButton">
   <PROPERTIES>
   <ACTION
       VALUE="DialogApp.EXISTS=false"
       TRIGGER="Selected"
   />
   </PROPERTIES>
</DEFINE>
</UIML>

The entire document is enclosed in a <UIML>...</UIML> tag pair. UIML is an XML compliant language and follows the convention of enclosing all information in descriptive tags in a nested fashion. This is very much like HTML with a few exceptions.

Note: The syntax for the UI definition is: <TAGNAME> all things belonging to the TAG </TAGNAME>. There are no restrictions about staying on the same line or indentations.

There are three primary sections to a UI definition file. They are

HEAD: The <HEAD> section contains information about the file itself. The <AUTHOR>, the <DATE> and the <VERSION> are the currently supported values that can be contained in <HEAD>

APP: The <APP> section contains the actual structure of the interface. The two basic elements <GROUP> and <ELEM> allow the designer to create a structure without filling in all of the particulars. <APP> requires a CLASS in order for the Style to properly render it. In this case we just make CLASS="App". We also give the APP a NAME "DialogApp" so that it can be controlled.

DEFINE: The <DEFINE> section defines the named groups and elements from the APP section in more detail. In this example, we define what action occurs when we "click" on the OKButton element.

Let's go through the <APP> section one line at a time and talk about each of the tags and their properties.

<APP CLASS="App" NAME="DialogApp">

The APP tag begins the official UI definition for this application. Although a dialog box may not be considered a separate application by most, it is a required convention to have an <APP>...</APP> in each UI definition file. You can, of course define multiple frames within a single UI definition.

<GROUP CLASS="Dialog" NAME="PrintFinishedDialog">

The tag GROUP indicates that this is a group of UI objects. In other words, there are other things nested within the group. While it is not absolutely necessary for their to be ELEMs or other GROUPs defined within the group, it is a good convention to follow.

The CLASS attribute is used to define a "CLASS" of UI objects that this GROUP belongs to. The value for CLASS can be any single alphanumeric word.† The CLASS value must be given a RENDERING in the style for the UI object to render. In this case the chosen value for the CLASS is "Dialog". By choosing names carefully, a single style can server many ui descriptions.

The NAME attribute is used to give this particular GROUP a name. As with CLASS, the value of NAME is chosen by the designer. The NAME given here is "PrintFinishedDialog".

At first glance, there may not seem to be a difference between NAME and CLASS. However, there can be many elements with the same CLASS value, but only one element with a particular NAME. If you want to create a group of buttons to perform some functions, you would give them all the same CLASS but different NAMEs. That way, the style can define the RENDERING of that class as "Button" but put in a different LABEL for each NAME. You can also use the NAME to call different functions for each of the buttons.

<ELEM CLASS="DialogMessage" NAME="PrintFinishedMsg"/>

This next element is an ELEM, which means that it does not contain any other UI objects. As with GROUP the CLASS and NAME are given values by the designer that indicate that the ELEM is a member of a CLASS of UI objects that has a certain look and that it has a unique NAME

You may have notice that the tag is syntactically different from the GROUP. The GROUP tag starts as <GROUP ...> and the ELEM tag is <ELEM..../>. This is because the tag does not actually enclose anything. It stands alone. This is one of the places where UIML is different from HTML. HTML is not XML compliant because you can have a <P> tag with no </P> which would not be allowed in XML. The language parser understands that the next value after a <tagname/> is not within the previous tag but a "sibling" to it. If the above line had been <ELEM CLASS="DialogMessage" NAME="PrintFinishedMsg"> (without the / before the closing >) then the parser would assume that the following line is a nested member of the <ELEM>, which would be an error because ELEMs cannot enclose other UI objects.

<ELEM CLASS="DialogButton" NAME="OKButton"/>

Another ELEM.

The order that these UI objects appear can be important. In this particular example it doesn't because "PrintFinishedMsg" and "OKButton" are positioned in the style (next section) with the layout manager. Some layouts, however, do not require each element to be positioned. If the layout were FlowLayout or GridLayout then "PrintFinishedMsg" would be to the left of "OKButton" because it is in the ui definition first.

Because FlowLayout and GridLayout exhibit this property, it is best to assume that the layout is partially determined by the order of element definitions.

</GROUP>

An end GROUP tag finishes out the Dialog definition. Any tag that encloses other tags or content must be ended in the form of "</tagname>".

</APP>

An end of APP tag finishes out the APP definition.

Now that the structure of the Dialog Box has been created, we can move on to defining the actions of this interface. In this example only one element requires an action definition, the "OKButton". The action that the button performs is shown in a DEFINE.

<DEFINE NAME="OKButton">

A <DEFINE> tag allows the designer to add more detail to a previously NAMEd UI object. This gives the designer the ability to explain the interface within the <APP>..</APP> tags in a brief and concise fashion so that others can easily grasp the structure without having to wade through the details.

<PROPERTIES>

A <PROPERTIES> tag allows the designer to add add certain information about the responses that a UI object make when an event occurs.

<ACTION VALUE=" DialogApp.EXISTS=false" TRIGGER="Selected" />

A <ACTION> tag defines actions that can be taken by this UI element on other UI objects. In this case the action taken is to change the attribute called Exists on the entire dialog box when the button is "clicked".

The VALUE attribute contains a list of element attribute settings. In other words, the action performed is to change attributes on UI objects, including the element performing the action. NOTE, that not all attributes can be currently changed (Please see the attribute dictionary for the current list). The attribute value "VISIBLE=true" means that the UI object can be seen on the screen. "ENABLED=true" means that the UI object is in the renderer, setting it the last frame to "false" exits the renderer. "ENABLED=true" means that the element is active, "ENABLED=false" means it's inactive (grayed-out buttons and menu items in Windows programs are inactive). The form of the attribute setting is "ElementName.ATTRIBUTE=value".

Each ACTION has an associated TRIGGER, or event that causes the action to occur. The Selected trigger means that a button has been pushed, a menuItem selected, or a text field finalized by hitting the "enter" key.

</PROPERTIES>

The </PROPERTIES> tag closes the property creation of the "OKButton" element.

</DEFINE>

The </DEFINE> tag closes the definition of the "OKButton" element.

Style:

Now that structure of the dialog box has been determined we can move on to style. The power of UIML is in the ability to completely change the look of a screen of arbitrary complexity by changing only the style definitions. This means we can define many different applications or screens and have them all use the same style.

The syntax of UIML style is different from that of the structure to parallel CSS (Cascading Style Sheets) which is available for HTML documents (this may change to an XML compliant style in the future).

Style defines how the elements described in the ui definition will be displayed on the screen. This includes both minor attributes such as Color or Size as well as the type of element such as Button or List. So a group of 5 commands, that are related, could be rendered as 5 buttons, or as a radio-group with 5 choices, or as a menu with 5 menu items.

In this case all we want is an AWT Frame with a Label and a Button. UIML style can define default attributes that will cascade to all "descendant" elements. There are two style elements that MUST be defined. Those are "TOOLKIT" and "RENDERING". These two items must be defined for all elements for them to render. The following is the style definition for the described dialog box:


APP.App{
    +TOOLKIT:            jfc;
    +RENDERING-PREFIX:   java.awt;
}
GROUP.Dialog {
    +RENDERING: Frame;	/* This is an AWT frame */
    +LAYOUT:    BorderLayout;
    +FONT_NAME: "sanserif";
    +FONT_SIZE: "11";
    SIZE:       "150,105";
    +CONTENT:   "Error: No Label";
    +BACKGROUND:"lightgray";
}

ELEM.DialogMessage{
    RENDERING:   "Label";
    FONT-STYLE:  "bold";
    ALIGNMENT:   "Center";
}

ELEM.DialogButton{
    RENDERING:   "Button";
    FONT-STYLE:  "Plain";
    ALIGNMENT:   "South";
    SIZE:        "80,25";
}

Note that the style is defined based on the CLASS of the elements, not the name. This allows the designer to change ALL of the buttons into a menu by changing one or two lines.

The syntax of the style is radically different from that of the ui definition. Each style definition is for a single CLASS. All attribute ß à value pairs are enumerated inside a set of "{}". The order of the attribute ß à value pairs is not important. If the attribute is preceded by a "+" sign, then that value is "scoped" to all decendents. In this example the Font-Face applies to all elements in the dialog box because the GROUP.Dialog is the parent of all elements.

Now let's do as before and go through the style one line at a time.

GROUP.Dialog {

This line starts the style for a particular class. Note that the CLASS is denoted as UITAG.CLASSNAME. This will provide future flexibility in naming schemes and style assignments (e.g. you can have a GROUP and and ELEM with the same CLASS name but rendered differently).

After denoting the CLASS, we use an "{" to start the style definition.

+TOOLKIT: jfc;

The toolkit is the name of the GUI toolkit used to put the elements on the screen. Currently only jfc is offered. Note that a "+" precedes the attribute name TOOLKIT. This means that all enclosed elements will also have a jfc TOOLKIT.

The act of passing an attribute to the child components is also known as "scoping". Note that scoping is not quite the same as inheritance. Scoping is syntactically based, whereas inheritance is based on programming object type.

The syntax of a style assignment is ATTRIBUTENAME: value;

+RENDERING-PREFIX: java.awt;

The RENDERING-PREFIX is the prefix to the standard Java classname. All AWT components begin with java.awt. This is merely a typing reduction mechanism. The two prefixes supported now are java.awt and com.sun.java.swing. Note, currently, if you mix awt and swing components you must put the full class name for each RENDERING.

+RENDERING: Frame; /* This is an AWT frame */

This is the Java component you wish to use in the interface for the particular class. In this case a Frame is desired. Frames are separate windows that can be moved, iconified and destroyed. Currently, all other user interface components MUST be contained within a Frame (e.g. a Frame is it's farthest ancestor).

This line also has a comment. Style comments look just like C or Java comments. Comments in the ui definition look like <!--comment goes here -->.

+LAYOUT: BorderLayout;

A Frame is a container and therefore has a layout. If no layout is specified the default is FlowLayout. Here, we want a BorderLayout because we only have two elements and one is below the other. We could have chosen GridLayout with one column if we wanted.

Layout fundamentals and layout design are discussed in another document.

+FONT_NAME: "sanserif";

When text is used, we want it to be a Serif or "footed" font. Recall that the "+" sign means that all enclosed elements will also use a Serif font unless they override it. There are five FONT-NAMEs: "serif", "Sanserif", and "monospaced" look like they do here. "dialog" and "dialoginput" depend on the computer setting for those types in the operating system.

+FONT_SIZE: "11";

The FONT-SIZE is the height of the text in points. Note: 72 points is 1 inch.

SIZE: "150,105";

This is the SIZE of the Frame in pixels the X (or horizontal) size is first and the Y (or vertical) size is second (X,Y). Note that there is no "+" sign here. Scoping the size of a container to child components can have odd effects on the interface if you should forget to set the size of those children. We recommend that the SIZE never be scoped.

+CONTENT: "Error: No Label";

This is the text that goes on the border of the Frame. In this case, I the text is an error message. Doing this allows me to visually check an interface for missing labels in individual components. The individual components are given their text labels in the content database, which will be discussed in the next section.

+BACKGROUND: "lightgray";

This sets the background color for the Frame (and all descendants). There is a short list of predefined colors that are available (black, blue, cyan, darkgray, gray, green, lightgray, magenta, orange, pink, red, white and yellow). You can also follow the color name with a "+" or "-" which will shift the brightness toward white or black respectively. If you must have full color control then you can input RGB, HSB, a color "integer" or use a system color name to match the desktop configuration colors. See the Attribute Dictionary for all the details.

}

When we have finished the style definition for the "Dialog" we close with a "}".

ELEM.DialogMessage{

Now we start the style definition for the "DialogMessage". This is a textual label.

RENDERING: "Label";

We render this as an AWT label. Note that we could have called this a Button but the button would not do anything since we did not define any action for it in the ui definition.

FONT_STYLE: "bold";

I decided that this label should be bold. The possible styles are "plain", "bold", "italic", and "bolditalic".

ALIGNMENT: "Center";}

This message is to appear in the "Center" of the parent Frame according to the rules of BorderLayout. Since this is the last style attribute for the message, we close the definition.

ELEM.DialogButton{

Now we define the button.

RENDERING: "Button";

It is rendered as an AWT Button.

FONT-STYLE: "Plain";

Make the font plain. This isn't required because plain is the default.

ALIGNMENT: "South";}

This button is to appear in the "South" of the parent Frame according to the rules of BorderLayout. Since this is the last style attribute for the message, we close the definition.

Although the style has listed HOW a particular class will look on the screen, there are certain features that have not been addressed. The style features that have not yet been inserted are those things that change based on the actual element rather than the class of the element. In other words, style information that is attached to the NAME of the element rather than the CLASS of the element. These declarations are put in a "Content Database". Most of the time labels for buttons, menu items and text areas go here. Because of that, the content database also has a "key" which allows the designer to use multiple languages for the same application.

The Content database for this example is short because there are only three elements, the Frame, the message and the button.

# Dialog Example
# Author: Stephen Williams
# Date: December 3, 1997
#
# Record format:  Key, Name (from .uiml file), Attribute, Value
#
English PrintFinishedDialog    CONTENT Print Monitor
English PrintFinishedMsg       CONTENT Printing Complete
English OKButton               CONTENT OK

The format of the content database is:

Key ElementName Attribute Value

Note that the separator is white space. But, because we know there are only four items, the "Value" can have white space without causing problems.

We have now finished the design. Assuming you name your files Ex1.ui Ex1.style and Ex1.cdb respectively, you can now look at the result by running the command.

java Render Ex1.ui Ex1.style Ex1.cdb -key English

The finished product does not look EXACTLY like what was envisioned, but is pretty close (it will get better as more functionality is added). If you click on the OK button, the frame disappears and the renderer exits.

 

 

© 1999-2000 UIML.org (all rights reserved)