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 provides basic containment hierarchies. It maintains a bag of 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 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 children nodes (sub-nodes)
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	hidden True if hidden (not rendered or picked)
static boolean	hidden_DEFAULT
protected boolean	isVolatile True if this node is specifically set to be volatile
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 nodes parent
protected java.util.Vector	properties
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 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	addChild(ZNode child) Adds a child to the 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.
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.
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.
boolean	getHidden() Get the value of hidden.
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	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.
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	isHidden() Get the value of hidden.
boolean	isVolatile() Determines if this node is volatile.
void	lower() Demotes this child one position to backwards in the node's children list.
void	lower(ZNode child) Lowers this child to the back of the node's children list.
protected void	lowerInternal()
void	lowerTo(ZNode afterNode) Moves this child to an exact position in the node's children list.
protected void	lowerToInternal(ZNode afterNode)
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() Advances this child one position to forwards in node's children list.
void	raise(ZNode child) Raises this child to the front of the node's children list.
protected void	raiseInternal()
void	raiseTo(ZNode afterNode) Moves this child to an exact position in the node's children list.
protected void	raiseToInternal(ZNode afterNode)
void	removeChild(ZNode child) Removes a child from the 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	setHidden(boolean h) Set the value of hidden.
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	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	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	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

hidden_DEFAULT

public static final boolean hidden_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 nodes parent

children

protected java.util.Vector children

This children nodes (sub-nodes)

visualComponent

protected ZVisualComponent visualComponent

The visual content of this node. Can never be null (should be the dummy conponent rather than null). Often abbrevieated to VC.

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

hidden

protected boolean hidden

True if hidden (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

cacheVolatile

protected boolean cacheVolatile

Cached volatility computation

properties

protected java.util.Vector properties

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)

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

Raises this child to the front of the node's children list. This has the effect of making this child appear above all other children.

Parameters:

child -

lower

public void lower(ZNode child)

Lowers this child to the back of the node's children list. This has the effect of making this child appear below all other children.

Parameters:

child -

raise

public void raise()

Advances this child one position to forwards in node's children list. Children in front of child in the list will be display in front of child and children behind child in the list will be display below child.

Parameters:

child -

raiseTo

public void raiseTo(ZNode afterNode)

Moves this child to an exact position in the node's children list. Children in front of child in the list will be display in front of child and children behind child in the list will be display below child.

Parameters:

child -

lower

public void lower()

Demotes this child one position to backwards in the node's children list. Children in front of child in the list will be display in front of child and children behind child in the list will be display below child.

Parameters:

child -

lowerTo

public void lowerTo(ZNode afterNode)

Moves this child to an exact position in the node's children list. Children in front of child in the list will be display in front of child and children behind child in the list will be display below child.

Parameters:

child -

raiseInternal

protected void raiseInternal()
                      throws ZOperationNotAllowedException

raiseToInternal

protected void raiseToInternal(ZNode afterNode)
                        throws ZOperationNotAllowedException

lowerInternal

protected void lowerInternal()
                      throws ZOperationNotAllowedException

lowerToInternal

protected void lowerToInternal(ZNode afterNode)
                        throws ZOperationNotAllowedException

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.

getHidden

public boolean getHidden()

Get the value of hidden. Nodes with the hidden flag set to true are not painted or displayed. Note that hidden nodes do not contribute do the bounds of their parents. Same as isHidden().

Returns:

Value of hidden.

isHidden

public boolean isHidden()

Get the value of hidden. Nodes with the hidden flag set to true are not painted or displayed. Note that hidden nodes do not contribute do the bounds of their parents. Same as getHidden().

Returns:

Value of hidden.

setHidden

public void setHidden(boolean h)

Set the value of hidden. Nodes with the hidden flag set to true are not painted or displayed. Note that hidden nodes do not contribute do the bounds of their parents.

Parameters:

h - Value of hidden.

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.

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 hidden 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 hidden 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 hidden, 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