All Packages  Class Hierarchy  This Package  Previous  Next  Index

Class tea.set.Forest

java.lang.Object
   |
   +----java.awt.Component
           |
           +----java.awt.Canvas
                   |
                   +----tea.set.Forest

public class Forest
extends Canvas
implements ItemSelectable
Forest widget implements an tree interface. Because there could be multiple roots, hence the name Forest. There are two types of nodes in the tree: leaf nodes and non-leaf nodes. Leaf nodes don't have any child nodes of their own, and it's associated with a page icon. A non-leaf node has one or more child nodes, and it's associated with a folder icon. The icon for the nodes can be changed by users. There are three types of images: folder open, folder close, and leaf node. One or all of them can be changed by calling setImage() method. If the user supplied image is null, the icon will not be drawn for the specified type. Image can also be specified for individual nodes. The node image overrides forest wide image.

Each node in the tree must have a name. The naming of the tree nodes is similar to a file path, but instead of using slash or back-slash, a dot is used to separate the components. For example, a root node can have a name "root", and it can have a child with name "root.child1". In turn this child can have another child "root.child1.grandchild1". This naming scheme is used to decide where to place a new node in the add(String) method. If one or more nonleaf nodes don't exist when a node is added, they are created automatically. Therefore, to create "root.child1.grandchild1", only one call is needed to create the entire branch.

The separator can be changed from the default '.' to any charactor by calling setSeparator() method. This method must be called before any node is added to the tree.

A subtree(folder) can be expended(open) or collapsed(close) by clicking on the subtree root node. If IconOnly option is set to true, then open/close operations are only performed if mouse click is inside the node icon area, not the entire node. When a node is selected, an ItemEvent.SELECTED is generated with item equaling the node selected. If mouse is double clicked, an ActionEvent.ACTION_PERFORMED is also generated with the same information.

Forest supports the following properties:
Property NameProperty TypeDescription
Separatorchar Separator character used to separate nodes in a tree path.
IconOnlyboolean True if only expend or collapse subtrees when mouse click happens inside the node icon.
Styleint Forest style flag.
SelectedLabelString (Readonly) Label of the currently selected node.
SelectedPathString (Readonly) Path of the currently selected node.
SelectedObjectsObject[] (Readonly) List of selected node paths.
MultiSelectboolean Multiple selection flag.

Forest generates the following events:
Event TypeEvent IDGenerated Description
ObjActionEventActionEvent.ACTION_PERFORMED Mouse double click on a node. ActionEvent.getActionCommand() is the path of the node. ObjActionEvent.getObject() points to the node.
ItemEventItemEvent.SELECTED Node selected ItemEvent.getItem() points to the selected node.
ItemEventItemEvent.DESELECTED Node deselected. ItemEvent.getItem() points to the deselected node.


Variable Index

 o eventMgr
EventMgr object handles added event processing and dispatching.
 o FOLDER_CLOSE
Folder closed image.
 o FOLDER_LEAF
Leaf node image.
 o FOLDER_OPEN
Folder openned image.
 o LINE
Display lines connecting parent nodes to their children nodes.
 o LINE_BOX
Display lines and a box with plus or minus sign for every non-leaf node.
 o NO_LINE
Display nodes without connecting them with lines.

Constructor Index

 o Forest()
Construct a Forest widget defaults to NO_LINE option.
 o Forest(int)
Construct a Forest widget with the specified style.
 o Forest(int, boolean)
Construct a Forest widget with the specified style and behavior.

Method Index

 o add(String)
Add a node to the forest.
 o addActionListener(ActionListener)
Add an action listener.
 o addItemListener(ItemListener)
Add an item listener.
 o deselect(String)
De-select(dehighlight) the specified node.
 o doLayout()
This function is called automatically to layout the tree nodes.
 o findNode(String, boolean)
Find the node with the specified path.
 o forceOpen(String, boolean)
Set the force open mode on or off on the node pointed to by path.
 o getImage(int)
Return a folder image.
 o getMinimumSize()
Return the minimum size of the forest.
 o getPreferredSize()
Return the preferred size of the forest.
 o getRoot(int)
Return the root node of the specified tree.
 o getRootCount()
Return the number of trees in the forest.
 o getSelectedIndexes()
This method always returns null.
 o getSelectedLabel()
Return the label of the node selected.
 o getSelectedObjects()
Returns the list of node paths that are currently selected.
 o getSelectedPath()
Return the path of the node selected.
 o getSeparator()
Return the current separator.
 o getStyle()
Return the Forest style.
 o hide(String)
Hide the specified node and its children.
 o hide(String, int)
Hide the specified node.
 o isIconOnly()
Return the icon only flag.
 o isMultiSelect()
Get multiple selection status.
 o locateNode(int, int)
Locate the node where the (x, y) coordinate is in.
 o paint(Graphics)
Paint the forest.
 o processActionEvent(ActionEvent)
Process and dispatch action event.
 o processEvent(AWTEvent)
Process and dispatch event.
 o processItemEvent(ItemEvent)
Handle and translate events.
 o processMouseEvent(MouseEvent)
Process mouse event to handle node selection and tree expension/ collapsing.
 o remove(String)
Remove the specified node and its subtree.
 o removeActionListener(ActionListener)
Remove an action listener.
 o removeAll()
Remove all nodes from the tree.
 o removeItemListener(ItemListener)
Remove an item listener.
 o select(String)
Select(highlight) the specified node.
 o setIconOnly(boolean)
Set folder open/close behavior.
 o setImage(Image, int)
Set the image for tree nodes.
 o setImage(String, Image)
Set the image icon for the specified node.
 o setMultiSelect(boolean)
Enabled or disable multiple node selection.
 o setSeparator(char)
Set the separator to the new charactor.
 o setStyle(int)
Set the display style of this Forest to either LINE, LINE_BOX, or NO_LINE.
 o show(int)
Show the nodes in the first 'level' levels.
 o show(String)
Show the specified node.
 o show(String, int)
Show the specified node.
 o showAll()
Show all nodes in the trees.
 o update(Graphics)
Overriden for double buffering.

Variables

 o NO_LINE
 public static final int NO_LINE
Display nodes without connecting them with lines. This is the default.

 o LINE
 public static final int LINE
Display lines connecting parent nodes to their children nodes.

 o LINE_BOX
 public static final int LINE_BOX
Display lines and a box with plus or minus sign for every non-leaf node.

 o FOLDER_OPEN
 public static final int FOLDER_OPEN
Folder openned image.

 o FOLDER_CLOSE
 public static final int FOLDER_CLOSE
Folder closed image.

 o FOLDER_LEAF
 public static final int FOLDER_LEAF
Leaf node image.

 o eventMgr
 protected EventMgr eventMgr
EventMgr object handles added event processing and dispatching.

Constructors

 o Forest
 public Forest()
Construct a Forest widget defaults to NO_LINE option.

 o Forest
 public Forest(int style)
Construct a Forest widget with the specified style.

Parameters:
style - line option.
 o Forest
 public Forest(int style,
               boolean iconOnly)
Construct a Forest widget with the specified style and behavior.

Parameters:
style - line option.
iconOnly - only open/close folder if clicked in icon. Default is entire node.

Methods

 o getSeparator
 public char getSeparator()
Return the current separator.

Returns:
separator charactor.
 o setSeparator
 public synchronized void setSeparator(char separator)
Set the separator to the new charactor. This method must be called before any node is added to the forest.

 o setIconOnly
 public synchronized void setIconOnly(boolean t)
Set folder open/close behavior. Only affect subsequent nodes. Existing nodes are not changed. If icon only option is true, subtrees are openned/closed only when the mouse click is inside the node image icon.

Parameters:
t - true if only open/close folder if click in node icon.
 o isIconOnly
 public boolean isIconOnly()
Return the icon only flag.

Returns:
true if icon only is set.
 o setStyle
 public synchronized void setStyle(int style)
Set the display style of this Forest to either LINE, LINE_BOX, or NO_LINE.

Parameters:
style - line option.
 o getStyle
 public int getStyle()
Return the Forest style.

Returns:
forest style flag.
 o add
 public synchronized void add(String path)
Add a node to the forest. If the nodes in the middle of the path don't exist, they are created automatically. Nothing is done if the node already exists in the tree.

Parameters:
path - node path, node names from root to the node separated by the separator.
 o select
 public synchronized void select(String path)
Select(highlight) the specified node.

Parameters:
path - node path, node names from root to the node separated by the separator.
 o deselect
 public synchronized void deselect(String path)
De-select(dehighlight) the specified node.

Parameters:
path - node path, node names from root to the node separated by the separator.
 o show
 public void show(String path)
Show the specified node.

Parameters:
path - node path, node names from root to the node separated by the separator.
 o show
 public synchronized void show(String path,
                               int level)
Show the specified node. Level must be greater than or equal to zero. If level is greater than zero, the child nodes in the next "level" levels will also be shown.

Parameters:
path - node path, node names from root to the node separated by the separator.
level - tree level.
 o forceOpen
 public synchronized void forceOpen(String path,
                                    boolean t)
Set the force open mode on or off on the node pointed to by path. If force open is true, the node will always be open (the next level shown).

Parameters:
path - node path, node names from root to the node separated by the separator.
t - true to force node always open.
 o show
 public synchronized void show(int level)
Show the nodes in the first 'level' levels. This method should be called after all add() has been done.

Parameters:
level - tree level.
 o showAll
 public synchronized void showAll()
Show all nodes in the trees.

 o hide
 public void hide(String path)
Hide the specified node and its children.

Parameters:
path - node path, node names from root to the node separated by the separator.
 o hide
 public synchronized void hide(String path,
                               int level)
Hide the specified node. If level is zero, the node pointed by to path and all its children will be hiden. If level is greater than zero, only those node "level" levels below the specified node will be hiden.

Parameters:
path - node path, node names from root to the node separated by the separator.
level - tree level.
 o remove
 public synchronized void remove(String path)
Remove the specified node and its subtree.

Parameters:
path - node path, node names from root to the node separated by the separator.
 o removeAll
 public synchronized void removeAll()
Remove all nodes from the tree.

 o getSelectedLabel
 public synchronized String getSelectedLabel()
Return the label of the node selected.

Returns:
label of selected node.
 o getSelectedPath
 public synchronized String getSelectedPath()
Return the path of the node selected. It is the labels from the root of the tree to the selected node concatenated together separated by the current separator.

Returns:
path of selected node.
 o getSelectedIndexes
 public int[] getSelectedIndexes()
This method always returns null.

 o getSelectedObjects
 public synchronized Object[] getSelectedObjects()
Returns the list of node paths that are currently selected.

 o setMultiSelect
 public synchronized void setMultiSelect(boolean f)
Enabled or disable multiple node selection.

Parameters:
f - true to enable multiple node selection.
 o isMultiSelect
 public boolean isMultiSelect()
Get multiple selection status.

Returns:
true if multiple select is enabled.
 o setImage
 public synchronized void setImage(Image img,
                                   int type)
Set the image for tree nodes. The type parameter specifies the type of image to change: FOLDER_OPEN specifies the image used when folder is open; FOLDER_CLOSE specifies the image used when folder is closed; FOLDER_LEAF specifies the leaf node image. The images are set for all existing nodes and subsequent nodes. If image is set to null, no icon will be drawn for the specified node type.

Parameters:
img - node imae.
type - type of image, FOLDER_OPEN, FOLDER_CLOSE, or FOLDER_LEAF.
 o setImage
 public synchronized void setImage(String path,
                                   Image image)
Set the image icon for the specified node.

Parameters:
path - node full path.
image - node image.
 o getRootCount
 public int getRootCount()
Return the number of trees in the forest.

Returns:
number of roots.
 o getRoot
 public Node getRoot(int idx)
Return the root node of the specified tree.

Parameters:
idx - tree index, between 0 and getRootCount()-1.
Returns:
the root node of the specified tree.
 o locateNode
 public synchronized Node locateNode(int x,
                                     int y)
Locate the node where the (x, y) coordinate is in.

Parameters:
x - x coordinate.
y - y coordinate.
Returns:
node.
 o findNode
 public Node findNode(String path,
                      boolean createit)
Find the node with the specified path. If the path does not exist, null is returned, or it can be optionally created. This does not call layout or repaint. Explicit call to them are necessary.

Parameters:
path - node full path.
Returns:
node object.
 o getImage
 public Image getImage(int type)
Return a folder image. This method must be called after the component has been added to a parent and fully validated. Otherwise a null will be returned.

Parameters:
type - the image type: FOLDER_OPEN, FOLDER_CLOSE, or FOLDER_LEAF.
Returns:
folder image.
 o getMinimumSize
 public synchronized Dimension getMinimumSize()
Return the minimum size of the forest.

Returns:
minimum size of forest.
Overrides:
getMinimumSize in class Component
 o getPreferredSize
 public Dimension getPreferredSize()
Return the preferred size of the forest.

Returns:
preferred size of forest.
Overrides:
getPreferredSize in class Component
 o doLayout
 public void doLayout()
This function is called automatically to layout the tree nodes. The user of this class need not to call it explicitly.

Overrides:
doLayout in class Component
 o paint
 public void paint(Graphics g)
Paint the forest.

Parameters:
g - Graphics content of this component.
Overrides:
paint in class Canvas
 o update
 public void update(Graphics g)
Overriden for double buffering.

Parameters:
g - Graphics content of this component.
Overrides:
update in class Component
 o addActionListener
 public void addActionListener(ActionListener listener)
Add an action listener.

Parameters:
listener - action listener.
 o removeActionListener
 public void removeActionListener(ActionListener listener)
Remove an action listener.

Parameters:
listener - action listener.
 o addItemListener
 public void addItemListener(ItemListener listener)
Add an item listener.

Parameters:
listener - item listener.
 o removeItemListener
 public void removeItemListener(ItemListener listener)
Remove an item listener.

Parameters:
listener - item listener.
 o processEvent
 public void processEvent(AWTEvent e)
Process and dispatch event.

Parameters:
e - event object.
Overrides:
processEvent in class Component
 o processActionEvent
 public void processActionEvent(ActionEvent e)
Process and dispatch action event.

Parameters:
e - action event.
 o processItemEvent
 public void processItemEvent(ItemEvent e)
Handle and translate events. An ItemEvent.SELECTED event is generated when a node is highlighted. If an user double clicks on a node, an ACTION event is also generated.

Parameters:
e - item event.
 o processMouseEvent
 public void processMouseEvent(MouseEvent e)
Process mouse event to handle node selection and tree expension/ collapsing.

Overrides:
processMouseEvent in class Component

All Packages  Class Hierarchy  This Package  Previous  Next  Index