com.sssw.rt.jform
Class AgcJTree

java.lang.Object
 |
 +--java.awt.Component
       |
       +--java.awt.Container
             |
             +--javax.swing.JComponent
                   |
                   +--javax.swing.JTree
                         |
                         +--com.sssw.rt.jform.AgcJTree

All Implemented Interfaces:

Accessible, AgiHelpInfo, AgiRowSetManager, EventListener, ImageObserver, MenuContainer, Scrollable, Serializable, TreeSelectionListener

public class AgcJTree

extends JTree

implements AgiRowSetManager, TreeSelectionListener, AgiHelpInfo

The AgcJTree control is a lightweight component that displays a multilevel hierarchy of data, organized into expandable and collapsible nodes. You can bind the control to a database column.

You can specify data for the control in the Form Designer by entering a list of display values and storage values or by specifying a database table that holds the display and storage values. In the Designer you can specify data for the first level below the root in the tree's hierarchy. You can add additional levels programmatically.

When the control is bound to a database column, the selected value in the tree becomes the value for the current row. The current value can be at any level in the hierarchy. The current value is saved in the database when you call updateRows() for the form.

Generally, a data-bound tree control is associated with at least two tables and often with additional tables:

• The table containing the column to which the control is bound
• The table containing the data displayed at the first level of the tree
• Additional tables as the data source for additional levels

When you load the tree from a row cursor, you can use methods of AgiRowSetManager to navigate the tree hierarchy. However, changes to the tree items do not affect the underlying data; therefore, calling updateRows() is not allowed. If you call it for the control, updateRows() throws AgoUnsupportedOperationException.

The data for the tree is managed by a model. When you create a tree control in the Form Designer, a DefaultTreeModel is created for the tree. You can also define your own model and associate it with the tree.

The data for the tree is made up of nodes, which are organized into levels. In the default model, these nodes are the DefaultMutableTreeNode class. To create additional levels, you add child nodes to existing nodes.

Additional classes for working with tree data include:

• AgoDisplayValue: Combines the display and storage values for a tree node in a single Object
• AgoRowCursorTableModel: Associates a result set associated with a AgiRowCursor with the tree's data model

Most of the methods you use to manipulate the tree, the model, and individual nodes are inherited from JTree. When you manipulate nodes of the model, you need to tell the tree control to update its data. When you use AgcJTree methods, this is handled for you. For information, see AgcJTree.insertItemAt(Object, DefaultMutableTreeNode).

This code is a simple example of populating a tree with two levels of data. In the Form Designer, five choices were specified: Mammal, Bird, Reptile, Amphibian, Insect. These values form the first level in the tree. The code loops through the first-level nodes and adds three child values to each first-level category:

   // array of static data for second level.
   // order of subarrays matches order
 	// of values specified in Designer
 	String value[] [] = {
 		{ "cat", "dog", "agouti" }, 
 		{ "duck", "goose", "egret" }, 
 		{ "iguana", "basilisk", "skink" },
 		{ "treefrog", "toad", "peeper" },
 		{ "mosquito", "greenhead fly", "moose fly" }
 	};
 		
 	int count;
 	DefaultMutableTreeNode root, parentNode, childNode;
 
 	// from the model, get the root node
 	DefaultTreeModel model = 
 		(DefaultTreeModel) Tree1.getModel();
 	root = (DefaultMutableTreeNode) model.getRoot();
 
 	// loop over the first-level nodes specified in Designer		
 	count = root.getChildCount();
 	for (int i = 0; i < count; i++) {
 
 		// get the first-level node
 		parentNode = 
 			(DefaultMutableTreeNode) root.getChildAt(i);
 
 		// set it to allow children
 		parentNode.setAllowsChildren(true);
 
 		// add child nodes from the data array
 		for (int j = 0; j < value[i].length; j++) {
 			childNode = Tree1.insertItemAt(value[i][j], 
 					null, parentNode);
 		}
 	}

For more information about this example and other ways of programming tree controls, see Programming Swing Tree Controls in the online book Application Techniques.

Properties:

Automatic Query, Choices, Control Type, Data Column, Display Value, Distinct, Enabled, Font Name, Font Size, Font Style, Height, Help Page, Left, Limit Rows, Load Choices, Maximum Rows, Name, Order By, Storage Value, Table, Tool Tip, Top, Values, Visible, Where Clause, Width

Events:

focusGained, focusLost, keyPressed, keyReleased, keyTyped, mouseClicked, mouseDragged, mouseEntered, mouseExited, mouseMoved, mousePressed, mouseReleased, validationFailed, validationTest, valueChanged, viewColumnResize, viewDoubleClick, viewHeaderRowClick, viewRowCollapse, viewRowExpand, viewSelectionChange

See Also:

Serialized Form

Inner classes inherited from class javax.swing.JTree

JTree.AccessibleJTree, JTree.DynamicUtilTreeNode, JTree.EmptySelectionModel, JTree.TreeModelHandler, JTree.TreeSelectionRedirector

Inner classes inherited from class javax.swing.JComponent

JComponent.AccessibleJComponent

Fields inherited from class javax.swing.JTree

CELL_EDITOR_PROPERTY, CELL_RENDERER_PROPERTY, cellEditor, cellRenderer, editable, EDITABLE_PROPERTY, INVOKES_STOP_CELL_EDITING_PROPERTY, invokesStopCellEditing, LARGE_MODEL_PROPERTY, largeModel, ROOT_VISIBLE_PROPERTY, rootVisible, ROW_HEIGHT_PROPERTY, rowHeight, SCROLLS_ON_EXPAND_PROPERTY, scrollsOnExpand, SELECTION_MODEL_PROPERTY, selectionModel, selectionRedirector, SHOWS_ROOT_HANDLES_PROPERTY, showsRootHandles, toggleClickCount, TREE_MODEL_PROPERTY, treeModel, treeModelListener, VISIBLE_ROW_COUNT_PROPERTY, visibleRowCount

Fields inherited from class javax.swing.JComponent

accessibleContext, listenerList, TOOL_TIP_TEXT_KEY, ui, UNDEFINED_CONDITION, WHEN_ANCESTOR_OF_FOCUSED_COMPONENT, WHEN_FOCUSED, WHEN_IN_FOCUSED_WINDOW

Fields inherited from class java.awt.Component

BOTTOM_ALIGNMENT, CENTER_ALIGNMENT, LEFT_ALIGNMENT, RIGHT_ALIGNMENT, TOP_ALIGNMENT

Constructor Summary

AgcJTree()
Unlike the no-argument Swing JTree constructor, this AgcJTree constructor initializes the control with an empty DefaultTreeModel.

AgcJTree(Hashtable value)
Returns a tree control created from a Hashtable which does not display the root.

AgcJTree(Object[] value)
Returns a tree control with each element of the specified array as the child of a new root node which is not displayed.

AgcJTree(TreeModel m)
Returns a tree control which displays the root node.

AgcJTree(TreeNode root)
Returns a tree control with the specified TreeNode as its root, which displays the root node.

AgcJTree(TreeNode root, boolean asksAllowsChildren)
Returns a tree control with the specified TreeNode as its root, which displays the root node and which decides whether a node is a leaf node in the specified manner.

AgcJTree(Vector value)
Returns a tree control with each element of the specified Vector as the child of a new root node which is not displayed.

Method Summary

DefaultMutableTreeNode	addItem(Object obj) Adds an item to the tree.
DefaultMutableTreeNode	addItem(String title, Object value) Adds an item to the tree, specifying both the display and storage values.
Object	getValue() Gets the value of the selected item.
DefaultMutableTreeNode	insertItemAt(Object obj, DefaultMutableTreeNode parent) Adds an item to the tree.
DefaultMutableTreeNode	insertItemAt(String title, Object value, DefaultMutableTreeNode parent) Adds an item to the tree, specifying both the display and storage values.
void	loadFromRowCursor(AgiRowCursor rc, int displaycol, int valuecol) Creates tree items from an AgiRowCursor source.
void	removeAllItems() Removes all items from the tree, except the root node.
void	setValue(Object value) Selects the item whose value matches the specified value.

Methods inherited from class javax.swing.JTree

addSelectionInterval, addSelectionPath, addSelectionPaths, addSelectionRow, addSelectionRows, addTreeExpansionListener, addTreeSelectionListener, addTreeWillExpandListener, cancelEditing, clearSelection, clearToggledPaths, collapsePath, collapseRow, convertValueToText, createTreeModel, createTreeModelListener, expandPath, expandRow, fireTreeCollapsed, fireTreeExpanded, fireTreeWillCollapse, fireTreeWillExpand, fireValueChanged, getAccessibleContext, getCellEditor, getCellRenderer, getClosestPathForLocation, getClosestRowForLocation, getDefaultTreeModel, getDescendantToggledPaths, getEditingPath, getExpandedDescendants, getInvokesStopCellEditing, getLastSelectedPathComponent, getLeadSelectionPath, getLeadSelectionRow, getMaxSelectionRow, getMinSelectionRow, getModel, getPathBetweenRows, getPathBounds, getPathForLocation, getPathForRow, getPreferredScrollableViewportSize, getRowBounds, getRowCount, getRowForLocation, getRowForPath, getRowHeight, getScrollableBlockIncrement, getScrollableTracksViewportHeight, getScrollableTracksViewportWidth, getScrollableUnitIncrement, getScrollsOnExpand, getSelectionCount, getSelectionModel, getSelectionPath, getSelectionPaths, getSelectionRows, getShowsRootHandles, getToolTipText, getUI, getUIClassID, getVisibleRowCount, hasBeenExpanded, isCollapsed, isCollapsed, isEditable, isEditing, isExpanded, isExpanded, isFixedRowHeight, isLargeModel, isPathEditable, isPathSelected, isRootVisible, isRowSelected, isSelectionEmpty, isVisible, makeVisible, paramString, removeDescendantToggledPaths, removeSelectionInterval, removeSelectionPath, removeSelectionPaths, removeSelectionRow, removeSelectionRows, removeTreeExpansionListener, removeTreeSelectionListener, removeTreeWillExpandListener, scrollPathToVisible, scrollRowToVisible, setCellEditor, setCellRenderer, setEditable, setExpandedState, setInvokesStopCellEditing, setLargeModel, setModel, setRootVisible, setRowHeight, setScrollsOnExpand, setSelectionInterval, setSelectionModel, setSelectionPath, setSelectionPaths, setSelectionRow, setSelectionRows, setShowsRootHandles, setUI, setVisibleRowCount, startEditingAtPath, stopEditing, treeDidChange, updateUI

Methods inherited from class javax.swing.JComponent

addAncestorListener, addNotify, addPropertyChangeListener, addPropertyChangeListener, addVetoableChangeListener, computeVisibleRect, contains, createToolTip, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, fireVetoableChange, getActionForKeyStroke, getAlignmentX, getAlignmentY, getAutoscrolls, getBorder, getBounds, getClientProperty, getComponentGraphics, getConditionForKeyStroke, getDebugGraphicsOptions, getGraphics, getHeight, getInsets, getInsets, getLocation, getMaximumSize, getMinimumSize, getNextFocusableComponent, getPreferredSize, getRegisteredKeyStrokes, getRootPane, getSize, getToolTipLocation, getToolTipText, getTopLevelAncestor, getVisibleRect, getWidth, getX, getY, grabFocus, hasFocus, isDoubleBuffered, isFocusCycleRoot, isFocusTraversable, isLightweightComponent, isManagingFocus, isOpaque, isOptimizedDrawingEnabled, isPaintingTile, isRequestFocusEnabled, isValidateRoot, paint, paintBorder, paintChildren, paintComponent, paintImmediately, paintImmediately, print, printAll, processComponentKeyEvent, processFocusEvent, processKeyEvent, processMouseMotionEvent, putClientProperty, registerKeyboardAction, registerKeyboardAction, removeAncestorListener, removeNotify, removePropertyChangeListener, removePropertyChangeListener, removeVetoableChangeListener, repaint, repaint, requestDefaultFocus, requestFocus, resetKeyboardActions, reshape, revalidate, scrollRectToVisible, setAlignmentX, setAlignmentY, setAutoscrolls, setBackground, setBorder, setDebugGraphicsOptions, setDoubleBuffered, setEnabled, setFont, setForeground, setMaximumSize, setMinimumSize, setNextFocusableComponent, setOpaque, setPreferredSize, setRequestFocusEnabled, setToolTipText, setUI, setVisible, unregisterKeyboardAction, update

Methods inherited from class java.awt.Container

add, add, add, add, add, addContainerListener, addImpl, countComponents, deliverEvent, doLayout, findComponentAt, findComponentAt, getComponent, getComponentAt, getComponentAt, getComponentCount, getComponents, getLayout, insets, invalidate, isAncestorOf, layout, list, list, locate, minimumSize, paintComponents, preferredSize, printComponents, processContainerEvent, processEvent, remove, remove, removeAll, removeContainerListener, setCursor, setLayout, validate, validateTree

Methods inherited from class java.awt.Component

action, add, addComponentListener, addFocusListener, addInputMethodListener, addKeyListener, addMouseListener, addMouseMotionListener, bounds, checkImage, checkImage, coalesceEvents, contains, createImage, createImage, disable, disableEvents, dispatchEvent, enable, enable, enableEvents, enableInputMethods, getBackground, getBounds, getColorModel, getComponentOrientation, getCursor, getDropTarget, getFont, getFontMetrics, getForeground, getInputContext, getInputMethodRequests, getLocale, getLocation, getLocationOnScreen, getName, getParent, getPeer, getSize, getToolkit, getTreeLock, gotFocus, handleEvent, hide, imageUpdate, inside, isDisplayable, isEnabled, isLightweight, isShowing, isValid, isVisible, keyDown, keyUp, list, list, list, location, lostFocus, mouseDown, mouseDrag, mouseEnter, mouseExit, mouseMove, mouseUp, move, nextFocus, paintAll, postEvent, prepareImage, prepareImage, processComponentEvent, processInputMethodEvent, processMouseEvent, remove, removeComponentListener, removeFocusListener, removeInputMethodListener, removeKeyListener, removeMouseListener, removeMouseMotionListener, repaint, repaint, repaint, resize, resize, setBounds, setBounds, setComponentOrientation, setDropTarget, setLocale, setLocation, setLocation, setName, setSize, setSize, show, show, size, toString, transferFocus

Methods inherited from class java.lang.Object

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

Methods implemented from interface com.sssw.rt.form.AgiHelpInfo

getHelpInfo, setHelpInfo

Methods implemented from interface com.sssw.rt.util.AgiRowSetManager

clearRows, haveRowsChanged, query, query, refreshRows, updateRows

Methods implemented from interface javax.swing.event.TreeSelectionListener

valueChanged

Constructor Detail

AgcJTree

public AgcJTree()

Unlike the no-argument Swing JTree constructor, this AgcJTree constructor initializes the control with an empty DefaultTreeModel.

AgcJTree

public AgcJTree(Hashtable value)

Returns a tree control created from a Hashtable which does not display the root. Each value of the key/value pairs in the Hashtable becomes a child of the new root node. By default, the tree defines a leaf node as any node without children.

Parameters:

value - a Hashtable containing display and storage values for first-level nodes

AgcJTree

public AgcJTree(Object[] value)

Returns a tree control with each element of the specified array as the child of a new root node which is not displayed. By default, the tree defines a leaf node as any node without children.

Parameters:

value - an array of Objects where each Object becomes a first-level node

AgcJTree

public AgcJTree(Vector value)

Returns a tree control with each element of the specified Vector as the child of a new root node which is not displayed. By default, the tree defines a leaf node as any node without children.

Parameters:

value - a Vector containing display values for first-level nodes

AgcJTree

public AgcJTree(TreeNode root)

Returns a tree control with the specified TreeNode as its root, which displays the root node. The root node can refer to additional child nodes when you create the tree. By default, the tree defines a leaf node as any node without children.

Parameters:

root - a TreeNode

AgcJTree

public AgcJTree(TreeNode root,
                boolean asksAllowsChildren)

Returns a tree control with the specified TreeNode as its root, which displays the root node and which decides whether a node is a leaf node in the specified manner.

Parameters:

root - a TreeNode object

asksAllowsChildren - if false, any node without children is a leaf node. If true, only nodes that do not allow children are leaf nodes.

AgcJTree

public AgcJTree(TreeModel m)

Returns a tree control which displays the root node. The nodes of the tree are described by the specified data model.

Parameters:

m - the TreeModel to use as the data model

Method Detail

insertItemAt

public DefaultMutableTreeNode insertItemAt(Object obj,
                                           DefaultMutableTreeNode parent)

Adds an item to the tree. The return value is the path to the added node.

Parameters:

obj - an Object that is the displayed in the tree. The Object's toString method provides the display text.

parent - a DefaultMutableTreeNode that is the new node's parent

Returns:

A DefaultMutableTreeNode object that is the new node

Usage:

The item is added as the last child of the specified parent node. If the parent is null, then the new item is added as a child of the root node.

The way the model updates the control control differs between AgcJTree and JTree. JTree is the only Swing control that you need to explicitly tell to update after changing its model. You do this by calling nodeChanged, nodeStructureChanged, nodesWereInserted, or nodesWereRemoved, whichever is most appropriate, on the DefaultTableModel after making the actual change.

AgcJTree methods that modify the data (e.g. insert, etc) automatically tell the control to update. This is easier and less error-prone, but is inefficient if you're making lots of changes. For example, if you add 17 nodes, it will do this 17 times (though the control probably won't repaint 17 times). So if you are adding or changing many nodes, it is more efficient to modify the model and then call the appropriate update method yourself.

This method works only if the AgcJTree uses the default data model. AgcJTree uses the default data model when created with the empty constructor and no other model has been set.

See Also:

AgcJTree.insertItemAt(String, Object, DefaultMutableTreeNode), AgcJTree.addItem(Object)

insertItemAt

public DefaultMutableTreeNode insertItemAt(String title,
                                           Object value,
                                           DefaultMutableTreeNode parent)

Adds an item to the tree, specifying both the display and storage values. The return value is the path to the added node.

Parameters:

title - a String specifying the value to be displayed in the tree

value - an Object that is the data value associated with the node. When bound to a database column, Object is the data that is stored in the database.

parent - a DefaultMutableTreeNode that is the new node's parent

Returns:

A DefaultMutableTreeNode object that is the new node

Usage:

The item is added as the last child of the specified parent node. If the parent is null, then the new item is added as a child of the root node. Internally, SilverStream combines the two values into an AgoDisplayValue object, Methods of the TreeNode class that interact with the node's user data get an AgoDisplayValue object.

For information about how the control is updated when nodes change, see AgcJTree.insertItemAt(Object, DefaultMutableTreeNode).

This method works only if the AgcJTree uses the default data model. AgcJTree uses the default data model when created with the empty constructor and no other model has been set.

See Also:

AgcJTree.insertItemAt(Object, DefaultMutableTreeNode), AgcJTree.addItem(String, Object)

addItem

public DefaultMutableTreeNode addItem(String title,
                                      Object value)

Adds an item to the tree, specifying both the display and storage values. The return value is the path to the added node.

Parameters:

title - a String specifying the value to be displayed in the tree

value - an Object that is the data value associated with the node. When bound to a database column, Object is the data that is stored in the database.

Returns:

A DefaultMutableTreeNode object that is the new node

Usage:

Equivalent to insertItemAt(title, value, null).

For information about how the control is updated when nodes change, see AgcJTree.insertItemAt(Object, DefaultMutableTreeNode).

This method works only if the AgcJTree uses the default data model. AgcJTree uses the default data model when created with the empty constructor and no other model has been set.

See Also:

AgcJTree.addItem(Object), AgcJTree.insertItemAt(String, Object, DefaultMutableTreeNode)

addItem

public DefaultMutableTreeNode addItem(Object obj)

Adds an item to the tree. The return value is the path to the added node.

Parameters:

obj - an Object that is the displayed in the tree. The Object's toString method provides the display text.

Returns:

A DefaultMutableTreeNode object that is the new node

Usage:

Equivalent to insertItemAt(obj, null).

For information about how the control is updated when nodes change, see AgcJTree.insertItemAt(Object, DefaultMutableTreeNode).

This method works only if the AgcJTree uses the default data model. AgcJTree uses the default data model when created with the empty constructor and no other model has been set.

See Also:

AgcJTree.addItem(String, Object), AgcJTree.insertItemAt(Object, DefaultMutableTreeNode)

removeAllItems

public void removeAllItems()

Removes all items from the tree, except the root node.

Usage:

This method works only if the AgcJTree uses the default data model. AgcJTree uses the default data model when created with the empty constructor and no other model has been set.

getValue

public Object getValue()

Gets the value of the selected item.

Returns:

an Object that is the storage value of the selected item

See Also:

AgcJTree.setValue(Object)

setValue

public void setValue(Object value)

Selects the item whose value matches the specified value.

Parameters:

value - an Object whose value matches the value of the item you want to select

See Also:

AgcJTree.getValue()

loadFromRowCursor

public void loadFromRowCursor(AgiRowCursor rc,
                              int displaycol,
                              int valuecol)
                       throws AgoSecurityException,
                              AgoTransientSystemException,
                              AgoUnrecoverableSystemException

Creates tree items from an AgiRowCursor source. The table populates the first level of the tree's hierarchy. Each row becomes a child node of the root node. This is similar to specifying in the Form Designer that you want to load values from a table.

Parameters:

rc - the AgiRowCursor object whose data you want to be nodes in the tree

displaycol - an int specifying the number of a column in the AgiRowCursor object whose values will be the display values for the nodes

valuecol - an int specifying the number of a column in the AgiRowCursor object whose values will be the storage values for the nodes