edu.umd.cs.jazz
Class ZGroup

java.lang.Object
  |
  +--edu.umd.cs.jazz.ZSceneGraphObject
        |
        +--edu.umd.cs.jazz.ZNode
              |
              +--edu.umd.cs.jazz.ZGroup

All Implemented Interfaces:

java.io.Serializable, ZSerializable

Direct Known Subclasses:

ZFadeGroup, ZInvisibleGroup, ZLayerGroup, ZRoot, ZTransformGroup, ZVisualGroup

public class ZGroup

extends ZNode

implements ZSerializable, java.io.Serializable

ZGroup is the basic hierarchial node. It has zero or more child nodes.

See Also:

Serialized Form

Field Summary

static boolean	childrenFindable_DEFAULT
static boolean	childrenPickable_DEFAULT
static boolean	hasOneChild_DEFAULT

Fields inherited from class edu.umd.cs.jazz.ZNode

findable_DEFAULT, listenerList, pickable_DEFAULT, savable_DEFAULT

Fields inherited from class edu.umd.cs.jazz.ZSceneGraphObject

bounds, objRefTable, volatileBounds_DEFAULT

Constructor Summary

ZGroup()
Constructs an empty ZGroup.

ZGroup(ZNode child)
Constructs a new group node with the specified node as a child of the new group.

Method Summary

void	addChild(ZNode child) Add a node to be a new child of this group node.
void	addGroupListener(ZGroupListener l) Adds the specified group listener to receive group events from this node
java.lang.Object	clone() Duplicates the current node by using the copy constructor.
protected void	computeBounds() Recomputes and caches the bounds for this node.
java.lang.String	dump() Generate a string that represents this object for debugging.
void	duplicateObject(ZGroup refNode) Copies all object information from the reference object into the current object.
protected void	fireGroupEvent(int id, ZNode child) Notifies all listeners that have registered interest for notification on this event type.
ZNode	getChild(int i) Returns the i'th child of this node.
ZNode[]	getChildren() Return a copy of the array of children of this node.
boolean	getChildrenFindable() Determines if this node finds its children.
java.util.Iterator	getChildrenIterator() Return an iterator over the children of this group in the proper order.
boolean	getChildrenPickable() Determines if this node picks its children.
int	getNumChildren() Return the number of children of this group node.
boolean	hasOneChild() Determines if this group node can have no more than one child
int	indexOf(ZNode child) Searches for the first occurence of the given child in the children of this node.
void	insertAbove(ZNode child) Insert this group node above the specified node.
void	lower(ZNode child) Lowers the specified child node within the drawing order of this node's children, so it gets rendered below (before) all of its siblings.
void	lowerTo(ZNode child, ZNode beforeNode) Lowers the specified child node within the drawing order of this node's siblings, so it gets rendered below (before) the specified node.
boolean	pick(java.awt.geom.Rectangle2D rect, ZSceneGraphPath path) Returns the first object under the specified rectangle (if there is one) in the subtree rooted with this as searched in reverse (front-to-back) order.
void	raise(ZNode child) Raises the specified child node within the drawing order of this node's children, so it gets rendered above (after) all of its siblings.
void	raiseTo(ZNode child, ZNode afterNode) Raises the specified child node within the drawing order of this node's siblings, so it gets rendered above (after) the specified node.
void	remove() Remove this node from the tree, merging the nodes above and below it.
void	removeChild(ZNode child) Remove the specified child node from this group node.
void	removeGroupListener(ZGroupListener l) Removes the specified group listener so that it no longer receives group events from this group.
void	render(ZRenderContext renderContext) Renders this node which results in its children getting painted.
void	setChildrenFindable(boolean childrenFindable) Specifies whether this node should find its children.
void	setChildrenPickable(boolean childrenPickable) Specifies whether this node should pick its children.
void	setHasOneChild(boolean oneChild) Specifies if this group is only allowed to have a maxium of one child.
void	setState(java.lang.String fieldType, java.lang.String fieldName, java.lang.Object fieldValue) Set some state of this object as it gets read back in.
void	trimToSize() Trims the capacity of the array that stores the children list points to the actual number of points.
protected void	updateVolatility() Internal method to compute and cache the volatility of a node, to recursively call the parents to compute volatility.
void	writeObject(ZObjectOutputStream out) Write out all of this object's state.
void	writeObjectRecurse(ZObjectOutputStream out) Specify which objects this object references in order to write out the scenegraph properly

Methods inherited from class edu.umd.cs.jazz.ZNode

addClientProperty, addMouseListener, addMouseMotionListener, duplicateObject, editor, fireMouseEvent, getClientProperty, getGlobalBounds, getGlobalToLocalTransform, getLocalToGlobalTransform, getParent, getRoot, globalToLocal, globalToLocal, hasMouseListener, isAncestorOf, isDescendentOf, isFindable, isPickable, isSavable, localToGlobal, localToGlobal, lower, lowerTo, putClientProperty, raise, raiseTo, removeMouseListener, removeMouseMotionListener, repaint, repaint, reparent, replaceWith, setEditorFactory, setFindable, setParent, setPickable, setSavable, updateBounds, updateObjectReferences, writeReplace

Methods inherited from class edu.umd.cs.jazz.ZSceneGraphObject

duplicateObject, getBounds, getVolatileBounds, reshape, setVolatileBounds

Methods inherited from class java.lang.Object

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

Field Detail

childrenPickable_DEFAULT

public static final boolean childrenPickable_DEFAULT

childrenFindable_DEFAULT

public static final boolean childrenFindable_DEFAULT

hasOneChild_DEFAULT

public static final boolean hasOneChild_DEFAULT

Constructor Detail

ZGroup

public ZGroup()

Constructs an empty ZGroup.

ZGroup

public ZGroup(ZNode child)

Constructs a new group node with the specified node as a child of the new group. If the specified child was already a member of a tree (i.e., had a parent), then this new node is inserted in the tree above the child so that the original child is still in that tree, but with this node inserted in the middle of the tree. If the specified child does not have a parent, then it is just made a child of this node.

Parameters:

child - Child of the new group node.

Method Detail

duplicateObject

public void duplicateObject(ZGroup refNode)

Copies all object information from the reference object into the current object. This method is called from the clone method. All ZSceneGraphObjects objects contained by the object being duplicated are duplicated, except parents which are set to null. This results in the sub-tree rooted at this object being duplicated.

Parameters:

refNode - The reference node to copy

clone

public java.lang.Object clone()

Duplicates the current node by using the copy constructor. The portion of the reference node that is duplicated is that necessary to reuse the node in a new place within the scenegraph, but the new node is not inserted into any scenegraph. The node must be attached to a live scenegraph (a scenegraph that is currently visible) or be registered with a camera directly in order for it to be visible.

In particular, all the children of this node will be cloned so that the entire subtree rooted at this group node will be duplicated.

Overrides:

clone in class ZNode

Returns:

A copy of this node.

See Also:

ZNode.updateObjectReferences(edu.umd.cs.jazz.util.ZObjectReferenceTable)

trimToSize

public void trimToSize()

Trims the capacity of the array that stores the children list points to the actual number of points. Normally, the children list arrays can be slightly larger than the number of points in the children list. An application can use this operation to minimize the storage of a children list.

Overrides:

trimToSize in class ZNode

insertAbove

public void insertAbove(ZNode child)

Insert this group node above the specified node. If the child node already had a parent, then this node will be properly inserted inbetween the original parent and the child. If this node already had a parent, then it will be removed before being inserted. If this node already had children, then they will be left alone, and the new child will be the last child of this node.

Parameters:

child - the child node that this node should go above.

indexOf

public int indexOf(ZNode child)

Searches for the first occurence of the given child in the children of this node.

Parameters:

child - The child to search for

Returns:

The index of the child, or -1 if not found

remove

public void remove()

Remove this node from the tree, merging the nodes above and below it. If this node has a parent, then this node's children will be added to that parent's children in the same position this node was in. If this node doesn't have a parent, then its children will just be removed from it.

addChild

public void addChild(ZNode child)

Add a node to be a new child of this group node. The new node is added to the end of the list of this node's children. If child was previously a child of another node, it is removed from that first.

If this group has 'hasOneChild' set, and if adding this child would result in there being more than one child, then a ZTooManyChildrenException is thrown.

Parameters:

child - The new child node.

removeChild

public void removeChild(ZNode child)

Remove the specified child node from this group node. If the specified node wasn't a child of this node, then nothing happens.

Parameters:

child - The child to be removed.

getChildren

public ZNode[] getChildren()

Return a copy of the array of children of this node. This method always returns an array, even when there are no children.

Returns:

the children of this node.

getChildrenIterator

public java.util.Iterator getChildrenIterator()

Return an iterator over the children of this group in the proper order.

Returns:

the iterator

getChild

public ZNode getChild(int i)

Returns the i'th child of this node.

getNumChildren

public int getNumChildren()

Return the number of children of this group node.

Returns:

the number of children.

raise

public void raise(ZNode child)

Raises the specified child node within the drawing order of this node's children, so it gets rendered above (after) all of its siblings. This is done by moving the child node to the end of this node's children list.

raiseTo

public void raiseTo(ZNode child,
                    ZNode afterNode)

Raises the specified child node within the drawing order of this node's siblings, so it gets rendered above (after) the specified node. This is done by moving this node just after the specified node in its parent's child list. If the specified node is not a child of this, then this call does nothing.

If the specified reference node is null, then this node is raised to be the last node rendered of its siblings (i.e., equivalent to calling {link #raise}

Parameters:

afterNode - The node to raise this node after.

lower

public void lower(ZNode child)

Lowers the specified child node within the drawing order of this node's children, so it gets rendered below (before) all of its siblings. This is done by moving the child node to the end of this node's children list.

lowerTo

public void lowerTo(ZNode child,
                    ZNode beforeNode)

Lowers the specified child node within the drawing order of this node's siblings, so it gets rendered below (before) the specified node. This is done by moving this node just before the specified node in its parent's child list. If the specified node is not a child of this, then this call does nothing.

If the specified reference node is null, then this node is lowered to be the first node rendered of its siblings (i.e., equivalent to calling {link #lower}

Parameters:

beforeNode - The node to lower this node before.

updateVolatility

protected void updateVolatility()

Internal method to compute and cache the volatility of a node, to recursively call the parents to compute volatility. A node is considered to be volatile if it is set to be volatile, or any of its descendants are volatile. All parents of this node are also volatile when this is volatile.

Overrides:

updateVolatility in class ZNode

See Also:

ZSceneGraphObject.setVolatileBounds(boolean), ZSceneGraphObject.getVolatileBounds()

setChildrenPickable

public void setChildrenPickable(boolean childrenPickable)

Specifies whether this node should pick its children. If this is true, then the pick() method will descend to group's children and will first pick them. If false, then the pick method will not pick children, and will only pick this node.

Parameters:

childrenPickable - True if this node should pick its children

See Also:

ZDrawingSurface.pick(int, int)

getChildrenPickable

public final boolean getChildrenPickable()

Determines if this node picks its children.

Returns:

True if this node picks its children.

setChildrenFindable

public void setChildrenFindable(boolean childrenFindable)

Specifies whether this node should find its children. If this is true, then the findNodes() method will descend to its children and will first find them. If false, then the find method will not find this node's children, and will only find this node. In any case, this or any other node is only findable if it satisfies the accept criteria of the find filter used in a find operation.

Parameters:

childrenFindable - True if this node should find its children

See Also:

ZDrawingSurface.findNodes(edu.umd.cs.jazz.util.ZFindFilter)

getChildrenFindable

public final boolean getChildrenFindable()

Determines if this node finds its children.

Returns:

True if this node finds its children.

setHasOneChild

public void setHasOneChild(boolean oneChild)

Specifies if this group is only allowed to have a maxium of one child. If it is true then a ZTooManyChildrenException will be thrown if an attempt to make this group have more than one child is made. This is typically used when an application wants to define a "decorator chain" which relates one group node to its child.

Jazz provides ZSceneGraphEditor to manage these decorator chains, and that class should be examined for more information.

Parameters:

oneChild - True if this node can have no more than one child

See Also:

ZSceneGraphEditor

hasOneChild

public final boolean hasOneChild()

Determines if this group node can have no more than one child

Returns:

True if this node can have no more than one child

See Also:

ZSceneGraphEditor

render

public void render(ZRenderContext renderContext)

Renders this node which results in its children getting painted.

The transform, clip, and composite will be set appropriately when this object is rendered. It is up to this object to restore the transform, clip, and composite of the Graphics2D if this node changes any of them. However, the color, font, and stroke are unspecified by Jazz. This object should set those things if they are used, but they do not need to be restored.

Overrides:

render in class ZNode

Parameters:

renderContext - The graphics context to use for rendering.

computeBounds

protected void computeBounds()

Recomputes and caches the bounds for this node. Generally this method is called by reshape when the bounds have changed, and it should rarely directly elsewhere. A ZGroup bounds is the union of its children's bounds

Overrides:

computeBounds in class ZSceneGraphObject

addGroupListener

public void addGroupListener(ZGroupListener l)

Adds the specified group listener to receive group events from this node

Parameters:

l - the group listener

removeGroupListener

public void removeGroupListener(ZGroupListener l)

Removes the specified group listener so that it no longer receives group events from this group.

Parameters:

l - the group listener

fireGroupEvent

protected void fireGroupEvent(int id,
                              ZNode child)

Notifies all listeners that have registered interest for notification on this event type. The event instance is lazily created using the parameters passed into the fire method. The listener list is processed in last to first order.

Parameters:

id - The event id (NODE_ADDED, NODE_REMOVED)

child - The child being added or removed from this node

See Also:

EventListenerList

pick

public boolean pick(java.awt.geom.Rectangle2D rect,
                    ZSceneGraphPath path)

Returns the first object under the specified rectangle (if there is one) in the subtree rooted with this as searched in reverse (front-to-back) order. This performs a depth-first search, first picking children. Only returns a node if this is "pickable".

If childrenPickable is false, then this will never return a child as the picked node. Instead, this node will be returned if any children are picked. If no children are picked, then this will return null.

Overrides:

pick in class ZNode

Parameters:

rect - Coordinates of pick rectangle in local coordinates

mag - The magnification of the camera being picked within.

Returns:

The picked node, or null if none

See Also:

dump

public java.lang.String dump()

Generate a string that represents this object for debugging.

Overrides:

dump in class ZNode

Returns:

the string that represents this object for debugging

See Also:

ZDebug.dump(edu.umd.cs.jazz.ZNode)

writeObject

public void writeObject(ZObjectOutputStream out)
                 throws java.io.IOException

Write out all of this object's state.

Specified by:

writeObject in interface ZSerializable

Overrides:

writeObject in class ZNode

Parameters:

out - The stream that this object writes into

writeObjectRecurse

public void writeObjectRecurse(ZObjectOutputStream out)
                        throws java.io.IOException

Specify which objects this object references in order to write out the scenegraph properly

Specified by:

writeObjectRecurse in interface ZSerializable

Overrides:

writeObjectRecurse in class ZNode

Parameters:

out - The stream that this object writes into

setState

public void setState(java.lang.String fieldType,
                     java.lang.String fieldName,
                     java.lang.Object fieldValue)

Set some state of this object as it gets read back in. After the object is created with its default no-arg constructor, this method will be called on the object once for each bit of state that was written out through calls to ZObjectOutputStream.writeState() within the writeObject method.

Specified by:

setState in interface ZSerializable

Overrides:

setState in class ZNode

Parameters:

fieldType - The fully qualified type of the field

fieldName - The name of the field

fieldValue - The value of the field