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, childrenVolatileBoundsCache, hasOneChild_DEFAULT
 
Fields inherited from class edu.umd.cs.jazz.ZNode
editorFactory, findable_DEFAULT, parent, pickable_DEFAULT, savable_DEFAULT, selectable_DEFAULT
 
Fields inherited from class edu.umd.cs.jazz.ZSceneGraphObject
bounds, inTransaction, invalidBounds, invalidVolatileBounds, 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, addChildren, addGroupListener, childAddedNotification, childRemovedNotification, computeBounds, computeVolatileBounds, dump, duplicateObject, extract, findNodes, getChild, getChildren, getChildrenFindable, getChildrenIterator, getChildrenPickable, getChildrenReference, getNumChildren, getShallowBounds, getVolatileBounds, hasOneChild, indexOf, insertAbove, iterator, lower, lowerTo, markInTransaction, markNotInTransaction, raise, raiseTo, removeAllChildren, removeAllChildren, removeChild, removeChild, removeChild, removeChildImpl, removeGroupListener, removeNodeListener, setChildrenFindable, setChildrenPickable, setHasOneChild, trimToSize, updateHasNodeListener
 
Methods inherited from class edu.umd.cs.jazz.ZNode
addNodeListener, editor, getGlobalBounds, getGlobalToLocalTransform, getLocalToGlobalTransform, getParent, getRoot, globalToLocal, globalToLocal, globalToLocal, hasNodeListener, isAncestorOf, isDescendentOf, isFindable, isPickable, isSavable, isSelectable, localToGlobal, localToGlobal, localToGlobal, lower, lowerTo, percolateEventUpSceneGraph, raise, raiseTo, remove, repaint, repaint, reparent, replaceWith, setEditorFactory, setFindable, setParent, setPickable, setSavable, setSelectable, setVolatileBounds, updateBounds, updateVolatility, writeReplace
 
Methods inherited from class edu.umd.cs.jazz.ZSceneGraphObject
addClientProperty, addMouseListener, addMouseMotionListener, clone, endTransaction, fireEvent, fireMouseEvent, getBounds, getBoundsReference, getClientProperty, getHandles, getListenerList, hasLisenerOfType, hasListenerOfType, hasMouseListener, processMouseEvent, putClientProperty, removeEventListener, removeMouseListener, removeMouseMotionListener, reshape, setBounds, startTransaction, updateObjectReferences
 
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.

See Also:
Constant Field Values

COMPOSITE_MAG

public static final short COMPOSITE_MAG
FadeType: Fade on composite magnification.

See Also:
Constant Field Values

ABSOLUTE_SCREEN_SIZE

public static final short ABSOLUTE_SCREEN_SIZE
FadeType: Fade on absolute screen size in pixels.

See Also:
Constant Field Values

PERCENT_OF_CAMERA

public static final short PERCENT_OF_CAMERA
FadeType: Fade on percentage of camera size.

See Also:
Constant Field Values

fadeType_DEFAULT

public static final short fadeType_DEFAULT
See Also:
Constant Field Values

alpha_DEFAULT

public static final double alpha_DEFAULT
See Also:
Constant Field Values

minMag_DEFAULT

public static final double minMag_DEFAULT
See Also:
Constant Field Values

maxMag_DEFAULT

public static final double maxMag_DEFAULT
See Also:
Constant Field Values

fadeRange_DEFAULT

public static final double fadeRange_DEFAULT
See Also:
Constant Field Values
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.


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