edu.umd.cs.jazz
Class ZNode

java.lang.Object
  |
  +--edu.umd.cs.jazz.ZSceneGraphObject
        |
        +--edu.umd.cs.jazz.ZNode
All Implemented Interfaces:
java.lang.Cloneable, java.io.Serializable, ZSerializable
Direct Known Subclasses:
ZGroup, ZLeaf

public class ZNode
extends ZSceneGraphObject
implements ZSerializable, java.io.Serializable

ZNode is the common superclass of all objects in a Jazz scenegraph. It has very limited functionality, and primarily exists to support sub-classes.

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
static ZSceneGraphEditorFactory editorFactory
           
static boolean findable_DEFAULT
           
 ZGroup parent
          This node's parent.
static boolean pickable_DEFAULT
           
static boolean savable_DEFAULT
           
static boolean selectable_DEFAULT
           
 
Fields inherited from class edu.umd.cs.jazz.ZSceneGraphObject
bounds, inTransaction, invalidBounds, invalidVolatileBounds, listenerList, volatileBounds, volatileBounds_DEFAULT
 
Constructor Summary
ZNode()
          Constructs a new ZNode.
 
Method Summary
 void addNodeListener(ZNodeListener l)
          Adds the specified node listener to receive node events from this node.
protected  java.lang.Object duplicateObject()
          Returns a clone of this object.
 ZSceneGraphEditor editor()
          This returns a new instance of a ZSceneGraphEditor for this node.
 void extract()
          Extract this node from the tree, merging back in any children.
protected  int findNodes(ZFindFilter filter, java.util.ArrayList nodes)
          Internal method used to return the list of nodes that are accepted by the specified filter in the subtree rooted with this.
 ZBounds getGlobalBounds()
          Return a copy of the bounds of the subtree rooted at this node in global coordinates.
 java.awt.geom.AffineTransform getGlobalToLocalTransform()
          Return the transform that converts global coordinates at the root node to local coordinates at this node.
 java.awt.geom.AffineTransform getLocalToGlobalTransform()
          Return the transform that converts local coordinates at this node to global coordinates at the root node.
 ZGroup getParent()
          Get the node's parent.
 ZRoot getRoot()
          Traverse the tree, find the root node, and return it.
 double globalToLocal(java.awt.geom.Dimension2D aDimension)
          Transform the specified dimension (in global coordinates) to local coordinates in this node's coordinate system.
 double globalToLocal(java.awt.geom.Point2D pt)
          Transform the specified point (in global coordinates) to local coordinates in this node's coordinate system.
 double globalToLocal(java.awt.geom.Rectangle2D rect)
          Transform the specified rectangle (in global coordinates) to local coordinates in this node's coordinate system.
 boolean hasNodeListener()
          Determines if this node has a node listener.
 boolean isAncestorOf(ZNode queryNode)
          Method to determine if this is an ancenstor of queryNode.
 boolean isDescendentOf(ZNode queryNode)
          Method to determine if this is a descendent of queryNode.
 boolean isFindable()
          Determines if this node is findable.
 boolean isPickable()
          Determines if this node is pickable.
 boolean isSavable()
          Determine if this node gets saved when written out.
 boolean isSelectable()
          Determines if this node is selectable.
 double localToGlobal(java.awt.geom.Dimension2D aDimension)
          Transform the specified dimension (in this node's local coordinates) to global coordinates.
 double localToGlobal(java.awt.geom.Point2D pt)
          Transform the specified point (in this node's local coordinates) to global coordinates.
 double localToGlobal(java.awt.geom.Rectangle2D rect)
          Transform the specified rectangle (in this node's local coordinates) to global coordinates.
 void lower()
          Lowers this node within the drawing order of its siblings, so it gets rendered below (before) all of its siblings.
 void lowerTo(ZNode beforeNode)
          Lowers this node within the drawing order of its siblings, so it gets rendered below (before) the specified node.
protected  void percolateEventUpSceneGraph(ZEvent anEvent)
          Notifies all listeners that have registered interest for notification on this event type, percolate up the scenegraph looking for listeners.
 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()
          Raises this node within the drawing order of its siblings, so it gets rendered above (after) all of its siblings.
 void raiseTo(ZNode afterNode)
          Raises this node within the drawing order of its siblings, so it gets rendered above (after) the specified node.
 void remove()
          Remove this node, and any subtree, from the scenegraph.
 void removeNodeListener(ZNodeListener l)
          Removes the specified node listener so that it no longer receives node events from this node.
 void render(ZRenderContext renderContext)
          Renders this node.
 void repaint()
          Repaint causes the portions of the surfaces that this object appears in to be marked as needing painting, and queues events to cause those areas to be painted.
 void repaint(ZBounds repaintBounds)
          Method to pass repaint methods up the tree.
 void reparent(ZGroup newParent)
          Set the parent of this node, and transform the node in such a way that it doesn't move in global coordinates.
 void replaceWith(ZNode replacement)
          Swaps this node out of the scenegraph tree, and replaces it with the specified replacement node.
static void setEditorFactory(ZSceneGraphEditorFactory factory)
          Define how editors should be created.
 void setFindable(boolean findable)
          Specifies whether this node is findable.
 void setParent(ZGroup newParent)
          Set the parent of this node.
 void setPickable(boolean pickable)
          Specifies whether this node is pickable.
 void setSavable(boolean s)
          Specify if this node should be saved.
 void setSelectable(boolean selectable)
          Specifies whether this node is selectable.
 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 setVolatileBounds(boolean v)
          Specifies whether or not this node is volatile.
protected  void updateBounds()
          Internal method that causes this node and all of its ancestors to invalidate their bounds.
protected  void updateVolatility()
          Internal method that causes this node and all of its ancestors to invalidate their volatileBounds.
 void writeObject(ZObjectOutputStream out)
          Write out all of this object's state.
 ZSerializable writeReplace()
          Node doesn't get written out if save property is false
 
Methods inherited from class edu.umd.cs.jazz.ZSceneGraphObject
addClientProperty, addMouseListener, addMouseMotionListener, clone, computeBounds, computeVolatileBounds, dump, endTransaction, fireEvent, fireMouseEvent, getBounds, getBoundsReference, getClientProperty, getHandles, getListenerList, getVolatileBounds, hasLisenerOfType, hasListenerOfType, hasMouseListener, markInTransaction, markNotInTransaction, processMouseEvent, putClientProperty, removeEventListener, removeMouseListener, removeMouseMotionListener, reshape, setBounds, startTransaction, trimToSize, updateObjectReferences, writeObjectRecurse
 
Methods inherited from class java.lang.Object
equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 
Methods inherited from interface edu.umd.cs.jazz.io.ZSerializable
writeObjectRecurse
 

Field Detail

savable_DEFAULT

public static final boolean savable_DEFAULT
See Also:
Constant Field Values

pickable_DEFAULT

public static final boolean pickable_DEFAULT
See Also:
Constant Field Values

findable_DEFAULT

public static final boolean findable_DEFAULT
See Also:
Constant Field Values

selectable_DEFAULT

public static final boolean selectable_DEFAULT
See Also:
Constant Field Values

editorFactory

public static ZSceneGraphEditorFactory editorFactory

parent

public ZGroup parent
This node's parent.

Constructor Detail

ZNode

public ZNode()
Constructs a new ZNode. The node must be attached to a live scenegraph (a scenegraph that is currently visible) order for it to be visible.

Method Detail

addNodeListener

public void addNodeListener(ZNodeListener l)
Adds the specified node listener to receive node events from this node. Also updates the hasNodeListener bit.

Parameters:
l - the node listener

duplicateObject

protected java.lang.Object duplicateObject()
Returns a clone of this object.

Overrides:
duplicateObject in class ZSceneGraphObject
See Also:
ZSceneGraphObject.duplicateObject()

editor

public ZSceneGraphEditor editor()
This returns a new instance of a ZSceneGraphEditor for this node. ZSceneGraphEditor provides a convenience mechanism used to locate and create instances of several node types. The specific nodes supported are defined by the particular editor being used.

See Also:
ZSceneGraphEditor, ZSceneGraphEditorFactory

extract

public void extract()
Extract this node from the tree, merging back in any children. As ZNode's do not have any children, ZNode.extract() has the same function as ZNode.remove(). However, extract() on subclasses such as ZGroup truly extract a node, merging any children back into the scenegraph.

See Also:
ZGroup.extract()

findNodes

protected int findNodes(ZFindFilter filter,
                        java.util.ArrayList nodes)
Internal method used 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.

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:
isFindable(), ZFindFilter

getGlobalBounds

public ZBounds getGlobalBounds()
Return a copy of the bounds of the subtree rooted at this node in global coordinates. Note that global bounds are not cached, and this method involves some computation.

Returns:
The bounds of the subtree rooted at this node in global coordinates.

getGlobalToLocalTransform

public java.awt.geom.AffineTransform getGlobalToLocalTransform()
Return the transform that converts global coordinates at the root node to local coordinates at this node.

Returns:
The inverse of the concatenation of transforms from the root down to this node.

getLocalToGlobalTransform

public java.awt.geom.AffineTransform getLocalToGlobalTransform()
Return the transform that converts local coordinates at this node to global coordinates at the root node.

Returns:
The concatenation of transforms from the root down to this node.

getParent

public final ZGroup getParent()
Get the node's parent.


getRoot

public ZRoot getRoot()
Traverse the tree, find the root node, and return it.

Returns:
The root node of this scenegraph
See Also:
ZRoot

globalToLocal

public double globalToLocal(java.awt.geom.Dimension2D aDimension)
Transform the specified dimension (in global coordinates) to local coordinates in this node's coordinate system. The input dimension is modified by this method.

NOTE: Dimension2D's are abstract. When creating a new Dimension2D for use with Jazz we recoment that you use edu.umd.cs.util.ZDimension instead of java.awt.Dimension. ZDimension uses doubles internally, while java.awt.Dimension uses integers.

Returns:
dz The change in scale from global coordinates to the node's local coordinate system.
See Also:
localToGlobal(java.awt.geom.Dimension2D)

globalToLocal

public double globalToLocal(java.awt.geom.Point2D pt)
Transform the specified point (in global coordinates) to local coordinates in this node's coordinate system. The input point is modified by this method. It also returns the change in scale from the global coordinate system to the node's local coordinate system.

Returns:
dz The change in scale from global coordinates to the node's local coordinate system.
See Also:
localToGlobal(java.awt.geom.Dimension2D)

globalToLocal

public double globalToLocal(java.awt.geom.Rectangle2D rect)
Transform the specified rectangle (in global coordinates) to local coordinates in this node's coordinate system. The input rectangle is modified by this method. It also returns the change in scale from the global coordinate system to the node's local coordinate system.

Returns:
dz The change in scale from global coordinates to the node's local coordinate system.
See Also:
localToGlobal(java.awt.geom.Dimension2D)

hasNodeListener

public final boolean hasNodeListener()
Determines if this node has a node listener. If this node does not have a node listener, it will not receive global bounds events.


isAncestorOf

public boolean isAncestorOf(ZNode queryNode)
Method to determine if this is an ancenstor of queryNode.

Parameters:
queryNode - a possible descendent of node
Returns:
true of queryNode is an descendent of node.

isDescendentOf

public boolean isDescendentOf(ZNode queryNode)
Method to determine if this is a descendent of queryNode.

Parameters:
queryNode - a possible ancenstor of node
Returns:
true of queryNode is an ancestor of node.

isFindable

public final boolean isFindable()
Determines if this node is findable. When a node is not findable, it will be ignored by the ZNode find methods.

Returns:
True if this node is findable

isPickable

public final boolean isPickable()
Determines if this node is pickable. When a node is not pickable, it will be ignored by the ZNode pick methods that determine which object is under a point.

Returns:
True if this node is pickable

isSavable

public final boolean isSavable()
Determine if this node gets saved when written out.

Returns:
true if this node gets saved.

isSelectable

public final boolean isSelectable()
Determines if this node is selectable. When a node is not selectable, it will be ignored by the ZSelectionManager.

Returns:
True if this node is selectable

localToGlobal

public double localToGlobal(java.awt.geom.Dimension2D aDimension)
Transform the specified dimension (in this node's local coordinates) to global coordinates. The input dimension is modified by this method.

NOTE: Dimension2D's are abstract. When creating a new Dimension2D for use with Jazz we recoment that you use edu.umd.cs.util.ZDimension instead of java.awt.Dimension. ZDimension uses doubles internally, while java.awt.Dimension uses integers.

Returns:
dz The change in scale from global coordinates to the node's local coordinate system.
See Also:
globalToLocal(java.awt.geom.Dimension2D)

localToGlobal

public double localToGlobal(java.awt.geom.Point2D pt)
Transform the specified point (in this node's local coordinates) to global coordinates. The input point is modified by this method. It also returns the change in scale from the local coordinate system to global coordinates.

Returns:
dz The change in scale from global coordinates to the node's local coordinate system.
See Also:
globalToLocal(java.awt.geom.Dimension2D)

localToGlobal

public double localToGlobal(java.awt.geom.Rectangle2D rect)
Transform the specified rectangle (in this node's local coordinates) to global coordinates. The input rectangle is modified by this method. It also returns the change in scale from the local coordinate system to global coordinates.

Returns:
dz The change in scale from global coordinates to the node's local coordinate system.
See Also:
globalToLocal(java.awt.geom.Dimension2D)

lower

public void lower()
Lowers this node within the drawing order of its siblings, so it gets rendered below (before) all of its siblings. This is done by moving this node to the beginning of its parent's child list.


lowerTo

public void lowerTo(ZNode beforeNode)
Lowers this node within the drawing order of its 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 sibling of this, then this call does nothing.

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

Parameters:
beforeNode - The node to lower this node before.

percolateEventUpSceneGraph

protected void percolateEventUpSceneGraph(ZEvent anEvent)
Notifies all listeners that have registered interest for notification on this event type, percolate up the scenegraph looking for listeners. Stop when the event is consumed. The event instance is lazily created using the parameters passed into the fire method. The listener list is processed in last to first order.

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. Only returns "pickable" nodes.

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)

raise

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


raiseTo

public void raiseTo(ZNode afterNode)
Raises this node within the drawing order of its 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 sibling of this, then this call does nothing.

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

Parameters:
afterNode - The node to raise this node after.

remove

public void remove()
Remove this node, and any subtree, from the scenegraph.


removeNodeListener

public void removeNodeListener(ZNodeListener l)
Removes the specified node listener so that it no longer receives node events from this node. Also updates the hasNodeListener bit and notifies its parent of the change, if necessary.

Parameters:
l - the node listener

render

public void render(ZRenderContext renderContext)
Renders this node.

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.

Parameters:
renderContext - The graphics context to use for rendering.

repaint

public void repaint()
Repaint causes the portions of the surfaces that this object appears in to be marked as needing painting, and queues events to cause those areas to be painted. The painting does not actually occur until those events are handled. If this object is visible in multiple places because more than one camera can see this object, then all of those places are marked as needing painting.

Scenegraph objects should call repaint when their internal state has changed and they need to be redrawn on the screen.

Important note : Scenegraph objects should call reshape() instead of repaint() if the internal state change effects the bounds of the shape in any way (e.g. changing penwidth, selection, transform, adding points to a line, etc.)

Overrides:
repaint in class ZSceneGraphObject
See Also:
ZSceneGraphObject.reshape()

repaint

public void repaint(ZBounds repaintBounds)
Method to pass repaint methods up the tree. Repaints only the sub-portion of this object specified by the given ZBounds. Note that the input parameter may be modified as a result of this call.

Overrides:
repaint in class ZSceneGraphObject
Parameters:
repaintBounds - The bounds to repaint
See Also:
ZSceneGraphObject.reshape()

reparent

public void reparent(ZGroup newParent)
Set the parent of this node, and transform the node in such a way that it doesn't move in global coordinates. If the node does not already have a transform node associated with it, then one will be created. This method operates on the handle (top) node of a decorator chain.

This method may fire NODE_ADDED or NODE_REMOVED ZGroupEvents. ZGroupEvents now contain 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:
newParent - The new parent of this node.
See Also:
ZGroupEvent

replaceWith

public void replaceWith(ZNode replacement)
Swaps this node out of the scenegraph tree, and replaces it with the specified replacement node. This node is left dangling, and it is up to the caller to manage it. The replacement node will be added to this node's parent in the same position as this was. That is, if this was the 3rd child of its parent, then after calling replaceWith(), the replacement node will also be the 3rd child of its parent. If this node has no parent when replace is called, then nothing will be done at all.

Parameters:
replacement - the new node that replaces the current node in the scenegraph tree.

setEditorFactory

public static void setEditorFactory(ZSceneGraphEditorFactory factory)
Define how editors should be created. This specifies a factory that is used whenever an editor needs to be created.

Parameters:
factory - The new factory to create editors with.
See Also:
editor()

setFindable

public void setFindable(boolean findable)
Specifies whether this node is findable. When a node is not findable, it will be ignored by the ZNode find methods that search the scenegraph for nodes that satisfy some criteria.

Parameters:
findable - True if this node should be findable.

setParent

public void setParent(ZGroup newParent)
Set the parent of this node. If it already was in the tree, then this moves the node to a new place in the tree specified by the new parent. This is equivalent to removing this from its original parent, and adding it to its new parent.

Parameters:
newParent - The new parent of this node.

setPickable

public void setPickable(boolean pickable)
Specifies whether this node is pickable. When a node is not pickable, it will be ignored by the ZNode pick methods that determine which object is under a point.

Parameters:
pickable - True if this node should be pickable.

setSavable

public void setSavable(boolean s)
Specify if this node should be saved. If not, then all references to this will be skipped in saved files.

Parameters:
s - true if node should be saved

setSelectable

public void setSelectable(boolean selectable)
Specifies whether this node is selectable. When a node is not selectable, it will be ignored by the ZSelectionManager.


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 ZSceneGraphObject
Parameters:
fieldType - The fully qualified type of the field
fieldName - The name of the field
fieldValue - The value of the field

updateBounds

protected void updateBounds()
Internal method that causes this node and all of its ancestors to invalidate their bounds. The bounds will get recomputed on the next call to getBoundsReference();

Overrides:
updateBounds in class ZSceneGraphObject

updateVolatility

protected void updateVolatility()
Internal method that causes this node and all of its ancestors to invalidate their volatileBounds. The volatileBounds will get recomputed on the next call to getVolatileBounds(); All parents of this node are also volatile when this is volatile.

Overrides:
updateVolatility in class ZSceneGraphObject
See Also:
setVolatileBounds(boolean), ZSceneGraphObject.getVolatileBounds()

setVolatileBounds

public void setVolatileBounds(boolean v)
Specifies whether or not this node is 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:
setVolatileBounds in class ZSceneGraphObject
Parameters:
v - the new specification of whether this node is volatile.
See Also:
ZSceneGraphObject.getVolatileBounds()

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 ZSceneGraphObject
Parameters:
out - The stream that this object writes into
java.io.IOException

writeReplace

public ZSerializable writeReplace()
Node doesn't get written out if save property is false



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