MDGModifier Class Reference
 
 
 
MDGModifier Class Reference

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


#include <MDGModifier.h>


Class 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:

AbcImport/NodeIteratorVisitorHelper.cpp, AbcImport/util.cpp, AshliShader/GLSLShaderNode.cpp, atomImportExport/atomFileUtils.cpp, cgfxAttrDef.cpp, cgfxAttrDef.h, cgfxShaderCmd.cpp, cgfxShaderCmd.h, cgfxShaderNode.cpp, closestPointOnCurve/closestPointOnCurveCmd.cpp, createClipCmd/createClipCmd.cpp, D3DViewportRenderer/D3DResourceManager.cpp, deletedMsgCmd/deletedMsgCmd.cpp, dx11Shader/dx11Shader.cpp, DX11ViewportRenderer/DX11ResourceManager.cpp, geometrySurfaceConstraint/geometrySurfaceConstraint.cpp, geometrySurfaceConstraint/geometrySurfaceConstraint.h, GLSLShaderNode.h, gpuCache/gpuCacheCmd.cpp, latticeNoise/latticeNoiseCmd.cpp, meshOpCmd/polyModifierCmd.cpp, meshOpCmd/polyModifierCmd.h, MetadataSample/createMetadataCmd.h, MetadataSample/importMetadataCmd.h, narrowPolyViewer/narrowPolyViewer.h, pointOnMeshInfo/pointOnMeshCmd.cpp, splitUVCmd/polyModifierCmd.cpp, splitUVCmd/polyModifierCmd.h, and xmlAssembly/BBoxesRep.cpp.

Inheritance diagram for MDGModifier:
MDagModifier

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  setMetadata (const MObject &node, const adsk::Data::Associations &metadata)
  Adds an operation to this dependency graph modifier that replaces metadata on a specific node.
MStatus  deleteMetadata (const MObject &node)
  Adds an operation to this dependency graph modifier that deletes all metadata from a node.
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] typeId type of the node to create
[out] ReturnStatus return status
Returns:
A handle for the new node
Status Codes:
Examples:
AbcImport/NodeIteratorVisitorHelper.cpp, and gpuCache/gpuCacheCmd.cpp.
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] type type name of the node to create
[out] ReturnStatus return 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] node node to delete
Returns:
Return status
Status Codes:
Examples:
AbcImport/CameraHelper.cpp, and 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] node node to rename
[in] newName new name for the node
Returns:
Return status
Status Codes:
Examples:
sceneAssembly/adskRepresentations.cpp.
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] node node to toggle lock state
[in] newState new 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] 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:
Examples:
AbcImport/NodeIteratorVisitorHelper.cpp, atomImportExport/atomImportExport.cpp, cgfxAttrDef.cpp, closestPointOnCurve/closestPointOnCurveCmd.cpp, dx11Shader/dx11Shader.cpp, gpuCache/gpuCacheCmd.cpp, latticeNoise/latticeNoiseCmd.cpp, meshOpCmd/polyModifierCmd.cpp, offsetNode/offsetNode.cpp, pointOnMeshInfo/pointOnMeshCmd.cpp, polyPrimitiveCmd/polyPrimitiveCmd.cpp, splitUVCmd/polyModifierCmd.cpp, and xmlAssembly/BBoxesRep.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] 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:
Examples:
AbcImport/util.cpp, cgfxAttrDef.cpp, dx11Shader/dx11Shader.cpp, and latticeNoise/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] source the source plug in the connection
[in] dest the 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] source the source plug in the connection
[in] dest the 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] node node to which to add the attribute
[in] attribute attribute to add
Returns:
The return status
Status Codes:
Examples:
AshliShader/GLSLShaderNode.cpp, atomImportExport/atomFileUtils.cpp, cgfxAttrDef.cpp, dx11Shader/dx11Shader.cpp, and polyPrimitiveCmd/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] node node to add an attribute to
[in] attribute attribute to add
Returns:
The return status
Status Codes:
Examples:
AshliShader/GLSLShaderNode.cpp, cgfxAttrDef.cpp, and dx11Shader/dx11Shader.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] nodeClass class of node to which to add the attribute
[in] attribute attribute 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] nodeClass class of node from which to remove the attribute
[in] attribute attribute 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] nodeClass class of node from which to remove the attribute
[in] attribute attribute 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] mPlugin plugin to which the attribute is to be tied
[in] mAttribute attribute 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] mPlugin plugin from which the attribute is to be released
[in] mAttribute attribute 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] command the command that will be executed (should be undoable)
Returns:
The return status
Status Codes:
Examples:
AbcImport/util.cpp, and 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] plug the plug to set
[in] plugValue the value to set
Returns:
The return status
Status Codes:
Examples:
geometrySurfaceConstraint/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] plug the plug to set
[in] plugValue the 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] plug the plug to set
[in] plugValue the 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] plug the plug to set
[in] plugValue the 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] plug the plug to set
[in] plugValue the 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] plug the plug to set
[in] plugValue the value to set
Returns:
The return status
Status Codes:
Examples:
gpuCache/gpuCacheCmd.cpp.
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] plug the plug to set
[in] plugValue the 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] plug the plug to set
[in] plugValue the 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] plug the plug to set
[in] plugValue the 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] plug the plug to set
[in] plugValue the 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] plug the plug to set
[in] plugValue the value to set
Returns:
The return status
Status Codes:
MStatus setMetadata ( const MObject node,
const adsk::Data::Associations metadata 
)

Adds an operation to this dependency graph modifier that replaces metadata on a specific node.

Parameters:
[in] node The node to receive the metadata
[in] metadata The metadata values it will receive
Returns:
The return status
Status Codes:
MStatus deleteMetadata ( const MObject node )

Adds an operation to this dependency graph modifier that deletes all metadata from a node.

Parameters:
[in] node the node from which the metadata is to be removed
Returns:
The return status
Status Codes:
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:
gpuCache/gpuCacheCmd.cpp, meshOpCmd/polyModifierCmd.cpp, polyPrimitiveCmd/polyPrimitiveCmd.cpp, and splitUVCmd/polyModifierCmd.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] 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:
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] 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:

The documentation for this class was generated from the following files: