edu.umd.cs.jazz.scenegraph
Class ZNode

java.lang.Object
  |
  +--edu.umd.cs.jazz.scenegraph.ZNode

Direct Known Subclasses:

ZCamera, ZRootNode

public class ZNode

extends java.lang.Object

implements ZScenegraphObject, ZSerializable

ZNode is the basic hierarchial structure. It has zero or more child nodes. The ZNode may also exhibit a visual appearance if it contains a ZVisualComponent in it's visualComponent slot. In discussion/comments, node is used interchangeably with ZNode.

See Also:

ZVisualComponent

Field Summary

protected float	alpha The alpha value that will be applied to the composite field (multiplicitivly) of the graphics2D during paint.
static float	alpha_DEFAULT
protected ZAncestorNotifier	ancestorNotifier
protected boolean	cacheVolatile Cached volatility computation
protected java.util.Vector	cameras All the cameras explicitly looking onto the scene graph rooted in this node.
protected java.util.Vector	children This node's children
protected java.util.Vector	clientProperties
protected boolean	compBoundsDirty True if globalCompBounds is out of date and needs to be recomputed
static boolean	compBoundsDirty_DEFAULT
protected ZBounds	globalBounds The region (currently a rectangle) in the global space occupied by the intersection of this nodes VC and the global bounds of this nodes children
protected boolean	globalBoundsDirty True if globalBounds is out of date and needs to be recomputed
static boolean	globalBoundsDirty_DEFAULT
protected ZBounds	globalCompBounds The region (currently a rectangle) in the global space occupied by the of this nodes VC
protected boolean	isVolatile True if this node is specifically set to be volatile
protected ZLayoutManager	layoutManager The layout manager that lays out the children of this node, or null if none.
protected javax.swing.event.EventListenerList	listenerList
protected float	maxMag This field is checked at render time.
static float	maxMag_DEFAULT
protected float	minMag This field is checked at render time.
static float	minMag_DEFAULT
protected ZNode	parent This node's parent
protected boolean	recursiveLayout Specifies if this node should be recursively layed out using its parent layout manager if it doesn' have one.
protected boolean	save True if this node should be saved
static boolean	save_DEFAULT
protected ZTransform	transform The transform applied to this node and by inheritance all of it's children as well.
protected boolean	visible True if visible (when not visible, nodes are not rendered or picked)
static boolean	visible_DEFAULT
protected ZVisualComponent	visualComponent The visual content of this node.

Constructor Summary

ZNode()
Constructs a new ZNode.

ZNode(ZNode node)
Constructs a new ZNode that is a copy of the specified node (i.e., a "copy constructor").

ZNode(ZVisualComponent vc)
Constructs a new Znode with the specified visual component.

Method Summary

void	addAncestorListener(ZAncestorListener listener) Registers listener so that it will receive ZAncestorEvents when it or any of its ancestors are changed in the following ways: A node is moved by a transform change A node is added/removed to/from the tree A node is made visible/invisible A node's alpha value is changed A node's min/max magnification is changed Events are also sent when the component or its ancestors are added or removed from the Component hierarchy
void	addChild(ZNode child) Adds a child to the node.
void	addNodeContainerListener(ZNodeContainerListener l) Adds the specified node container listener to receive node container events from this node.
void	addNodeListener(ZNodeListener l) Adds the specified node listener to receive node events from this node.
void	addProperty(java.lang.String key, java.lang.Object value) Add a new property to this node.
void	addProperty(ZProperty newProp) Add a new property to this node.
protected void	clearVisualComponent() Removes a child from the node.
java.lang.Object	clone() Duplicates the current node by using the copy constructor.
protected void	computeGlobalBounds() Recomputes and caches the bounds for this node.
protected void	computeGlobalCompBounds() Recomputes and caches the bounds for the nodes visual component.
java.awt.geom.AffineTransform	computeGlobalCoordinateFrame() Return the preConcatenation of transforms that exist between this node and the rootNode This node's transform IS included.
protected java.awt.Composite	createComposite(java.awt.Composite currentComposite, float currentMag)
void	damage() Damage causes the portions of the surfaces that this object appears in to be marked as needing to be repainted.
void	damage(boolean boundsChanged) Damage causes the portions of the surfaces that this object appears in to be marked as needing to be repainted.
void	doLayout() Causes the subtree rooted at this node to be laid out.
java.util.Vector	findAllCameras() Returns a list of all the cameras that look on to this node.
java.util.Vector	findCameras() Returns a list of cameras that look directly at this node or any of it's parents.
ZNode	findNode() A utility function that supports finding the node that references a particular visual component.
int	findNodes(ZFindFilter filter, java.util.Vector nodes) Return the list of nodes that are accepted by the specified filter in the subtree rooted with this.
ZRootNode	findRoot() Traverse the tree, find the root node, and return it.
ZVisualComponent	findVisualComponent(java.lang.Class type) Traverse the list of visual components, and return the first one that is of the specified Class, or null if none.
protected void	fireNodeContainerEvent(int id, ZNode child) Notifies all listeners that have registered interest for notification on this event type.
protected void	fireNodeEvent(int id, java.awt.geom.AffineTransform origTransform) Notifies all listeners that have registered interest for notification on this event type.
float	getAlpha() Get the alpha value (transparency) for this node.
java.util.Vector	getCameras() Returns this node's list of cameras.
java.util.Vector	getChildren() Return the node's children.
ZBounds	getCompBounds() Return the bounds of this node's visual component transformed by this node's transform.
ZBounds	getGlobalBounds() Return the bounds of the union of all descendents including the node's visual component.
ZBounds	getGlobalCompBounds() Returns the bounds (in global coords) for this nodes visual component.
ZLayoutManager	getLayoutManager() Returns the current layout manager for this node.
float	getMaxMag() Get the maximum magnification for this node.
float	getMinMag() Get the minimumn magnification for this node.
java.util.Vector	getObjs(java.awt.geom.Rectangle2D bounds) Returns the children within the specified bounds
ZNode	getParent() Get the node's parent.
java.util.Vector	getProperties() Get all the properties that this node has.
java.lang.Object	getProperty(java.lang.String key) Get the property with the specified key.
boolean	getRecursiveLayout() Determine if this node is laid out recursively using its parent's layout manager if this doesn't have one.
boolean	getSave() Determine if this node gets saved when written out.
java.util.Vector	getSelectedChildren() Return a vector containing all of the nodes in the subgraph rooted at this node (including this node) that are currently selected.
ZTransform	getTransform() Get the nodes transform.
boolean	getVisible() Get the value of 'visible'.
ZVisualComponent	getVisualComponent() Returns the visual component.
protected void	helpFindAllCameras(java.util.Vector result)
boolean	isAncestor(ZNode queryNode) Method to determine if node is ancenstor of queryNode.
boolean	isDescendent(ZNode queryNode) Method to determine if node is a descendent of queryNode.
boolean	isVisible() Get the value of 'visible'.
boolean	isVolatile() Determines if this node is volatile.
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.
void	paint(ZRenderContext renderContext) Paints the associated visual component and children of this node.
ZNode	pick(java.awt.geom.Rectangle2D rect, float mag) Returns the first object under the specified rectangle (if there is one) 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	removeAncestorListener(ZAncestorListener listener) Unregisters listener so that it will no longer receive ZAncestorEvents
void	removeChild(ZNode child) Removes a child from the node.
void	removeNodeContainerListener(ZNodeContainerListener l) Removes the specified node container listener so that it no longer receives node container events from this node.
void	removeNodeListener(ZNodeListener l) Removes the specified node listener so that it no longer receives node events from this node.
void	reparent(ZNode newParent) Move this node in the hierarchy, and update its transform so that its global position does not change.
void	selectAll(ZCamera camera) Select this node's visual component.
void	setAlpha(float alpha) set the alpha value (transparency) for this node.
void	setLayoutManager(ZLayoutManager manager) Specifies the layout manager for this node.
void	setMaxMag(float v) Set the maximum magnification for this node.
void	setMinMag(float v) set the minimumn magnification for this node.
protected void	setParent(ZNode parent) Used internally to set a node's parent.
void	setRecursiveLayout(boolean recursive) Specify if this node should be laid out recursively using its parent's layout manager if it doesn't have one.
void	setSave(boolean s) Specify if this node should be saved.
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	setTransform(ZTransform v) Set the nodes transform.
void	setVisible(boolean v) Set the value of 'visible'.
void	setVisualComponent(ZVisualComponent vc) Set the visual component.
void	setVolatile(boolean v) Specifies that this node is volatile.
void	swap(ZNode replacement) Swaps this node out of the scenegraph tree, and replaces it with the specified replacement node.
void	transformChanged(java.awt.geom.AffineTransform origTransform) Internal method used to notify a node that its transform has changed.
void	unselectAll() Un-Select this node's visual component.
void	updateBounds() Request this node to recompute its bounds.
void	updateChildBounds() Implementation of inherited interface method.
void	updateGlobalBounds() Notifies the node that its cached bounds are no longer valid.
void	updateGlobalCompBounds() Notifies the node that the cached bounds for its visual component are no longer valid.
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 java.lang.Object

equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

alpha_DEFAULT

public static final float alpha_DEFAULT

compBoundsDirty_DEFAULT

public static final boolean compBoundsDirty_DEFAULT

globalBoundsDirty_DEFAULT

public static final boolean globalBoundsDirty_DEFAULT

visible_DEFAULT

public static final boolean visible_DEFAULT

minMag_DEFAULT

public static final float minMag_DEFAULT

maxMag_DEFAULT

public static final float maxMag_DEFAULT

save_DEFAULT

public static final boolean save_DEFAULT

parent

protected ZNode parent

This node's parent

children

protected java.util.Vector children

This node's children

visualComponent

protected ZVisualComponent visualComponent

The visual content of this node. Can never be null (should be the dummy component rather than null).

cameras

protected transient java.util.Vector cameras

All the cameras explicitly looking onto the scene graph rooted in this node. Other cameras may actually see this node *indirectly* (some ancestor may have a camera in ITS vector). However, this Vector contains only those cameras that have called addRenderingStartPoint with this node as a param

transform

protected ZTransform transform

The transform applied to this node and by inheritance all of it's children as well. It modifies the nodes globalBounds and globalCompBounds in the global space

globalBounds

protected transient ZBounds globalBounds

The region (currently a rectangle) in the global space occupied by the intersection of this nodes VC and the global bounds of this nodes children

globalCompBounds

protected transient ZBounds globalCompBounds

The region (currently a rectangle) in the global space occupied by the of this nodes VC

alpha

protected float alpha

The alpha value that will be applied to the composite field (multiplicitivly) of the graphics2D during paint. All children of this node inherit this nodes alpha

minMag

protected float minMag

This field is checked at render time. If the zoom at the time of render is less than the value of this field, neither this node nor any of its children will be rendered

maxMag

protected float maxMag

This field is checked at render time. If the zoom at the time of render is greater than the value of this field, neither this node nor any of its children will be rendered

compBoundsDirty

protected boolean compBoundsDirty

True if globalCompBounds is out of date and needs to be recomputed

globalBoundsDirty

protected boolean globalBoundsDirty

True if globalBounds is out of date and needs to be recomputed

visible

protected boolean visible

True if visible (when not visible, nodes are not rendered or picked)

isVolatile

protected boolean isVolatile

True if this node is specifically set to be volatile

save

protected boolean save

True if this node should be saved

layoutManager

protected ZLayoutManager layoutManager

The layout manager that lays out the children of this node, or null if none.

recursiveLayout

protected boolean recursiveLayout

Specifies if this node should be recursively layed out using its parent layout manager if it doesn' have one.

cacheVolatile

protected boolean cacheVolatile

Cached volatility computation

clientProperties

protected java.util.Vector clientProperties

ancestorNotifier

protected ZAncestorNotifier ancestorNotifier

listenerList

protected javax.swing.event.EventListenerList listenerList

Constructor Detail

ZNode

public ZNode()

Constructs a new ZNode. ZNodes start out empty with no children, no VC and no cameras. A node has no visual content by itself. Either add a VC to this node or add a child with a non-dummy VC for this node to have visual content. Also, The node must be attached to a live scenegraph (a scenegraph that is currently visible) or be registered with a camera directly in order for it to be visible.

ZNode

public ZNode(ZVisualComponent vc)

Constructs a new Znode with the specified visual component. ZNodes instantiated with this constructor start out empty with no children, and no cameras. The node must be attached to a live scenegraph (a scenegraph that is currently visible) or be registered with a camera directly in order for it to be visible.

ZNode

public ZNode(ZNode node)

Constructs a new ZNode that is a copy of the specified node (i.e., a "copy constructor"). The portion of the reference node that is duplicated is that necessary to reuse the node in a new place within the scenegraph, but the new node is not inserted into any scenegraph. The node must be attached to a live scenegraph (a scenegraph that is currently visible) or be registered with a camera directly in order for it to be visible. The information copied includes the node's visual component, and all children. However, If any cameras were looking at the reference node, they will not look at the new node, and the new node does not have a parent. In addition, if the associated visual component is selected, then the duplicated visual component will not be selected.

Method Detail

clone

public java.lang.Object clone()

Duplicates the current node by using the copy constructor. See the copy constructor comments for complete information about what is duplicated.

Overrides:

clone in class java.lang.Object

See Also:

ZNode(ZNode)

addAncestorListener

public void addAncestorListener(ZAncestorListener listener)

Registers listener so that it will receive ZAncestorEvents when it or any of its ancestors are changed in the following ways:

• A node is moved by a transform change
• A node is added/removed to/from the tree
• A node is made visible/invisible
• A node's alpha value is changed
• A node's min/max magnification is changed

Events are also sent when the component or its ancestors are added or removed from the Component hierarchy

See Also:

ZAncestorEvent

removeAncestorListener

public void removeAncestorListener(ZAncestorListener listener)

Unregisters listener so that it will no longer receive ZAncestorEvents

See Also:

addAncestorListener(edu.umd.cs.jazz.event.ZAncestorListener)

addNodeContainerListener

public void addNodeContainerListener(ZNodeContainerListener l)

Adds the specified node container listener to receive node container events from this node.

Parameters:

l - the node container listener

removeNodeContainerListener

public void removeNodeContainerListener(ZNodeContainerListener l)

Removes the specified node container listener so that it no longer receives node container events from this node.

Parameters:

l - the node container listener

fireNodeContainerEvent

protected void fireNodeContainerEvent(int id,
                                      ZNode child)

Notifies all listeners that have registered interest for notification on this event type. 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 (NODE_ADDED, NODE_REMOVED)

child - The child being added or removed from this node

See Also:

EventListenerList

addNodeListener

public void addNodeListener(ZNodeListener l)

Adds the specified node listener to receive node events from this node.

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.

Parameters:

l - the node listener

fireNodeEvent

protected void fireNodeEvent(int id,
                             java.awt.geom.AffineTransform origTransform)

Notifies all listeners that have registered interest for notification on this event type. 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 (NODE_TRANSFORMED, NODE_SHOWN, or NODE_HIDDEN)

origTransform - The original transform (for transform events)

See Also:

EventListenerList

setLayoutManager

public void setLayoutManager(ZLayoutManager manager)

Specifies the layout manager for this node.

Parameters:

manager - The new layout manager.

getLayoutManager

public ZLayoutManager getLayoutManager()

Returns the current layout manager for this node. If this node specifies that it desires recursive layout, and it does not have its own layout manager, then it returns its parent's layout manager.

Returns:

The current layout manager.

setRecursiveLayout

public void setRecursiveLayout(boolean recursive)

Specify if this node should be laid out recursively using its parent's layout manager if it doesn't have one.

Parameters:

recursive - True to layout recursively.

getRecursiveLayout

public boolean getRecursiveLayout()

Determine if this node is laid out recursively using its parent's layout manager if this doesn't have one.

Returns:

true if this node is laid out recursively.

doLayout

public void doLayout()

Causes the subtree rooted at this node to be laid out. This works by doing a depth-first search on the tree, laying out children first, and then the node (recursively). If there is no layout manager for this node, then nothing happens.

See Also:

getLayoutManager()

addChild

public void addChild(ZNode child)

Adds a child to the node. This method will automatically damage the global space. However, the application will need to call restore on any surfaces that see this node before the visual content will be updated.

Parameters:

child - is the child that gets added to this.

See Also:

ZSurface.restore()

removeChild

public void removeChild(ZNode child)

Removes a child from the node. This method will automatically damage the global space. However, the application will need to call restore on any surfaces that see this node before the visual content will be updated.

Parameters:

child - is the child that is removed.

See Also:

ZSurface.restore()

getChildren

public java.util.Vector getChildren()

Return the node's children.

reparent

public void reparent(ZNode newParent)

Move this node in the hierarchy, and update its transform so that its global position does not change. This node will be removed from its current parent, and added as a child to the new parent. Its transform will be changed so that its global hierarchical transform is the same under the new parent as the under the old parent.

Parameters:

newParent - the node that this node will be put under

swap

public void swap(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's parent in the same position as this was. That is, if this was the 3rd child of its parent, then after calling swap(), the replacement node will also be the 3rd child of its parent. If this node has no parent when swap is called, then nothing will be done at all.

If this was a paint start point for any cameras, then it will be removed from those camera lists, and the replacement will be added to those cameras in the same position as this node was.

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 {link #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 {link #lower}

Parameters:

beforeNode - The node to lower this node before.

getCameras

public java.util.Vector getCameras()

Returns this node's list of cameras. That is, this returns the list of cameras for which this node is one of those cameras "paintStartPoints".
There are three methods for getting a list of camera's that can see the portion of the scenegraph containing a node. This method getCameras() returns only those cameras that have registered the node as a paintStartPoint. The second method findCameras() contains all the cameras that getCameras() would return plus all of the cameras returned by calling getCameras() on the ancestors of the node. The last method findAllCamaras, returns all the cameras found with findCameras() plus the the cameras that can be found by ascending up the ancestors of all the cameras (remember that cameras are also nodes)

Returns:

the list of cameras.

See Also:

findCameras(), findAllCameras()

findCameras

public java.util.Vector findCameras()

Returns a list of cameras that look directly at this node or any of it's parents. Note that this does not check if this node is actually visible within the cameras' view, just that the camera renders the portion of the scenegraph that includes this node.

Returns:

the list of cameras.

See Also:

getCameras()

findAllCameras

public java.util.Vector findAllCameras()

Returns a list of all the cameras that look on to this node. This performs a recursive search on the cameras so even cameras that see a camera that see a camera that see this node are included. Note that this does not check if this node is actually visible within the cameras' view, just that the camera renders the portion of the scenegraph that includes this node.

Returns:

the list of cameras.

See Also:

getCameras()

helpFindAllCameras

protected void helpFindAllCameras(java.util.Vector result)

isVolatile

public boolean isVolatile()

Determines if this node is volatile. A node is considered to be volatile if it is specifically set to be volatile with setVolatile(boolean), or if its visual component or any of its descendants are volatile.

Volatile objects are those objects that change regularly, such as an object that is animated, or one whose rendering depends on its context. For instance, a selection marker ZSelectionDecorator is always one-pixel thick, and thus its bounds depend on the current magnification.

Returns:

true if this node is volatile

See Also:

setVolatile(boolean)

setVolatile

public void setVolatile(boolean v)

Specifies that this node is volatile. Note that this node is considered to be volatile if its visual component or any of its descendants are volatile, even if this node's volatility is set to false. This implies that all parents of this node are also volatile when this is volatile.

Parameters:

v - the new specification of whether this node is volatile.

See Also:

isVolatile()

updateVolatility

public 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 its visual component or any of its descendants are volatile.

Specified by:

updateVolatility in interface ZScenegraphObject

See Also:

setVolatile(boolean), isVolatile()

getAlpha

public float getAlpha()

Get the alpha value (transparency) for this node. Alpha values are applied multiplicitivly with the alpha values of ancestors. That is, alpha is an inherited attribute.

Returns:

Value of alpha.

setAlpha

public void setAlpha(float alpha)

set the alpha value (transparency) for this node. Alpha values are applied multiplicitivly with the alpha values of ancestors. That is, alpha is an inherited attribute.

getVisible

public boolean getVisible()

Get the value of 'visible'. Nodes with the visible flag set to false are not painted or displayed. Note that invisible nodes do not contribute to the bounds of their parents. Same as isVisible().

Returns:

Value of hidden.

See Also:

isVisible()

isVisible

public boolean isVisible()

Get the value of 'visible'. Nodes with the visible flag set to false are not painted or displayed. Note that invisible nodes do not contribute to the bounds of their parents. Same as getVisible().

Returns:

Value of hidden.

See Also:

getVisible()

setVisible

public void setVisible(boolean v)

Set the value of 'visible'. Nodes with the visible flag set to false are not painted or displayed. Note that invisible nodes do not contribute to the bounds of their parents.

Parameters:

v - Value of visible.

getSave

public boolean getSave()

Determine if this node gets saved when written out.

Returns:

true if this node gets saved.

setSave

public void setSave(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

getTransform

public ZTransform getTransform()

Get the nodes transform.

setTransform

public void setTransform(ZTransform v)

Set the nodes transform.

transformChanged

public void transformChanged(java.awt.geom.AffineTransform origTransform)

Internal method used to notify a node that its transform has changed.

Specified by:

transformChanged in interface ZScenegraphObject

Parameters:

origTransform - The value of the original transform (before it was changed)

getVisualComponent

public ZVisualComponent getVisualComponent()

Returns the visual component. Remember that the visual component is quite likely not a single object, but a chain of objects. Often you will need to descend the chain looking for a particular type of visual component. Regardless, always check the type of the visual component before performing an operation on it.

setVisualComponent

public void setVisualComponent(ZVisualComponent vc)

Set the visual component. Remember that the visual component is quite likely not a single object, but a chain of objects. Often you will need to descend the chain looking for a particular type of visual component. Regardless, always check the type of the visual component before performing an operation on it.
Calling this method will damage the space accordingly. Be sure to call restore() on any applicable surfaces. The visual content of the node on the surface will not be updated until a call to restore() is made.

Specified by:

setVisualComponent in interface ZScenegraphObject

Parameters:

vc - The new visual component

clearVisualComponent

protected void clearVisualComponent()

Removes a child from the node. Damage causes each camera to be updated so they can maintain their data structures.

setParent

protected void setParent(ZNode parent)
                  throws ZOperationNotAllowedException

Used internally to set a node's parent.

Parameters:

parent -

getParent

public ZNode getParent()

Get the node's parent. Note that this method has no associated public setParent method (parent.add(thisNode) is used instead)

See Also:

addChild(ZNode)

getMinMag

public float getMinMag()

Get the minimumn magnification for this node. Magnification is a culling mechanism. During paint, the current magnification (from the render context) is compared to the min magnification. If the current magnification is less than min magnification. Neither this node, nor any of its children will be rendered.

Returns:

The minimum magnification of this node

setMinMag

public void setMinMag(float v)

set the minimumn magnification for this node. Magnification is a culling mechanism. During paint, the current magnification (from the render context) is compared to the min magnification. If the current magnification is less than min magnification. Neither this node, nor any of its children will be rendered.

Parameters:

v - The new minimumn magnification for this node.

getMaxMag

public float getMaxMag()

Get the maximum magnification for this node. Magnification is a culling mechanism. During paint, the current magnification (from the render context) is compared to the max magnification. If the current magnification is greater than max magnification. Neither this node, nor any of its children will be rendered. If the maximum magnification is set to the special value of -1, then this feature is disabled (i.e., it never is culled because it is too large).

Returns:

The maximum magnification of this node

setMaxMag

public void setMaxMag(float v)

Set the maximum magnification for this node. Magnification is a culling mechanism. During paint, the current magnification (from the render context) is compared to the max magnification. If the current magnification is greater than max magnification. Neither this node, nor any of its children will be rendered. If the maximum magnification is set to the special value of -1, then this feature is disabled (i.e., it never is culled because it is too large).

Parameters:

v - The new maximum magnification for this node.

getSelectedChildren

public java.util.Vector getSelectedChildren()

Return a vector containing all of the nodes in the subgraph rooted at this node (including this node) that are currently selected.

createComposite

protected java.awt.Composite createComposite(java.awt.Composite currentComposite,
                                             float currentMag)

paint

public void paint(ZRenderContext renderContext)

Paints the associated visual component and children of this node. Nothing is painted if the node is invisible or is magnified more than its maximum or less than its minimum magnification. Before anything is rendered, the node's transformation and transparency is applied.

The node makes the guarantee that before anything is rendered, the transform, clip, and composite of the Graphics2D will be set properly. However, the color, font, and stroke are unset, and the visual component must set those things as needed. The visual components that are painted are not obligated to restore any aspect of the Graphics2D state.

Parameters:

renderContext - The graphics context to use for rendering.

See Also:

ZVisualComponent.paint(ZRenderContext)

pick

public ZNode pick(java.awt.geom.Rectangle2D rect,
                  float mag)

Returns the first object under the specified rectangle (if there is one) as searched in reverse (front-to-back) order. Only returns nodes with "pickable" visual components. The magnification of the camera being picked within is specified, and objects which larger than their maximum magnification, or smaller than minimum magnification are skipped.

Parameters:

rect - Coordinates of pick rectangle in camera coordinates.

mag - The magnification of the camera being picked within.

Returns:

The picked object, or null if none

See Also:

ZVisualComponent.isPickable()

findNodes

public int findNodes(ZFindFilter filter,
                     java.util.Vector nodes)

Return the list of nodes that are accepted by the specified filter in the subtree rooted with this. If this node is invisible or it 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 vector (results will be place here).

Returns:

the number of nodes searched

See Also:

ZVisualComponent.isFindable(), ZFindFilter

findNode

public ZNode findNode()

A utility function that supports finding the node that references a particular visual component.

Specified by:

findNode in interface ZScenegraphObject

Returns:

this node

See Also:

ZVisualComponent.findNode()

findRoot

public ZRootNode findRoot()

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

Returns:

The root node of this scenegraph

See Also:

ZRootNode

findVisualComponent

public ZVisualComponent findVisualComponent(java.lang.Class type)

Traverse the list of visual components, and return the first one that is of the specified Class, or null if none.

Parameters:

type - the object class to look for.

Returns:

The first visual component encountered of type

damage

public void damage()

Damage causes the portions of the surfaces that this object appears in to be marked as needing to be repainted. The repainting does not actually occur until ZSurface.restore() is called.

If this object is visible in multiple places on a surface because the surface has more than one camera where each camera can see this object, then this call to damage causes all of those places to be marked as needing to be repainted. A single call to that surface's restore method will cause all of those damaged areas to be repainted.

If this object is visible within multiple surfaces, then this call to damage causes those places that this object is visible on each surface to be marked as needing to be repainted. The restore method of each surface must be called in order to repaint the damaged area associated with this object.

Important note : There are two proper uses of damage.

1. When the bounds of the object do not change, you can simply call this damage method
2. When making a change to an object that affects it's bounds in any way (change of penWidth, selection, transform, etc.) you must call damage(boolean).

Specified by:

damage in interface ZScenegraphObject

See Also:

ZSurface.restore(), damage(boolean)

damage

public void damage(boolean boundsChanged)

Damage causes the portions of the surfaces that this object appears in to be marked as needing to be repainted. The repainting does not actually occur until ZSurface.restore() is called.

If this object is visible in multiple places on a surface because the surface has more than one camera where each camera can see this object, then this call to damage causes all of those places to be marked as needing to be repainted. A single call to that surface's restore method will cause all of those damaged areas to be repainted.

If this object is visible within multiple surfaces, then this call to damage causes those places that this object is visible on each surface to be marked as needing to be repainted. The restore method of each surface must be called in order to repaint the damaged area associated with this object.

Important note : There are two proper uses of damage.

1. When the bounds of the object do not change, you should call damage().
2. When making a change to an object that affects it's bounds in any way (change of penWidth, selection, transform, etc.) you must call this damage method.

Specified by:

damage in interface ZScenegraphObject

See Also:

ZSurface.restore(), damage()

updateChildBounds

public void updateChildBounds()

Implementation of inherited interface method. This method will propagate the request to updateChildBounds to all it's children and update its own bounds as well.
For a discussion on coordinate systems and bounds see ZScenegraphObject.

Specified by:

updateChildBounds in interface ZScenegraphObject

See Also:

ZScenegraphObject, ZScenegraphObject.updateChildBounds()

updateBounds

public void updateBounds()

Request this node to recompute its bounds. This will result in propagating the request to its parent and update its own (both types) bounds as well.

This method invalidates the cached values for both the globalBounds and globalCompBounds. GlobalCompBounds consists of the bounding rectangle containing this nodes visual components. GlobalBounds consists of the bounding rectangle containing the globalCompBounds and all of this nodes descendents globalBounds. For a discussion on coordinate systems and bounds see ZScenegraphObject.

Specified by:

updateBounds in interface ZScenegraphObject

See Also:

ZScenegraphObject, ZScenegraphObject.updateBounds(), updateGlobalCompBounds(), updateGlobalBounds()

updateGlobalCompBounds

public void updateGlobalCompBounds()

Notifies the node that the cached bounds for its visual component are no longer valid. Used when the visual component changes in some way that changes its bounds in the space. For a discussion on coordinate systems and bounds see ZScenegraphObject.

See Also:

ZScenegraphObject

computeGlobalCompBounds

protected void computeGlobalCompBounds()

Recomputes and caches the bounds for the nodes visual component. Generally this method is called by getGlobalCompBounds when the dirty bit is set. Should rarely be called from application code. For a discussion on coordinate systems and bounds see ZScenegraphObject.

See Also:

ZScenegraphObject

getGlobalCompBounds

public ZBounds getGlobalCompBounds()

Returns the bounds (in global coords) for this nodes visual component. If a valid cached value is available, this method returns it. If a valid cache is not available (i.e. the dirty bit is set) then the bounds are recomputed, cached and then returned to the caller. For a discussion on coordinate systems and bounds see ZScenegraphObject.

Returns:

The node's visual component bounds in global coords

See Also:

ZScenegraphObject, updateGlobalCompBounds(), computeGlobalCompBounds()

getCompBounds

public ZBounds getCompBounds()

Return the bounds of this node's visual component transformed by this node's transform. That is, this is neither "local", nor "global" bounds, but just the result of transforming the visual component's bounds by this node's transform. Note that the node component bounds is not cached, and this is computed every time it is requested.

Returns:

The node's component bounds

updateGlobalBounds

public void updateGlobalBounds()

Notifies the node that its cached bounds are no longer valid. Used when one of its descendents or its visual component changes in some way that changes their bounds in the space. For a discussion on coordinate systems and bounds see ZScenegraphObject.

See Also:

ZScenegraphObject

computeGlobalBounds

protected void computeGlobalBounds()

Recomputes and caches the bounds for this node. Generally this method is called by getGlobalBounds when the dirty bit is set. It should rarely be called from application code. Note that if a node is invisible, it does not contribute to its parent's bounds. For a discussion on coordinate systems and bounds see ZScenegraphObject.

See Also:

ZScenegraphObject

getGlobalBounds

public ZBounds getGlobalBounds()

Return the bounds of the union of all descendents including the node's visual component. If a valid cached value is available, this method returns it. If a valid cache is not available (i.e. the dirty bit is set) then the bounds are recomputed, cached and then returned to the caller. For a discussion on coordinate systems and bounds see ZScenegraphObject.

Returns:

The bounds of the intersection of all descendents including the node's visual component bounds in global coords* Note that the node component bounds is not cached, and this

See Also:

ZScenegraphObject, updateGlobalBounds(), computeGlobalBounds()

computeGlobalCoordinateFrame

public java.awt.geom.AffineTransform computeGlobalCoordinateFrame()

Return the preConcatenation of transforms that exist between this node and the rootNode This node's transform IS included. If you need the transform between this node and the rootNode without this node, call computeGlobalCoordinateFrame on this node's parent.

Returns:

The concatentation of ZNode transforms of this node's transform and all the anscestors of this node.

getObjs

public java.util.Vector getObjs(java.awt.geom.Rectangle2D bounds)

Returns the children within the specified bounds

Returns:

A Vector of ZNodes.

isDescendent

public boolean isDescendent(ZNode queryNode)

Method to determine if node is a descendent of queryNode.

Parameters:

queryNode - a possible ancenstor of node

Returns:

true of queryNode is an ancestor of node.

isAncestor

public boolean isAncestor(ZNode queryNode)

Method to determine if node is ancenstor of queryNode.

Parameters:

queryNode - a possible descendent of node

Returns:

true of queryNode is an descendent of node.

selectAll

public void selectAll(ZCamera camera)

Select this node's visual component. Propagate the request to all of its children

unselectAll

public void unselectAll()

Un-Select this node's visual component. Propagate the request to all of its children

addProperty

public void addProperty(java.lang.String key,
                        java.lang.Object value)

Add a new property to this node. The property is specified by the String key. If there is already a property with the same key, it will be replaced.

Parameters:

key - The key to the new property.

value - The value of the new property.

addProperty

public void addProperty(ZProperty newProp)

Add a new property to this node. The property is specified by the String key. If there is already a property with the same key, it will be replaced.

Parameters:

property - The new property.

getProperty

public java.lang.Object getProperty(java.lang.String key)

Get the property with the specified key. If the property doesn't exist, then this returns null. Note that it is impossible to have two properties with the same key.

Returns:

the value of the specified property, or null if it doesn't exist

getProperties

public java.util.Vector getProperties()

Get all the properties that this node has.

Returns:

the properties of this node, or null if none.

writeObject

public void writeObject(ZObjectOutputStream out)
                 throws java.io.IOException

Write out all of this object's state.

Specified by:

writeObject in interface ZSerializable

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

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

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