edu.umd.cs.jazz.scenegraph
Class ZVisualComponent

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

Direct Known Subclasses:

ZCoordList, ZDummyVisualComponent, ZImage, ZRectangle, ZText, ZVisualComponentDecorator

public class ZVisualComponent

extends java.lang.Object

implements ZScenegraphObject, ZSerializable

See Also:

ZVisualComponentDecorator

Field Summary

protected boolean	cacheVolatile
protected boolean	findable
static boolean	findable_DEFAULT
protected boolean	isVolatile
protected ZBounds	localBounds Bounds of this visual component relative to its coordinate frame.
protected boolean	localBoundsDirty
protected ZScenegraphObject	parent The parent of this visual component (or null if none).
protected boolean	pickable
static boolean	pickable_DEFAULT
protected boolean	selected

Constructor Summary

ZVisualComponent()
Default constructor for visual component.

ZVisualComponent(ZVisualComponent vc)
Constructs a new ZVisualComponent that is a copy of the specified component (i.e., a "copy constructor").

Method Summary

java.lang.Object	clone() Duplicates the current visual component by using the copy constructor.
protected void	computeLocalBounds() All sub-classes need to define this method to compute their local bounds.
void	damage()
void	damage(boolean boundsChanged)
ZNode	findNode() Traverses the parents until it finds the ZNode that references this visual component (or the decorator chain that leads to this component).
ZVisualComponent	findVisualComponent(java.lang.Class type) Traverse the list of visual components (downwards), and return the first one that is of the specified Class, or null if none.
ZBounds	getLocalBounds() Returns the local bounds of this component.
ZScenegraphObject	getParent() Returns the parent of this component, or null if none.
boolean	isFindable() Determines if this visual component is findable.
boolean	isPickable() Determines if this visual component is pickable.
boolean	isSelected() Determines if this component is selected.
boolean	isVolatile() Determines if this visual component is volatile.
void	paint(ZRenderContext renderContext) Paints this visual component.
boolean	pick(java.awt.geom.Rectangle2D rect) Determines whether the specified rectangle 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	select(ZCamera camera) Select this visual component by inserting a ZSelectionDecorator component just above this as a decorator.
void	select(ZSelectionDecorator selectionDecorator) Select this visual component.
void	setFindable(boolean findable) Specifies whether this visual component is findable.
void	setParent(ZScenegraphObject parent) Sets the parent of this component.
void	setPickable(boolean pickable) Specifies whether this visual component is pickable.
void	setSelected(boolean b, ZCamera camera) Specify if this component is selected.
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	setVisualComponent(ZVisualComponent child) This should never be called.
void	setVolatile(boolean v) Specifies that this visual component is volatile.
java.lang.String	toString() Generate a string that represents this object for debugging.
void	transformChanged(java.awt.geom.AffineTransform origTransform) always a noop
void	unselect() Unselect this visual component by searching its parents for a ZSelectionDecorator to remove.
void	updateBounds() Notifies this component that it must recompute its bounds.
void	updateChildBounds() Since a visual component does not have children, this method does nothing, but it may do something for other types of scenegraph objects.
void	updateLocalBounds() Specifies that this component's cached local bounds are out of date, and should be recomputed before being accessed.
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 java.lang.Object

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

Field Detail

pickable_DEFAULT

public static final boolean pickable_DEFAULT

findable_DEFAULT

public static final boolean findable_DEFAULT

localBounds

protected ZBounds localBounds

Bounds of this visual component relative to its coordinate frame.

parent

protected ZScenegraphObject parent

The parent of this visual component (or null if none).

selected

protected boolean selected

pickable

protected boolean pickable

findable

protected boolean findable

isVolatile

protected boolean isVolatile

cacheVolatile

protected boolean cacheVolatile

localBoundsDirty

protected boolean localBoundsDirty

Constructor Detail

ZVisualComponent

public ZVisualComponent()

Default constructor for visual component.

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

ZVisualComponent

public ZVisualComponent(ZVisualComponent vc)

Constructs a new ZVisualComponent that is a copy of the specified component (i.e., a "copy constructor"). The portion of the reference component that is duplicated is that necessary to reuse the component within a new node, but the new visual component is not inserted into a node.

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

Method Detail

clone

public java.lang.Object clone()

Duplicates the current visual component 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:

ZVisualComponent(ZVisualComponent)

transformChanged

public void transformChanged(java.awt.geom.AffineTransform origTransform)

always a noop

Specified by:

transformChanged in interface ZScenegraphObject

Parameters:

child -

isVolatile

public boolean isVolatile()

Determines if this visual component is volatile. A visual component is considered to be volatile if it is specifically set to be volatile with setVolatile(boolean), or if 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 component is volatile

See Also:

setVolatile(boolean)

setVolatile

public void setVolatile(boolean v)

Specifies that this visual component is volatile. Note that this component is considered to be volatile if any of its descendants are volatile, even if this component's volatility is set to false. This implies that all parents of this visual component 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. For instance, a selection marker ZSelectionDecorator is always one-pixel thick, and thus its bounds depend on the current magnification.

Parameters:

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

See Also:

isVolatile()

updateVolatility

public void updateVolatility()

Internal method to compute and cache the volatility of a component, to recursively call the parents to compute volatility. A component is considered to be volatile if it is set to be volatile, or if any of its descendants are volatile.

Specified by:

updateVolatility in interface ZScenegraphObject

See Also:

setVolatile(boolean), isVolatile()

isSelected

public boolean isSelected()

Determines if this component is selected.

Returns:

true if this component is selected.

setSelected

public void setSelected(boolean b,
                        ZCamera camera)

Specify if this component is selected. A component is selected by adding a ZSelectionDecorator that wraps this component. The default selection decorator renders a constant one-pixel thick rectangle around the component. The camera parameter is necessary to specify through which camera the selection rectangle is one-pixel thick within.

Parameters:

b - true if the component should be selected, false otherwise

camera - the camera that the selection is rendered constant thickness within

See Also:

ZSelectionDecorator

select

public void select(ZCamera camera)

Select this visual component by inserting a ZSelectionDecorator component just above this as a decorator. A component is selected by adding a ZSelectionDecorator that wraps this component. The default selection decorator renders a constant one-pixel thick rectangle around the component. The camera parameter is necessary to specify through which camera the selection rectangle is one-pixel thick within.

Parameters:

camera - the camera that the selection is rendered constant thickness within

See Also:

ZSelectionDecorator, select(ZSelectionDecorator)

select

public void select(ZSelectionDecorator selectionDecorator)

Select this visual component. This uses the selection decorator that is passed in.

Parameters:

selectionDecorator - - the decorator that should wrap this

See Also:

select(ZCamera)

unselect

public void unselect()

Unselect this visual component by searching its parents for a ZSelectionDecorator to remove.

See Also:

select(ZCamera), select(ZSelectionDecorator)

getParent

public ZScenegraphObject getParent()

Returns the parent of this component, or null if none.

Returns:

the parent.

setParent

public void setParent(ZScenegraphObject parent)

Sets the parent of this component. Note that generally, this method should not be used by an application as the parent pointer is properly set or cleared when a visual component is added removed.

Parameters:

parent - The new parent of this visual component

See Also:

ZNode.addChild(edu.umd.cs.jazz.scenegraph.ZNode), ZNode.removeChild(edu.umd.cs.jazz.scenegraph.ZNode)

isPickable

public boolean isPickable()

Determines if this visual component is pickable. When a visual component is not pickable, it will be ignored by the Jazz pick methods that determine which object is under a point. If an object is not pickable, it will not respond to input events.

Returns:

True if this component is pickable

See Also:

setPickable(boolean), ZCamera.pick(edu.umd.cs.jazz.util.ZBounds), ZNode.pick(java.awt.geom.Rectangle2D, float), isFindable()

setPickable

public void setPickable(boolean pickable)

Specifies whether this visual component is pickable. When a visual component is not pickable, it will be ignored by the Jazz pick methods that determine which object is under a point. If an object is not pickable, it will not respond to input events.

See Also:

isPickable(), ZCamera.pick(edu.umd.cs.jazz.util.ZBounds), ZNode.pick(java.awt.geom.Rectangle2D, float), isFindable()

isFindable

public boolean isFindable()

Determines if this visual component is findable. When a visual component is not findable, it will be ignored by the Jazz findNodes methods that determine which object satisfy some search criteria.

Returns:

True if this component is findable

See Also:

setFindable(boolean), ZCamera.findNodes(edu.umd.cs.jazz.util.ZFindFilter), ZNode.findNodes(edu.umd.cs.jazz.util.ZFindFilter, java.util.Vector), isPickable()

setFindable

public void setFindable(boolean findable)

Specifies whether this visual component is findable. When a visual component is not findable, it will be ignored by the Jazz findNodes methods that determine which object satisfy some search criteria.

Parameters:

findable - True if this component should be findable

See Also:

isFindable(), ZCamera.findNodes(edu.umd.cs.jazz.util.ZFindFilter), ZNode.findNodes(edu.umd.cs.jazz.util.ZFindFilter, java.util.Vector), isPickable()

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)

Determines whether the specified rectangle 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

Returns:

true if the rectangle picks this visual component

findNode

public ZNode findNode()

Traverses the parents until it finds the ZNode that references this visual component (or the decorator chain that leads to this component).

Specified by:

findNode in interface ZScenegraphObject

Returns:

this component's node

findVisualComponent

public ZVisualComponent findVisualComponent(java.lang.Class type)

Traverse the list of visual components (downwards), and return the first one that is of the specified Class, or null if none.

setVisualComponent

public void setVisualComponent(ZVisualComponent child)

This should never be called. It is a place holder because all ZScenegraphObjects must implement the setVisualComponent method. A regular visual component does not have any children, and so it does not make any sense to try and add a child to it.

Specified by:

setVisualComponent in interface ZScenegraphObject

paint

public void paint(ZRenderContext renderContext)

Paints this visual component. The rendercontext contains various aspects of the rendering state including the Graphics2D and the camera being rendered within.

It is guaranteed that the transform, clip, and composite of the Graphics2D will be set properly for this component. However, the color, font, and stroke are unset, and the visual component must set those things as needed. The visual component is not obligated to restore any aspect of the Graphics2D state.

Parameters:

renderContext - The graphics context to use for rendering.

See Also:

paint(ZRenderContext)

damage

public void damage()

Specified by:

damage in interface ZScenegraphObject

damage

public void damage(boolean boundsChanged)

Specified by:

damage in interface ZScenegraphObject

updateBounds

public void updateBounds()

Notifies this component that it must recompute its bounds. It actually just sets a bit saying that the bounds are out of date, and the next time the bounds are requested, they will be recomputed by calling computeLocalBounds()

Specified by:

updateBounds in interface ZScenegraphObject

updateChildBounds

public void updateChildBounds()

Since a visual component does not have children, this method does nothing, but it may do something for other types of scenegraph objects.

Specified by:

updateChildBounds in interface ZScenegraphObject

See Also:

ZNode.updateChildBounds()

updateLocalBounds

public void updateLocalBounds()

Specifies that this component's cached local bounds are out of date, and should be recomputed before being accessed.

computeLocalBounds

protected void computeLocalBounds()

All sub-classes need to define this method to compute their local bounds. The current bounds should be stored in the 'localBounds' variable. which will be accessed by getLocalBounds().

Note that this method is not typically called directly by application writers, but if it is called, then the caller must clear the dirty bit which records the fact that the stored bounds is up to date. Do this with: localBoundsDirty = false

See Also:

getLocalBounds()

getLocalBounds

public ZBounds getLocalBounds()

Returns the local bounds of this component. If the bounds are out date, or the component is volatile, then the bounds will be recomputed with computeLocalBounds() first.

Returns:

the bounds

toString

public java.lang.String toString()

Generate a string that represents this object for debugging.

Returns:

the string that represents this object for debugging

Overrides:

toString in class java.lang.Object

writeObject

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

Write out all of this object's state. Also note that visual components are never written out selected. So, even if it is selected, the selected bit is not written out.

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