edu.umd.cs.jazz
Class ZFadeGroup

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

All Implemented Interfaces:

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

public class ZFadeGroup

extends ZGroup

implements ZSerializable, java.io.Serializable

ZFadeGroup is a group node that controls transparency and fading of its sub-tree. Inserting a fade node into the tree lets you control transparency and minimum/maximum magnification of all its descendants. If this node is rendered below its minimum magnification, or above its maximum magnification, it and its children will not be rendered. The node and its subtree will be smoothly faded out as the minimum or maximum magnification is approached.

Four types of fading have been implemented, selected with the setFadeType method:

CAMERA_MAG fades a node on camera magnification.
COMPOSITE_MAG fades on composite camera magnification.
ABSOLUTE_SCREEN_SIZE fades on absolute screen size in pixels.
PERCENT_OF_CAMERA fades on percentage of the camera size.

ZSceneGraphEditor provides a convenience mechanism to locate, create and manage nodes of this type.

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:

Serialized Form

Field Summary

static short	ABSOLUTE_SCREEN_SIZE FadeType: Fade on absolute screen size in pixels.
static double	alpha_DEFAULT
static short	CAMERA_MAG FadeType: Fade on camera magnification.
static short	COMPOSITE_MAG FadeType: Fade on composite magnification.
static double	fadeRange_DEFAULT
static short	fadeType_DEFAULT
static double	maxMag_DEFAULT
static double	minMag_DEFAULT
static short	PERCENT_OF_CAMERA FadeType: Fade on percentage of camera size.

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

children, childrenFindable_DEFAULT, childrenPickable_DEFAULT, hasOneChild_DEFAULT

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

findable_DEFAULT, pickable_DEFAULT, savable_DEFAULT, selectable_DEFAULT

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

bounds, listenerList, volatileBounds, volatileBounds_DEFAULT

Constructor Summary

ZFadeGroup()
Constructs a new empty fade group node.

ZFadeGroup(ZNode child)
Constructs a new fade group node with the specified node as a child of the new group.

Method Summary

double	getAlpha() Get the alpha value (opacity) for this node.
protected java.awt.Composite	getComposite(java.awt.Composite currentComposite, double metric) Internal method to compute and access an alpha Composite given the current rendering composite, and the current metric.
double	getFadeRange() Returns the current fade range of this node.
int	getFadeType() Determine the type of fading that this node implements.
double	getMaxMag() Get the maximum magnification for this node, as defined by the fade type.
double	getMinMag() Get the minimumn magnification for this node, as defined by the fade type.
boolean	isVisible(double metric) Internal method: determines if this fade node is visible at the specified magnification.
boolean	isVisible(ZSceneGraphPath path) Determines if this fade node is visible.
boolean	pick(java.awt.geom.Rectangle2D rect, ZSceneGraphPath path) Returns the first object under the specified rectangle (if there is one) in the subtree rooted with this as searched in reverse (front-to-back) order.
void	render(ZRenderContext renderContext) Renders this node which results in the node's visual component getting rendered, followed by its children getting rendered.
void	setAlpha(double alpha) Set the alpha value (opacity) for this node.
void	setFadeRange(double fadeRange) Sets the percentage of magnification change over which an object is faded in or out as it reaches its minimum or maximum magnification.
void	setFadeType(short aFadeType) Set the type of fading that this node implements.
void	setMaxMag(double maxMag) Set the maximumn magnification for this node.
void	setMinMag(double minMag) Set the minimumn magnification for this node.
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	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.ZGroup

addChild, addChildImpl, addChildren, addGroupListener, childAddedNotification, childRemovedNotification, computeBounds, dump, duplicateObject, extract, findNodes, getChild, getChildren, getChildrenFindable, getChildrenIterator, getChildrenPickable, getChildrenReference, getNumChildren, getShallowBounds, getVolatileBounds, hasOneChild, indexOf, insertAbove, iterator, lower, lowerTo, raise, raiseTo, removeAllChildren, removeChild, removeChild, removeChild, removeChildImpl, removeGroupListener, removeNodeListener, setChildrenFindable, setChildrenPickable, setHasOneChild, trimToSize, updateHasNodeListener, updateVolatility

Methods inherited from class edu.umd.cs.jazz.ZNode

addClientProperty, addNodeListener, editor, getClientProperty, getGlobalBounds, getGlobalToLocalTransform, getLocalToGlobalTransform, getParent, getRoot, globalToLocal, globalToLocal, hasNodeListener, isAncestorOf, isDescendentOf, isFindable, isPickable, isSavable, isSelectable, localToGlobal, localToGlobal, lower, lowerTo, percolateEventUpSceneGraph, putClientProperty, raise, raiseTo, remove, repaint, repaint, repaint, reparent, replaceWith, setEditorFactory, setFindable, setParent, setPickable, setSavable, setSelectable, updateBounds, updateObjectReferences, writeReplace

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

addMouseListener, addMouseMotionListener, clone, fireEvent, fireMouseEvent, getBounds, getBoundsReference, getListenerList, 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

Field Detail

CAMERA_MAG

public static final short CAMERA_MAG

FadeType: Fade on camera magnification.

COMPOSITE_MAG

public static final short COMPOSITE_MAG

FadeType: Fade on composite magnification.

ABSOLUTE_SCREEN_SIZE

public static final short ABSOLUTE_SCREEN_SIZE

FadeType: Fade on absolute screen size in pixels.

PERCENT_OF_CAMERA

public static final short PERCENT_OF_CAMERA

FadeType: Fade on percentage of camera size.

fadeType_DEFAULT

public static final short fadeType_DEFAULT

alpha_DEFAULT

public static final double alpha_DEFAULT

minMag_DEFAULT

public static final double minMag_DEFAULT

maxMag_DEFAULT

public static final double maxMag_DEFAULT

fadeRange_DEFAULT

public static final double fadeRange_DEFAULT

Constructor Detail

ZFadeGroup

public ZFadeGroup()

Constructs a new empty fade group node.

ZFadeGroup

public ZFadeGroup(ZNode child)

Constructs a new fade group node with the specified node as a child of the new group.

Parameters:

child - Child of the new group node.

Method Detail

getAlpha

public double getAlpha()

Get the alpha value (opacity) for this node. Alpha values are applied multiplicitively with the current alpha values at render time.

Returns:

The alpha value for this node.

setAlpha

public void setAlpha(double alpha)

Set the alpha value (opacity) for this node. Alpha values are applied multiplicitively with the current alpha values at render time. Alpha valus range from 0 to 1 where 0 represents a node being completely transparent, and 1 represents a node being completely opaque. Alpha is clamped to the range [0, 1].

Parameters:

alpha - The new alpha value for this node.

getMinMag

public double getMinMag()

Get the minimumn magnification for this node, as defined by the fade type.

Returns:

The minimum magnification of this node

setMinMag

public void setMinMag(double minMag)

Set the minimumn magnification for this node.
This node will not be rendered when the current rendering camera's magnification is less than then specified minimum magnification for this node. The node with smoothly fade from its regular opacity to completely transparent during a small magnification range just before the minimum magnification is reached. This transparency control affects the entire sub-tree rooted at this node. The minimum magnification has a minimum value of 0, and is clamped to that value.

If fade type is CAMERA_MAG, then minMag is the minimum magnification for this node.
If fade type is COMPOSITE_MAG, then minMag is the minimum composite magnification for this node.
if fade type is ABSOLUTE_SCREEN_SIZE, then minMag is the minimum size of the node in pixels.
if fade type is PERCENT_OF_CAMERA, then minMag is the minimum size, as a percentage of the camera size.

Parameters:

minMag - The new minimumn magnification for this node.

getMaxMag

public double getMaxMag()

Get the maximum magnification for this node, as defined by the fade type.

Returns:

The maximum magnification of this node

setMaxMag

public void setMaxMag(double maxMag)

Set the maximumn magnification for this node.
This node will not be rendered when the current rendering camera's magnification is greater than then specified maximum magnification for this node. The node with smoothly fade from its regular opacity to completely transparent during a small magnification range just before the maximum magnification is reached. This transparency control affects the entire sub-tree rooted at this node. To disable the maximum magnification feature, set the value to any negative value.

If fade type is CAMERA_MAG, then maxMag is the maximum magnification for this node.
If fade type is COMPOSITE_MAG, then maxMag is the maximum composite magnification for this node.
if fade type is ABSOLUTE_SCREEN_SIZE, then maxMag is the maximum size of the node in pixels.
if fade type is PERCENT_OF_CAMERA, then maxMag is the maximum size, as a percentage of the camera size.

Parameters:

maxMag - The new maximumn magnification for this node.

setFadeRange

public void setFadeRange(double fadeRange)

Sets the percentage of magnification change over which an object is faded in or out as it reaches its minimum or maximum magnification. A value of 0 means there is no fading at all and the object just jumps in and out of visibility. A value of 0.3 is reasonable, meaning it fades in and out over 30% of its size. The input is clamped between 0 and 1.

Parameters:

fadeRange - the new fade range [0, 1]

getFadeRange

public double getFadeRange()

Returns the current fade range of this node.

Returns:

the current fade range

See Also:

setFadeRange(double)

setFadeType

public void setFadeType(short aFadeType)

Set the type of fading that this node implements. Must be CAMERA_MAG, COMPOSITE_MAG, ABSOLUTE_SCREEN_SIZE or PERCENT_OF_CAMERA.
CAMERA_MAG fades a node on camera magnification.
COMPOSITE_MAG fades on composite camera magnification.
ABSOLUTE_SCREEN_SIZE fades on absolute screen size in pixels.
PERCENT_OF_CAMERA fades on percentage of the camera size.

Parameters:

fadeType - The fade type for this node.

getFadeType

public int getFadeType()

Determine the type of fading that this node implements.

Returns:

They fade type.

isVisible

public boolean isVisible(ZSceneGraphPath path)

Determines if this fade node is visible.

Parameters:

path - A scenegraph path.

Returns:

True if this node is visible at the current magnification.

isVisible

public boolean isVisible(double metric)

Internal method: determines if this fade node is visible at the specified magnification.

Parameters:

metric - The magnification, as defined by fade type.

Returns:

True if this node is visible at the specified magnification.

getComposite

protected java.awt.Composite getComposite(java.awt.Composite currentComposite,
                                          double metric)

Internal method to compute and access an alpha Composite given the current rendering composite, and the current metric. The metric can be magnification, composite magnification, absolute size in pixels, or percentage of camera size in pixels, depending on fadeType. This method determines the alpha based on this node's alpha value, minimum metric, and maximum metric.

Parameters:

currentComposite - The composite in the current render context

currentMag - The metric of the current rendering camera

Returns:

Composite The Composite to use to render this node

render

public void render(ZRenderContext renderContext)

Renders this node which results in the node's visual component getting rendered, followed by its children getting rendered.

The transform, clip, and composite will be set appropriately when this object is rendered. It is up to this object to restore the transform, clip, and composite of the Graphics2D if this node changes any of them. However, the color, font, and stroke are unspecified by Jazz. This object should set those things if they are used, but they do not need to be restored.

Overrides:

render in class ZGroup

Parameters:

renderContext - The graphics context to use for rendering.

pick

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

Returns the first object under the specified rectangle (if there is one) in the subtree rooted with this as searched in reverse (front-to-back) order. This performs a depth-first search, first picking children. Only returns a node if this is "pickable". If no nodes in the sub-tree are picked, then this node's visual component is picked.

If childrenPickable is false, then this will never return a child as the picked node. Instead, this node will be returned if any children are picked, or if this node's visual component is picked. Else, it will return null.

Overrides:

pick in class ZGroup

Parameters:

rect - Coordinates of pick rectangle in local coordinates

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

Returns:

The picked node, or null if none

See Also:

ZDrawingSurface.pick(int, int)

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 ZGroup

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 ZGroup

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 ZGroup

Parameters:

fieldType - The fully qualified type of the field

fieldName - The name of the field

fieldValue - The value of the field