edu.umd.cs.jazz
Class ZSceneGraphObject

java.lang.Object
  |
  +--edu.umd.cs.jazz.ZSceneGraphObject

All Implemented Interfaces:

java.lang.Cloneable, java.io.Serializable, ZSerializable

Direct Known Subclasses:

ZNode, ZVisualComponent

public abstract class ZSceneGraphObject

extends java.lang.Object

implements ZSerializable, java.io.Serializable, java.lang.Cloneable

ZSceneGraphObject is the base class for all objects in the Jazz scenegraph. It provides support for the basic shared methods between all nodes and visual components.

Coordinate Systems
Application developers must understand the basic coordinate systems used in Jazz. The basic coordinate system has its origin at the upper-left. The X-axis increases positively to the right, and the Y-axis increase positively down.

Because certain node types define transforms which define a new relative coordinate system, it is important to realize that typically, objects are not placed in "global" coordinates. Rather, every object is defined in their own "local" coordinate system. The relationship of the local coordinate system to the global coordinate system is determined by the series of transforms between that object, and the root of the scenegraph.

All Jazz operations occur in local coordinates. For instance, coordinates of rectangles are specified in local coordinates. In addition, objects maintain a bounding box which is stored in local coordinates.

See the Jazz Tutorial for a more complete description of the scene graph.

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:

ZNode, ZVisualComponent, Serialized Form

Field Summary

protected ZBounds	bounds The bounding rectangle occupied by this object in its own local coordinate system.
protected javax.swing.event.EventListenerList	listenerList A list of event listeners for this node.
protected boolean	volatileBounds True if this node is specifically set to have volatile bounds
static boolean	volatileBounds_DEFAULT

Constructor Summary

protected

ZSceneGraphObject() Constructs an empty scenegraph object.

Method Summary

void	addMouseListener(ZMouseListener l) Adds the specified mouse listener to receive mouse events from this object
void	addMouseMotionListener(ZMouseMotionListener l) Adds the specified mouse motion listener to receive mouse motion events from this object
java.lang.Object	clone() Clones this scene graph object and all its children and returns the newly cloned sub-tree.
protected void	computeBounds() Recomputes and caches the bounds for this node.
java.lang.String	dump() Generate a string that represents this object for debugging.
protected java.lang.Object	duplicateObject() Creates a copy of this scene graph object and all its children.
protected void	fireEvent(ZEvent anEvent) Notifies all listeners that have registered interest for notification on this event type.
void	fireMouseEvent(ZMouseEvent e) Deprecated. as of Jazz 1.1
ZBounds	getBounds() Return a copy of the bounds of the subtree rooted at this node in local coordinates.
ZBounds	getBoundsReference() Return a reference to the bounds of the subtree rooted at this node in local coordinates.
protected javax.swing.event.EventListenerList	getListenerList() Return this objects current event listener list.
boolean	getVolatileBounds() Determines if this node is volatile.
boolean	hasLisenerOfType(java.lang.Class aType) Determines if this Object has a registered listener of the type specified in its listener list.
boolean	hasMouseListener() Determines if this object has any kind of mouse listener (i.e., mouse or mouse motion listener.)
void	processMouseEvent(ZMouseEvent e) Forwards event to fireEvent(ZMouseEvent e);
protected void	removeEventListener(java.lang.Class listenerType, java.util.EventListener listener) Removes the specified mouse listener so that it no longer receives mouse events from this object.
void	removeMouseListener(ZMouseListener l) Removes the specified mouse listener so that it no longer receives mouse events from this object.
void	removeMouseMotionListener(ZMouseMotionListener l) Removes the specified mouse motion listener so that it no longer receives mouse motion events from this object.
void	repaint() Repaint causes the portions of the surfaces that this object appears in to be marked as needing painting, and queues events to cause those areas to be painted.
void	reshape() Reshape causes the portion of the surface that this object appears in before the bounds are changed to be marked as needing painting, and queues events to cause those areas to be painted.
protected void	setBounds(ZBounds newBounds) Internal method to specify the bounds of this object.
void	setState(java.lang.String fieldType, java.lang.String fieldName, java.lang.Object fieldValue) Set some state of this object as it gets read back in.
void	setVolatileBounds(boolean v) Specifies whether or not this node is volatile.
protected void	updateBounds() Internal method that causes this node and all of its ancestors to recompute their bounds.
protected void	updateObjectReferences(ZObjectReferenceTable objRefTable) Updates references to scene graph nodes after a clone operation.
protected void	updateVolatility() Internal method to compute and cache the volatility of a node, to recursively call the parents to compute volatility.
void	writeObject(ZObjectOutputStream out) Write out all of this object's state.
void	writeObjectRecurse(ZObjectOutputStream out) Specify which objects this object references in order to write out the scenegraph properly

Methods inherited from class java.lang.Object

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

Field Detail

volatileBounds_DEFAULT

public static final boolean volatileBounds_DEFAULT

bounds

protected ZBounds bounds

The bounding rectangle occupied by this object in its own local coordinate system. Conceptually, the bounding rectangle is defined as the minimum rectangle that would surround all of the geometry drawn by the node and its children. The bounding rectangle's coordinates are in the node's local coordinates. That is, they are independant of any viewing transforms, or of transforms performed by parents of the node.

volatileBounds

protected boolean volatileBounds

True if this node is specifically set to have volatile bounds

listenerList

protected transient javax.swing.event.EventListenerList listenerList

A list of event listeners for this node.

Constructor Detail

ZSceneGraphObject

protected ZSceneGraphObject()

Constructs an empty scenegraph object.

Most objects will want to store their bounds, and so we allocate bounds here. However, if a particular object is implemented by computing its bounds every time it is asked instead of allocating it, then it can free up the bounds allocated here.

Method Detail

getBounds

public ZBounds getBounds()

Return a copy of the bounds of the subtree rooted at this node in local coordinates. If a valid cached value is available, this method returns it. If a valid cache is not available (i.e. the object is volatile) then the bounds are recomputed, cached and then returned to the caller.

If the object is a context-sensitive object, then it may compute the bounds based on the current render context.

Returns:

The bounds of the subtree rooted at this in local coordinates.

See Also:

ZRoot.getCurrentRenderContext()

getBoundsReference

public ZBounds getBoundsReference()

Return a reference to the bounds of the subtree rooted at this node in local coordinates. If a valid cached value is available, this method returns it. If a valid cache is not available (i.e. the object is volatile) then the bounds are recomputed, cached and then returned to the caller. The ZBounds returned should not be modified.

Warning: This method returns a reference to an internal ZBounds object. Any modification of this ZBounds object will result in undefined behavior.

If the object is a context-sensitive object, then it may compute the bounds based on the current render context.

Returns:

The bounds of the subtree rooted at this in local coordinates.

See Also:

ZRoot.getCurrentRenderContext()

setBounds

protected void setBounds(ZBounds newBounds)

Internal method to specify the bounds of this object.

computeBounds

protected void computeBounds()

Recomputes and caches the bounds for this node. Generally this method is called by reshape when the bounds have changed, and it should rarely directly elsewhere.

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

See Also:

reshape()

reshape

public void reshape()

Reshape causes the portion of the surface that this object appears in before the bounds are changed to be marked as needing painting, and queues events to cause those areas to be painted. Then, the bounds are updated, and finally, the portion of the screen corresponding to the newly computed bounds are marked for repainting. 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 reshape when their internal state has changed in such a way that their bounds have changed.

Important note : Scenegraph objects should call repaint() instead of reshape() if the bounds of the shape have not changed.

See Also:

repaint()

updateBounds

protected void updateBounds()

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

getVolatileBounds

public boolean getVolatileBounds()

Determines if this node is volatile. A node is considered to be volatile if it is specifically set to be volatile with setVolatileBounds(boolean). 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.

Returns:

true if this node is volatile

See Also:

setVolatileBounds(boolean)

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.

Parameters:

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

See Also:

getVolatileBounds()

updateVolatility

protected void updateVolatility()

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

See Also:

setVolatileBounds(boolean), getVolatileBounds()

duplicateObject

protected java.lang.Object duplicateObject()

Creates a copy of this scene graph object and all its children.

ZSceneGraphObject.duplicateObject() calls Object.clone() on this object, and returns the newly cloned object. This results in a shallow copy of the object.

Subclasses override this method to modify the cloning behavior for nodes in the scene graph. Typically, subclasses first invoke super.duplicateObject() to get the default cloning behavior, and then take additional actions after this. In particular, ZGroup.duplicateObject() first invokes super.duplicateObject(), and then calls duplicateObject() on all of the children in the group, so that the whole tree beneath the group is cloned. Applications do not call duplicateObject directly. Instead, ZSceneGraphObject.clone() is used clone a scene graph object.

updateObjectReferences

protected void updateObjectReferences(ZObjectReferenceTable objRefTable)

Updates references to scene graph nodes after a clone operation.

This method is invoked on cloned objects after the clone operation has been completed. The objRefTable parameter is a table mapping from the original uncloned objects to their newly cloned versions. Subclasses override this method to update any internal references they have to scene graph nodes. For example, ZNode's updateObjectReferences does:

      super.updateObjectReferences(objRefTable);

      // Set parent to point to the newly cloned parent, or to
      // null if the parent object was not cloned.
      parent = (ZNode)objRefTable.getNewObjectReference(parent);
 

Parameters:

objRefTable - Table mapping from uncloned objects to their cloned versions.

clone

public java.lang.Object clone()

Clones this scene graph object and all its children and returns the newly cloned sub-tree. Applications must then add the sub-tree to the scene graph for it to become visible.

Overrides:

clone in class java.lang.Object

Returns:

A cloned copy of this object.

dump

public java.lang.String dump()

Generate a string that represents this object for debugging.

Returns:

the string that represents this object for debugging

See Also:

ZDebug.dump(edu.umd.cs.jazz.ZNode)

addMouseListener

public void addMouseListener(ZMouseListener l)

Adds the specified mouse listener to receive mouse events from this object

Parameters:

l - the mouse listener

addMouseMotionListener

public void addMouseMotionListener(ZMouseMotionListener l)

Adds the specified mouse motion listener to receive mouse motion events from this object

Parameters:

l - the mouse motion listener

fireEvent

protected void fireEvent(ZEvent anEvent)

Notifies all listeners that have registered interest for notification on this event type. The listener list is processed in last to first order.

If the event is consumed, then the event will not be passed to any more listeners in the list.

Parameters:

anEvent - The ZEvent

See Also:

ZEvent

getListenerList

protected javax.swing.event.EventListenerList getListenerList()

Return this objects current event listener list. If the list is currently null then create a new listener list and return that one.

hasLisenerOfType

public boolean hasLisenerOfType(java.lang.Class aType)

Determines if this Object has a registered listener of the type specified in its listener list.

Parameters:

aType - The type of listener to search for.

Returns:

ture if it does have such a listener.

hasMouseListener

public boolean hasMouseListener()

Determines if this object has any kind of mouse listener (i.e., mouse or mouse motion listener.)

Returns:

true if this object does have at least one mouse listener

removeEventListener

protected void removeEventListener(java.lang.Class listenerType,
                                   java.util.EventListener listener)

Removes the specified mouse listener so that it no longer receives mouse events from this object.

Parameters:

l - the mouse listener

removeMouseListener

public void removeMouseListener(ZMouseListener l)

Removes the specified mouse listener so that it no longer receives mouse events from this object.

Parameters:

l - the mouse listener

removeMouseMotionListener

public void removeMouseMotionListener(ZMouseMotionListener l)

Removes the specified mouse motion listener so that it no longer receives mouse motion events from this object.

Parameters:

l - the mouse motion listener

fireMouseEvent

public void fireMouseEvent(ZMouseEvent e)

Deprecated. as of Jazz 1.1

Notifies all listeners that have registered interest for notification on this event type. The listener list is processed in last to first order.

If the event is consumed, then the event will not be passed event listeners on the Component that the event came through.

Parameters:

e - The mouse event

See Also:

EventListenerList

processMouseEvent

public void processMouseEvent(ZMouseEvent e)

Forwards event to fireEvent(ZMouseEvent e);

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