class MDGModifier

Jump to documentation

Inheritance:

MDGModifier

public members:

	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 ()

Documentation

Description

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; 
	}
  

Functions

MDGModifier:: MDGModifier ()

Description

The class constructor.

MDGModifier:: ~MDGModifier ()

Description

The class destructor.

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

Description

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.

Arguments

• typeId type of the node to create
• ReturnStatus return status

Return Value

• 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 )

Description

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.

Arguments

• typeId type name of the node to create
• ReturnStatus return status

Return Value

• 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 )

Description

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.

Arguments

• node node to delete

Return Value

• Return status

Status Codes

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

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

Description

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

Arguments

• node node to rename
• newName new name for the node

Return Value

• 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 )

Description

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

Arguments

• node node to toggle lock state
• newState new lock state

Return Value

• 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 )

Description

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.

Arguments

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

Return Value

• the return status

Status Codes

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

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

Description

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.

Arguments

• source the source plug in the connection
• dest the destination plug in the connection

Return Value

• the return status

Status Codes

• MS::kSuccess operation successful

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

Description

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

Arguments

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

Return Value

• the return status

Status Codes

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

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

Description

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

Arguments

• source the source plug in the connection
• dest the destination plug in the connection

Return Value

• the return status

Status Codes

• MS::kSuccess operation successful

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

Description

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.

Arguments

• node node to add an attribute to
• attribute attribute to add
• type determines if this is a local or global attribute

Return Value

• the return status

Status Codes

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

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

Description

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.

Arguments

• node node to add an attribute to
• attribute attribute to add
• type determines if this is a local or global attribute

Return Value

• the return status

Status Codes

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

MStatus MDGModifier:: commandToExecute ( const MString & command )

Description

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.

Arguments

• command the command that will be executed (should be undoable)

Return Value

• 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 )

Description

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

Arguments

• plug the plug to set
• plugValue the value to set

Return Value

• 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

MStatus MDGModifier:: doIt ()

Description

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.

Return Value

• the return status

Status Codes

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

MStatus MDGModifier:: undoIt ()

Description

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.

Return Value

• the return status

Status Codes

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

Direct child classes:

- MDagModifier