#include <MItEdits.h>
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:
Edits made from C to nodes in C. These edits were made from the C file/assembly. These edits are stored on C
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
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
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. More... | |
MItEdits (MObject &editsOwner, const MString &targetNodeName, EditStatus editStatus=ALL_EDITS, Direction direction=kForward, MStatus *ReturnStatus=NULL) | |
Class Constructor. More... | |
virtual | ~MItEdits () |
Class Destructor. | |
MStatus | reset () |
Resets the iterator. More... | |
MStatus | next () |
Moves to the next edit. More... | |
bool | isDone (MStatus *ReturnStatus=NULL) |
Indicates end of the iteration. More... | |
bool | isReverse (MStatus *ReturnStatus=NULL) const |
Indicates whether the edit lists are iterated in reverse order. More... | |
MString | currentEditString (MStatus *ReturnStatus=NULL) const |
Returns the ASCII string related to the current edit. More... | |
MEdit::EditType | currentEditType (MStatus *ReturnStatus=NULL) const |
Returns the enum related to the type of the current edit. More... | |
bool | removeCurrentEdit (MStatus *ReturnStatus=NULL) |
Removes the current edit. More... | |
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. More... | |
MSetAttrEdit | setAttrEdit (MStatus *ReturnStatus=NULL) const |
Returns the current edit if the current edit is a setAttr edit. More... | |
MParentingEdit | parentingEdit (MStatus *ReturnStatus=NULL) const |
Returns the current edit if the current edit is a parenting edit. More... | |
MFcurveEdit | fcurveEdit (MStatus *ReturnStatus=NULL) const |
Returns the current edit if the current edit is an fcurve edit. More... | |
MConnectDisconnectAttrEdit | connectDisconnectEdit (MStatus *ReturnStatus=NULL) const |
Returns the current edit if the current edit is a connection or disconnection edit. More... | |
Static Public Member Functions | |
static const char * | className () |
Returns the name of this class. More... | |
enum EditStatus |
enum Direction |
OPENMAYA_MAJOR_NAMESPACE_OPEN 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.
[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) |
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.
[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) |
MStatus reset | ( | ) |
Resets the iterator.
MStatus next | ( | ) |
Moves to the next edit.
bool isDone | ( | MStatus * | ReturnStatus = NULL | ) |
Indicates end of the iteration.
[out] | ReturnStatus | Status Code (see below) |
bool isReverse | ( | MStatus * | ReturnStatus = NULL | ) | const |
Indicates whether the edit lists are iterated in reverse order.
[out] | ReturnStatus | Status Code (see below) |
Returns the ASCII string related to the current edit.
[out] | ReturnStatus | return status |
MEdit::EditType currentEditType | ( | MStatus * | ReturnStatus = NULL | ) | const |
Returns the enum related to the type of the current edit.
[out] | ReturnStatus | return status |
bool removeCurrentEdit | ( | MStatus * | ReturnStatus = NULL | ) |
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.
[out] | ReturnStatus | return status |
[out] | ReturnStatus | return status |
MAddRemoveAttrEdit addRemoveAttrEdit | ( | MStatus * | ReturnStatus = NULL | ) | const |
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.
[out] | ReturnStatus | return status |
MSetAttrEdit setAttrEdit | ( | MStatus * | ReturnStatus = NULL | ) | const |
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.
[out] | ReturnStatus | return status |
MParentingEdit parentingEdit | ( | MStatus * | ReturnStatus = NULL | ) | const |
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.
[out] | ReturnStatus | return status |
MFcurveEdit fcurveEdit | ( | MStatus * | ReturnStatus = NULL | ) | const |
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.
[out] | ReturnStatus | return status |
MConnectDisconnectAttrEdit connectDisconnectEdit | ( | MStatus * | ReturnStatus = NULL | ) | const |
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.
[out] | ReturnStatus | return status |
|
static |
Returns the name of this class.