- Main Page
- Related Pages
- Modules
- Namespaces
- Classes
- Examples

- Class List
- Class Hierarchy
- Class Members

Public Types | Public Member Functions | Static Public Member Functions

# MItEdits Class Reference
OpenMaya - API module for common classes

This reference page is linked to from the following overview topics: Extension for Autodesk Maya 2013.

Search for all occurrences

## Detailed Description

Edits iterator.

Use the edits iterator to traverse all the edits on a reference or assembly. An edit is any operation that modifies the dependency graph such as modifications to values, connections, parenting and so on.

In the case of references, edits are the changes that occur to referenced nodes. In the case of assemblies, edits are the changes that occur to assembly members.

Edits are returned as either strings representing an equivalent MEL call, or as a class derived from MEdit.

The edits iterator works regardless of whether the related reference or assembly is loaded or unloaded. However, please note that loading or unloading the related reference or assembly will cause any in-progress iteration to be reset.

If new edits were created while iterating, the iterator will not necessarily traverse them.

To control which edits you will traverse over, use the combination of the 'editsOwner' and 'targetNode'/'targetNodeName' parameters.

The editsOwner is the reference or assembly node that "owns" edits. This is the top-level assembly/reference at the time the edit was made. If you were to save a file, this is the node that the edits would be stored on.

The targetNode is the innermost reference or assembly node containing the edited nodes. Edits will be physically stored on the edits owner, so use targetNode to get just edits that affect nodes in a specific assembly/reference. If the nested assembly or reference is not loaded, you can still query edits that affect that node by specifying a string targetNodeName, instead of a targetNode MObject.

Hierarchical Example:

The following example explains the above terminology in the hierarchical case. Suppose you have a reference or assembly hierarchy that looks like this.

    A
    |_ B
       |_ C

Edits can be made at three different levels: 1) Edits made from C to nodes in C. These edits were made from the C file/assembly. These edits are stored on C

2) Edits made from B to nodes in B or C. These edits were made from the B file/assembly. These edits are stored on B

3) Edits made from A to nodes in A, B or C. These edits were made from the main scene. These edits are stored on A

To query all the edits stored on A, use: editsOwner = A targetNode = MObject::kNullObj

To query edits stored on A that affect nodes in A, use: editsOwner = A targetNode = A

To query edits stored on A that affect nodes in B, use: editsOwner = A targetNode = B

To query all the edits stored on B, use: editsOwner = B targetNode = MObject::kNullObj

To only query edits stored on B that affect nodes in C, use: editsOwner = B targetNode = C

`#include <MItEdits.h>`

List of all members.

## Public Types
enum | EditStatus { SUCCESSFUL_EDITS, ALL_EDITS }
| The status of edits this iterator will visit. More...
enum | Direction { kForward, kReverse }
| The direction in which the iterator will visit its edits. More...
## Public Member Functions
| MItEdits (MObject &editsOwner, MObject &targetNode=MObject::kNullObj, EditStatus editStatus=ALL_EDITS, Direction direction=kForward, MStatus *ReturnStatus=NULL)
| Class Constructor.
| MItEdits (MObject &editsOwner, const MString &targetNodeName, EditStatus editStatus=ALL_EDITS, Direction direction=kForward, MStatus *ReturnStatus=NULL)
| Class Constructor.
virtual | ~MItEdits ()
| Class Destructor.
MStatus | reset ()
| Resets the iterator.
MStatus | next ()
| Moves to the next edit.
bool | isDone (MStatus *ReturnStatus=NULL)
| Indicates end of the iteration.
bool | isReverse (MStatus *ReturnStatus=NULL) const
| Indicates whether the edit lists are iterated in reverse order.
MString | currentEditString (MStatus *ReturnStatus=NULL) const
| Returns the ASCII string related to the current edit.
MEdit::EditType | currentEditType (MStatus *ReturnStatus=NULL) const
| Returns the enum related to the type of the current edit.
bool | removeCurrentEdit (MStatus *ReturnStatus=NULL)
| Removes the current edit.
MEdit | edit (MStatus *ReturnStatus=NULL) const
MAddRemoveAttrEdit | addRemoveAttrEdit (MStatus *ReturnStatus=NULL) const
| Returns the current edit if the current edit is an edit for adding or removing an attribute.
MSetAttrEdit | setAttrEdit (MStatus *ReturnStatus=NULL) const
| Returns the current edit if the current edit is a setAttr edit.
MParentingEdit | parentingEdit (MStatus *ReturnStatus=NULL) const
| Returns the current edit if the current edit is a parenting edit.
MFcurveEdit | fcurveEdit (MStatus *ReturnStatus=NULL) const
| Returns the current edit if the current edit is an fcurve edit.
MConnectDisconnectAttrEdit | connectDisconnectEdit (MStatus *ReturnStatus=NULL) const
| Returns the current edit if the current edit is a connection or disconnection edit.
## Static Public Member Functions
static const char * | className ()
| Returns the name of this class.

## Member Enumeration Documentation

enum EditStatus

Search for all occurrences

The status of edits this iterator will visit.

Enumerator:

  SUCCESSFUL_EDITS | Visit successful edits only. Search for all occurrences
  ALL_EDITS | Visit all the edits. Search for all occurrences

enum Direction

Search for all occurrences

The direction in which the iterator will visit its edits.

Enumerator:

  kForward | Visit the edits in the order in which they were added. Search for all occurrences
  kReverse | Visit the edits in the reverse order from how they were added. Search for all occurrences

## Constructor & Destructor Documentation

MItEdits | ( | MObject & | editsOwner,
|  | MObject & | targetNode = `MObject::kNullObj`,
|  | EditStatus | editStatus = `ALL_EDITS`,
|  | Direction | direction = `kForward`,
|  | MStatus * | ReturnStatus = `NULL`
| ) |  |

Class Constructor.

Initializes the iterator.

This iterator traverses all edits stored on the 'editsOwner'. This 'editsOwner' is the top-level assembly/reference node at the time the edit was made.

To filter edits to only show those that affect nodes in a given assembly/reference, provide a targetNode. This is the innermost reference or assembly that contains the edited nodes. If a null targetNode is passed in, the iterator will traverse over all edits that are stored on the editsOwner.

If we have an assembly hierarchy like this:

    A_AR
    |_ A:B_AR
       |_ A:B:testSphere

And we make edit1 to :A:B_AR and edit2 to :A:B:testSphere from top level.

    Case1:
    editsOwner = A_AR
    targetNode = A_AR

edit1 will be listed. Because edit1 is the one that affects B_AR, which is a direct node member of A_AR. Edits on further down descendants are not included, that's why edit2 is not listed.

    Case2:
    editsOwner = A_AR
    targetNode = B_AR

edit2 will be listed.

    Case3:
    editsOwner = A_AR
    targetNode = testSphere

This is not allowed, targetNode must be assembly/reference node.

    Case4:
    editsOwner = A_AR
    targetNode = NULL

Both edit1 and edit2 will be listed. Because the iterator will traverse over all edits that are stored on the editsOwner when targetNode is NULL.

NOTE: When iterating over multiple target nodes, the order in which each target node is encountered is arbitrary. However, all edits for a given target node are visited in the order in which they were added before the iteration proceeds to another target node. When the iterator operates in reverse order, the edits for each target node are visited in reverse order before the iteration proceeds to another target node. The target nodes are visited in the same order as when iterating in forward order.

Parameters:

  [in] | editsOwner | The node edits live on. We accept either reference nodes or assembly nodes
  [in] | targetNode | The innermost reference or assembly node holding the edited nodes. Can be MObject::kNullObj.
  [in] | editStatus | The status of edits the iterator will visit.
  [in] | direction | The direction in which the edits will be visited.
  [out] | ReturnStatus | Status Code (see below)

Status Codes:
  - MS::kSuccess Success
  - MS::kFailure Failure creating iterator

MItEdits | ( | MObject & | editsOwner,
|  | const MString & | targetNodeName,
|  | EditStatus | editStatus = `ALL_EDITS`,
|  | Direction | direction = `kForward`,
|  | MStatus * | ReturnStatus = `NULL`
| ) |  |

Class Constructor.

Initializes the iterator.

This iterator traverses all edits stored on the 'editsOwner'. This editsOwner is the top-level assembly/reference node at the time the edit was made.

To filter edits to only show those that affect nodes in a given assembly/reference provide a targetNodeName. This is the name of the innermost reference or assembly that contains the edited nodes. You can provide an absolute namespace path to this target assembly/reference node. Or, you can provide the name of the target node relative to the assembly/reference namespace.

Here is an example. If we have an assembly hierarchy like this:

    A_AR (Assembly namespace is A)
    |_ A:B_AR (Assembly namespace is B)
       |_ A:B:testSphere

The assembly/reference namespace for A_AR is A, for B_AR is B.

    For A_AR:
    absolute name = :A_AR
    relative name = ..:A_AR

    For B_AR:
    absolute name = :A:B_AR
    relative name = B_AR

Please also note since assembly node names are unique within a namespace, even if a dag path is provided, it will be stripped out. For example, |:A_AR will be stripped to :A_AR and |:A_AR|:A:B_AR will be stripped to :A:B_AR internally.

For the expected behavior of the filter, please take a look at comment of the above version constructor which use targetNode.

Besides, with this version of MItEdits, even if the targetNode for the nested assembly or reference is not currently in the scene, we can still query edits that affect nodes in that assembly or reference by passing in the targetNode's name as a string to this constructor. In above example, if A_AR or :A:B_AR is activated to None, this version of MItEdits can still reach edits made to :A:B_AR or :A:B:testSphere.

If an empty string is provided for the targetNodeName, the iterator will traverse over all the edits that are stored on the editsOwner.

Parameters:

  [in] | editsOwner | The node edits are stored on. Accepts either reference or assembly nodes.
  [in] | targetNodeName | The name of the innermost reference or assembly node containing the edited nodes.
  [in] | editStatus | The status of edits the iterator will visit.
  [in] | direction | The direction in which the edits will be visited.
  [out] | ReturnStatus | Status Code (see below)

Status Codes:
  - MS::kSuccess Success
  - MS::kFailure Failure creating iterator

## Member Function Documentation

MStatus reset | ( |  | ) |

Search for all occurrences

Resets the iterator.

Returns:
  Status code

Status Codes:
  - MS::kSuccess Success
  - MS::kFailure Failure resetting iterator

MStatus next | ( |  | ) |

Search for all occurrences

Moves to the next edit.

Returns:
  Status code

Status Codes:
  - MS::kSuccess Success
  - MS::kFailure Object error

bool isDone | ( | MStatus * | ReturnStatus = `NULL` | ) |

Search for all occurrences

Indicates end of the iteration.

Parameters:

  [out] | ReturnStatus | Status Code (see below)

Returns:
  Bool: true if the iteration is done, false otherwise

Status Codes:
  - MS::kSuccess Success
  - MS::kFailure Object error

bool isReverse | ( | MStatus * | ReturnStatus = `NULL` | ) | const

Search for all occurrences

Indicates whether the edit lists are iterated in reverse order.

Parameters:

  [out] | ReturnStatus | Status Code (see below)

Returns:
  Bool: true if the iteration is reversed, false otherwise

Status Codes:
  - MS::kSuccess Success
  - MS::kFailure Object error

MString currentEditString | ( | MStatus * | ReturnStatus = `NULL` | ) | const

Search for all occurrences

Returns the ASCII string related to the current edit.

Parameters:

  [out] | ReturnStatus | return status

Returns:
  The ASCII string related to the current edit

Status Codes:
  - MS::kSuccess operation successful
  - MS::kFailure no current edit or an invalid iterator

MEdit::EditType currentEditType | ( | MStatus * | ReturnStatus = `NULL` | ) | const

Search for all occurrences

Returns the enum related to the type of the current edit.

Parameters:

  [out] | ReturnStatus | return status

Returns:
  The current reference or assembly edit type or kNullEdit if there is no current edit.

Status Codes:
  - MS::kSuccess Operation successful
  - MS::kFailure Edit was not initialized successfully

bool removeCurrentEdit | ( | MStatus * | ReturnStatus = `NULL` | ) |

Search for all occurrences

Removes the current edit.

Edits can only be removed from top-level assemblies/references.

Edits from nested assemblies/references are physically saved in those nested files. So we do not have write access to them from the main scene, and thus, they cannot be removed.

Where possible, the remove operation will simply reverse the edit. For example, if the current edit is a setAttr edit, the value of the attribute will be returned to its previous value.

Once an edit has been removed, the iterator will point to a null operation, which can be skipped using next(). If the iterator is reset, this null operation will still be present, and must be skipped.

NOTE: This method must be used with care. Removing just one specific edit from a group of related edits may leave your scene in an undesirable state. For example, if you removed just one connection in a complex shading network, the network may not function correctly.

Parameters:

  [out] | ReturnStatus | return status

Returns:
  True if the edit was removed successfully. False if the edit is stored on a nested assembly or reference.

Status Codes:
  - MS::kSuccess operation successful
  - MS::kFailure no current edit or an invalid iterator

MEdit edit | ( | MStatus * | ReturnStatus = `NULL` | ) | const

Search for all occurrences

Parameters:

  [out] | ReturnStatus | return status

Returns:
  The current edit.

Status Codes:
  - MS::kSuccess operation successful
  - MS::kFailure no current edit or an invalid iterator

MAddRemoveAttrEdit addRemoveAttrEdit | ( | MStatus * | ReturnStatus = `NULL` | ) | const

Search for all occurrences

Returns the current edit if the current edit is an edit for adding or removing an attribute.

The method currentEditType can be used to validate whether the current edit is of the appropriate type. An edit for adding or removing an attribute indicates that an attribute has been added or removed since the file was referenced.

Note that whenever an attribute is added and the new attribute is keyable, an associated setAttr edit will also be added to record the fact that the attribute keyable.

Parameters:

  [out] | ReturnStatus | return status

Returns:
  The add or remove attribute edit

Status Codes:
  - MS::kSuccess operation successful
  - MS::kFailure no current add/remove attribute edit or an invalid iterator

MSetAttrEdit setAttrEdit | ( | MStatus * | ReturnStatus = `NULL` | ) | const

Search for all occurrences

Returns the current edit if the current edit is a setAttr edit.

The method currentEditType can be used to validate whether or not the current edit is a setAttr edit. A setAttr edit is a modification to a plug value on an object from a reference or assembly.

Parameters:

  [out] | ReturnStatus | return status

Returns:
  The setAttr edit.

Status Codes:
  - MS::kSuccess operation successful
  - MS::kFailure no current setAttr edit or an invalid iterator

MParentingEdit parentingEdit | ( | MStatus * | ReturnStatus = `NULL` | ) | const

Search for all occurrences

Returns the current edit if the current edit is a parenting edit.

The method currentEditType can be used to validate whether or not the current edit is a parenting edit. Parenting edits are modifications to the parent or child of an object from a reference or an assembly.

Parameters:

  [out] | ReturnStatus | return status

Returns:
  The parenting edit.

Status Codes:
  - MS::kSuccess operation successful
  - MS::kFailure no current parenting edit or an invalid iterator

MFcurveEdit fcurveEdit | ( | MStatus * | ReturnStatus = `NULL` | ) | const

Search for all occurrences

Returns the current edit if the current edit is an fcurve edit.

The method currentEditType can be used to validate whether or not the current edit is an fcurve edit. An fcurve edit is a modification to an animCurve from a reference.

Parameters:

  [out] | ReturnStatus | return status

Returns:
  The fcurve edit.

Status Codes:
  - MS::kSuccess operation successful
  - MS::kFailure no current fcurve edit or an invalid iterator

MConnectDisconnectAttrEdit connectDisconnectEdit | ( | MStatus * | ReturnStatus = `NULL` | ) | const

Search for all occurrences

Returns the current edit if the current edit is a connection or disconnection edit.

The method currentEditType can be used to validate whether the current edit is a connection or disconnection edit. A connection or disconnection edit indicates that a connection has been made or broken since the file or assembly was referenced.

Parameters:

  [out] | ReturnStatus | return status

Returns:
  The connection or disconnection edit.

Status Codes:
  - MS::kSuccess operation successful
  - MS::kFailure no current connect/disconnect edit or an invalid iterator

const char * className | ( |  | ) | `[static]`

Search for all occurrences

Returns the name of this class.

Returns:
  The name of this class.

MItEdits MItEdits MItEdits MItEdits MItEdits MItEdits MItEdits MItEdits MItEdits MItEdits
MItEdits MItEdits MItEdits MItEdits MItEdits MItEdits MItEdits MItEdits MItEdits MItEdits