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, ZSelectionResizeHandler.ResizeHandles, 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

Field Summary
 
Fields inherited from class edu.umd.cs.jazz.ZSceneGraphObject
bounds, inTransaction, invalidBounds, invalidVolatileBounds, 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 invalidate their bounds.
protected  void updateObjectReferences(ZObjectReferenceTable objRefTable)
          Called to update internal object references after a clone operation by ZSceneGraphObject.clone().
protected  void updateVolatility()
          Internal method invalidate the volatility of a component.
 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
addClientProperty, addMouseListener, addMouseMotionListener, clone, computeBounds, computeVolatileBounds, dump, endTransaction, fireEvent, fireMouseEvent, getBounds, getBoundsReference, getClientProperty, getHandles, getListenerList, getVolatileBounds, hasLisenerOfType, hasListenerOfType, hasMouseListener, markInTransaction, markNotInTransaction, processMouseEvent, putClientProperty, removeEventListener, removeMouseListener, removeMouseMotionListener, reshape, setBounds, setVolatileBounds, startTransaction
 
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
Parameters:
objRefTable - Table mapping from uncloned objects to their cloned versions.
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.

Overrides:
trimToSize in class ZSceneGraphObject

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

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

Overrides:
repaint in class ZSceneGraphObject
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 invalidate their bounds.

Overrides:
updateBounds in class ZSceneGraphObject

updateVolatility

protected void updateVolatility()
Internal method invalidate the volatility of a component. This will also invalidate the volatility of all the parents of this component. All parents of this component are also volatile when this is volatile.

Overrides:
updateVolatility in class ZSceneGraphObject
See Also:
ZSceneGraphObject.setVolatileBounds(boolean), ZSceneGraphObject.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
Overrides:
writeObject in class ZSceneGraphObject
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
Overrides:
writeObjectRecurse in class ZSceneGraphObject
Parameters:
out - The stream that this object writes into
java.io.IOException

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


Copyright 2003 by University of Maryland, College Park, MD 20742, USA All rights reserved.