chrriis.uihierarchy
Class UIH

java.lang.Object
  extended bychrriis.uihierarchy.UIH

public class UIH
extends Object

The user interface hierarchy core class. This is the base class that allows to create easily some simple to complex user interfaces containment hierarchies.

The first steps to creating a hierarchy is to get a clear representation of it. Let's take this simple example:

* Content pane of a root pane container.
  + A panel, using a gridBag layout, added to the center.
    - A label "A label: " in the cell [0, 0], left aligned.
    - A button "A button" in the cell [0, 1].


Then to call UIH the same way:

UIH h = new UIH();
h.openNew(getContentPane());
  h.open().layout(new GridBagLayout()).constrain(BorderLayout.CENTER);
    h.add("A label: ").constrain("anchor=WEST");
    h.add(new JButton("A button")).constrain("gridx=0, gridy=1");
  h.close();
h.close();


When building the hierarchy containment tree, four methods are important:

The openNew, open and add methods return an object representing the level, on which it is possible to perform additional operations like setting the constraints or the layout.
The openNew method assumes that the container it contains already belongs to a parent. Thus, it is used to start the complete hierarchy, or to add a new level for which the container must not be added to the container of the parent level.

Labels can be created using just a String, and intermediate panels can be omitted. They are traditionaly declared only to be able to add them to the hierarchy or apply layouts, which is not required with UIH.

Constraints for layouts are passed as an object. If there is a handler registered for the layout and if it can handle this type of constraints, it will be used: some handlers in the package chrriis.uihierarchy.constraints are pre-defined to handle Strings. The example above is using one of them. Note that it is possible to register custom constraints handler for existing or custom layouts. It is also possible to use a handler when invoking the method: the constraints for the component will be obtained from this handler.

Another possibility to declare the same example is to use the XmlUIHierarchy class (more about this topic is explained in the corresponding class documentation).

Note that only when the last close() is invoked, the containement hierarchy gets created.

After the hierarchy is created it is possible to create some accessors for the levels. An accessor allows to manipulate many levels at once, including their sublevels. For example, it is possible to run an action on one or more levels, eventually including all their sublevels. One creates an Accessor by invoking the createAccessor(String) method using some names that were used to map some levels.
Apart from running custom actions, accessors already define convenient methods to disable/enable all the components of the levels it contains, or the levels and their sublevels, and to show/hide the components at those levels.

Generally, a logical set of tasks is to be performed when building a containment hierarchy. It is usually good to follow this sequence:

More capabilities are provided, like the possibility to print the hierarchy that is under creation. It is a convenient method to facilitate debugging.

Version:
2.0 2003.11.03
Author:
Christopher Deckers (chrriis@brainlex.com)

Nested Class Summary
 class UIH.SingleLevelHandler
          A handler of a child level
 
Field Summary
 UIH _
          A reference to this UIH instance.
 
Constructor Summary
UIH()
          Construct a hierarchy of components.
UIH(UIHConfig uihConfig)
          Construct a hierarchy of components, using the specific configuration.
 
Method Summary
 HLeaf add()
          Create a leaf in the hierarchy.
 HLeaf add(Object component)
          Create a leaf in the hierarchy with a specific component.
 UIH.SingleLevelHandler add(SingleLevelAccessor accessor)
          Add a child level and its sub levels from an accessor of a single level.
 void close()
          Close a hierarchy level.
 Accessor createAccessor(String names)
          Create an accessor for some mapped levels.
 Accessor createAccessor(String names, String excludedNames)
          Create an accessor for some mapped levels, with excluding some.
 void debug(String names)
          Add some levels to the debugging process, using default parameters.
 void debug(String names, Object parameters)
          Add some levels to the debugging process, using default parameters.
 Component getComponent()
          Get the last component (or container) that was added.
 UIHConfig getConfig()
          Get the configuration of this hierarchy instance.
 Container getContainer()
          Get the container for which the hierarchy is currently being defined, or the last root container that was created if the hierarchy is completed.
 boolean isClosed()
          Indicate whether the hierarchy is closed.
 HNode open()
          Create a node in the hierarchy.
 HNode open(Object container)
          Create a node in the hierarchy with a specific container.
 HRootNode openNew(Object container)
          Start a hierarchy.
 UIH print()
          Print the hierarchy to help debugging.
 void realize()
          Realize the hierarchy.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

_

public final UIH _
A reference to this UIH instance. It is mainly used to visually represent the hierarchy tree in the source code, and keep the source format after some IDE automatic source formatting.

Here is an example of its use:
UIH h = new UIH();
h.openNew(getContentPane());
h._.open().layout(new GridBagLayout()).constrain(BorderLayout.CENTER);
h._._.add("A label: ").constrain("anchor=WEST");
h._._.add(new JButton("A button")).constrain("gridx=0, gridy=1");
h._.close();
h.close();

Constructor Detail

UIH

public UIH()
Construct a hierarchy of components.


UIH

public UIH(UIHConfig uihConfig)
Construct a hierarchy of components, using the specific configuration.

Parameters:
uihConfig - The configuration to use.
Method Detail

createAccessor

public Accessor createAccessor(String names)
Create an accessor for some mapped levels. If several levels appear more than once in the mapping, they will be considered only once.
This method uses the accessor factory currently defined, so one can cast the resulting accessor to a more suitable accessor.

Parameters:
names - The names of the hierarchy levels to get, in a comma separated String if more than one name is to be specified.
Returns:
The hierarchy level accessor.
See Also:
AccessorFactory

createAccessor

public Accessor createAccessor(String names,
                               String excludedNames)
Create an accessor for some mapped levels, with excluding some. If several levels appear more than once in the mapping, they will be considered only once.
This method uses the accessor factory currently defined, so one can cast the resulting accessor to a more suitable accessor.

Parameters:
names - The names of the hierarchy levels to get, in a comma separated String if more than one name is to be specified.
excludedNames - The names of the levels to exclude when creating an accessor on the names.
Returns:
The hierarchy level accessor.
See Also:
AccessorFactory

print

public UIH print()
Print the hierarchy to help debugging.

Returns:
The hierarchy.

getContainer

public Container getContainer()
Get the container for which the hierarchy is currently being defined, or the last root container that was created if the hierarchy is completed.

Returns:
The container of the current hierarchy, or null if there is no hierarchy.

isClosed

public boolean isClosed()
Indicate whether the hierarchy is closed.

Returns:
True if the hierarchy is closed.

getComponent

public Component getComponent()
Get the last component (or container) that was added.

Returns:
The last added component.

openNew

public HRootNode openNew(Object container)
Start a hierarchy.

Parameters:
container - The container to add to the hierarchy.
Returns:
The root node that was created.

open

public HNode open()
Create a node in the hierarchy.

Returns:
The node that was created.

open

public HNode open(Object container)
Create a node in the hierarchy with a specific container.

Parameters:
container - The container to add to the hierarchy.
Returns:
The node that was created.

add

public HLeaf add()
Create a leaf in the hierarchy.

Returns:
The leaf that was created.

add

public HLeaf add(Object component)
Create a leaf in the hierarchy with a specific component.

Parameters:
component - The component to add to the hierarchy.
Returns:
The leaf that was created.

add

public UIH.SingleLevelHandler add(SingleLevelAccessor accessor)
Add a child level and its sub levels from an accessor of a single level. This method is usefull when modifying a hierarchy after it was completely constucted, eventually to add levels from another hierarchy.

Parameters:
accessor - The accessor from which to retrieve the hierarchy to add.
Returns:
A child level handler, or null if the level that is added is a root node.

close

public void close()
Close a hierarchy level.

Returns:
The hierarchy.

realize

public void realize()
Realize the hierarchy. This happens automatically at the last close invocation unless indicated otherwise in the configuration.


getConfig

public UIHConfig getConfig()
Get the configuration of this hierarchy instance. For defaults each instance share, they can be changed by using the static methods of the UIHClassConfig class.

Returns:
The configuration of this hierarchy.

debug

public void debug(String names)
Add some levels to the debugging process, using default parameters.

Parameters:
names - The names of the mapped levels to debug.

debug

public void debug(String names,
                  Object parameters)
Add some levels to the debugging process, using default parameters.

Parameters:
names - The names of the mapped levels to debug.
parameters - The parameters to use to debug, which can actually be a debugger to use.