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 boolean	findable_DEFAULT
static boolean	pickable_DEFAULT
static boolean	savable_DEFAULT
static boolean	selectable_DEFAULT

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

bounds, listenerList, volatileBounds, volatileBounds_DEFAULT

Constructor Summary

ZNode()
Constructs a new ZNode.

Method Summary

protected void	addClientProperty(ZProperty prop) Internal method to add the specified property.
void	addNodeListener(ZNodeListener l) Adds the specified node listener to receive node events from 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.
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.
java.lang.Object	getClientProperty(java.lang.Object key) Returns the value of the property with the specified key.
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.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.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	putClientProperty(java.lang.Object key, java.lang.Object value) Add an arbitrary key/value "client property" to this component.
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	repaint(ZSceneGraphObject obj, java.awt.geom.AffineTransform at, ZBounds clipBounds) 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	trimToSize() Trims the capacity of the array that stores the clientProperties list points to the actual number of points.
protected void	updateBounds() Internal method that causes this node and all of its ancestors to recompute their bounds.
protected void	updateObjectReferences(ZObjectReferenceTable objRefTable) Called to update internal object references after a clone operation by ZSceneGraphObject.clone().
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
ZSerializable	writeReplace() Node doesn't get written out if save property is false

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

addMouseListener, addMouseMotionListener, clone, computeBounds, fireEvent, fireMouseEvent, getBounds, getBoundsReference, getListenerList, getVolatileBounds, 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

savable_DEFAULT

public static final boolean savable_DEFAULT

pickable_DEFAULT

public static final boolean pickable_DEFAULT

findable_DEFAULT

public static final boolean findable_DEFAULT

selectable_DEFAULT

public static final boolean selectable_DEFAULT

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

duplicateObject

protected java.lang.Object duplicateObject()

Returns a clone of this object.

Overrides:

duplicateObject in class ZSceneGraphObject

See Also:

ZSceneGraphObject.duplicateObject()

updateObjectReferences

protected void updateObjectReferences(ZObjectReferenceTable objRefTable)

Called to update internal object references after a clone operation by ZSceneGraphObject.clone().

Overrides:

updateObjectReferences in class ZSceneGraphObject

See Also:

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

trimToSize

public void trimToSize()

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

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

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

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

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

remove

public void remove()

Remove this node, and any subtree, from the scenegraph.

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

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.

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.

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.

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.

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

getParent

public final ZGroup getParent()

Get the node's parent.

updateVolatility

protected void updateVolatility()

Internal method to compute and cache the volatility of a node, to recursively call the parents to compute volatility. All parents of this node are also volatile when this is volatile.

Overrides:

updateVolatility in class ZSceneGraphObject

See Also:

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

isSavable

public final boolean isSavable()

Determine if this node gets saved when written out.

Returns:

true if this node gets saved.

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

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.

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

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.

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

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.

Parameters:

findable - True if this node should be selectable.

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

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.

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.

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.

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.Point2D)

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.Point2D)

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.Point2D)

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.Point2D)

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.

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.

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.

Parameters:

repaintBounds - The bounds to repaint

repaint

public void repaint(ZSceneGraphObject obj,
                    java.awt.geom.AffineTransform at,
                    ZBounds clipBounds)

Method to pass repaint methods up the tree. Repaints the area of the surface that is covered by the bounds of this object. Note that the transform and clipBounds parameters may be modified as a result of this call.

Parameters:

obj - The object to repaint

at - The affine transform

clipBounds - The bounds to clip to when repainting

updateBounds

protected void updateBounds()

Internal method that causes this node and all of its ancestors to recompute their bounds.

Overrides:

updateBounds in class ZSceneGraphObject

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)

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

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.

Parameters:

id - The event id (BOUNDS_CHANGED or GLOBAL_BOUNDS_CHANGED)

node - The node being affected.

See Also:

EventListenerList

getRoot

public ZRoot getRoot()

Traverse the tree, find the root node, and return it.

Returns:

The root node of this scenegraph

See Also:

ZRoot

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.

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.

putClientProperty

public void putClientProperty(java.lang.Object key,
                              java.lang.Object value)

Add an arbitrary key/value "client property" to this component.

The get/putClientProperty methods provide access to a small per-instance hashtable. Callers can use get/putClientProperty to annotate components that were created by another module.

If value is null this method will remove the property.

See Also:

getClientProperty(java.lang.Object)

addClientProperty

protected void addClientProperty(ZProperty prop)

Internal method to add the specified property.

Parameters:

prop - The new property.

getClientProperty

public java.lang.Object getClientProperty(java.lang.Object key)

Returns the value of the property with the specified key. Only properties added with putClientProperty will return a non-null value.

Returns:

the value of this property or null

See Also:

putClientProperty(java.lang.Object, java.lang.Object)

dump

public java.lang.String dump()

Generate a string that represents this object for debugging.

Overrides:

dump in class ZSceneGraphObject

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 ZSceneGraphObject

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 ZSceneGraphObject

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 ZSceneGraphObject

Parameters:

fieldType - The fully qualified type of the field

fieldName - The name of the field

fieldValue - The value of the field

writeReplace

public ZSerializable writeReplace()

Node doesn't get written out if save property is false