ࡱ > r } { 5@ bjbj22 X X C / ~ x x x
x $x $x $x x ` ` ` X l Ĉ $ x 8 , | ,
^ c $ R V
$x d d d $x $x 4 8 8 8 d $x $x ^ 8 d ^ 8 8 8 F Zt < $x $x T{ !) ` ` 1 x $
T
0 8 y ړ 6 ړ T{ x x $x $x $x $x T{ ړ $x } ( @ 8 , v @ @ @ x x |~ .8 v x x |~
User Interface Markup Language (UIML) Version 4.0
Committee Draft
26 September 2007
Specification URIs:
This Version:
HYPERLINK "http://docs.oasis-open.org/%5btc-short-name%5d%20/%20%5badditional%20path/filename%5d%20.pdf" TBD
Previous Version:
http://www.oasis-open.org/committees/download.php/5937/uiml-core-3.1-draft-01-20040311.pdf
Latest Version:
TBD
Latest Approved Version:
TBD
Technical Committee:
HYPERLINK "http://www.oasis-open.org/committees/" OASIS User Interface Markup Language (UIML) TC
Chair(s):
James Helms
Editor(s):
James Helms, HYPERLINK "mailto:jhelms@harmonia.com"jhelms@harmonia.com
Robbie Schaefer, HYPERLINK "mailto:jhelms@harmonia.com"robbie@c-lab.de
Kris Luyten, kris.luyten@uhasselt.be
Jean Vanderdonckt, vanderdonckt@isys.ucl.ac.be
Jo Vermeulen, jo.vermeulen@uhasselt.be
Marc Abrams, HYPERLINK "mailto:abrams@vt.edu"abrams@vt.edu
Related work:
This specification replaces or supercedes:
None
This specification is related to:
None
Declared XML Namespace(s):
uiml
Abstract:
The design objective of the User Interface Markup Language (UIML) is to provide a vendor-neutral, canonical representation of any user interface (UI) suitable for mapping to existing languages. UIML provides a highly device-independent method to describe a user interface. UIML factors any user interface description into six orthogonal pieces, answering six questions:
What are the parts comprising the UI?
What is the presentation (look/feel/sound) used for the parts?
What is the content (e.g., text, images, sounds) used in the UI?
What is the behavior of the UI (e.g., when someone clicks or says something)?
What is the mapping of the parts to UI controls in some toolkit (e.g., Java Swing classes or HTML tags)?
What is the API of the business logic that the UI is connected to?
UIML is a meta-language, which is augmented by a vocabulary of user interface parts, properties, and events defined outside this specification. In this way, UIML is independent of user interface metaphors (e.g., "graphical user interface", "dialogs").
UIML version 4 is a refinement of the previous versions of UIML, which were developed starting in 1997.
It is the intent that this specification can be freely implemented by anyone.
Status:
This document was last revised or approved by the User Interface Markup Language (UIML) Technical Committee on the above date. The level of approval is also listed above. Check the Latest Version or Latest Approved Version location noted above for possible later revisions of this document.
Technical Committee members should send comments on this specification to the Technical Committees email list. Others should send comments to the Technical Committee by using the Send A Comment button on the Technical Committees web page at HYPERLINK "http://www.oasis-open.org/committees/%5bTC%20short%20name%5d%20/" http://www.oasis-open.org/committees/uiml/.
For information on whether any patents have been disclosed that may be essential to implementing this specification, and any offers of patent licensing terms, please refer to the Intellectual Property Rights section of the Technical Committee web page ( HYPERLINK "http://www.oasis-open.org/committees/%5bTC%20short%20name%5d%20/ipr.php" http://www.oasis-open.org/committees/uiml/ipr.php.
The non-normative errata page for this specification is located at HYPERLINK "http://www.oasis-open.org/committees/%5bTC%20short%20name%5d%20/" http://www.oasis-open.org/committees/uiml/.
Notices
Copyright OASIS 2007. All Rights Reserved.
All capitalized terms in the following text have the meanings assigned to them in the OASIS Intellectual Property Rights Policy (the "OASIS IPR Policy"). The full Policy may be found at the OASIS website.
This document and translations of it may be copied and furnished to others, and derivative works that comment on or otherwise explain it or assist in its implementation may be prepared, copied, published, and distributed, in whole or in part, without restriction of any kind, provided that the above copyright notice and this section are included on all such copies and derivative works. However, this document itself may not be modified in any way, including by removing the copyright notice or references to OASIS, except as needed for the purpose of developing any document or deliverable produced by an OASIS Technical Committee (in which case the rules applicable to copyrights, as set forth in the OASIS IPR Policy, must be followed) or as required to translate it into languages other than English.
The limited permissions granted above are perpetual and will not be revoked by OASIS or its successors or assigns.
This document and the information contained herein is provided on an "AS IS" basis and OASIS DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY OWNERSHIP RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
OASIS requests that any OASIS Party or any other party that believes it has patent claims that would necessarily be infringed by implementations of this OASIS Committee Specification or OASIS Standard, to notify OASIS TC Administrator and provide an indication of its willingness to grant patent licenses to such patent claims in a manner consistent with the IPR Mode of the OASIS Technical Committee that produced this specification.
OASIS invites any party to contact the OASIS TC Administrator if it is aware of a claim of ownership of any patent claims that would necessarily be infringed by implementations of this specification by a patent holder that is not willing to provide a license to such patent claims in a manner consistent with the IPR Mode of the OASIS Technical Committee that produced this specification. OASIS may include such claims on its website, but disclaims any obligation to do so.
OASIS takes no position regarding the validity or scope of any intellectual property or other rights that might be claimed to pertain to the implementation or use of the technology described in this document or the extent to which any license under such rights might or might not be available; neither does it represent that it has made any effort to identify any such rights. Information on OASIS' procedures with respect to rights in any document or deliverable produced by an OASIS Technical Committee can be found on the OASIS website. Copies of claims of rights made available for publication and any assurances of licenses to be made available, or the result of an attempt made to obtain a general license or permission for the use of such proprietary rights by implementers or users of this OASIS Committee Specification or OASIS Standard, can be obtained from the OASIS TC Administrator. OASIS makes no representation that any information or list of intellectual property rights will at any time be complete, or that any claims in such list are, in fact, Essential Claims.
The names "OASIS", User Interface Markup Language, and UIML are trademarks of OASIS, the owner and developer of this specification, and should be used only to refer to the organization and its official outputs. OASIS welcomes reference to, and implementation and use of, specifications, while reserving the right to enforce its marks against misleading uses. Please see HYPERLINK "http://www.oasis-open.org/who/trademark.php" http://www.oasis-open.org/who/trademark.php for above guidance.
Table of Contents
TOC \o "1-3" \h \z \u HYPERLINK \l "_Toc178587483" 1 Introduction PAGEREF _Toc178587483 \h 7
HYPERLINK \l "_Toc178587484" 1.1 Terminology PAGEREF _Toc178587484 \h 9
HYPERLINK \l "_Toc178587485" 1.2 Normative References PAGEREF _Toc178587485 \h 11
HYPERLINK \l "_Toc178587486" 1.3 Non-Normative References PAGEREF _Toc178587486 \h 12
HYPERLINK \l "_Toc178587487" 1.4 UIML, an Open Specification PAGEREF _Toc178587487 \h 12
HYPERLINK \l "_Toc178587488" 1.5 Purpose of This Document PAGEREF _Toc178587488 \h 12
HYPERLINK \l "_Toc178587489" 2 Structure of a UIML Document PAGEREF _Toc178587489 \h 13
HYPERLINK \l "_Toc178587490" 2.1 Overview PAGEREF _Toc178587490 \h 13
HYPERLINK \l "_Toc178587491" 2.1.1 Dynamic Interfaces through a Virtual UI Tree PAGEREF _Toc178587491 \h 13
HYPERLINK \l "_Toc178587492" 2.1.2 Interface Behavior PAGEREF _Toc178587492 \h 14
HYPERLINK \l "_Toc178587493" 2.1.3 Philosophy behind UIMLs Tags PAGEREF _Toc178587493 \h 14
HYPERLINK \l "_Toc178587494" 2.1.4 First UIML Example: Hello World PAGEREF _Toc178587494 \h 15
HYPERLINK \l "_Toc178587495" 2.2 UIML Document Structure PAGEREF _Toc178587495 \h 16
HYPERLINK \l "_Toc178587496" 2.2.1 Second UIML Example PAGEREF _Toc178587496 \h 17
HYPERLINK \l "_Toc178587497" 2.3 UIML Namespace PAGEREF _Toc178587497 \h 21
HYPERLINK \l "_Toc178587498" 2.4 UIML Mime Type PAGEREF _Toc178587498 \h 22
HYPERLINK \l "_Toc178587499" 2.5 A General Rule of Thumb PAGEREF _Toc178587499 \h 22
HYPERLINK \l "_Toc178587500" 3 Rendering PAGEREF _Toc178587500 \h 23
HYPERLINK \l "_Toc178587501" 4 Table of UIML Elements PAGEREF _Toc178587501 \h 24
HYPERLINK \l "_Toc178587502" 5 The and Elements PAGEREF _Toc178587502 \h 26
HYPERLINK \l "_Toc178587503" 5.1 The Element PAGEREF _Toc178587503 \h 26
HYPERLINK \l "_Toc178587504" 5.2 The Element PAGEREF _Toc178587504 \h 26
HYPERLINK \l "_Toc178587505" 5.2.1 The Element PAGEREF _Toc178587505 \h 27
HYPERLINK \l "_Toc178587506" 6 Interface Description PAGEREF _Toc178587506 \h 28
HYPERLINK \l "_Toc178587507" 6.1 Overview PAGEREF _Toc178587507 \h 28
HYPERLINK \l "_Toc178587508" 6.2 Attributes Common to Multiple Elements PAGEREF _Toc178587508 \h 28
HYPERLINK \l "_Toc178587509" 6.2.1 The id and class Attributes PAGEREF _Toc178587509 \h 28
HYPERLINK \l "_Toc178587510" 6.2.2 The source and how Attributes PAGEREF _Toc178587510 \h 28
HYPERLINK \l "_Toc178587511" 6.2.3 The export Attribute PAGEREF _Toc178587511 \h 29
HYPERLINK \l "_Toc178587512" 6.3 The Element PAGEREF _Toc178587512 \h 29
HYPERLINK \l "_Toc178587513" 6.4 The Element PAGEREF _Toc178587513 \h 30
HYPERLINK \l "_Toc178587514" 6.4.1 Dynamic Structure PAGEREF _Toc178587514 \h 31
HYPERLINK \l "_Toc178587515" 6.4.2 The Element PAGEREF _Toc178587515 \h 31
HYPERLINK \l "_Toc178587516" 6.5 The
...
To complete this example, we must provide something for the element.
A VoiceXML rendering engine REF VoiceXML \h [VoiceXML] using the above UIML code and the following element
would output the following VoiceXML code:
A WML REF WML \h [WML] Rendering engine using the above UIML code and the following element
would output the following WML code:
Hello World!
UIML Document Structure
A typical UIML 4.0 document is composed of these two parts:
1. A prologue identifying the XML language version, encoding, and the location of the UIML 4.0 document type definition (DTD):
Note: This prolog should appear in the beginning of every UIML file (even files containing only UIML templates [see Section REF _Ref159569018 \r \h 8.1.1 REF _Ref524175729 \n \h 8.1]), but for ease of readability some of the examples given in this document omit it.
2. The root element in the document, which is the tag:
...
See Section REF _Ref534201035 \r \h 5.1 REF _Ref457554852 \n \h 5.1 for more information on the root element . The element contains four child elements:
a). An optional header element giving metadata about the document:
...
The element is discussed in Section REF _Ref534201164 \r \h 5.2 REF _Ref457554834 \n \h 5.2.
b). An optional element that allows reuse of fragments of UIML:
...
Section REF _Ref159569018 \r \h 8.1.1 REF _Ref464617531 \n \h 8.1 discusses the element, and its use in building libraries of reusable UI components.
c). An optional UI description, which describes the parts comprising the UI, and their structure, content, style, and behavior:
...
Section REF _Ref172901016 \r \h 6.3 REF _Ref456716689 \n \h 6.3 discusses the element.
d). An optional element that describes the mapping of classes and names used in the UIML document to a UI toolkit and to the application logic:
...
Discussion of the element is deferred until Section REF _Ref172901037 \r \h 7.1 REF _Ref464577378 \n \h 7.1, because the element normally just sources an external file.
White spaces, blank spaces, new lines, tabs, and XML comments may appear before or after each of the above tags (provided that the XML formatting rules are not violated).
To summarize, here is a skeleton of a UIML document:
...
...
... ...
Second UIML Example
This section contains a simple example of a UIML document, which includes event handling. In order to provide a concrete example, we have chosen to use Java specific abstractions in this example. We will explain how these abstractions are added to the UIML document and how they are used. Please note that UIML is not tied to any particular set of abstractions or widget toolkit and therefore can be made as generic as the implementer wishes.
REF _Ref66783693 \h Figure 3 displays a single window representing a dictionary. The dictionary contains a list box in which an end-user can select a term (i.e. Cat, Dog, Mouse). The dictionary also contains a text area in which the definition of the currently selected term is displayed. For example, if Cat is selected on the left, a definition of a cat replaces the string "Select term on the left." The style element in the UIML document that describes this interface uses the properties found in the Java AWT and Swing components.
Figure SEQ "Figure" \*Arabic 3: A dictionary Window rendered from UIML
Carnivorous, domesticated mammal that's fond of rats and miceDomestic animal related to a wolf that's fond of chasing catsSmall rodent often seen running away from a cat
The UIML document above starts with to identify that it is an XML document, to make sure the document is correct with respect to the UIML schema, and the tag which starts every UIML document and contains the actual user interface description.
Next comes the element, enclosed by the first box. The element inside peers contains base="Java_1.5_Harmonia_1.0", which means that this UIML document uses the vocabulary defined in http://uiml.org/toolkits/Java_1.5_Harmonia_1.0.uiml. The vocabulary defines, among other things, the legal class names for elements, the legal property values for each part class. Setting the base attribute to Java_1.5_Harmonia_1.0 implies that most of the Java AWT and Swing class names (e.g., JButton, JLabel) can be used as part names in UIML, and names similar to AWT and Swing property method names can be used as UIML property names (e.g., foreground for a JLabel). Element specifies that any renderer that supports the Java_1.5_Harmonia_1.0 vocabulary can render this UIML document. (In general, if a UIML document contains then that document can be rendered by any rendering engine that supports vocabulary "uiml.org/toolkits/x.uiml".)
The element comes next. The first element inside interface is structure, which appears in the second box. The element in this example describes a UI consisting of five parts. The first is named JFrame, and contains the other four parts, named TermLabel, TermList, DefnLabel, and DefnArea. The class names used to make the interface are JFrame, JLabel, List, JLabel, and TextArea. http://uiml.org/toolkits/Java_1.5_Harmonia_1.0.uiml defines these names as corresponding to the Java AWT and Swing classes javax.swing.JFrame, javax.swing.JLabel, java.awt.List, and java.awt.TextArea. So whenever these names are used as the class for a element, the default value of the rendering property for the parts defaults to the corresponding AWT or Swing class. Thus the with id "DefnArea" will be rendered as a java.awt.TextArea.
The
To learn more about XML name-spacing, refer to http://www.w3.org/2000/xmlns/.
Note that in order for a rendering engine to take full benefit of this feature it would also need to know how to handle the elements from alternate namespaces.
UIML Mime Type
The following mime type should be used for UIML documents:
text/uiml+xml
Furthermore, the mime type could include the value of the base attribute in the element (see Section REF _Ref457464118 \r \h 7.2 REF _Ref457464118 \n \h 7.2), which identifies that any recipient software that processes the UIML document must implement the vocabulary identified in the base attribute. Here are some examples:
text/uiml/Java_1.5_Harmonia_1.0
text/uiml/Html_4.01frameset_Harmonia_0.1
A General Rule of Thumb
Several of the top level elements in UIML can be repeated multiple times. For example, ,
The element enumerates a set of interface parts and their organization for various platforms.
The
An external reference: URI names another document. An external reference works exactly like an internal reference with the exception that another document is being accessed. This implies there could be collisions between the same identifier values (Section REF _Ref534199706 \r \h 8.1.2.3) included in different document. Section REF _Ref534199706 \r \h 8.1.2.3 explains how a UIML renderer should take care of this.
A how attribute of cascade achieves behavior similar to cascading in CSS, while replace allows parts of a UIML document to be overwritten by content from multiple files.
The export Attribute
The export attribute is used in the context of templates. See Section REF _Ref464898019 \n \h 8.5 for details.
The Element
DTD
Description
All elements that describe a user interface are contained in the element. The element describes a UI and a users interaction with a UI. The element is used to describe how the UI can communicate with the application logic. The element is not a child of the interface element see Section REF _Ref456596440 \n \h 7.3. A UIML interface may be as simple as a single graphical label showing text, or as complex as hundreds of elements that employ various interface technologies (e.g., voice, graphics, and 3D).
An interface is composed of five elements: (see Section REF _Ref455915015 \n \h 6.4),
The use of the style sheet helps achieve device independence. This is discussed in Section REF _Ref161742330 \r \h 6.5 REF _Ref472777690 \n \h 6.5.2.
There must be at least one
...
The element (contained in the element of a UIML document) defines the code to which DoMath and random corresponds and how to invoke that code; see Section REF _Ref456596433 \n \h 7.3.
5. A element. Inside a template, the value of a property can be set to the value of a parameter that was previously passed to this template.
For more details we refer to section REF _Ref159572185 \r \h 8.3.2.4 and the example in section REF _Ref174167250 \r \h 8.3.3.
Using event-class with Elements
Just as elements may have properties, so too may elements have properties. There are some restrictions on using with the event-class attribute. A with the event-class attribute can only be used if the following apply:
The is a property-get operation (unless the name is rendering). Therefore the parent of must be another , , or
The has as an ancestor.
The ancestor of the has in its child an element.
The naming an event-class always returns the value corresponding to the event occurrence named in the .
The three restrictions above arise because events normally represent transient events in a program, so it makes sense to query data associated with an event when the event occurs, but not later in the lifetime of the user interface.
Example
In the following UIML fragment, whenever a mouse click occurs for part P, method doSomething in object O is called with the x position of the mouse when clicked as an argument.
Resolving Conflicting Property Values
A UIML document may contain more than one element that sets the same property name for the same property. This is illustrated by the following example:
...
...
In the example above, the background color of Button1 is set in three elements, to blue, orange, and yellow. A rendering engine to resolve such a conflict must follow the following precedence rules:
elements nested under the have the highest priority,
elements with a valid part-name attribute located in a separate style section have the next highest priority, and
elements with a valid part-class attribute have the lowest priority.
Whenever a conflict arises that is note resolved by the above precedence rules, the element that appears last in document order must be used and the others must be ignored.
By the above rules, the button will have a background color of blue in the preceding UIML document.
In the following example, the Button1, Button2, and Button3 have background colors yellow, yellow, and green, respectively:
...
...
A rendering engine must evaluate all elements for a given part in textual order and adhere to the conflict resolution policy described above when dealing with multiple conflicting elements. Implementations of this policy are beyond the scope of this document, provided that the end result guarantees that the effect is equivalent to evaluating all conflicting elements.
Using Properties to Achieve Platform Independence
One of the powerful aspects of UIML is the ability to design a UIML document that can be mapped to multiple platforms. This is achieved by a special property called rendering.
To illustrate the use of rendering, let's look at an example. Suppose we were going to create a UI specifically for Java AWT. First our UIML document would need to specify that it uses a vocabulary for Java AWT. This is done by a element (exemplified earlier in Section REF _Ref472781322 \n \h 2.2.1):
The above UIML fragment names base attribute that maps to a URI that defines the vocabulary. JavaAWT_1.3_Harmonia_1.0.uiml can be viewed as a black box by the UIML author. (It actually contains a element, discussed in Section REF _Ref457464118 \n \h 7.2.) JavaAWT_1.3_Harmonia_1.0.uiml uses all Java AWT class names as UI widget names: Button, List, and so on. The UIML author can then directly use these names as class names when defining parts:
On the other hand, suppose we want to design a UIML document that could be mapped either to Java AWT or to Java Swing. And suppose the Web resource named in the element introduced all the Swing class names as vocabulary to use in the UIML document. Now if we want to map the submitButton either to an AWT Button or to a Swing JButton, then we could not make submitButton's class Button. Instead, UIML permits the introduction of a pseudo-name chosen by the UIML author. Suppose we choose as our class name AWTorSwingButton. Our UIML fragment above then becomes this:
Now comes the key idea. The
If the rendering engine is invoked with style name AWT-specific, then the submitButton will map to an AWT button; otherwise if Swing-specific is used, then the submitButton maps to JButton.
The above example is also very useful in a dynamic UI, where the binding of a part (e.g., submitButton to Button versus JButton) can change every time the UI is rendered. In the example below, each time the UIML document is rendered, the renderer executes the element, and the return value of the is either the string "Button" or "JButton". Therefore sometimes when the UI is rendered part submitButton will be an AWT Button and other times a Swing JButton. This might be useful if the UI is sometimes displayed on various devices, all of which implement AWT, and only some of which implement Swing.
Another example of the use of rendering for a part-name or part-class is for UIs that contain the results of searches. The search result might be a table, and one column of the table might contain images on one search but text on another search. The choice of table column parts being images versus text would be determined by a element to get the part rendering, similar to the one illustrated above.
Given this basic example, some variations are possible. First, the
The
(The values ButtonSelected and MenuSelected are part of the vocabulary of the target platform, defined in the element.)
As a second example, the dictionary example of Section REF _Ref472782182 \n \h 2.2.1 contains the following:
...
...
...
The element describes what actions to take in response to various user interface events (see Section REF _Ref456323113 \n \h 6.8). The element refers to an event of class LSelected, named to represent a list selection of one of the animals in the dictionary list. The
leftentry,vertirightentry,verticopyleft,copyright
The resulting interface would look as follows:
The Element
DTD
Description
A constraint element either contains a rule with a constraint grammar instance or an alias which references such a rule for two related parts.
The Element
DTD
Description
The rule element contains an expression representing the constraint grammar. The type of grammar depends on the constraint solver used in the UIML implementation.
Example
label.top >= button.bottom
This rule means that the label is positioned below the button.
The Element
DTD
Description
For the definition of an alias, d-param elements have to be specified, which are input for the left and right side of the constraint rule. If an alias is used, the #PCDATA references the part names as a comma separated list that serve as input for the constraint solving rule.
Example
While the use of alias is shown in section REF _Ref159573569 \n \h 6.6, the following example shows how an alias is defined:
x.right <= y.left
The Element
DTD
Description
A part in a UI can be associated with various types of content, such as words, characters, sounds, or images. UIML permits separation of the content from the structure in a UI. Separation is useful when different content should be displayed under different circumstances. For example, a UI might display the content in English or French. Or a UI might use different words for an expert versus a novice user, or different icons for a color-blind user. UIML can express this.
Normally one would set the content associated with a UI part through the element:
In the UIML fragment above, the button label is hard-wired to the string "Yes". Suppose we wanted to internationalize the interface. In this case UIML allows the value of a property to be what a programmer would think of as a variable reference using the element:
The element refers to a constant-name, which is defined in the element in a UIML document. The important concept is that there may be multiple elements in a UIML document, each with a different name. When the interface is rendered, one of the elements is specified, and the elements inside are then used to satisfy the elements.
This is illustrated in the following example. The UI contains two parts. The class name "button" suggests that each part be rendered as a button in a graphical UI. (The
The last element could also be shortened, by using the source attribute, discussed in Section REF _Ref534201100 \r \h 6.7, so that EnglishSlang inherited the negativeLabel from English as follows:
The Element
DTD
Description
elements contain the actual text strings, sounds, and images associated with UI parts from the element. Each element is identified by an id attribute and is referenced by the element.
Example
The following example shows how to create elements that point to a string, a sound clip, and an image. Similarly, you can create constants that point to video clips, binary files, and other objects. Note the following URIs are for demonstration purposes and may not be active.
The element can also be used to represent literal strings used inside the element (see Section REF _Ref464577701 \n \h 6.8.3). For example:
The Element
DTD
Description
The element references the value of the element specified by the constant-name attribute. Alternatively the element may specify a url-name attribute that contains a URI to an external document containing elements.
Example uses of the element are given in Sections REF _Ref472784449 \n \h 6.5.1.3 and REF _Ref161742328 \r \h 6.5.1.
There are several uses for references:
The same text string might be used in two or more places in a UIML document. In this case a element can be defined containing the string and anywhere the string is required (e.g., as values of a property) the element can be used. Thus, if we can modify the text in the element, the change propagates to all the places in the UIML document that is referenced.
Often an interface part is initialized to contain several text strings, and when an event later occurs for the part, an element tests to see which text string the end-user selected in triggering the event. (For example, lists and choices in Java AWT contain multiple text items.) In this case, a element can be defined in the element, and then the part's values can be initialized in the
The example above demonstrates the two uses of the element and would result in the appearance of a Dialog containing ten CheckBoxes. The CheckBoxes would be numbered 1 to 10.
The Element
DTD
Description
The element provides a way for the UI to change as a result of some condition being met. Most conditions include but are not limited to users interactions. For example, using the Java AWT/Swing vocabulary for UIML, a UI containing a window with a button and a panel is described like this:
Suppose when the initial UI is displayed, we wanted only the button to appear. When the user clicks the button, the panel appears. We would use the element to define the necessary changes within the UI to remove the button and display the panel.
The semantics of UIML are changed to include the concept of a virtual UI tree. During the lifetime of a UI, the parts comprising the UI may change. (All parts that exist but are invisible to an end user are still part of the tree.) The parts present in the UI have a hierarchical relationship, therefore forming a tree. At any moment during the UI lifetime, one could enumerate the tree of parts that currently exist, and this is the virtual UI tree. Each node in this tree corresponds to a element in the UI generated by UIML. We call the tree "virtual" because it may or may not be physically represented as a data structure on a computer, depending on how a rendering engine is implemented.
The initial value of the virtual UI tree is the content of the element in a UIML document. During the UI lifetime, the virtual UI tree can be modified by deleting nodes or adding nodes using the tag. (The tag is so-named because it modifies the section's representation in the virtual UI tree.) The tag can only appear inside an element in UIML.
Syntax of
The syntax of follows:
The element may not contain a body if one of the following holds:
The source attribute is present
how ="delete" is present
Otherwise the element must contain a body, and that body must contain exactly one element, which must contain exactly one element that matches the part specified in the at-part attribute.
Semantics of
The semantics of are to modify the virtual UI tree as follows:
how ="delete":
Delete from the current virtual UI tree the sub-tree rooted at the part named in the "at-part" attribute. Also delete any properties or rules of the part. There can be no body for . Attributes where, where-part, and source cannot be used.
how="replace":
Replaces the part specified by the "at-part" attribute with the parts defined as children of the template T, where T is defined as the child of the restructure.
how="append":
Appends parts defined as children of the template T, where T is defined as the child of the restructure. The way parts are appended to the structure is defined through use of the "where" and "where-part" attribute (see below).
how="cascade":
Cascades parts defined as children of the template T, where T is defined as the child of the restructure. The way parts are cascaded to the structure is defined through use of the "where" and "where-part" attribute (see below). The cascading behavior exhibits the same behavior as found in Section REF _Ref534199706 \r \h 8.1.2.3.
The where attribute can only be used when the source attribute is present and how="cascade" or how="append" is present. The where-part attribute can be used only when where="before" or where="after" is used.
The attributes have the following semantics. Let the part element specified by at-part be
If attribute where="first" is present: All children of P in the named in the source attribute must be inserted as children of P before the existing children.
If attribute where="last" is present: All children of the P in named in the source attribute must be inserted as children of P after the existing children.
If attribute where="before" and where-part="[part-name]" is present: All children of P in the named in the source attribute must be inserted as children of P before the child of P with part name part-name, but after any children appearing before the child "part-name".
If attribute where="after" and where-part="[part-name]" is present: All children of P in the named in the source attribute must be inserted as children of P after the child of P with part name part-name, but before any subsequent children of P.
Examples of
Consider the button and panel introduced at the beginning of the proposal, where the panel contains three components: a label, a text field, and a check box. The UIML looks like this:
Append Examples
To add another label before L1, do this:
The panel now contains the parts in this order: A_T1_L2, L1, TF, C. Note: the naming convention used for parts that are added from a template is discussed in Section REF _Ref534199706 \r \h 8.1.2.3.
To add a label and a text area between TF and C, do this:
(Alternately, one could have used where="before" where-part="C".) The order of parts in the panel is now A_T1_L2, L1, TF, A_T2_L3, A_T2_TA, C.
As the UI is modified, the virtual UI tree changes. At any point in time, when a is processed, the "where" attribute refers to the current virtual tree. So if we executed the above restructures and then the following, the resulting order of components in the panel would be A_T1_L2, L1, TF, A_T2_L3, A_T2_TA, A_T3_L4, C:
The template tag surrounding the part tag provides a resolution mechanism for any name conflicts that might occur when using append. Consider the restructure tag below.
There is already a part named L1 as a child of A, but the part L1 being added gets renamed to A_T4_L1, so now the panel A has the following children: A_T1_L2, L1, TF, A_T2_L3, A_T2_TA, A_T3_L4, C, A_T4_L1.
Replace Example
To replace the entire panel with a new panel containing just a label and a text field, do this:
The set of children of A in the virtual UI tree is replaced with the set of children listed in the restructure tag. So now the panel has only the following children: A_T5_L1, A_T5_TF.
Cascade Example
When cascade is used, parts in the template that have the same name as a child of the specified by at-part are not used, but any other parts in the template are added as children of the . For example:
Since A already has a child named L1 (A_T5_L1), the L1 in template T6 is not used, but part L5 from the template is added as a child of A. So A's children are now A_T5_L1, A_T5_TF, A_T6_L5. Note that when checking for a part with the same name, only the last part of a fully-qualified name is checked, so A_T5_L1 matches L1.
Delete Example
To delete the panel, simply do this:
The Element
DTD
Description
The element defines a set of actions to be executed when the evaluation of a conditional expression defined by the element results to be the Boolean value true.
The Element
DTD
Description
The element defines a set of actions to be executed when the evaluation of a conditional expression defined by the element results to be the Boolean value false.
The Element
DTD
Description
The element defines a set of actions to be executed regardless of the evaluation of a conditional expression defined by the element .
Note that there is one special case where the tag may not fire. If a or element preceding the fires an event that in turn triggers another the tag may be ignored. An implementer's rendering engine should clearly define the behavior in this case and publish the means by which it will handle this case.
The Element
DTD
Description
Describes a single actual parameter of the method call specified by the parent element. Note that the values of all parameters in UIML are character strings. See Section REF _Ref464554334 \n \h 7.4.5 for information on conversion of the arguments to the types required by the formal parameters of the method being called.
If the number of elements equals the number of formal parameters in the method being called then the following hold:
The name attribute is optional, and is ignored by the rendering engine if present.
The order of elements within the element must match the order of the formal parameters in the method being called.
Otherwise there must be fewer elements than formal parameters in the method being called, and the following holds:
The name attribute is required on all elements.
The name attribute must be used by the rendering engine to match each element to a formal parameter in the method being called.
A element must have exactly one child
HYPERLINK "http://wiki.oasis-open.org/uiml/The__Element?action=fullsearch&value=linkto%3A"The Element
DTD
Description
Variables are containers for values that may change over the lifetime of a user interface. The main usage of variables is to supplement the behavior in order to store system states (e.g. to implement a UI state machine) but also for other purposes as input validation and for use with simple, UI-related arithmetic.
In principle properties could be used like variables, since they can be defined, values can be assigned to properties and property values can be retrieved for example with operations defined in the op element. However, the use of properties as variables is quite cumbersome, as they per definition only apply to certain parts of the interface, specified in the style description. Variables on the other hand are used to deal with the dynamic aspects of the interface and therefore should amongst others be defined and used in the behavior part to accomplish more complex dynamic behavior of the final user interface.
Variables are required to have an id, while the type and value attributes are optional. The constant attribute determines whether the variable may be changed after initialization or is immutable.
The reference attribute determines whether the variable is declared (reference="false") or if an already declared variable is referenced. The default value is "true" since a variable is only declared once and always referenced thereafter.
Definition of Variables
Variables can be declared in several places of a UIML document and are defined if the variable either contains a child element which can be reduced to #PCDATA or if the value attribute is set. If the attribute type is not set, the type "string" is implied. So following are legal variable definitions:
55
The types which are permitted for UIML variables are a selection of the built-in datatypes of the XML Schema specification REF SCHEMA \h [SCHEMA] namely:
boolean
integer
float
string
The number of datatypes for UIML is constrained on purpose since they should only allow simple arithmetic that might be required by the UI while more complex tasks belong to the backend application.
The values of the variables should therefore be formatted according to the lexical mappings, defined in the XML Schema specification, while schema facets are not supported. For convenience the lexical mappings are also provided in this specification:
boolean: boolean ::= 'true' | 'false' | '1' | '0'
integer: integer ::= (+|-)?(0|([1-9][0-9]*))
float: float ::= (-|+)?(([0-9]+(.[0-9]*)?)|(.[0-9]+))((e|E)(-|+)?[0-9]+)?|-?INF|NaN
string: string ::= Char* /* (as defined in XML: [XML]) */
Type Conversion:
In some circumstances, a variable of one type can be assigned a value of a different type. Following conversions are allowed:
(Boolean, integer, float) -> string: The characters used to specify the values are interpreted as a string
string -> integer: only character strings that specify a valid integer may be interpreted as an integer
string -> float: only character strings that specify a valid float may be interpreted as a float
string -> Boolean: only character strings that specify a valid Boolean may be interpreted as a Boolean
Boolean -> integer: if 'true' or '1', the integer will be assigned the value 1, if 'false' or '0', the integer will be assigned the value 0
Boolean -> float: if 'true' or '1', the integer will be assigned the value 1.0, if 'false' or '0', the integer will be assigned the value 0
integer -> float: The integer value will be interpreted as a float value
Operations on Variables:
The arithmetic operations on variables are defined in the scope of the element in section REF _Ref536432317 \r \h 6.8.5. Following binary operations are defined:
add calculates the value of A + B
sub calculates the value of A - B
mul calculates the value of A * B
div calculates the value of A / B
mod calculates the modulo (A%B)
Not every operation can be used by every data type. For boolean, only boolean operators are allowed. String supports only the add operator, which is interpreted as the concatenation of string A and B. Add, sub, mul and div are allowed for integers and float, while modulo is only allowed for integers.
Implicit Casting:
Automated casting of types is only allowed for the case when an integer and a float are part of a binary expresion. If the result is supposed to be an integer, the float value is rounded to the nearest integer (values >= x.5 are rounded to x+1, values < x.5 are rounded to x) and the integer operation is performed. If the result is supposed to be a float, the integer is treated as a corresponding float.
Scoping and Lifetime
Scoping
Variables can be declared at different places in the UIML document and the definition takes place, once the variable contains a child element. However, a second declaration of a variable could mean two things: Either the variable is resetted to its initial state, or a variable is temporarily overwritten. The latter is known as scoping.
In imperative programming languages, the scope of a variable can be easily defined. For example if a variable "a" is declared in the main routine and in a subroutine, the variable "a" of the main routine is not visible while the code of the subroutine is processed. This however is not applicable since UIML does not have such constructs which provide a "natural" scope.
Another solution for the scoping problem is provided with XSLT, where the scope of the variable is dependent on the position in the DOM tree. So if a variable "a" is declared in an element and declared in a child element of , then "a" of the child element is only visible inside that element and its children, while the variable "a" of is not visible. This concept can be applied for UIML as the following example shows:
11
...
2
...
In this example, two variables "A" and "B" are defined in , while in the behavior section, "A" is defined again. In the part both variables are accessed. After the first assignment, "X" will have the value "2" since the variable "A" inside the element overrides the one outside the element. After the second assignment, X will have the value "1", since no potential conflicts occurred and the variable "B" of is the only valid candidate. If the value of the variable "A" of structure needs to be retrieved in the part of this example, the id-attribute needs to hold the xPath-expression which leads to the variable.
In summary: A variable scope in UIML consists of the -element its sibling elements and all child elements. If two identical identifiers are part of the UIML document, a conflict exists which has to be resolved by the scoping rules.
Lifetime
While the scope of a variable can be defined statically, the lifetime of a variable has to be determined dynamically. In principle, the creation of the variable takes place when the renderer arrives at the first occurrence and the maximum lifetime will be until the renderer ends. In order to delete variables explicitly, the tag can be used. This is relevant when for example a sub interface is deleted and therefore the variables belonging to it are a) useless and b) should be in an initialized state when the sub-interface is instantiated again at a later time
Examples with variables
The following three examples show, how variables are used in UIML:
implementing a simple state machine for a push button
implementing a more complex state machine for a copier
validating input for a hotel reservation form
Implementing a Simple State Machine
Most simple example of a push-button, switching the state between on and off each time the button is pressed. The statespace is {on, off} and the inputspace consists only of a push-button.
false
true
false
Implementing a More Complex State Machine
This example shows a part of a copier to set the machine state with respect to brightness and the page mode. There are two buttons, one to set the brightness (dark, normal and bright) and one to switch between single and double sided. Pushing the buttons cycles through the different states. The state-space is {dark, bright, normal}X{single, double} and the input-space is {setBrightness, setPageMode} Since the brightness and page mode settings are independent from each other, 5 rules are sufficient to describe 9 transitions.
normal
single
bright
normal
dark
single
double
Validating Input
This is an example of a part of a hotel reservation form that checks the entered number of rooms with the policy of the hotel booking system. In this example, the hotel requires a minimum of one room and a maximum of four rooms to be booked by individuals. Rooms can be entered directly in the textfield or by using up- and down buttons. by pressing the buttons, the new room number is immediately checked and the value in the textfield changed respectively. In case that the upper or lower bounds are reached, the value in the textfield does not change. By pressing the "submit" button, the value in the textfield will be submitted to the backend. The advantage of this method is evident when the User Interface is connected via a network to the backend logic. By checking valid values on the client side no re-transmissions are required. This is equivalent to HTML-forms, where JavaScript would be used to check the input prior submission.
141
1
Peer Components
This section describes the elements that go inside the element, their attributes, and their syntax. Examples are provided to help show common usage of each element.
The Element
DTD
Description
To facilitate extensibility, UIML includes a element that defines mappings from class, property, event, and call names used in a UIML document to entities external to the UIML document. The element has two child elements, for two types of mappings:
The element contains mappings of part and event classes, property names, and event names to a UI toolkit. This mapping defines a vocabulary to be used with a UIML document, such as a vocabulary of classes and names for VoiceXML. Normally a UIML author does not write a element, but instead uses names in a UIML document that have been defined in the list of vocabularies at http://uiml.org/toolkits. Section REF _Ref523122240 \n \h \* MERGEFORMAT 7.2.1 discusses vocabularies.
The element maps names and classes used in elements to application logic external to the UIML document. In large-scale software development, the element is defined once to represent the API of the application logic (typically as a element), and then included in each UI for the project.
Please note that the child is explained in Section REF _Ref159573619 \n \h 8.3.2.3.
The Element
DTD
Description
Every UIML document uses a vocabulary. The vocabulary defines the legal class names that can be used for parts and events in a UIML document, as well as the legal property names. The formal definition of a vocabulary is done through a element containing elements (see Section REF _Ref534201116 \r \h 7.4.2). Each element defines a legal class name.
At present, the list of standard vocabularies is posted on HYPERLINK "http://uiml.org/toolkits"http://uiml.org/toolkits, in the form of a set of templates that may be included into UIML documents.
In the remainder of this section, we first discuss (Section REF _Ref523122240 \n \h 7.2.1) UIMLs use of a standard set of vocabulary names, which is all that most UIML authors need to know about the element. Then (Section REF _Ref523631878 \n \h 7.2.2) we discuss how to define a new vocabulary using the children of the element.
Naming an Existing Vocabulary in
Normally, a UIML author uses an existing vocabulary. Therefore UIML requires a way to label each UIML document with the vocabulary used in that document. The labeling follows a convention, and authors of new UIML vocabularies must follow this convention.
There are two categories of vocabularies:
Vocabularies with widespread use, whose definition is posted on uiml.org, in http://uiml.org/toolkits. Examples are vocabularies for Java 1.3 AWT and Swing, HTML 3.2, WML, and VoiceXML. We call these base vocabularies.
Custom vocabularies that individuals, companies, or other organizations define. These may or may not be not posted on uiml.org. The vocabularies may be posted on web sites around the world of interest to specific communities, or posted in a company's internal network, or not posted at all. We call these custom vocabularies.
Typically a custom vocabulary extends a base vocabulary (e.g., a company creates custom Java UI classes that extend Swing classes). The unlikely exception is when someone creates a custom vocabulary from scratch that does not rely on any base vocabulary, yet a rendering engine for some base vocabulary can render that custom vocabulary. For example, someone might create a new UI toolkit for Java from scratch that does not use AWT or Swing, but design the classes so that a rendering engine for UIML using the Java 1.3 or Swing base vocabulary can still render the custom classes.
A UIML document must be labeled by a base vocabulary name, and may be labeled by a custom vocabulary name, in the manner described next.
Labeling Base Vocabularies with Attribute base
To easily determine the base language used within the UIML document, the element requires an attribute named base, which identifies the base target language of the UIML document.
The syntax of values for the "base" attribute must follow this convention:
___
Several rules apply to base:
The value of base is case insensitive.
If the value of base is x, then the following URL must define x: http:// HYPERLINK "http://www.uiml.org/"uiml.org/toolkits/x.uiml. This URL must contain a element, whose child is a element, whose children define the vocabulary x. (Requests to post a new file should be sent to HYPERLINK "mailto:info@uiml.org"info@uiml.org.)
Every rendering engine must implement one or more base vocabularies. If a rendering engine implements vocabulary "uiml.org/toolkits/x.uiml", then the rendering engine must be able to render any document that contains (with or without the source attribute).
For example, a rendering engine could be created to display UIs using the Java 1.3 Swing and AWT toolkits; in this case the rendering engine might recognize the vocabularies Java_1.5_Harmonia_1.0.uiml, JavaAWT_1.3_Harmonia_1.0.uiml, and JavaSwing_1.3_Harmonia_1.0.uiml. Such a rendering engine must also render custom classes that a UIML author creates that extend Swing classes, by writing their own element to extend the base vocabulary.
Consider the following element:
The element says that any rendering engine that implements vocabulary uiml.org/toolkits/Java_1.5_Harmonia_1.0.uiml can render the UIML document containing the element, even though the rendering engine was written without knowledge of what is in vocabulary MySwing_1.0_JoeProgrammer_0.1.uiml.
(It is the responsibility of the UIML author to insure consistency between the values of the source and base attributes. For example, the UIML author should not define class names mapped to HTML tags in MySwing_1.0_JoeProgrammer_0.1.uiml and then set base to a vocabulary for Java [e.g., Java_1.5_Harmonia_1.0].)
The following table gives the vocabulary that a rendering engine actually uses to render a UIML document. The table assumes that the has the attribute base="x".
Does contain source attribute (e.g., source="y")?Does have body?Vocabulary is defined by this:Example (see below)YesDoesn't matterCombination of y and, if the body of is not empty, anything in the body of #4NoNouiml.org/toolkits/x.uiml#1,2,3Yesuiml.org/toolkits/x.uiml augmented by the body of #5Here are some examples of legal elements and their meanings:
UIML document must be rendered by rendering engines implementing vocabulary uiml.org/toolkits/Java_1.5_Harmonia_1.0.uiml.
UIML document must be rendered by rendering engines implementing vocabulary uiml.org/toolkits/HTML_3.2_Harmonia_1.0.uiml.
UIML document must be rendered by rendering engines implementing vocabulary uiml.org/toolkits/GenericJH_1.3_Harmonia_1.0.uiml.
UIML document must be rendered by rendering engine implementing vocabulary uiml.org/toolkits/ Java_1.3_Harmonia_0.8.uiml, but the vocabulary used in this UIML document is the combination of Java_1.3_Harmonia_0.8 and the presentation defined in http://xyz.com/MySwing_1.0_xyz_0.1.uiml#vocab. Note that HYPERLINK "http://xyz.com/PrettySwing_1.0_xyz_0.1.uiml" \l "vocab"http://xyz.com/MySwing_1.0_xyz_0.1.uiml#vocab must contain a element (see Section REF _Ref464617531 \n \h 8.1) whose id is vocab.
...
UIML document must be rendered by a rendering engine implementing vocabulary uiml.org/toolkits/Java_1.3_Harmonia_0.8.uiml, but the actual vocabulary used in this UIML document is Java_1.3_Harmonia_0.8 augmented by the part class MySuperCoolButton defined in the element.
Labeling Custom Vocabularies with Attribute source
It is recommended that if a UIML author uses a custom vocabulary, that he/she creates a new UIML file containing a element whose id attribute is "vocab", and whose body is a element containing elements defining the custom vocabulary. (Unless this recommended practice is followed, the custom vocabulary cannot be reused in multiple UIML documents.) Furthermore, the name of the UIML file should use the following syntax:
___.uiml
For example, if you developed a library of classes that extends Java 1.3 Swing, and you call the library "MySwing", and the current version of MySwing is 1.0, and your name is JoeProgrammer, and this is the first UIML file you wrote to define the vocabulary (version 0.1), then you might name the custom vocabulary file MySwing_1.0_JoeProgrammer_0.1.uiml. Any UIML documents that use this custom vocabulary should then contain the following element:
Permitted Optimization for Rendering Engine
An implementation of a rendering engine may omit reading the element to reduce the execution time of and mitigate the effect of network delays upon rendering time. Instead, the engine might cache copies of the presentation files for the toolkits that it supports (e.g., Java_1.5_Harmonia_1.0). Alternatively, the elements information might be hard-wired into the rendering engine, so that the engine does not even have to spend time reading and processing the information.
Multiple Presentation Elements
A UIML document may contain multiple elements. However, each element must contain the id attribute. A rendering engine selects one of them based on information outside the UIML document (e.g., as a command line option to the rendering engine).
Suggested Use of Base Attribute in Authoring Tools
When an authoring tool for UIML opens an existing UIML document, the tool can quickly identify which vocabulary is used in the document from the base attribute, perhaps to display an appropriate palette of user interface widgets for further editing of the document (e.g., a palette of Java Swing objects if the file uses the Java 1.5 vocabulary).
Creating a New Vocabulary using
This section discusses two vocabulary files, for HTML and Java. Based on these examples, one can define a new vocabulary file. The full vocabularies for HTML and Java used here are available at the following URLs:
http://uiml.org/toolkits/HTML_3.2_Harmonia_1.0.uiml
http://uiml.org/toolkits/Java_1.5_Harmonia_1.0.uiml
Defining Legal Part Class Names Via
HTML Case
To start with, suppose a UIML document contains the following:
...
...
The mapping of the Button part to HTML is defined by uiml.org/toolkits/HTML_3.2_Harmonia_1.0.uiml, which maps any part of class Button to the HTML 3.2 tag:
...
UIML uses a set of elements that start with . The "d-" prefix means that this element defines a class, property, or parameter name. Thus defines a class name.
Java Case
In contrast, suppose a UIML document uses a Java JButton:
...
...
The mapping of the JButton part to Java is defined by uiml.org/toolkits/Java_1.5_Harmonia_1.0.uiml, which maps any part of class JButton to the Swing JButton class:
...
Note these differences between the HTML and Java elements:
The maps-type is tag for a mapping to a markup language, like HTML, and class for a mapping to an imperative object-oriented language like Java.
The maps-to attribute lists a namespace and tag in that namespace ("html:INPUT" for HTML) or a string whose syntax is, at present, not defined in this specification ("javax.swing.JButton" for Java).
Next we will discuss what goes in the "..." inside each in the above elements. This part answers the following questions:
What property names can be used with the part class (e.g. the color of a button)?
What events and event listeners are used with the part class (e.g. the event of clicking a button)?
What properties exist for events (e.g. the X and Y positions for a mouse click event)?
These are discussed in turn below.
Defining Legal Property Names for Classes via
HTML Case
The UIML document below extends our previous example to give our HTML button a text label that says "Press me!".
...
...
Now lets look at what is required in the element to map the UIML property VALUE to the corresponding VALUE attribute of the HTML tag. This is defined in the third element below:
BUTTON
...
The three elements above say that an HTML 3.2 button has three properties: its type (which is always BUTTON, and therefore cannot be set in a UIML document, its name, and its value (or the string text that appears in the button).
Java Case
Now consider the Java JButton. The UIML document below extends our previous example to give our Java Swing button a text label that says "Press me!".
...
...
Now lets look at what is required in the element to map the UIML property text to the proper Java set method for javax.swing.JButton. This is defined in the two elements below:
...
The elements in the box above say that a property named text can be used with JButtons. In a element that sets the property, the Java method setText(java.lang.String) should be used. To get the property, use javax.swing.JButton.getText().
A JButton has many other properties these are defined by additional elements (e.g., to set color, font, icon) where the ellipsis appears in the element in Java_1.5_Harmonia_1.0.uiml.
The box above could also contain elements. This is useful for exposing methods in the Java class that are not properties (and hence should not be accessed in UIML elements), but could be invoked via a element. For example, java.awt.List contains a method add(...) to add another item to a list. An in a UIML document might contain a to the add method.
Defining Legal Events and Listeners for Part Classes Via
HTML Case
The UIML document below extends our previous example to provide a behavior for an event called onClick for our HTML button.
...
...
...
...
The element in the box above causes the element to be executed whenever an onClick event occurs for the button. The meaning of onClick is defined by additional lines in the element:
...
The above UIML says that one of the events in HTML is OnClick, and that a whose class is Button can receive an OnClick event.
To summarize, when writing rules, the class attribute of an event element in a condition can be any of the names listed in an element that is associated with the in the section. In the UIML example above, a Button's events include OnClick, and therefore the following line was used in the UIML document given earlier:
Java Case
Java provides a much richer UI toolkit than HTML, and so the information required in the element is more complex.
There are two styles of events used by platforms:
Method 1: A defines how events for it are handled.
Method 2: A does not define how events for it are handled.
Method 1 is used in Java 1.0 and in HTML. In Java 1.0, a java.awt.Component had a method called action(Event, Object). This method was called when an event occurred for the Component. In HTML, many tags (represented by elements in UIML) can contain attributes denoting events. An example in HTML is . In this case the defines the event handling (calling myfunction()). In UIML, this association between the event onClick and myfunction is made by a .
Method 2 is used in Java 1.1 and later. UIML adopts the Java model of requiring a Listener entity that defines how events are handled on behalf of a . (If there exists a target language for UIML that uses Method 2 and also uses a concept entirely different than listeners, then UIML will need modification.) In this case, a Listener class defines how events are handled. In UIML, the association between the event mouseClicked and the actions to perform in response is made by a . The UIML user is not aware of the Listener or Event classes involved.
Thus UIML must contain a rich enough syntax to define the following:
Class names representing events (such as "OnClick" for HTML, or "MouseEvent" for Java)
Class names representing event listeners for Method 2 (such as MouseListener)
Methods in event listeners (such as MouseListener.mouseClicked())
A means to associate components, listeners, and events.
Event property names (such as "X" and "Y" coordinates for a MouseEvent)
Next we show what these look like for clicks on a JButton.
The UIML document below extends our previous example to provide a behavior for an event called ActionListener.actionPerformed for our Java JButton.
...
...
...
Here are the elements in in Java_1.5_Harmonia_1.0.uiml to define the event actionPerformed for a button click:
...
...
The section under the comment "Define Event Classes" defines a class named ActionEvent. The children of are discussed in Section REF _Ref523643923 \n \h 7.2.2.4. This is analogous to the element in the HTML earlier.
The section under the comment "Define Event Listener Classes" uses the element to define a Java event listener. This section has no analog in the HTML earlier, because the HTML event model ("Method 1") does not use listeners.
The section under the comment "Define Part Classes" was shown in our earlier examples, and defines the JButton class. Here we add elements to list which listeners are used with a JButton. The element includes an "attacher" attribute that names the method that the JButton uses to attach the listener to itself. For example, the UIML above says that JButton has a method called "addActionListener" that is used to attach an ActionListener to a JButton.
To summarize, the above UIML says that one of the events in Java AWT/Swing is ActionEvent, one of the listeners is ActionListener, ActionListener has a method named actionPerformed that processes ActionEvents, and a listener named ActionListener handles events for any whose class is JButton.
Recall the following lines from the UIML document earlier:
When writing rules, the class attribute of an event element in a condition uses a dotted notation consisting of the form .. The is a class name defined by a element, such as ActionListener in the UIML example above. The is a method name defined in a element that is a child of the element, such as actionPerformed in the UIML above.
Whenever a JButton is clicked, the Java Virtual Machine calls the actionPerformed method. The above is therefore executed when actionPerformed is called on a JButton.
Defining Legal Event Property Names Via
Lets consider our UIML document again. Suppose we want to display the x coordinate of the mouse pointer when it is clicked inside a button. The label on the button will be changed to display the x coordinate. The following UIML document accomplishes this:
...
...
Here are the elements in in Java_1.5_Harmonia_1.0.uiml to define the property named X for a mouse click:
...
The Element
DTD
Description
The element describes how the UI interacts with the underlying application logic that implements the functionality manifested through the interface. The underlying logic might be implemented by middleware in a three tier application, or it might be implemented by scripts in some scripting language, or it might be implemented by a set of objects whose methods are invoked as the end-user interacts with the UI, or by some combination of these (e.g., to check for validity of data entered by an end-user into a UI and then object methods are called), or in other ways.
Thus, the element acts as the glue between a UI described in UIML and other code. It describes the calling conventions for methods in application logic that the UI invokes. Examples of such functions include objects in languages such as C++ or Java, CORBA objects, programs, legacy systems, server-side scripts, databases, and scripts defined in various scripting languages.
Example of Element
Here is an example of the element:
The fragment above says that there is an external object reached by name com.harmonia.example.Counter2. This object is given the name Counter in the UIML document. The component has two methods, named count and reset in the UIML document. These map, respectively, to count and setCount in com.harmonia.example.Counter2. Each returns a value of type int, where the meaning of int is whatever meaning ascribed by the language in which com.harmonia.example.Counter2 is implemented. Finally, count takes no arguments when called, and setCount takes one argument, an int.
Example
The following UIML fragment describes the calling conventions for a variety of functions in external application logic and functions in scripts. Note that URLs given below are for example purposes only.
Subelements of and
The Element
DTD
Description
The (a child of only) acts as a container for application methods (e.g., a class in an object oriented language). A contains .
The maps-to attribute specifies the platform-specific type of the component or container that is being bound. The location attribute gives additional information (e.g., a URI) that is used by the rendering engine to locate the widget, event, or application class at runtime.
The Element
DTD
Description
The (a child of only) element binds a name used in the rendering property of a part or an element elsewhere in the interface to a component that is part of the presentation toolkit.
The maps-to attribute specifies the platform-specific type of the component or container that is being bound.
The Element
DTD
Description
The element specifies the mapping between the name appearing in a element and the associated methods that assign or retrieve a value for the property.
Example
...
...
...
The Element
DTD
Description
The element describes a method in the external application logic or presentation toolkit in terms of its optional formal parameters and optional return value.
The maps-to attribute specifies the name that is being bound. The value of maps-to gives the name of a method that can be executed. The method can represent a toolkit method (if it is inside a element), an application method (if it is inside a element), or scripting code (with scripting nested inside the element).
If the method described returns a value, the return-type attribute should be specified and assigned the name of the type of object returned (e.g. int, java.lang.String, etc.). The return value will be converted to a string before being used. If the return-type attribute is omitted any value that might be returned by the method is discarded.
The element supports three different execution models:
The method represents a remote (outside the rendering engine) executable code. This code executes outside the run-time context of the rendering engine and is treated as a black box. The rendering engine packages all the parameters, sends them to the server executing the code (which can be on the same machine or across the network), and waits for a reply. Here is an example:
The method represents a local script. This script is embedded inside the method and is executed within the run-time context of the rendering engine (i.e., it executes locally with respect to the rendering engine). If the maps-to attribute for the component is missing, this means that all the code is local. Here is an example:
The method represents a combination of the above. This is useful if you want to do some error checking locally before calling a remote method or manipulate the result after it is returned. The semantics of how to do this are under revision.
The Element
DTD
Description
Describes a single formal parameter of the function described by the parent element. Note that all parameters are character strings. The string value of a matching element will be converted to a platform-specific data type specified by the type attribute, and that type is the type of the formal parameter of the function (e.g., java.lang.String). It is up to some intermediary to convert parameters from UIML character strings to other data types. For example, if we have
37
which is mapped to the parameter of function f(double) in this Java class
public class Demo {
static void f(double);
}
then string "37" is converted by some intermediary to type double in Java.
Furthermore, if there is ambiguity in which function of the target language a parameter maps to, the rules of the target language are used to resolve the ambiguity. For example, suppose class Demo contains two functions f as follows:
public class Demo {
static void f(double);
static void f(float);
}
In this case the rules of Java would determine whether string "37" would be converted to a double or to a float. (Note: The semantics of Java are to use the method "f(float)". See J a v a D e v e l o p e r C o n n e c t i o n "! ( J D C ) T e c h T i p s , M a r c h 1 4 , 2 0 0 0 , h t t p : / / d e v e l o p e r . j a v a . s u n . c o m / d e v e l o p e r / T e c h T i p s / 2 0 0 0 / t t 0 3 1 4 . h t m l f o r m o r e i n f o r m a t i o n o n t h i s a s p e c t o f J a v a s s e m a n t i c s . )
S e e S e c t i o n R E F _ R e f 4 6 5 8 4 0 1 6 4 \ n \ h 6 . 8 . 1 4 o n t h e s i g n i f i c a n c e o f parameter order.
If a has children then the tags will be considered an enumeration of the valid values for the . For example:
The above example defines a parameter identified as "color" that will converted into a java.awt.Color object by the rendering engine. This parameter has three valid values: Blue, Red, and Green. If a user attempts to insert a non-valid values (one not defined in the enumeration) the rendering engine must provide an informative error message. Please note that values defined in the enumeration are case sensitive, thus "blue", "red", and "green" are not valid values of our "color" parameter.
If a is given a value, then the value is considered to be the default value for the parameter. So for example:
0
Results in the index Parameter having a default value of 0 if it is excluded from the element.
The
Structure
The structure element can contain several part tags, when it contains more then one, there is a new "top-container" part created which contains the different parts. Assume a structure tag which contains, after being sourced with a template, more then one part child. When there was no "top-container" element it will be created and the different part children will be added, otherwise the part childs are immediately added without creating a new "top-container". An example of the structure element is given in listing 9.
Listing 9: A structure example
...