net.wotonomy.ui.swing
Class TreeAssociation

java.lang.Object
  net.wotonomy.control.EODelayedObserver
      net.wotonomy.ui.EOAssociation
          net.wotonomy.ui.swing.TreeModelAssociation
              net.wotonomy.ui.swing.TreeAssociation

All Implemented Interfaces:

java.awt.event.FocusListener, java.lang.Runnable, java.util.EventListener, java.util.Observer, javax.swing.event.TreeExpansionListener, javax.swing.event.TreeSelectionListener, javax.swing.event.TreeWillExpandListener, javax.swing.tree.TreeModel, net.wotonomy.control.EOObserving

public class TreeAssociation
extends TreeModelAssociation
implements java.awt.event.FocusListener, javax.swing.event.TreeExpansionListener, javax.swing.event.TreeWillExpandListener, java.lang.Runnable

TreeAssociation is a TreeModelAssociation further customized for JTrees. It binds a JTree to a display group's list of displayable objects, each of which may have a list of child objects managed by another display group, and so on. TreeAssociation works exactly like a ListAssociation, with the additional capability to specify a "Children" aspect, that will allow child objects to be retrieved from a parent display group. Note that the children aspect requires the bound display group to have a DataSource that can vend a DataSource appropriate for the bound key That data source is then used to create data sources for child nodes, and so on.

• titles: a property convertable to a string for display in the nodes of the tree. The objects in the bound display group will be used to populate the initial root nodes of the tree (more accurately, children of the offscreen root node in the tree).
• children: a property of a node value that returns zero, one or many objects, each of which will correspond to a child node for the corresponding node in the tree. The data source of the bound display group is replaced a data source that populates the display group with the visible nodes in the tree component as determined by calling fetchObjectsIntoChildrenGroup. If this aspect is not bound, the tree behaves like a list.
  
  Binding this aspect with a null display group is the same as binding it with the titles display group. In this configuration the contents of the titles display group will be replaced with the visible nodes in the tree component, as specified above, replacing the existing data source.
  
  In that case, the display groups for the nodes in the tree will still use the original data source for resolving their children key, and programmatically setting the contents of the display group will still repopulate the root nodes of the tree.
• isLeaf: a property of a node value that returns a value convertable to a boolean value (aside from an actual boolean value, zeroes evaluate to true, as does any String containing "yes" or "true" or that is convertable to a number equal to zero; other values evaluate to false).
  
  If the isLeaf aspect is not bound, the tree must force nodes to load their children to determine whether they are leaf nodes (in effect loading the grandchildren for any expanded node). If bound, child loading is deferred until the node is actually expanded.
  
  For example, binding this value to a null display group and the key "false" will result in a deferred-loading tree that works much like Windows Explorer's network volume browser - all nodes appear with "pluses" until they are expanded.
  
  Note that the display group is ignored: the property will be applied directly to the object corresponding to the node.

All other usage is as TreeModelAssociation.

Version:

$Revision: 904 $

Author:

michael@mpowers.net, $Author: cgruber $

Field Summary

Fields inherited from class net.wotonomy.ui.swing.TreeModelAssociation

childrenGroupChanged, isListening, titlesGroupChanged

Fields inherited from class net.wotonomy.ui.EOAssociation

ActionAspect, ArgumentAspect, aspectToGroup, aspectToKey, AttributeAspectSignature, AttributeToManyAspectSignature, AttributeToOneAspectSignature, AttributeToOneToManyAspectSignature, BoldAspect, ChildrenAspect, control, DestinationAspect, EditableAspect, EnabledAspect, IconAspect, IsLeafAspect, ItalicAspect, LabelAspect, NullAspectSignature, ObjectsAspect, ParentAspect, SelectedObjectAspect, SelectedTitleAspect, SourceAspect, TitlesAspect, ToManyAspectSignature, ToOneAspectSignature, ToOneToManyAspectSignature, URLAspect, ValueAspect, VisibleAspect

Fields inherited from class net.wotonomy.control.EODelayedObserver

ObserverNumberOfPriorities, ObserverPriorityFifth, ObserverPriorityFirst, ObserverPriorityFourth, ObserverPriorityImmediate, ObserverPriorityLater, ObserverPrioritySecond, ObserverPrioritySixth, ObserverPriorityThird

Constructor Summary

TreeAssociation(java.lang.Object anObject)
Constructor expecting a JTree.

TreeAssociation(java.lang.Object anObject, java.lang.Object aRootLabel)
Constructor expecting a JTree or similar component and specifying a label for the root node.

Method Summary

void	establishConnection() Overridden to not fire events during initial population.
void	fireTreeNodesChanged(java.lang.Object source, java.lang.Object[] path, int[] childIndices, java.lang.Object[] children) Fires a tree nodes changed event to all listeners.
void	fireTreeNodesInserted(java.lang.Object source, java.lang.Object[] path, int[] childIndices, java.lang.Object[] children) Fires a tree nodes inserted event to all listeners.
void	fireTreeNodesRemoved(java.lang.Object source, java.lang.Object[] path, int[] childIndices, java.lang.Object[] children) Fires a tree nodes removed event to all listeners.
void	fireTreeStructureChanged(java.lang.Object source, java.lang.Object[] path, int[] childIndices, java.lang.Object[] children) Fires a tree structure changed event to all listeners.
void	focusGained(java.awt.event.FocusEvent evt) Notifies of beginning of edit.
void	focusLost(java.awt.event.FocusEvent evt) Updates object on focus lost and notifies of end of edit.
protected void	init() Called by both constructors.
static boolean	isUsableWithObject(java.lang.Object anObject) Returns whether this class can control the specified object.
boolean	isVisible(java.lang.Object node) Overridden to check whether the node is visible in the tree on screen.
net.wotonomy.foundation.NSArray	objectsFetchedIntoChildrenGroup() Overridden to return all visible rows in the tree.
void	run() Fires any queued node changed and structure changed events.
void	treeCollapsed(javax.swing.event.TreeExpansionEvent event) Updates the children display group, if any.
void	treeExpanded(javax.swing.event.TreeExpansionEvent event) Updates the children display group, if any.
void	treeWillCollapse(javax.swing.event.TreeExpansionEvent event)
void	treeWillExpand(javax.swing.event.TreeExpansionEvent event)
void	valueChanged(javax.swing.event.TreeSelectionEvent e)

Methods inherited from class net.wotonomy.ui.swing.TreeModelAssociation

addAsListener, addTreeModelListener, aspects, aspectSignatures, associationClassesSuperseded, bindAspect, breakConnection, canBindAspect, createNode, fireRootStructureChanged, getChild, getChildCount, getIndexOfChild, getNodeForObject, getObjectForNode, getPathForNode, getPathForObject, getPathsForObject, getRoot, getRootLabel, isInsertingAfter, isInsertingChild, isLeaf, isSelectionPaintedImmediately, objectDeletedFromChildrenGroup, objectInsertedIntoChildrenGroup, objectKeysTaken, objectWillChange, primaryAspect, processRecentChanges, removeAsListener, removeTreeModelListener, rootLabel, setInsertingAfter, setInsertingChild, setRootLabel, setSelectionPaintedImmediately, subjectChanged, valueForPathChanged

Methods inherited from class net.wotonomy.ui.EOAssociation

associationClassesForObject, copyMatchingBindingsFromAssociation, displayGroupForAspect, displayGroupKeyForAspect, displayName, endEditing, object, setValueForAspect, setValueForAspectAtIndex, shouldEndEditing, shouldEndEditingAtIndex, valueForAspect, valueForAspectAtIndex

Methods inherited from class net.wotonomy.control.EODelayedObserver

discardPendingNotification, observerQueue, priority, update

Methods inherited from class java.lang.Object

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

Constructor Detail

TreeAssociation

public TreeAssociation(java.lang.Object anObject)

Constructor expecting a JTree.

TreeAssociation

public TreeAssociation(java.lang.Object anObject,
                       java.lang.Object aRootLabel)

Constructor expecting a JTree or similar component and specifying a label for the root node.

Method Detail

init

protected void init()

Called by both constructors.

isUsableWithObject

public static boolean isUsableWithObject(java.lang.Object anObject)

Returns whether this class can control the specified object.

establishConnection

public void establishConnection()

Overridden to not fire events during initial population.

Overrides:

establishConnection in class TreeModelAssociation

valueChanged

public void valueChanged(javax.swing.event.TreeSelectionEvent e)

Specified by:

valueChanged in interface javax.swing.event.TreeSelectionListener

Overrides:

valueChanged in class TreeModelAssociation

isVisible

public boolean isVisible(java.lang.Object node)

Overridden to check whether the node is visible in the tree on screen. Offscreen in a scrollpane does not count.

Overrides:

isVisible in class TreeModelAssociation

fireTreeNodesChanged

public void fireTreeNodesChanged(java.lang.Object source,
                                 java.lang.Object[] path,
                                 int[] childIndices,
                                 java.lang.Object[] children)

Fires a tree nodes changed event to all listeners. Provided as a convenience if you need to make manual changes to the tree model.

Overrides:

fireTreeNodesChanged in class TreeModelAssociation

fireTreeNodesInserted

public void fireTreeNodesInserted(java.lang.Object source,
                                  java.lang.Object[] path,
                                  int[] childIndices,
                                  java.lang.Object[] children)

Fires a tree nodes inserted event to all listeners. Provided as a convenience if you need to make manual changes to the tree model.

Overrides:

fireTreeNodesInserted in class TreeModelAssociation

fireTreeNodesRemoved

public void fireTreeNodesRemoved(java.lang.Object source,
                                 java.lang.Object[] path,
                                 int[] childIndices,
                                 java.lang.Object[] children)

Fires a tree nodes removed event to all listeners. Provided as a convenience if you need to make manual changes to the tree model.

Overrides:

fireTreeNodesRemoved in class TreeModelAssociation

fireTreeStructureChanged

public void fireTreeStructureChanged(java.lang.Object source,
                                     java.lang.Object[] path,
                                     int[] childIndices,
                                     java.lang.Object[] children)

Fires a tree structure changed event to all listeners. Provided as a convenience if you need to make manual changes to the tree model.

Overrides:

fireTreeStructureChanged in class TreeModelAssociation

objectsFetchedIntoChildrenGroup

public net.wotonomy.foundation.NSArray objectsFetchedIntoChildrenGroup()

Overridden to return all visible rows in the tree.

Overrides:

objectsFetchedIntoChildrenGroup in class TreeModelAssociation

focusGained

public void focusGained(java.awt.event.FocusEvent evt)

Notifies of beginning of edit.

Specified by:

focusGained in interface java.awt.event.FocusListener

focusLost

public void focusLost(java.awt.event.FocusEvent evt)

Updates object on focus lost and notifies of end of edit.

Specified by:

focusLost in interface java.awt.event.FocusListener

treeWillExpand

public void treeWillExpand(javax.swing.event.TreeExpansionEvent event)
                    throws javax.swing.tree.ExpandVetoException

Specified by:

treeWillExpand in interface javax.swing.event.TreeWillExpandListener

Throws:

javax.swing.tree.ExpandVetoException

treeWillCollapse

public void treeWillCollapse(javax.swing.event.TreeExpansionEvent event)
                      throws javax.swing.tree.ExpandVetoException

Specified by:

treeWillCollapse in interface javax.swing.event.TreeWillExpandListener

Throws:

javax.swing.tree.ExpandVetoException

treeExpanded

public void treeExpanded(javax.swing.event.TreeExpansionEvent event)

Updates the children display group, if any.

Specified by:

treeExpanded in interface javax.swing.event.TreeExpansionListener

treeCollapsed

public void treeCollapsed(javax.swing.event.TreeExpansionEvent event)

Updates the children display group, if any.

Specified by:

treeCollapsed in interface javax.swing.event.TreeExpansionListener

run

public void run()

Fires any queued node changed and structure changed events. Typically invoked on a delayed event loop.

Specified by:

run in interface java.lang.Runnable