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.lang.Cloneable, java.io.Serializable, ZSerializable

Direct Known Subclasses:

ZClipGroup, ZFadeGroup, ZInvisibleGroup, ZLayerGroup, ZNameGroup, ZRoot, ZSpatialIndexGroup, ZTransformGroup, ZVisualGroup

public class ZGroup

extends ZNode

implements ZSerializable, java.io.Serializable

ZGroup is a node with children. Applications may use ZGroup to "group" children. By inserting a group node above several children, the group node can then be manipulated which will affect all of its children. Groups are typically used when several objects should be treated as a semantic unit.

Warning: Serialized and ZSerialized objects of this class will not be compatible with future Jazz releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Jazz. A future release of Jazz will provide support for long term persistence.

Author:

Ben Bederson

See Also:

Serialized Form

Field Summary

protected ZList.ZNodeList	children The array of children under this group node.
static boolean	childrenFindable_DEFAULT
static boolean	childrenPickable_DEFAULT
static boolean	hasOneChild_DEFAULT

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

findable_DEFAULT, pickable_DEFAULT, savable_DEFAULT, selectable_DEFAULT

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

bounds, listenerList, volatileBounds, 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.
protected void	addChildImpl(ZNode child, boolean fireEvent) The implementation of the addChild method
void	addChildren(java.util.Collection newChildren, boolean fireEvent) Adds a collection of nodes to be new children of this group node.
void	addGroupListener(ZGroupListener l) Adds the specified group listener to receive group events from this node.
void	childAddedNotification(ZNode child, boolean isModification) Notifies all listeners that have registered interest for notification on ZGroupEvents that a child has been added to the group, then percolates the event up scenegraph, notifying any listeners on any higher ZGroup nodes.
void	childRemovedNotification(ZNode child, boolean isModification) Notifies all listeners that have registered interest for notification on ZGroupEvents that a child has been removed from the group, then percolates the event up scenegraph, notifying any listeners on any higher ZGroup nodes.
protected void	computeBounds() Recomputes and caches the bounds for this node.
java.lang.String	dump() Generate a string that represents this object for debugging.
protected java.lang.Object	duplicateObject() Returns a clone of this object.
void	extract() Extract this node from the tree, merging the nodes above and below it.
protected int	findNodes(ZFindFilter filter, java.util.ArrayList nodes) Internal method to return the list of nodes that are accepted by the specified filter in the subtree rooted with this.
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.
ZNode[]	getChildrenReference() Returns a reference to the actual children of this node.
int	getNumChildren() Return the number of children of this group node.
ZBounds	getShallowBounds() Return the bounds of this ZGroup without taking the groups children into consideration.
boolean	getVolatileBounds() Determines if this node is volatile.
boolean	hasOneChild() Determines if this group node can have no more than one child
int	indexOf(ZNode child) Searches for the first occurrence of the given child in the children of this node.
void	insertAbove(ZNode child) Insert this group node above the specified node.
java.util.Iterator	iterator() Deprecated. use getChildrenIterator() instead.
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	removeAllChildren() Remove all chidren from this group node.
void	removeChild(int index) Remove the child at the specified position of this group node's children.
void	removeChild(ZNode child) Remove the specified child node from this group node.
protected void	removeChild(ZNode child, boolean fireEvent) Remove the specified child node from this group node.
protected void	removeChildImpl(int index, boolean fireEvent) The implementation of the removeChild method @param index The position of the child to be removed @param fireEvent Should the group event be fired
void	removeGroupListener(ZGroupListener l) Removes the specified group listener so that it no longer receives group events from this group.
void	removeNodeListener(ZNodeListener l) This method overriddes ZNode.removeNodeListener so as to properly update the hasNodeListener bit taking into consideration the ZGroup's children.
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.
void	updateHasNodeListener() Updates the hasNodeListener bit taking into consideration the ZGroup's children.
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, addNodeListener, editor, getClientProperty, getGlobalBounds, getGlobalToLocalTransform, getLocalToGlobalTransform, getParent, getRoot, globalToLocal, globalToLocal, hasNodeListener, isAncestorOf, isDescendentOf, isFindable, isPickable, isSavable, isSelectable, localToGlobal, localToGlobal, lower, lowerTo, percolateEventUpSceneGraph, putClientProperty, raise, raiseTo, remove, repaint, repaint, repaint, reparent, replaceWith, setEditorFactory, setFindable, setParent, setPickable, setSavable, setSelectable, updateBounds, updateObjectReferences, writeReplace

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

addMouseListener, addMouseMotionListener, clone, fireEvent, fireMouseEvent, getBounds, getBoundsReference, getListenerList, hasLisenerOfType, hasMouseListener, processMouseEvent, removeEventListener, removeMouseListener, removeMouseMotionListener, reshape, setBounds, 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

children

protected ZList.ZNodeList children

The array of children under this group node. This is guaranteed to point to a valid array, even if this group does not have any children.

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

protected java.lang.Object duplicateObject()

Returns a clone of this object.

Overrides:

duplicateObject in class ZNode

See Also:

ZSceneGraphObject.duplicateObject()

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 in between 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.

This method may fire NODE_ADDED or NODE_REMOVED ZGroupEvents. ZGroupEvents now contains a method isModificationEvent() to distinguish a modification event from a true node addition or removal. A modification event is one in which a node changes position in a single scenegraph or between two different scenegraphs. A true addition or removal event is one in which a node is first added to or removed from a scenegraph.

Parameters:

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

See Also:

ZGroupEvent

extract

public void extract()

Extract 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. Note that this method delays firing any necessary group events until the tree has been completely updated.

This method may fire NODE_ADDED or NODE_REMOVED ZGroupEvents. ZGroupEvents now contains a method isModificationEvent() to distinguish a modification event from a true node addition or removal. A modification event is one in which a node changes position in a single scenegraph or between two different scenegraphs. A true addition or removal event is one in which a node is first added to or removed from a scenegraph.

Overrides:

extract in class ZNode

See Also:

ZGroupEvent

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.

This method may fire NODE_ADDED or NODE_REMOVED ZGroupEvents. ZGroupEvents now contains a method isModificationEvent() to distinguish a modification event from a true node addition or removal. A modification event is one in which a node changes position in a single scenegraph or between two different scenegraphs. A true addition or removal event is one in which a node is first added to or removed from a scenegraph.

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.

See Also:

ZGroupEvent

addChildImpl

protected void addChildImpl(ZNode child,
                            boolean fireEvent)

The implementation of the addChild method

Parameters:

child - The child to be added

fireEvent - Should the group event be fired

addChildren

public void addChildren(java.util.Collection newChildren,
                        boolean fireEvent)

Adds a collection of nodes to be new children of this group node. If you are added a large number of children to a group this method will be much faster then repeatedly calling ZGroup's addChild method.

Parameters:

newChildren - The children to be added

fireEvent - Should the group event be fired for each child added.

removeAllChildren

public void removeAllChildren()

Remove all chidren from this group node. If the node has no children, then nothing happens.

This method may fire NODE_ADDED or NODE_REMOVED ZGroupEvents. ZGroupEvents now contains a method isModificationEvent() to distinguish a modification event from a true node addition or removal. A modification event is one in which a node changes position in a single scenegraph or between two different scenegraphs. A true addition or removal event is one in which a node is first added to or removed from a scenegraph.

Parameters:

child - The child to be removed.

See Also:

ZGroupEvent

removeChild

public void removeChild(int index)

Remove the child at the specified position of this group node's children. Any subsequent children are shifted to the left (one is subtracted from their indices).

This method may fire NODE_ADDED or NODE_REMOVED ZGroupEvents. ZGroupEvents now contains a method isModificationEvent() to distinguish a modification event from a true node addition or removal. A modification event is one in which a node changes position in a single scenegraph or between two different scenegraphs. A true addition or removal event is one in which a node is first added to or removed from a scenegraph.

Parameters:

index - The position of the child node to be removed.

See Also:

ZGroupEvent

removeChild

protected void removeChild(ZNode child,
                           boolean fireEvent)

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

This method may fire NODE_ADDED or NODE_REMOVED ZGroupEvents. ZGroupEvents now contains a method isModificationEvent() to distinguish a modification event from a true node addition or removal. A modification event is one in which a node changes position in a single scenegraph or between two different scenegraphs. A true addition or removal event is one in which a node is first added to or removed from a scenegraph.

Parameters:

child - The child to be removed.

fireEvent - Should the group event be fired.

See Also:

ZGroupEvent

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.

This method may fire NODE_ADDED or NODE_REMOVED ZGroupEvents. ZGroupEvents now contains a method isModificationEvent() to distinguish a modification event from a true node addition or removal. A modification event is one in which a node changes position in a single scenegraph or between two different scenegraphs. A true addition or removal event is one in which a node is first added to or removed from a scenegraph.

Parameters:

child - The child to be removed.

See Also:

ZGroupEvent

removeChildImpl

protected void removeChildImpl(int index,
                               boolean fireEvent)

The implementation of the removeChild method @param index The position of the child to be removed @param fireEvent Should the group event be fired

indexOf

public int indexOf(ZNode child)

Searches for the first occurrence 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

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

iterator

public java.util.Iterator iterator()

Deprecated. use getChildrenIterator() instead.

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.

Returns:

the i'th child of this node.

getChildrenReference

public ZNode[] getChildrenReference()

Returns a reference to the actual children of this node. It should not be modified by the caller. Note that the actual number of children could be less than the size of the array. Determine the actual number of children with getNumChildren().

Warning: This method returns a reference to an internal array. Any modification of this array will result in undefined behavior.

Returns:

the children 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.

Parameters:

child - the child node to be raised.

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 raise(edu.umd.cs.jazz.ZNode)

Parameters:

child - the child node to be raised.

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 front of this node's children list.

Parameters:

child - the child to be lowered.

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 lower(edu.umd.cs.jazz.ZNode)

Parameters:

child - the child to be lowered.

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), getVolatileBounds()

getVolatileBounds

public boolean getVolatileBounds()

Determines if this node is volatile. A node is considered to be volatile if it is specifically set to be volatile with ZSceneGraphObject.setVolatileBounds(boolean), or if any of its children are volatile. All parents of this node are also volatile when this is volatile.

Volatile objects are those objects that change regularly, such as an object that is animated, or one whose rendering depends on its context.

Overrides:

getVolatileBounds in class ZSceneGraphObject

Returns:

true if this node is volatile

See Also:

ZSceneGraphObject.setVolatileBounds(boolean)

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 the children of this node are findable.

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

getShallowBounds

public ZBounds getShallowBounds()

Return the bounds of this ZGroup without taking the groups children into consideration. For the class ZGroup this will always return an empty bounds. But for sublclasses such as ZVisualGroup it may return a non-empty bounds.

removeNodeListener

public void removeNodeListener(ZNodeListener l)

This method overriddes ZNode.removeNodeListener so as to properly update the hasNodeListener bit taking into consideration the ZGroup's children.

Overrides:

removeNodeListener in class ZNode

Parameters:

l - The node listener to be removed

updateHasNodeListener

public void updateHasNodeListener()

Updates the hasNodeListener bit taking into consideration the ZGroup's children. If the bit for this group changes, it notifies its parent.

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.

childAddedNotification

public void childAddedNotification(ZNode child,
                                   boolean isModification)

Notifies all listeners that have registered interest for notification on ZGroupEvents that a child has been added to the group, then percolates the event up scenegraph, notifying any listeners on any higher ZGroup nodes. The listener list is processed in last to first order.

Parameters:

child - The child being added or removed from this node

isModification - true if this is a modification event.

See Also:

EventListenerList, ZGroupEvent

childRemovedNotification

public void childRemovedNotification(ZNode child,
                                     boolean isModification)

Notifies all listeners that have registered interest for notification on ZGroupEvents that a child has been removed from the group, then percolates the event up scenegraph, notifying any listeners on any higher ZGroup nodes. The listener list is processed in last to first order.

Parameters:

child - The child being added or removed from this node

isModification - true if this is a modification event.

See Also:

EventListenerList, ZGroupEvent

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

path - The path through the scenegraph to the picked node. Modified by this call.

Returns:

The picked node, or null if none

See Also:

ZDrawingSurface.pick(int, int)

findNodes

protected int findNodes(ZFindFilter filter,
                        java.util.ArrayList nodes)

Internal method to return the list of nodes that are accepted by the specified filter in the subtree rooted with this. If this node is not "findable", then neither this node, nor any of its descendants will be included. The filter specifies whether or not this node should be accepted by the search, and whether the node's children should be searched.

If findChildren is false, then the children of this node are are not checked for being found, and only this node (possibly) is found.

Overrides:

findNodes in class ZNode

Parameters:

filter - The filter that decides whether or not to include individual nodes in the find list

nodes - the accumulation list (results will be place here).

Returns:

the number of nodes searched

See Also:

ZNode.isFindable(), ZFindFilter

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