#include <MItEdits.h>

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

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

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...

Member Enumeration Documentation

enum EditStatus

The status of edits this iterator will visit.

Enumerator
SUCCESSFUL_EDITS	Visit successful edits only.
ALL_EDITS	Visit all the edits.

enum Direction

The direction in which the iterator will visit its edits.

Enumerator
kForward	Visit the edits in the order in which they were added.
kReverse	Visit the edits in the reverse order from how they were added.

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

Resets the iterator.

Returns: Status code

Status Codes:

MS::kSuccess Success
MS::kFailure Failure resetting iterator

MStatus next ( )

Moves to the next edit.

Returns: Status code

Status Codes:

MS::kSuccess Success
MS::kFailure Object error

bool isDone ( MStatus * ReturnStatus = NULL )

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

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

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

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 )

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

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

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

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

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

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

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

Returns the name of this class.

Returns: The name of this class.

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

MItEdits.h
MItEdits.cpp

MItEdits Class Reference

Class Description

Public Types

Public Member Functions

Static Public Member Functions

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation