MDGModifier Class Reference
[OpenMaya - API module for common classes]

#include <MDGModifier.h>

Inheritance diagram for MDGModifier:

[legend]

List of all members.

---

Detailed Description

Dependency graph modifier.

An MDGModifier is used to change the structure of the dependency graph. This includes adding nodes, making new connections, and removing existing connections. To perform operations using an MDGModifier, register all of the changes that are to be made and then call the doIt method to make the changes. Undo is provided through the undoIt method.

Under some situations, a doIt() call may be required to separate some of the operations. The specific case of interest involves performing a disconnect() and a deleteNode() on the same node within the stack of operations.

Assuming that the Maya model has a connected node that was going to be deleted, do the following:

        MStatus cmd::redoIt()
        {
                MStatus result = dgModifier.disconnect(plugA, plugB);
                if (!result)
                        ...
                result = dgModifier.doIt();
                if (!result)
                        ...

                result = dgModifier.deleteNode(plugBNode);
                if (!result)
                        ...

                result = dgModifier.doIt();
                if (!result)
                        ...

                return result;
        }

Then undoIt() can be implemented as:

        MStatus cmd::undoIt()
        {
                MStatus result = dgModifier.undoIt();
                if (!result)
                        ...
                return result;
        }

Examples:

cgfxAttrDef.cpp, cgfxAttrDef.h, cgfxShaderCmd.cpp, cgfxShaderCmd.h, cgfxShaderNode.cpp, closestPointOnCurveCmd.cpp, createClipCmd.cpp, D3DResourceManager.cpp, deletedMsgCmd.cpp, geometrySurfaceConstraint.cpp, geometrySurfaceConstraint.h, GLSLShaderNode.cpp, GLSLShaderNode.h, latticeNoiseCmd.cpp, narrowPolyViewer.h, pointOnMeshCmd.cpp, polyModifierCmd.cpp, polyModifierCmd.h, and polyPrimitiveCmd.cpp.

Public Member Functions
	MDGModifier ()
virtual	~MDGModifier ()
MObject	createNode (const MTypeId &typeId, MStatus *ReturnStatus=NULL)
MObject	createNode (const MString &type, MStatus *ReturnStatus=NULL)
MStatus	deleteNode (const MObject &node)
MStatus	renameNode (const MObject &node, const MString &newName)
MStatus	setNodeLockState (const MObject &node, bool newState)
MStatus	connect (const MObject &sourceNode, const MObject &sourceAttr, const MObject &destNode, const MObject &destAttr)
MStatus	disconnect (const MObject &sourceNode, const MObject &sourceAttr, const MObject &destNode, const MObject &destAttr)
MStatus	connect (const MPlug &source, const MPlug &dest)
MStatus	disconnect (const MPlug &source, const MPlug &dest)
MStatus	addAttribute (const MObject &node, const MObject &attribute, MFnDependencyNode::MAttrClass type=MFnDependencyNode::kLocalDynamicAttr)
MStatus	removeAttribute (const MObject &node, const MObject &attribute, MFnDependencyNode::MAttrClass type=MFnDependencyNode::kLocalDynamicAttr)
MStatus	commandToExecute (const MString &command)
MStatus	newPlugValue (const MPlug &plug, MObject &plugValue)
MStatus	doIt ()
MStatus	undoIt ()

---

Constructor & Destructor Documentation

MDGModifier::MDGModifier

(

)

The class constructor.

MDGModifier::~MDGModifier

(

)

[virtual]

The class destructor.

---

Member Function Documentation

MObject MDGModifier::createNode	(	const MTypeId &	typeId,
		MStatus *	ReturnStatus = NULL
	)

This method adds an operation to this dependency graph modifier that will add a new dependency graph node of the given type to the dependency graph. This method may not be used to construct new DAG nodes. Use MDagModifier for that purpose.

When createNode is called, the new node is created and the MObject handle for it is returned. It should be noted that the node will not be added to the dependency graph until the doIt method is called.

If a node is created with this method, but the operation is undone, then the MDGModifier will take responsibility for freeing the node. This will be done when the MDGModifier is destructed.

Parameters:

[in]	typeId	type of the node to create
[out]	ReturnStatus	return status

Returns:

A handle for the new node

Status Codes:

• MS::kSuccess operation successful
• MS::kInvalidParameter the type passed in is not valid or the type is a DAG node (see MDagModifier)

MObject MDGModifier::createNode	(	const MString &	type,
		MStatus *	ReturnStatus = NULL
	)

This method adds an operation to this dependency graph modifier that will add a new dependency graph node of the given type to the dependency graph. This method may not be used to construct new DAG nodes. Use MDagModifier for that purpose.

When createNode is called, the new node is created and the MObject handle for it is returned. It should be noted that the node will not be added to the dependency graph until the doIt method is called.

If a node is created with this method, but the operation is undone, then the MDGModifier will take responsibility for freeing the node. This will be done when the MDGModifier is destructed.

Parameters:

[in]	type	type name of the node to create
[out]	ReturnStatus	return status

Returns:

A handle for the new node

Status Codes:

• MS::kSuccess operation successful
• MS::kInvalidParameter the type passed in is not valid or the type is a DAG node (see MDagModifier)

MStatus MDGModifier::deleteNode

(

const MObject &

node

)

This method adds an operation to this dependency graph modifier that will delete a dependency graph node from the dependency graph.

Information on disconnecting and deleting a node using a single MDGModifier can be found in the class description.

Parameters:

[in]

node

node to delete

Returns:

Return status

Status Codes:

• MS::kSuccess operation successful
• MS::kInvalidParameter the node is invalid or is NULL

Examples:

cgfxAttrDef.cpp, and polyPrimitiveCmd.cpp.

MStatus MDGModifier::renameNode	(	const MObject &	node,
		const MString &	newName
	)

This method adds an operation to this dependency graph modifier that will rename a dependency graph node.

Parameters:

[in]	node	node to rename
[in]	newName	new name for the node

Returns:

Return status

Status Codes:

• MS::kSuccess operation successful
• MS::kInvalidParameter the node is invalid or is NULL

MStatus MDGModifier::setNodeLockState	(	const MObject &	node,
		bool	newState
	)

This method adds an operation to this dependency graph modifier that will set the lock state of the node.

Parameters:

[in]	node	node to toggle lock state
[in]	newState	new lock state

Returns:

Return status

Status Codes:

• MS::kSuccess operation successful
• MS::kInvalidParameter the node is invalid or is NULL

MStatus MDGModifier::connect	(	const MObject &	sourceNode,
		const MObject &	sourceAttr,
		const MObject &	destNode,
		const MObject &	destAttr
	)

Adds an operation to this dependency graph modifier that connects two attributes of two nodes in the dependency graph. The value of the destination attribute is supplied by the value of the source attribute once they are connected.

It is the users responsibility to ensure that the source and destination attributes are of compatible types. For instance, if the source attribute is a nurbs surface then the destination must also be a nurbs surface.

To connect array attributes use the other version of connect which takes MPlugs as parameters.

Parameters:

[in]	sourceNode	the source node in the connection
[in]	sourceAttr	the attribute of the source node that is to be connected
[in]	destNode	the destination node in the connection
[in]	destAttr	the attribute of the destination node that is to be connected

Returns:

The return status

Status Codes:

• MS::kSuccess operation successful
• MS::kInvalidParameter one of the input objects is invalid

Examples:

cgfxAttrDef.cpp, closestPointOnCurveCmd.cpp, latticeNoiseCmd.cpp, offsetNode.cpp, pointOnMeshCmd.cpp, and polyModifierCmd.cpp.

MStatus MDGModifier::disconnect	(	const MObject &	sourceNode,
		const MObject &	sourceAttr,
		const MObject &	destNode,
		const MObject &	destAttr
	)

Adds an operation to this dependency graph modifier that disconnects two attributes of two nodes in the dependency graph.

Parameters:

[in]	sourceNode	the source node in the connection
[in]	sourceAttr	the attribute of the source node that is connected
[in]	destNode	the destination node in the connection
[in]	destAttr	the attribute of the destination node that is connected

Returns:

The return status

Status Codes:

• MS::kSuccess operation successful
• MS::kInvalidParameter one of the input objects is invalid

Examples:

cgfxAttrDef.cpp, and latticeNoiseCmd.cpp.

MStatus MDGModifier::connect	(	const MPlug &	source,
		const MPlug &	dest
	)

Adds an operation to this dependency graph modifier that connects two plugs in the dependency graph. The value of the destination plug is supplied by the value of the source plug once they are connected.

It is the users responsibility to ensure that the source and destination attributes are of compatible types. For instance, if the source attribute is a nurbs surface then the destination must also be a nurbs surface.

Parameters:

[in]	source	the source plug in the connection
[in]	dest	the destination plug in the connection

Returns:

The return status

Status Codes:

• MS::kSuccess operation successful

MStatus MDGModifier::disconnect	(	const MPlug &	source,
		const MPlug &	dest
	)

Adds an operation to this dependency graph modifier that disconnects two plugs in the dependency graph.

Parameters:

[in]	source	the source plug in the connection
[in]	dest	the destination plug in the connection

Returns:

The return status

Status Codes:

• MS::kSuccess operation successful

MStatus MDGModifier::addAttribute	(	const MObject &	node,
		const MObject &	attribute,
		MFnDependencyNode::MAttrClass	type = MFnDependencyNode::kLocalDynamicAttr
	)

Add a new dynamic attribute to the given dependency node. The type parameter allows the attribute to be added to a particular node, or the whole class of nodes.

This method also adds all children of the attribute if it is a compound. So, if a compound attribute is being added to a node, then only the parent attribute needs to be added using this method.

Parameters:

[in]	node	node to add an attribute to
[in]	attribute	attribute to add
[in]	type	determines if this is a local or global attribute

Returns:

The return status

Status Codes:

• MS::kSuccess operation successful
• MS::kInvalidParameter either the node or attribute is invalid or the attribute already exists.

Examples:

cgfxAttrDef.cpp, and GLSLShaderNode.cpp.

MStatus MDGModifier::removeAttribute	(	const MObject &	node,
		const MObject &	attribute,
		MFnDependencyNode::MAttrClass	type = MFnDependencyNode::kLocalDynamicAttr
	)

Removes a dynamic attribute from the given dependency node.

This method also removes all children of the attribute if it is a compound.

Note: After a successful call to this method, the MObject passed to it that contains the attribute will have been reset to MObject::kNullObj because the attribute it referenced no longer exists. Thus no function sets, such as MFnAttribute, should be attached to the MObject at the time this call is made.

Parameters:

[in]	node	node to add an attribute to
[in]	attribute	attribute to add
[in]	type	determines if this is a local or global attribute

Returns:

The return status

Status Codes:

• MS::kSuccess operation successful
• MS::kInvalidParameter either the node or attribute is invalid

Examples:

cgfxAttrDef.cpp, and GLSLShaderNode.cpp.

MStatus MDGModifier::commandToExecute

(

const MString &

command

)

Adds an operation to this dependency graph modifier that executes a MEL command. The specified command must be undoable otherwise unexepected results may occur.

NOTE: It is best to use multiple commandToExecute() calls rather than batching multiple commands into one call to commandToExecute(). Using one command per call to commandToExecute() will simplify the undo stack which is important in case of command failure.

Parameters:

[in]

command

the command that will be executed (should be undoable)

Returns:

The return status

Status Codes:

• MS::kSuccess operation successful
• MS::kInsufficientMemory No memory available.
• MS::kFailure operation failed

MStatus MDGModifier::newPlugValue	(	const MPlug &	plug,
		MObject &	plugValue
	)

Adds an operation to this dependency graph modifier that sets a plug value. Plug values can be created with the MFnNumericData class.

Parameters:

[in]	plug	the plug to set
[in]	plugValue	the value to set

Returns:

The return status

Status Codes:

• MS::kSuccess operation successful
• MS::kInvalidParameter plug or plugValue are null
• MS::kInsufficientMemory No memory available.
• MS::kFailure operation failed

Examples:

geometrySurfaceConstraint.cpp.

MStatus MDGModifier::doIt

(

)

Executes all of the operations that have been given to this modifier. It is only valid to call this method after all of the operations have been specified. This method may also be called after undoIt to redo the operations.

Returns:

The return status

Status Codes:

• MS::kSuccess operation successful
• MS::kFailure operation failed because at least one of the operations was invalid

Examples:

cgfxAttrDef.cpp, cgfxShaderNode.cpp, closestPointOnCurveCmd.cpp, GLSLShaderNode.cpp, latticeNoiseCmd.cpp, pointOnMeshCmd.cpp, polyModifierCmd.cpp, and polyPrimitiveCmd.cpp.

MStatus MDGModifier::undoIt

(

)

Undoes all of the operations that have been given to this modifier. It is only valid to call this method after the doIt method has been called.

Returns:

The return status

Status Codes:

• MS::kSuccess operation successful
• MS::kFailure operation failed because at least one of the operations was invalid

Examples:

polyModifierCmd.cpp.