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

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.

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.

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