Package eu.bandm.tools.util.ui

Class SwingForester

java.lang.Object

eu.bandm.tools.util.ui.SwingForester

@PropertyDependency("eu.bandm.tools.umod.runtime.SwingForester.TreeProxy.separator")
public abstract class SwingForester
extends Object

Makes a swing "tree" gui representation for a graph of Java objects. The gui is selectable/expandable/collapsable. The graph data is assumed not to change during the livetime of this representation. But it can be infinite, i.e. contain cycles, thanks to lazy construction.

Usage: One subclass must be defined of SwingForester, and one or multiple subclasses of SwingForester.LazyNode.
The former must override growBranch(TreeNode,String,Object). This method is called when a new branch of the graphic tree shall be made visible for the given object. It can deliver null, so that some default leaf node (not expandable) will be presented. Or it can deliver a new instance of a subclass of LazyNode. This represents a sub-tree with the given node as its root. The eval() method of this node must be overridden to add all sub-nodes. For this, the field source can be read, which contains the data object related to that node. According to its data contents, the methods SwingForester.LazyNode.add(String, boolean), SwingForester.LazyNode.add(String, long), SwingForester.LazyNode.add(String, double), SwingForester.LazyNode.add(String, Object), SwingForester.LazyNode.addMAP(String, Map), SwingForester.LazyNode.addREL(String, Multimap), SwingForester.LazyNode.addSEQ(String, List), and SwingForester.LazyNode.addSET(String, Set) can be called. Examples can be found in formatDiagnosis/FormatTree.java and in all code generated by umod with --swingtree t.

The nodes representing objects and collections behave lazy: They will call the generation of (again lazy) subnodes not before they are clicked explcitly for expansion. Therefore cyclic data can be displayed: The data can be called "tree" only insofar there is one single entry object. But cycles are not recognized and thus visually marked, but naively displayed by the repetition of the data (on demand).

A separator between label and primitive values can be set by the user via the system property "eu.bandm.tools.umod.runtime.SwingForester.TreeProxy.separator".

Finally the display is initiated by new JTree (mySwingForester.growRoot(myData));, see JTree.

     Swing runtime system needs getChildAt(..)/getChildCount()/...
       |   |
       |   v
       v   Leaf.getChildAt(..)/getChildCount()/..
       LazyNode.getChildAt(..)/getChildCount()/..
       |                                    +----- user derived class ----+
       |                                    : UserNode extends LazyNode:  :
       v                                    :                             :
       LazyNode.demand()      ----------------------------> UserNode.eval()
                                             generate subtrees according to
                                       type of the represented data object:
                                                                |
           add(..) <--------------------------------------------+
            |  add representation of a single object reference  |
            V                                                   |
           grow(..)  -----------------------> growBranch()      |
                     <------------------------                  |
             returns a LazyNode for a complex object display    |
             OR                                                 |
             add a Leaf for a field with primitive value        |
                                                                |
           addMAP(..)/addSEQ(..)/.. <---------------------------+
            |   add a specialized subclass of LazyNode for a field of 
            |   collection type
            v
            growMap(..)/growCollection(..)/..
  

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
class	SwingForester.LazyNode	Lazy node which will display sub-nodes on demand.
final class	SwingForester.Leaf	Tree node with no sub-nodes, representing a field of primitive type.
class	SwingForester.TreeProxy	Common superclass of the two kinds of nodes which are displayed: lazy subtrees or simple leafs.

Field Summary

Fields

Modifier and Type	Field	Description
static final String	SEPARATOR_PROPERTY	Property name for the separator between field name and value representation.

Constructor Summary

Constructors

Constructor	Description
SwingForester()	Sole constructor.

Method Summary

Modifier and Type	Method	Description
boolean	getHTML()	Return whether html rendering shall be used.
protected abstract @Opt TreeNode	growBranch(TreeNode parent, @Opt String label, Object x)	Generate representation for one single object.
TreeNode	growRoot(Object x)	Central service access point: is called with the top-most object of the data structure to display and generates the complete Swing tree.
void	setHTML(boolean html)	Whether the label text for GUI nodes shall be formatted using HTML mark-up.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Details

SEPARATOR_PROPERTY

public static final String SEPARATOR_PROPERTY

Property name for the separator between field name and value representation.

See Also:

• Constant Field Values

Constructor Details

SwingForester

public SwingForester()

Sole constructor.

Method Details

setHTML

public void setHTML(boolean html)

Whether the label text for GUI nodes shall be formatted using HTML mark-up. In this case all strings to print will be transformed accordingly. Is used whenever a node is created. (Changing it on the fly will result in inconsistent node appearance.)

Parameters:

html - whether html rendering shall be used.

getHTML

public boolean getHTML()

Return whether html rendering shall be used.

Returns:

whether html rendering shall be used.

See Also:

• setHTML(boolean)

growRoot

public TreeNode growRoot(Object x)

Central service access point: is called with the top-most object of the data structure to display and generates the complete Swing tree.

Parameters:

x - the root object of the data structure to dispaly

Returns:

the complete (but lazy) swing tree.

growBranch

@Opt
protected abstract @Opt TreeNode growBranch(TreeNode parent,
 @Opt
 @Opt String label,
 Object x)

Generate representation for one single object. Derived class must differentiated whether the type of the object shall be displayed as a subtree. In this case it will call return the result of one of growCollection(String,TreeNode,String,Collection), growMap(TreeNode,String,Map), or growMultimap(TreeNode,String,Multimap). Otherwise it simply returns null, and a graphic leaf node will be generated by the caller (which is testForBranch(javax.swing.tree.@eu.bandm.tools.annotations.Opt TreeNode,java.lang.@eu.bandm.tools.annotations.Opt String,java.lang.Object)).

Parameters:

parent - the tree node under which the new node will be placed

label - the visible label text

x - the object to display, often simply a boxed primitive value.

Returns:

a lazy node with overridden eval() method, or a self-defined leaf node, or null to request a leaf node with default appearance