edu.umd.cs.jazz
Class ZVisualComponent

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

All Implemented Interfaces:

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

Direct Known Subclasses:

ZBasicVisualComponent, ZCamera, ZImage, ZLabel, ZSwing, ZText

public class ZVisualComponent

extends ZSceneGraphObject

implements ZSerializable, java.io.Serializable

ZVisualComponent is the base class for objects that actually get rendered. A visual component primarily implements three methods: paint(), pick(), and computeBounds(). New sub-classes must override at least paint() and computeBounds(), and will often choose to override pick() as well.

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, Britt McAlister

See Also:

Serialized Form

Fields inherited from class edu.umd.cs.jazz.ZSceneGraphObject

bounds, listenerList, volatileBounds, volatileBounds_DEFAULT

Constructor Summary

ZVisualComponent()
Default constructor for visual component.

Method Summary

void	addParent(ZNode parent) Method to add a node to be a new parent of this component.
protected java.lang.Object	duplicateObject() Returns a clone of this object.
int	getNumParents() Return the number of parents of this visual component.
ZNode[]	getParents() Return a copy of the array of parents of this node.
ZNode[]	getParentsReference() Returns a reference to the parents of this component.
ZRoot	getRoot() Returns the root of the scene graph that this component is in.
void	paint(java.awt.Graphics2D g2) Paints this component.
boolean	pick(java.awt.geom.Rectangle2D rect, ZSceneGraphPath path) Determines whether the specified rectangle (in local coordinates) should "pick" this visual component.
boolean	pickBounds(java.awt.geom.Rectangle2D rect) This is a utility function to determine if the specified rectangle intersects the bounds of this visual component.
void	removeParent(ZNode parent) Method to remove the specified parent node from this visual component.
void	render(ZRenderContext renderContext) Renders this visual component.
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	repaint(ZBounds repaintBounds) This causes just the specified bounds of this visual component to be repainted.
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	trimToSize() Trims the capacity of the array that stores the parents list points to the actual number of points.
protected void	updateBounds() Internal method that causes this node and all of its ancestors to recompute their bounds.
protected void	updateObjectReferences(ZObjectReferenceTable objRefTable) Called to update internal object references after a clone operation by ZSceneGraphObject.clone().
protected void	updateParentBounds() Internal method that causes all the ancestors of this component to recompute their bounds.
protected void	updateVolatility() Internal method to compute and cache the volatility of a component, 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 edu.umd.cs.jazz.ZSceneGraphObject

addMouseListener, addMouseMotionListener, clone, computeBounds, dump, fireEvent, fireMouseEvent, getBounds, getBoundsReference, getListenerList, getVolatileBounds, hasLisenerOfType, hasMouseListener, processMouseEvent, removeEventListener, removeMouseListener, removeMouseMotionListener, reshape, setBounds, setVolatileBounds

Methods inherited from class java.lang.Object

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

Constructor Detail

ZVisualComponent

public ZVisualComponent()

Default constructor for visual component.

Method Detail

duplicateObject

protected java.lang.Object duplicateObject()

Returns a clone of this object.

Overrides:

duplicateObject in class ZSceneGraphObject

See Also:

ZSceneGraphObject.duplicateObject()

updateObjectReferences

protected void updateObjectReferences(ZObjectReferenceTable objRefTable)

Called to update internal object references after a clone operation by ZSceneGraphObject.clone().

Overrides:

updateObjectReferences in class ZSceneGraphObject

See Also:

ZSceneGraphObject.updateObjectReferences(edu.umd.cs.jazz.util.ZObjectReferenceTable)

trimToSize

public void trimToSize()

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

updateVolatility

protected void updateVolatility()

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

Overrides:

updateVolatility in class ZSceneGraphObject

See Also:

ZSceneGraphObject.setVolatileBounds(boolean), ZSceneGraphObject.getVolatileBounds()

getRoot

public ZRoot getRoot()

Returns the root of the scene graph that this component is in. Actually returns the root of the first node this is a child of.

getParents

public ZNode[] getParents()

Return a copy of the array of parents of this node. This method always returns an array, even when there are no children.

Returns:

the parents of this node.

getNumParents

public int getNumParents()

Return the number of parents of this visual component.

Returns:

the number of parents.

getParentsReference

public ZNode[] getParentsReference()

Returns a reference to the parents of this component. It should not be modified by the caller. Note that the actual number of parents could be less than the size of the array. Determine the actual number of parents with getNumParents().

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

Returns:

the parents of this visual component.

addParent

public void addParent(ZNode parent)

Method to add a node to be a new parent of this component. The new node is added to the end of the list of this node's parents; These methods are used primarily by the implementation of node objects that need to update the internal scenegraph hierarchy, and should be used with caution. For example, instead consider using ZVisualLeaf.addVisualComponent(edu.umd.cs.jazz.ZVisualComponent) instead.

Parameters:

parent - The new parent node.

removeParent

public void removeParent(ZNode parent)

Method to remove the specified parent node from this visual component. If the specified node wasn't a parent of this node, then nothing happens. These methods are used primarily by the implementation of node objects that need to update the internal scenegraph hierarchy, and should be used with caution. For example, instead consider using ZVisualLeaf.addVisualComponent(edu.umd.cs.jazz.ZVisualComponent) instead.

Parameters:

parent - The parent to be removed.

pickBounds

public boolean pickBounds(java.awt.geom.Rectangle2D rect)

This is a utility function to determine if the specified rectangle intersects the bounds of this visual component.

Parameters:

rect - the rectangle that this method tests for intersection with

Returns:

true if this component's local bounds intersects the specified rectangle

pick

public boolean pick(java.awt.geom.Rectangle2D rect,
                    ZSceneGraphPath path)

Determines whether the specified rectangle (in local coordinates) should "pick" this visual component. Picking is typically used to determine if a pointer is over an object, and thus pick should be implemented to retur true if the rectangle intersects the object.

The implementation of this pick method for the base visual component returns true if the rectangle intersects the bounds of the component. If a sub-class wants more detailed picking, then it must extend this class. For example, a circle may only consider itself to be picked if the pointer is within the circle - rather than within the rectangular bounds.

Parameters:

rect - The rectangle that is picking this visual component in local coordinates.

path - The path through the scenegraph to the picked node. Modified by this call.

Returns:

true if the rectangle picks this visual component

See Also:

ZDrawingSurface.pick(int, int)

paint

public void paint(java.awt.Graphics2D g2)

Paints this component. This method is called when the contents of the visual component should be painted, either when the component is being shown for the first time, or when repaint() has been called.

The clip rectangle, composite mode and transform of the Graphics2D parameter are set by Jazz to reflect the context in which the component is being painted. However, the color, font and stroke of the Graphics2D parameter are left undefined by Jazz, and each visual component must set these attributes explicitly to ensure that they are painted correctly.

The paint method is called by ZVisualComponent.render. Some visual components may need to override render() instead of paint().

Parameters:

Graphics2D - The graphics context to use for painting.

See Also:

render(ZRenderContext)

render

public void render(ZRenderContext renderContext)

Renders this visual component.

This method is called by Jazz when the component needs to be redrawn on the screen. The default implementation of render simply calls paint(), passing it the graphics object stored in the renderContext:

paint(renderContext.getGraphics2D());

Sophisticated visual components may need access to the state information stored in the ZRenderContext to draw themselves. Such components should override render() rather than paint().

Parameters:

renderContext - The graphics context to use for rendering.

See Also:

paint(Graphics2D)

repaint

public void repaint()

Description copied from class: ZSceneGraphObject

Repaint causes the portions of the surfaces that this object appears in to be marked as needing painting, and queues events to cause those areas to be painted. The painting does not actually occur until those events are handled. If this object is visible in multiple places because more than one camera can see this object, then all of those places are marked as needing painting.

Scenegraph objects should call repaint when their internal state has changed and they need to be redrawn on the screen.

Important note : Scenegraph objects should call reshape() instead of repaint() if the internal state change effects the bounds of the shape in any way (e.g. changing penwidth, selection, transform, adding points to a line, etc.)

Overrides:

repaint in class ZSceneGraphObject

Following copied from class: edu.umd.cs.jazz.ZSceneGraphObject

See Also:

ZSceneGraphObject.reshape()

repaint

public void repaint(ZBounds repaintBounds)

This causes just the specified bounds of this visual component to be repainted. Note that the input parameter may be modified as a result of this call.

Parameters:

repaintBounds - The bounds to repaint

See Also:

repaint()

updateBounds

protected void updateBounds()

Internal method that causes this node and all of its ancestors to recompute their bounds. Calls computeBounds(), followed by updateParentBounds().

Overrides:

updateBounds in class ZSceneGraphObject

updateParentBounds

protected void updateParentBounds()

Internal method that causes all the ancestors of this component to recompute their bounds.

writeObject

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

Write out all of this object's state.

Specified by:

writeObject in interface ZSerializable

Overrides:

writeObject in class ZSceneGraphObject

Parameters:

out - The stream that this object writes into

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

Overrides:

writeObjectRecurse in class ZSceneGraphObject

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

Overrides:

setState in class ZSceneGraphObject

Parameters:

fieldType - The fully qualified type of the field

fieldName - The name of the field

fieldValue - The value of the field