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


Copyright © 2001 by University of Maryland, College Park, MD 20742, USA All rights reserved.