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:

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

volatileBounds_DEFAULT

public static final boolean volatileBounds_DEFAULT

See Also:

Constant Field Values

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.

invalidBounds

protected transient boolean invalidBounds

True if this nodes bounds need to be recomputed.

volatileBounds

protected boolean volatileBounds

True if this node is specifically set to have volatile bounds

invalidVolatileBounds

protected transient boolean invalidVolatileBounds

True if this nodes volatileBounds need to be recomputed.

inTransaction

protected transient boolean inTransaction

True if the scenegraph rooted by this object is in a transaction.

listenerList

protected transient javax.swing.event.EventListenerList listenerList

A list of event listeners for this node.

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.

addClientProperty

protected void addClientProperty(ZProperty prop)

Internal method to add the specified property.

Parameters:

prop - The new property.

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

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.

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. ZGroup and ZVisualLeaf overide this method to compute the cached volatile bounds of their children.

computeVolatileBounds

protected void computeVolatileBounds()

Recomputes and caches the volatile bounds for this node. Generally this method is called by getVolatileBounds when the volatileBounds are invalid, and it should rarely get called directly elsewhere.

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)

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.

endTransaction

public void endTransaction()

End the transaction for the scenegraph rooted at this object. This ends the transaction making sure that the volatilily, and bounds of the scenegraph rooted at this object are up to date. This object is also repainted.

See Also:

startTransaction()

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

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

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

getClientProperty

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

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

Returns:

the value of this property or null

See Also:

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

getHandles

public java.util.Collection getHandles()

Return the collection of handles associated with this object.

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.

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 ZNode.setVolatileBounds(boolean). All parents of this node are also considered volatile when a child is volatile and should return true when responding to this message.

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)

hasLisenerOfType

public boolean hasLisenerOfType(java.lang.Class aType)

Deprecated. as of Jazz 1.2 replaced with hasListenerOfType (proper spelling)

hasListenerOfType

public boolean hasListenerOfType(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

markInTransaction

protected void markInTransaction()

Mark this object and any of its children as part of a transaction.

markNotInTransaction

protected void markNotInTransaction()

Mark this object and any of its children as not part of a transaction.

processMouseEvent

public void processMouseEvent(ZMouseEvent e)

Forwards event to fireEvent(ZMouseEvent e);

putClientProperty

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

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

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

If value is null this method will remove the property.

See Also:

getClientProperty(java.lang.Object)

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.

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

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

repaint

public void repaint(ZBounds bounds)

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

setBounds

protected void setBounds(ZBounds newBounds)

Internal method to specify the bounds of this object.

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

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

startTransaction

public void startTransaction()

Start a transaction for the scenegraph rooted at this object. Transactions allow for efficient manipulation of the scenegraph. While a transaction is in effect many of the updating methodes (such as repaint) will not get called, this can result in signifigant performance improvments when a large number of objects are involved. endTransaction() should be be called after the modifications have been made so that the scenegraph will get properly updated.

See Also:

endTransaction()

trimToSize

public void trimToSize()

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

updateBounds

protected void updateBounds()

Internal method that causes this node and all of its ancestors to invalidate their bounds. If the bounds are invalid this will get recomputed on the next call to getBoundsReference();

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.

updateVolatility

protected void updateVolatility()

Internal method to invalidate the volatility of a node, The next call to getVolatileBounds() will cause the volatileBounds to get recomputed.

See Also:

setVolatileBounds(boolean), getVolatileBounds()

writeObject

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

Write out all of this object's state.

Specified by:

writeObject in interface ZSerializable

Parameters:

out - The stream that this object writes into

java.io.IOException

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

java.io.IOException