Public Member Functions | Static Public Member Functions

MDGModifier Class Reference

This reference page is linked to from the following overview topics: Extension for Autodesk Maya 2013, Autodesk Maya 2013, Creating and Manipulating Objects, polyModifierCmd example.


Search for all occurrences

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

MDGModifier does not understanding the hierarchical relationship between DAG nodes. When performing DG operations on DAG nodes MDagModifier should be used instead. In some cases MDagModifier may even be required when operating on non-DAG nodes. For example, a container node is a non-DAG node but it may contain DAG nodes. When the container is deleted its members will be deleted as well. Since some of those members may be DAG nodes an MDagModifier should be used to delete the container node.

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, and polyModifierCmd.h.

#include <MDGModifier.h>

Inheritance diagram for MDGModifier:
Inheritance graph
[legend]

List of all members.

Public Member Functions

 MDGModifier ()
 The class constructor.
virtual ~MDGModifier ()
 The class destructor.
MObject 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.
MObject 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.
MStatus 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.
MStatus renameNode (const MObject &node, const MString &newName)
 This method adds an operation to this dependency graph modifier that will rename a dependency graph node.
MStatus 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.
MStatus 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.
MStatus 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.
MStatus connect (const MPlug &source, const MPlug &dest)
 Adds an operation to this dependency graph modifier that connects two plugs in the dependency graph.
MStatus disconnect (const MPlug &source, const MPlug &dest)
 Adds an operation to this dependency graph modifier that disconnects two plugs in the dependency graph.
MStatus addAttribute (const MObject &node, const MObject &attribute)
 Add a new dynamic attribute to the given dependency node.
MStatus removeAttribute (const MObject &node, const MObject &attribute)
 Removes a dynamic attribute from the given dependency node.
MStatus addExtensionAttribute (const MNodeClass &nodeClass, const MObject &attribute)
 Add a new extension attribute to the given dependency node class.
MStatus removeExtensionAttribute (const MNodeClass &nodeClass, const MObject &attribute)
 Removes an extension attribute from the given dependency node type.
MStatus removeExtensionAttributeIfUnset (const MNodeClass &nodeClass, const MObject &attribute)
 Removes an extension attribute from the given dependency node type but only if there are no nodes in the graph with non-default values for this attribute.
MStatus linkExtensionAttributeToPlugin (const MObject &plugin, const MObject &attribute)
 The plugin calls this to indicate that the extension attribute defines part of the plugin, regardless of the node type to which it attaches itself.
MStatus unlinkExtensionAttributeFromPlugin (const MObject &mPlugin, const MObject &mAttribute)
 Tells a plugin that it no longer requires an extension attribute for operation.
MStatus commandToExecute (const MString &command)
 Adds an operation to this dependency graph modifier that executes a MEL command.
MStatus newPlugValue (const MPlug &plug, MObject &plugValue)
 Adds an operation to this dependency graph modifier that sets a plug value.
MStatus newPlugValueBool (const MPlug &plug, bool plugValue)
 Adds an operation to this dependency graph modifier that sets a plug to a boolean value.
MStatus newPlugValueChar (const MPlug &plug, char plugValue)
 Adds an operation to this dependency graph modifier that sets a plug to a char value.
MStatus newPlugValueDouble (const MPlug &plug, double plugValue)
 Adds an operation to this dependency graph modifier that sets a plug to a double value.
MStatus newPlugValueFloat (const MPlug &plug, float plugValue)
 Adds an operation to this dependency graph modifier that sets a plug to a float value.
MStatus newPlugValueInt (const MPlug &plug, int plugValue)
 Adds an operation to this dependency graph modifier that sets a plug to an int value.
MStatus newPlugValueMAngle (const MPlug &plug, const MAngle &plugValue)
 Adds an operation to this dependency graph modifier that sets a plug to an MAngle value.
MStatus newPlugValueMDistance (const MPlug &plug, const MDistance &plugValue)
 Adds an operation to this dependency graph modifier that sets a plug to an MDistance value.
MStatus newPlugValueMTime (const MPlug &plug, const MTime &plugValue)
 Adds an operation to this dependency graph modifier that sets a plug to an MTime value.
MStatus newPlugValueShort (const MPlug &plug, short plugValue)
 Adds an operation to this dependency graph modifier that sets a plug to a short value.
MStatus newPlugValueString (const MPlug &plug, const MString &plugValue)
 Adds an operation to this dependency graph modifier that sets a plug to a string value.
MStatus doIt ()
 Executes all of the operations that have been given to this modifier.
MStatus undoIt ()
 Undoes all of the operations that have been given to this modifier.
MStatus addAttribute (const MObject &node, const MObject &attribute, MFnDependencyNode::MAttrClass type)
MStatus removeAttribute (const MObject &node, const MObject &attribute, MFnDependencyNode::MAttrClass type)

Static Public Member Functions

static const char * className ()
 Returns the name of this class.

Member Function Documentation

MObject 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]typeIdtype of the node to create
[out]ReturnStatusreturn status
Returns:
A handle for the new node
Status Codes:
MObject 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]typetype name of the node to create
[out]ReturnStatusreturn status
Returns:
A handle for the new node
Status Codes:
MStatus 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]nodenode to delete
Returns:
Return status
Status Codes:
Examples:
cgfxAttrDef.cpp.
MStatus 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]nodenode to rename
[in]newNamenew name for the node
Returns:
Return status
Status Codes:
MStatus 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]nodenode to toggle lock state
[in]newStatenew lock state
Returns:
Return status
Status Codes:
MStatus 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]sourceNodethe source node in the connection
[in]sourceAttrthe attribute of the source node that is to be connected
[in]destNodethe destination node in the connection
[in]destAttrthe attribute of the destination node that is to be connected
Returns:
The return status
Status Codes:
Examples:
cgfxAttrDef.cpp, closestPointOnCurveCmd.cpp, latticeNoiseCmd.cpp, offsetNode.cpp, pointOnMeshCmd.cpp, polyModifierCmd.cpp, and polyPrimitiveCmd.cpp.
MStatus 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]sourceNodethe source node in the connection
[in]sourceAttrthe attribute of the source node that is connected
[in]destNodethe destination node in the connection
[in]destAttrthe attribute of the destination node that is connected
Returns:
The return status
Status Codes:
Examples:
cgfxAttrDef.cpp, and latticeNoiseCmd.cpp.
MStatus 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]sourcethe source plug in the connection
[in]destthe destination plug in the connection
Returns:
The return status
Status Codes:
MStatus 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]sourcethe source plug in the connection
[in]destthe destination plug in the connection
Returns:
The return status
Status Codes:
MStatus addAttribute ( const MObject node,
const MObject attribute 
)

Add a new dynamic attribute to the given dependency node.

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]nodenode to which to add the attribute
[in]attributeattribute to add
Returns:
The return status
Status Codes:
Examples:
cgfxAttrDef.cpp, GLSLShaderNode.cpp, and polyPrimitiveCmd.cpp.
MStatus removeAttribute ( const MObject node,
const MObject attribute 
)

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]nodenode to add an attribute to
[in]attributeattribute to add
Returns:
The return status
Status Codes:
Examples:
cgfxAttrDef.cpp, and GLSLShaderNode.cpp.
MStatus addExtensionAttribute ( const MNodeClass nodeClass,
const MObject attribute 
)

Add a new extension attribute to the given dependency node class.

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 type, then only the parent attribute needs to be added using this method.

Parameters:
[in]nodeClassclass of node to which to add the attribute
[in]attributeattribute to add
Returns:
The return status
Status Codes:
MStatus removeExtensionAttribute ( const MNodeClass nodeClass,
const MObject attribute 
)

Removes an extension attribute from the given dependency node type.

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 may no longer exist. Thus no function sets, such as MFnAttribute, should be attached to the MObject at the time this call is made.

Parameters:
[in]nodeClassclass of node from which to remove the attribute
[in]attributeattribute to remove
Returns:
The return status
Status Codes:
MStatus removeExtensionAttributeIfUnset ( const MNodeClass nodeClass,
const MObject attribute 
)

Removes an extension attribute from the given dependency node type but only if there are no nodes in the graph with non-default values for this attribute.

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 may have been reset to MObject::kNullObj because the attribute it referenced may no longer exist. Thus no function sets, such as MFnAttribute, should be attached to the MObject at the time this call is made.

Parameters:
[in]nodeClassclass of node from which to remove the attribute
[in]attributeattribute to remove
Returns:
The return status
Status Codes:
MStatus linkExtensionAttributeToPlugin ( const MObject mPlugin,
const MObject mAttribute 
)

The plugin calls this to indicate that the extension attribute defines part of the plugin, regardless of the node type to which it attaches itself.

This requirement is used when the plugin is checked to see if it is in use or if is able to be unloaded or if it is required as part of a stored file.

This should only be called once for root attributes (i.e. those with no parent). It is an error to call it with a child attribute. All children and ancestors are recursively tested. Forcing it to be called only on the root keeps the calling code simple and avoids duplicate calls.

Parameters:
[in]mPluginplugin to which the attribute is to be tied
[in]mAttributeattribute to associate with the plugin, must not have a parent
Returns:
The return status
Status Codes:
MStatus unlinkExtensionAttributeFromPlugin ( const MObject mPlugin,
const MObject mAttribute 
)

Tells a plugin that it no longer requires an extension attribute for operation.

This requirement is used when the plugin is checked to see if it is in use or if is able to be unloaded.

This should only be called once for root attributes (i.e. those with no parent). It is an error to call it with a child attribute. All children and ancestors are recursively removed. Forcing it to be called only on the root keeps the calling code simple and avoids duplicate calls.

Parameters:
[in]mPluginplugin from which the attribute is to be released
[in]mAttributeattribute to disassociate with the plugin, must not have a parent
Returns:
The return status
Status Codes:
MStatus 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]commandthe command that will be executed (should be undoable)
Returns:
The return status
Status Codes:
Examples:
cgfxAttrDef.cpp.
MStatus 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]plugthe plug to set
[in]plugValuethe value to set
Returns:
The return status
Status Codes:
Examples:
geometrySurfaceConstraint.cpp.
MStatus newPlugValueBool ( const MPlug plug,
bool  plugValue 
)

Adds an operation to this dependency graph modifier that sets a plug to a boolean value.

Parameters:
[in]plugthe plug to set
[in]plugValuethe value to set
Returns:
The return status
Status Codes:
MStatus newPlugValueChar ( const MPlug plug,
char  plugValue 
)

Adds an operation to this dependency graph modifier that sets a plug to a char value.

Parameters:
[in]plugthe plug to set
[in]plugValuethe value to set
Returns:
The return status
Status Codes:
MStatus newPlugValueDouble ( const MPlug plug,
double  plugValue 
)

Adds an operation to this dependency graph modifier that sets a plug to a double value.

Parameters:
[in]plugthe plug to set
[in]plugValuethe value to set
Returns:
The return status
Status Codes:
MStatus newPlugValueFloat ( const MPlug plug,
float  plugValue 
)

Adds an operation to this dependency graph modifier that sets a plug to a float value.

Parameters:
[in]plugthe plug to set
[in]plugValuethe value to set
Returns:
The return status
Status Codes:
MStatus newPlugValueInt ( const MPlug plug,
int  plugValue 
)

Adds an operation to this dependency graph modifier that sets a plug to an int value.

Parameters:
[in]plugthe plug to set
[in]plugValuethe value to set
Returns:
The return status
Status Codes:
MStatus newPlugValueMAngle ( const MPlug plug,
const MAngle plugValue 
)

Adds an operation to this dependency graph modifier that sets a plug to an MAngle value.

Parameters:
[in]plugthe plug to set
[in]plugValuethe value to set
Returns:
The return status
Status Codes:
MStatus newPlugValueMDistance ( const MPlug plug,
const MDistance plugValue 
)

Adds an operation to this dependency graph modifier that sets a plug to an MDistance value.

Parameters:
[in]plugthe plug to set
[in]plugValuethe value to set
Returns:
The return status
Status Codes:
MStatus newPlugValueMTime ( const MPlug plug,
const MTime plugValue 
)

Adds an operation to this dependency graph modifier that sets a plug to an MTime value.

Parameters:
[in]plugthe plug to set
[in]plugValuethe value to set
Returns:
The return status
Status Codes:
MStatus newPlugValueShort ( const MPlug plug,
short  plugValue 
)

Adds an operation to this dependency graph modifier that sets a plug to a short value.

Parameters:
[in]plugthe plug to set
[in]plugValuethe value to set
Returns:
The return status
Status Codes:
MStatus newPlugValueString ( const MPlug plug,
const MString plugValue 
)

Adds an operation to this dependency graph modifier that sets a plug to a string value.

Parameters:
[in]plugthe plug to set
[in]plugValuethe value to set
Returns:
The return status
Status Codes:
MStatus 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:
Examples:
cgfxAttrDef.cpp, cgfxShaderNode.cpp, closestPointOnCurveCmd.cpp, GLSLShaderNode.cpp, latticeNoiseCmd.cpp, pointOnMeshCmd.cpp, polyModifierCmd.cpp, and polyPrimitiveCmd.cpp.
MStatus 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:
Examples:
polyModifierCmd.cpp, and polyPrimitiveCmd.cpp.
const char * className ( ) [static]

Returns the name of this class.

Returns:
The name of this class.

Reimplemented in MDagModifier.

MStatus addAttribute ( const MObject node,
const MObject attribute,
MFnDependencyNode::MAttrClass  type 
)
Deprecated:
Use the method MDGModifier::addAttribute( const MObject&, const MObject& ) instead

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]nodenode to add an attribute to
[in]attributeattribute to add
[in]typedetermines if this is a local or global attribute
Returns:
The return status
Status Codes:
MStatus removeAttribute ( const MObject node,
const MObject attribute,
MFnDependencyNode::MAttrClass  type 
)
Deprecated:
Use MDGModifier::removeAttribute( const MObject&, const MObject& ) instead

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]nodenode to add an attribute to
[in]attributeattribute to add
[in]typedetermines if this is a local or global attribute
Returns:
The return status
Status Codes:

MDGModifier MDGModifier MDGModifier MDGModifier MDGModifier MDGModifier MDGModifier MDGModifier MDGModifier MDGModifier
MDGModifier MDGModifier MDGModifier MDGModifier MDGModifier MDGModifier MDGModifier MDGModifier MDGModifier MDGModifier