chrriis.uihierarchy.xml
Class XmlUIH

java.lang.Object
  extended bychrriis.uihierarchy.xml.XmlUIH

public class XmlUIH
extends Object

A builder of UI hierarchy from XML documents. It parses XML documents and creates their hierarchies using the UIH class.

The DTD file "uih.dtd" indicates what are the possible tags. The basic idea is that where you would call the openNew method there is a tag <rootNode> with attributes or children entities representing the possible method calls of the node that is added. It is the same for the open and add methods where the corresponding tags are <node> and <leaf>.

One important point that is worth to detail is the way parameters work: by default they are supposed to be Strings. Let's look at this example:

<node value="A label: " constraints="gridx=0, gridy=0"/>

The constraints are a String. This next example is equivalent:

<node value="A label: ">
  <constraints class="String" value="gridx=0, gridy=0">
</node>


From the above example, we can see that any type of data can be used, provided they have a constructor using a String, as the value will be given to the constructor as a String.

We can also notice that "java.lang" classes or base types do not need the full package name. Also the package name can be omitted for known layouts or for layouts with a name ending with "Layout" and located in the "java.awt" package.
Constraints are using this mechanism, as well as subConstraints and layoutParam.

An addition to layoutParam is the ability to provide more than one attribute. Let's consider an example where the layout to use is a CardLayout and we need to construct it with two parameters of type int. The result would be:

<node layout="CardLayout">
  <layoutParam>
    <param class="int" value="20"/>
    <param class="int" value="20"/>
  </layoutParam>
...


Internally this code generates an array with two elements. If you need an array of arrays, just declare them using some children <param> tags:

...
  <param>
    <param class="String" value="s1"/>
    <param class="Integer" value="i1"/>
    <param>
      <param class="String" value="s2"/>
    </param>
  </param>
...


Note that this is not extensively tested for now, and only supports Object[] arrays (no support for String[] or other types).

Version:
1.0 2003.12.08
Author:
Christopher Deckers (chrriis@brainlex.com)

Constructor Summary
XmlUIH()
          Construct a hierarchy of components.
XmlUIH(UIH uih)
          Construct a hierarchy of components.
 
Method Summary
 void build(InputStream xmlInputStream, ComponentResolver componentResolver)
          Build a user interface containment hierarchy from an XML stream.
 void build(InputStream xmlInputStream, Object[] parameters)
          Build a user interface containment hierarchy from an XML stream.
 ComponentResolver getComponentResolver()
          Get the component resolver that was used when creating the hierarchy, to map the names in the XML document to some real components.
 String getHierarchyName()
          Get the name of the hierarchy to use.
 UIH getUIH()
          Get the hierarchy that was constructed by this XML module.
 void setHierarchyName(String hierarchyName)
          Set the name of the hierarchy to use.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

XmlUIH

public XmlUIH()
Construct a hierarchy of components.


XmlUIH

public XmlUIH(UIH uih)
Construct a hierarchy of components.

Parameters:
uih - The hierarchy object to use to build the hierarchy from XML.
Method Detail

getComponentResolver

public ComponentResolver getComponentResolver()
Get the component resolver that was used when creating the hierarchy, to map the names in the XML document to some real components.

Returns:
The component resolver. It can be null if the hierarchy is not yet created.

getHierarchyName

public String getHierarchyName()
Get the name of the hierarchy to use.

Returns:
The name of the hierarchy to use.

setHierarchyName

public void setHierarchyName(String hierarchyName)
Set the name of the hierarchy to use.

Parameters:
hierarchyName - The name of the hierarchy to use.

getUIH

public UIH getUIH()
Get the hierarchy that was constructed by this XML module.

Returns:
The hierarchy.

build

public void build(InputStream xmlInputStream,
                  Object[] parameters)
           throws IOException
Build a user interface containment hierarchy from an XML stream. It uses the first hierarchy found in the XML stream.

Parameters:
xmlInputStream - The stream containing the XML definitions.
parameters - The optional parameters. They are in the form {"name_of_component_1_in_xml", component_1,
"name_of_component_2_in_xml", component_2, ...}
or:
{component_1, component_2, ...} with the components' names set.
or a mix of both.
Throws:
IOException - If an IO error occurs.

build

public void build(InputStream xmlInputStream,
                  ComponentResolver componentResolver)
           throws IOException
Build a user interface containment hierarchy from an XML stream. It uses the first hierarchy found in the XML stream.

Parameters:
xmlInputStream - The stream containing the XML definitions.
componentResolver - The component resolver used to get a component from its name.
Throws:
IOException - If an IO error occurs.