edu.umd.cs.jazz.util
Class ZSceneGraphEditor

java.lang.Object
  |
  +--edu.umd.cs.jazz.util.ZSceneGraphEditor

All Implemented Interfaces:

java.io.Serializable

public class ZSceneGraphEditor

extends java.lang.Object

implements java.io.Serializable

ZSceneGraphEditor provides a convenience mechanism used to locate and create instances of the following types of group nodes:

• Custom (i.e., any group that the editor does not have ordering information, see below)
• ZNameGroup
• ZInvisibleGroup
• ZLayoutGroup
• ZAnchorGroup
• ZTransformGroup
• ZStickyGroup
• ZSelectionGroup
• ZClipGroup
• ZFadeGroup
• ZSpatialIndexGroup

ZSceneGraphEditor uses lazy evaluation to automatically create these group nodes in a scene graph as they are needed.

For example, you can use a graph editor to obtain a ZTransformGroup for a leaf node. The first time you do this, a new ZTransformGroup is inserted above the leaf. Subsequently, that ZTransformGroup is reused. e.g.

    ZTransformGroup t = node.editor().getTransformGroup();
    t.translate(1, 0);
 

will translate node by 1, 0. Repeatedly executing this code will cause the node to move horizontally across the screen.

If multiple group types are created for a given node in the scene graph, they are ordered as shown in the list above - so custom groups will be inserted at the top (closest to the root), whereas spatialIndex groups will be inserted at the bottom (closest to the node being edited.)

Group nodes inserted into the scene graph by ZSceneGraphEditor have their hasOneChild flag set to true - such group nodes are referred to as "edit groups", and can only act on the single node immediately beneath them in the scene graph. This guarantees that translations or scalings applied to a ZTransformGroup node created by ZSceneGraphEditor effect only the node being edited. ZSceneGraphEditor uses the hasOneChild flag to identify edit groups that it has created in the scene graph, to avoid creating the same group nodes twice.

Customization: You can also use the scene graph editor to manage your own custom edit groups. This is done with the following methods;

      getEditGroup(ZMyCustomGroup.class);
      hasEditGroup(ZMyCustomGroup.class);
      removeEditGroup(ZMyCustomGroup.class);
 

If ZMyCustomGroup.class is a class that the scene graph editor does not have ordering information for then the edit group will be inserted at the top of the edit groups.

If you need to have your edit group inserted somewhere else (for example below the ZTransformGroup editor) then you need to give the ZSceneGraphEditor ordering information for this that type. This is done by calling

      ZSceneGraphEditor.setEditorOrder(ZMyCustomGroup.class, ZSceneGraphEditor.TRANSFORM_GROUP_ORDER - 1);
 

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:

Jonathan Meyer, 25 Aug 99, Ben Bederson, Jesse Grosjean

See Also:

ZNode.editor(), Serialized Form

Inner Class Summary

protected class

ZSceneGraphEditor.ZEditGroupIterator

Field Summary

static int	ANCHOR_GROUP_ORDER
static int	CLIP_GROUP_ORDER
protected ZNode	editNode The edit node.
static int	FADE_GROUP_ORDER
static int	INVISIBLE_GROUP_ORDER
static int	LAYOUT_GROUP_ORDER
static int	NAME_GROUP_ORDER Defines the ordering of the edit goups above the edit node.
static int	SELECTION_GROUP_ORDER
static int	SPATIAL_INDEX_GROUP_ORDER
static int	STICKY_GROUP_ORDER
static int	TRANSFORM_GROUP_ORDER

Constructor Summary

ZSceneGraphEditor(ZNode aNode)
Create a new editor for aNode.

Method Summary

java.util.Iterator	editorIterator() Returns an iterator over the list of "edit" groups above the node - groups above the node whose hasOneChild flag is set to true.
ZAnchorGroup	getAnchorGroup() Returns a ZAnchorGroup to use for a node, inserting one above the edited node if none exists.
ZClipGroup	getClipGroup() Returns a ZClipGroup to use for a node, inserting one above the edited node if none exists.
ZGroup	getEditGroup(java.lang.Class aType) Checks to see if an editor of this type already exists, if so it returns that editor if not it creates a new editor, inserts that editor above the edit node, and then returns that new editor.
ZFadeGroup	getFadeGroup() Returns a ZFadeGroup to use for a node, inserting one above the edited node if none exists.
java.util.ArrayList	getGroups() Deprecated. as of Jazz 1.1 editorIterator() instead.
ZInvisibleGroup	getInvisibleGroup() Returns a ZInvisibleGroup to use for a node, inserting one above the edited node if none exists.
ZLayoutGroup	getLayoutGroup() Returns a ZLayoutGroup to use for a node, inserting one above the edited node if none exists.
ZNameGroup	getNameGroup() Returns a ZNameGroup to use for a node, inserting one above the edited node if none exists.
ZNode	getNode() Returns the node being edited.
protected int	getOrderFor(java.lang.Class aType) Returns the order where aType of editor group should be inserted above the edit node.
ZSelectionGroup	getSelectionGroup() Returns a ZSelectionGroup to use for a node, inserting one above the edited node if none exists.
ZSpatialIndexGroup	getSpatialIndexGroup() Returns a ZSpatialIndexGroup to use for a node, inserting one above the edited node if none exists.
ZStickyGroup	getStickyGroup() Returns a ZStickyGroup to use for a node, inserting one above the edited node if none exists.
ZNode	getTop() If ZSceneGraphEditor has inserted groups above a node, this returns the topmost of those groups (the group nearest the root of the scene graph).
ZTransformGroup	getTransformGroup() Returns a ZTransformGroup to use for a node, inserting one above the edited node if none exists.
boolean	hasAnchorGroup() Returns true if this node has a ZAnchorGroup above it as an edit group, false otherwise.
boolean	hasClipGroup() Returns true if this node has a ZClipGroup above it as an edit group, false otherwise.
boolean	hasEditGroup(java.lang.Class aType) Searches to see if the edit node has an edit group of a matching type.
boolean	hasFadeGroup() Returns true if this node has a ZFadeGroup above it as an edit group, false otherwise.
boolean	hasInvisibleGroup() Returns true if this node has a ZInvisibleGroup above it as an edit group, false otherwise.
boolean	hasLayoutGroup() Returns true if this node has a ZLayoutGroup above it as an edit group, false otherwise.
boolean	hasNameGroup() Returns true if this node has a ZNameGroup above it as an edit group, false otherwise.
boolean	hasSelectionGroup() Returns true if this node has a ZSelectionGroup above it as an edit group, false otherwise.
boolean	hasSpatialIndexGroup() Returns true if this node has a ZSpatialIndexGroup above it as an edit group, false otherwise.
boolean	hasStickyGroup() Returns true if this node has a ZStickyGroup above it as an edit group, false otherwise.
boolean	hasTransformGroup() Returns true if this node has a ZTransformGroup above it as an edit group, false otherwise.
protected void	insertEditGroup(ZGroup aGroup) Insert aGroup above the edit node.
protected boolean	isEditGroup(ZNode aNode) Returns true if aNode is an edit group;
boolean	removeAnchorGroup() Removes a ZAnchorGroup edit group from above a node.
boolean	removeClipGroup() Removes a ZClipGroup edit group from above a node.
boolean	removeEditGroup(java.lang.Class aType) Looks for an edit group of matching type, and if found removes that edit group.
boolean	removeFadeGroup() Removes a ZFadeGroup edit group from above a node.
boolean	removeInvisibleGroup() Removes a ZInvisibleGroup edit group from above a node.
boolean	removeLayoutGroup() Removes a ZLayoutGroup edit group from above a node.
boolean	removeNameGroup() Removes a ZNameGroup edit group from above a node.
boolean	removeSelectionGroup() Removes a ZSelectionGroup edit group from above a node.
boolean	removeSpatialIndexGroup() Removes a ZSpatialIndexGroup edit group from above a node.
boolean	removeStickyGroup() Removes a ZStickyGroup edit group from above a node.
boolean	removeTransformGroup() Removes a TransformGroup edit group from above a node.
static void	setEditorOrder(java.lang.Class aType, int aOrder) Set the ordering information for aType of edit group.

Methods inherited from class java.lang.Object

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

Field Detail

NAME_GROUP_ORDER

public static final int NAME_GROUP_ORDER

Defines the ordering of the edit goups above the edit node.

INVISIBLE_GROUP_ORDER

public static final int INVISIBLE_GROUP_ORDER

LAYOUT_GROUP_ORDER

public static final int LAYOUT_GROUP_ORDER

ANCHOR_GROUP_ORDER

public static final int ANCHOR_GROUP_ORDER

TRANSFORM_GROUP_ORDER

public static final int TRANSFORM_GROUP_ORDER

STICKY_GROUP_ORDER

public static final int STICKY_GROUP_ORDER

SELECTION_GROUP_ORDER

public static final int SELECTION_GROUP_ORDER

CLIP_GROUP_ORDER

public static final int CLIP_GROUP_ORDER

FADE_GROUP_ORDER

public static final int FADE_GROUP_ORDER

SPATIAL_INDEX_GROUP_ORDER

public static final int SPATIAL_INDEX_GROUP_ORDER

editNode

protected ZNode editNode

The edit node. This node is found in the ZSceneGraphEditor constructor.

Constructor Detail

ZSceneGraphEditor

public ZSceneGraphEditor(ZNode aNode)

Create a new editor for aNode.

Method Detail

setEditorOrder

public static void setEditorOrder(java.lang.Class aType,
                                  int aOrder)

Set the ordering information for aType of edit group.

getTop

public ZNode getTop()

If ZSceneGraphEditor has inserted groups above a node, this returns the topmost of those groups (the group nearest the root of the scene graph). If no edit groups have been inserted above a node, this returns the node itself. This method is useful if you want to remove a node and also its associated edit groups from a scene graph.

Returns:

The top edit group, or the edit node of there are no edit groups.

getNode

public ZNode getNode()

Returns the node being edited. This is the node that is the bottom-most node of an edit group. It is defined as being this node, or the first descendant that does not have 'hasOneChild' set.

Returns:

The node being edited.

getGroups

public java.util.ArrayList getGroups()

Deprecated. as of Jazz 1.1 editorIterator() instead.

Returns an array representing the list of "edit" groups above the node - groups above the node whose hasOneChild flag is set to true. The groups are listed in bottom-top order.

editorIterator

public java.util.Iterator editorIterator()

Returns an iterator over the list of "edit" groups above the node - groups above the node whose hasOneChild flag is set to true. The groups are listed in bottom-top order.

Returns:

An iterator over the edit groups being managed.

getEditGroup

public ZGroup getEditGroup(java.lang.Class aType)

Checks to see if an editor of this type already exists, if so it returns that editor if not it creates a new editor, inserts that editor above the edit node, and then returns that new editor.

Parameters:

type - The type of edit group to return

Returns:

The edit group

getTransformGroup

public ZTransformGroup getTransformGroup()

Returns a ZTransformGroup to use for a node, inserting one above the edited node if none exists.

getFadeGroup

public ZFadeGroup getFadeGroup()

Returns a ZFadeGroup to use for a node, inserting one above the edited node if none exists.

getStickyGroup

public ZStickyGroup getStickyGroup()

Returns a ZStickyGroup to use for a node, inserting one above the edited node if none exists.

getSelectionGroup

public ZSelectionGroup getSelectionGroup()

Returns a ZSelectionGroup to use for a node, inserting one above the edited node if none exists.

getAnchorGroup

public ZAnchorGroup getAnchorGroup()

Returns a ZAnchorGroup to use for a node, inserting one above the edited node if none exists.

getLayoutGroup

public ZLayoutGroup getLayoutGroup()

Returns a ZLayoutGroup to use for a node, inserting one above the edited node if none exists.

getNameGroup

public ZNameGroup getNameGroup()

Returns a ZNameGroup to use for a node, inserting one above the edited node if none exists.

getInvisibleGroup

public ZInvisibleGroup getInvisibleGroup()

Returns a ZInvisibleGroup to use for a node, inserting one above the edited node if none exists.

getSpatialIndexGroup

public ZSpatialIndexGroup getSpatialIndexGroup()

Returns a ZSpatialIndexGroup to use for a node, inserting one above the edited node if none exists.

getClipGroup

public ZClipGroup getClipGroup()

Returns a ZClipGroup to use for a node, inserting one above the edited node if none exists.

hasEditGroup

public boolean hasEditGroup(java.lang.Class aType)

Searches to see if the edit node has an edit group of a matching type.

Parameters:

type - The type of edit group to search for.

Returns:

True if such an edit group was found.

hasTransformGroup

public boolean hasTransformGroup()

Returns true if this node has a ZTransformGroup above it as an edit group, false otherwise.

hasFadeGroup

public boolean hasFadeGroup()

Returns true if this node has a ZFadeGroup above it as an edit group, false otherwise.

hasStickyGroup

public boolean hasStickyGroup()

Returns true if this node has a ZStickyGroup above it as an edit group, false otherwise.

hasSelectionGroup

public boolean hasSelectionGroup()

Returns true if this node has a ZSelectionGroup above it as an edit group, false otherwise.

hasAnchorGroup

public boolean hasAnchorGroup()

Returns true if this node has a ZAnchorGroup above it as an edit group, false otherwise.

hasLayoutGroup

public boolean hasLayoutGroup()

Returns true if this node has a ZLayoutGroup above it as an edit group, false otherwise.

hasNameGroup

public boolean hasNameGroup()

Returns true if this node has a ZNameGroup above it as an edit group, false otherwise.

hasInvisibleGroup

public boolean hasInvisibleGroup()

Returns true if this node has a ZInvisibleGroup above it as an edit group, false otherwise.

hasSpatialIndexGroup

public boolean hasSpatialIndexGroup()

Returns true if this node has a ZSpatialIndexGroup above it as an edit group, false otherwise.

hasClipGroup

public boolean hasClipGroup()

Returns true if this node has a ZClipGroup above it as an edit group, false otherwise.

removeEditGroup

public boolean removeEditGroup(java.lang.Class aType)

Looks for an edit group of matching type, and if found removes that edit group.

Parameters:

type - The type of edit group to remove

Returns:

True if the edit group was found and removed.

removeTransformGroup

public boolean removeTransformGroup()

Removes a TransformGroup edit group from above a node. Returns true if the ZTransformGroup could be removed, false otherwise.

removeFadeGroup

public boolean removeFadeGroup()

Removes a ZFadeGroup edit group from above a node. Returns true if the ZFadeGroup could be removed, false otherwise.

removeStickyGroup

public boolean removeStickyGroup()

Removes a ZStickyGroup edit group from above a node. Returns true if the ZStickyGroup could be removed, false otherwise.

removeSelectionGroup

public boolean removeSelectionGroup()

Removes a ZSelectionGroup edit group from above a node. Returns true if the ZSelectionGroup could be removed, false otherwise.

removeAnchorGroup

public boolean removeAnchorGroup()

Removes a ZAnchorGroup edit group from above a node. Returns true if the ZAnchorGroup could be removed, false otherwise.

removeLayoutGroup

public boolean removeLayoutGroup()

Removes a ZLayoutGroup edit group from above a node. Returns true if the ZLayoutGroup could be removed, false otherwise.

removeNameGroup

public boolean removeNameGroup()

Removes a ZNameGroup edit group from above a node. Returns true if the ZNameGroup could be removed, false otherwise.

removeInvisibleGroup

public boolean removeInvisibleGroup()

Removes a ZInvisibleGroup edit group from above a node. Returns true if the ZInvisibleGroup could be removed, false otherwise.

removeClipGroup

public boolean removeClipGroup()

Removes a ZClipGroup edit group from above a node. Returns true if the ZClipGroup could be removed, false otherwise.

removeSpatialIndexGroup

public boolean removeSpatialIndexGroup()

Removes a ZSpatialIndexGroup edit group from above a node. Returns true if the ZSpatialIndexGroup could be removed, false otherwise.

isEditGroup

protected boolean isEditGroup(ZNode aNode)

Returns true if aNode is an edit group;

insertEditGroup

protected void insertEditGroup(ZGroup aGroup)

Insert aGroup above the edit node.

getOrderFor

protected int getOrderFor(java.lang.Class aType)

Returns the order where aType of editor group should be inserted above the edit node. If no order is specified then it returns MAX_VALUE, meaning that the edit group will be inserted at the top of the edit groups.