class MItDag

Jump to documentation

public members:

enum	TraversalType Secondary Direction of Traversal (Vertical or Horizontal) kInvalidType kDepthFirst kBreadthFirst
	MItDag ( TraversalType = kDepthFirst , MFn::Type = MFn::kInvalid, MStatus * ReturnStatus = NULL )
	MItDag ( MIteratorType & dagInfoObject, TraversalType = kDepthFirst , MStatus * ReturnStatus = NULL)
MStatus	reset ()
MStatus	reset ( const MObject & object, TraversalType = kDepthFirst , MFn::Type = MFn::kInvalid )
MStatus	reset ( const MDagPath & path, TraversalType = kDepthFirst , MFn::Type = MFn::kInvalid )
MStatus	reset ( MIteratorType & dagInfoObject, const MObject * object, const MDagPath * path, TraversalType = kDepthFirst )
MObject	item ( MStatus * ReturnStatus = NULL ) OBSOLETE
MObject	currentItem ( MStatus * ReturnStatus = NULL )
MStatus	next ()
MStatus	prune ()
bool	isDone ( MStatus * ReturnStatus = NULL ) const
MObject	root ( MStatus * ReturnStatus = NULL )
unsigned int	depth ( MStatus * ReturnStatus = NULL ) const
TraversalType	getType ( MStatus * ReturnStatus = NULL ) const
MStatus	getPath ( MDagPath & path ) const
MStatus	getAllPaths ( MDagPathArray & paths ) const
MString	fullPathName ( MStatus *ReturnStatus = NULL) const
MString	partialPathName ( MStatus *ReturnStatus = NULL) const
bool	isInstanced ( bool indirect = true, MStatus * ReturnStatus = NULL ) const
unsigned int	instanceCount ( bool total, MStatus * ReturnStatus = NULL ) const
MStatus	traverseUnderWorld ( bool flag )
bool	willTraverseUnderWorld ( MStatus * ReturnStatus = NULL ) const
virtual	~MItDag ()

Documentation

Class MItDag provides the capability to traverse the DAG and to retrieve specific nodes for subsequent querying and editing using compatible Function Sets.

Description

Use the DAG iterator to traverse the DAG either depth first or breadth first, visiting each node and, if desired, retrieving the node (as an MObject). The DAG iterator provides a basic filtering capability, so that DAG node retrieval can be limited to a specific type (MFn::Type) of node. With filtering enabled the iterator checks to see if the node is compatible with the type of Function Set specified by the filter. See MFn::Type for a list of all valid Function set types.

Since each object, if retrieved, is returned as an MObject, the MObject::hasFn() method can be used to further check for compatible function set types since an MObjects may be compatible with more than one function set).

Any compatible Function Set can be attached to the retrieved object to query or or edit it. Often you will want to use the DAG node Function Set (MFnDagNode), which is compatible with all DAG objects, to perform basic queries on each node as the iterator traverses the DAG.

The iterator also provides the capability to reset the root of the iteration, the type of traversal, and the filter.

Additionally, the iterator can be queried for the root, mode and type of traversal, and to determine if the the traversal has been completed.

Functions

MItDag:: MItDag ( MItDag::TraversalType type, MFn::Type filter, MStatus * ReturnStatus)

Description

Class Constructor

Initializes the root of iteration at the world node, sets the type of the traversal, and the filter. Sets a return status parameter to indicate success or failure.

Arguments

• type Enumerated type that determines the direction of the traversal
  • kDepthFirst - Traverse vertically first
  • kBreadthFirst - Traverse horizontally first
• filter Function set type (MFn::Type)
  • kInvalid - Filtering disabled
  • See MFn::Type for other values
• ReturnStatus Status Code (see below)

Status Codes

• MS::kSuccess Success
• MS::kInvlaidParameter Invalid parameter passed for mode or type
• MS::kFailure Failure creating iterator

MItDag:: MItDag ( MIteratorType & dagInfoObject, MItDag::TraversalType type, MStatus * ReturnStatus)

Description

Class Constructor

Initializes the root of iteration at the world node, sets the type of the traversal, and the filter list. Sets a return status parameter to indicate success or failure.

Arguments

• type Enumerated type that determines the direction of the traversal
  • kDepthFirst - Traverse vertically first
  • kBreadthFirst - Traverse horizontally first
• dagInfoObject Object which has details of type_filter or filter list.
• ReturnStatus Status Code (see below)

Status Codes

• MS::kSuccess Success
• MS::kInvlaidParameter Invalid parameter passed for mode or type
• MS::kFailure Failure creating iterator

MStatus MItDag:: reset ()

Description

Resets the iterator. The iterator is reset to the previous traversal setting.

Return Value

• MS::kSuccess operation successful
• MS::kFailure operation failed

MStatus MItDag:: reset ( const MObject & object, MItDag::TraversalType type, MFn::Type filter )

Description

Resets root, type and filter of the iterator.

Arguments

• object Root node to begin traversal
• type Enumerated type that determines the direction of the traversal
  • kDepthFirst - Traverse vertically first
  • kBreadthFirst - Traverse horizontally first
• filter Function set type (MFn::Type)
  • kInvalid - Filtering disabled
  • See MFn::Type for other values

Return Value

• MS::kSuccess Success
• MS::kInvalidParameter Invalid parameter passed for object, mode or type
• MS::kFailure Failure resetting iterator

MStatus MItDag:: reset ( const MDagPath & path, MItDag::TraversalType type, MFn::Type filter )

Description

Resets root, type and filter of the iterator. This method is usefull when a node is instanced and a DAG path is necessary to specify which instance should be the root of the traversal.

Arguments

• path Path to begin traversal
• type Enumerated type that determines the direction of the traversal
  • kInvalid - Invalid parameter. Not used.
  • kDepthFirst - Traverse vertically first
• filter Function set type (MFn::Type)
  • kInvalid - Filtering disabled
  • See MFn::Type for other values

Return Value

• MS::kSuccess Success
• MS::kInvlaidParameter Invalid parameter passed for object, mode or type
• MS::kFailure Failure resetting iterator

MStatus MItDag:: reset ( MIteratorType & dagInfoObject, const MObject * object, const MDagPath * path, MItDag::TraversalType type)

Description

Resets root, type and filter list of the iterator. This method is usefull when a node is instanced and a DAG path is necessary to specify which instance should be the root of the traversal.

Arguments

• dagInfoObject Iterator object having info on filter or filterlist.
• object MObject, to which the iterator will be reset to. This may be NULL if we are setting the iterator root to dagpath object.
• path MDagPath object, to which the iterator will be reset to. This may be NULL if we are setting the iterator root to MObject.
• type Enumerated type that determines the direction of the traversal
  • kInvalid - Invalid parameter. Not used.
  • kDepthFirst - Traverse vertically first

Return Value

• MS::kSuccess Success
• MS::kInvlaidParameter Invalid parameter passed for object, mode or type
• MS::kFailure Failure resetting iterator

MObject MItDag:: item ( MStatus * ReturnStatus)

Description

This method is OBSOLETE, please use the other currentItem method.

Retrieves DAG node to which the iterator points.

Arguments

• ReturnStatus Status Code (see below).

Return Value

• Pointer to the DAG node. Null pointer indicates failure.

Status Codes

• MS::kSuccess Success
• MS::kInvalidParameter Null DAG object - end of iteration
• MS::kFailure Object error

MObject MItDag:: currentItem ( MStatus * ReturnStatus)

Description

Retrieves DAG node to which the iterator points.

Arguments

• ReturnStatus Status Code (see below).

Return Value

• Pointer to the DAG node. Null pointer indicates failure.

Status Codes

• MS::kSuccess Success
• MS::kInvalidParameter Null DAG object - end of iteration
• MS::kFailure Object error

MStatus MItDag:: next ()

Description

Moves to the next node matching the filter in the graph.

Arguments

• ReturnStatus Status Code (see below)

Return Value

• MS::kSuccess Success
• MS::kFailure Object error

MStatus MItDag:: prune ()

Description

Prunes iteration tree at current node.

Arguments

• ReturnStatus Status Code (see below)

Return Value

• MS::kSuccess Success
• MS::kFailure Could not access node

bool MItDag:: isDone ( MStatus * ReturnStatus) const

Description

Indicates end of iteration path.

Arguments

• ReturnStatus Status Code (see below)

Return Value

• true Done
• false Not done

Status Codes

• MS::kSuccess Success
• MS::kFailure Object error

MObject MItDag:: root ( MStatus * ReturnStatus)

Description

Returns the root (start node) of the current traversal. The constructor sets the root of traversal to the world node. The root can be changed by the reset() method.

Arguments

• ReturnStatus Status Code (see below)

Return Value

• Root of the traversal

Status Codes

• MS::kSuccess Success
• MS::kFailure Could not access node

unsigned int MItDag:: depth ( MStatus * ReturnStatus) const

Description

Returns the height or depth of the current node in the DAG relative to the root node. The root node has a depth of zero.

Arguments

• ReturnStatus Status Code (see below)

Return Value

• Depth of the current node

Status Codes

• MS::kSuccess Success
• MS::kFailure Object error

MItDag::TraversalType MItDag:: getType ( MStatus * ReturnStatus) const

Description

Returns the direction of the traversal.

Arguments

• ReturnStatus Status Code (see below)

Return Value

• kDepthFirst Recursively visits grandchildren of each child node
• kBreadthFirst Recursively visits each child/parent node before any grandchild/grandparent nodes

Status Codes

• MS::kSuccess Success
• MS::kFailure Object error or internal error

MStatus MItDag:: getPath ( MDagPath & path ) const

Determines a DAG Path to the current item in the iteration.

Arguments

• path The DAG Path that is found (implicit return)

Return Value

• Status Code (see below)

Status Codes

• MS::kSuccess Success
• MS::kFailure Object error or NULL DAG node

MStatus MItDag:: getAllPaths ( MDagPathArray & paths ) const

Determines all DAG Paths to current item in the iteration.

Arguments

• path Array of all DAG Paths that are found (implicit return)

Return Value

• Status Code (see below)

Status Codes

• MS::kSuccess Success
• MS::kFailure Object error or invalid DAG node

MString MItDag:: fullPathName ( MStatus *ReturnStatus) const

Return a string representing the full path from the root of the dag to this object.

Arguments

• ReturnStatus Status Code (see below)

Return Value

• The full path name

Status Codes

• MS::kSuccess Success
• MS::kFailure Object error or invalid DAG node

MString MItDag:: partialPathName ( MStatus *ReturnStatus) const

Return a string representing the partial path from the root of the dag to this object.

The partial path is the minimum path that is still unique. This string may contain wildcards.

Arguments

• ReturnStatus Status Code (see below)

Return Value

• The partial path name

Status Codes

• MS::kSuccess Success
• MS::kFailure Object error or invalid DAG node

bool MItDag:: isInstanced ( bool indirect, MStatus * ReturnStatus ) const

Determines whether the current item (DAG node) in the iteration is directly or indirectly instanced.

If indirect instance flag is false, the result is true if and only if the Node itself is multiply instanced (node->parentCount > 1).

If the indirect flag is true, the result is true if and only if the Node itself is multiply instanced (node->parentCount > 1) or if the Node is not multipuly instanced, but it has a directly instanced parent (node->parentCount()=1 and parent->parentCount >1).

Arguments

• indirect Indirect instance flag
• ReturnStatus Status Code (see below)

Return Value

• true = Node is instanced (directly or indirectly according to indirect instance flag)
• false = Node is not instanced (directly or indirectly according to indirect instance flag)

Status Codes

• MS::kSuccess Success
• MS::kFailure Object error or invalid DAG node

unsigned int MItDag:: instanceCount ( bool total, MStatus * ReturnStatus ) const

Description

Determines the number of times the current item (DAG node) in the iteration is instanced.

If indirect instance flag is false, the number of direct instances is returned.

If the indirect flag is true, the total number of times the Node is instanced in the DAG above it is returned.

Arguments

• indirect Indirect instance flag
• ReturnStatus Status Code (see below)

Return Value

• Number of instances (direct or indirect according to indirect instance flag).

Status Codes

• MS::kSuccess Success
• MS::kFailure Object error or invalid DAG node

MStatus MItDag:: traverseUnderWorld ( bool flag )

Description

Specifies whether underworld traversal is turned on. The default is off.

The underworld for a shape is a sub dag that hangs off of the shape. For example, if you have a curve on surface for a shape then there will be an underworld or sub-dag for the curve on surface.

Arguments

• flag turns on/off underworld traversal

Return Value

• Status Code (see below)

Status Codes

• MS::kSuccess Success
• MS::kFailure Object error

bool MItDag:: willTraverseUnderWorld ( MStatus * ReturnStatus ) const

Description

Returns true if this iterator will traverse into underworld items.

The underworld for a shape is a sub dag that hangs off of the shape. For example, if you have a curve on surface for a shape then there will be an underworld or sub-dag for the curve on surface.

Arguments

• ReturnStatus Status Code (see below)

Return Value

• true underworld traversal is on
• false underworld traversal is off

Status Codes

• MS::kSuccess Success
• MS::kFailure Object error

MItDag:: ~MItDag ()

Description

Class Destructor

Deletes iterator.

Description

Checks if the given Mobject has any of the function type given in the filter list.

Arguments

• ReturnStatus Status Code (see below).

Return Value

• Boolean indicating whether the object is having the given function type or not.

Status Codes

• MS::kSuccess Success
• MS::kFailure Object error

Description

Checks if the given dagpath has any of the function type given in the filter list.

Arguments

• ReturnStatus Status Code (see below).

Return Value

• Boolean indicating whether the object is having the given function type or not.

Status Codes

• MS::kSuccess Success
• MS::kFailure Object error

Description

Checks whether the type filter or filterlist is on the mobject.

Arguments

• path mobject
• type Enumerated type that determines the direction of the traversal
  • kDepthFirst - Traverse vertically first
  • kBreadthFirst - Traverse horizontally first

Return Value

• MS::kSuccess Success
• MS::kInvalidParameter Invalid parameter passed for object, mode or type
• MS::kFailure Failure resetting iterator

Description

Checks whether the type filter or filterlist is on the dagpath.

Arguments

• path Dagpath
• type Enumerated type that determines the direction of the traversal
  • kDepthFirst - Traverse vertically first
  • kBreadthFirst - Traverse horizontally first

Return Value

• MS::kSuccess Success
• MS::kInvalidParameter Invalid parameter passed for object, mode or type
• MS::kFailure Failure resetting iterator

This class has no child classes.