MAnimUtil Class Reference
[OpenMayaAnim - API module for animation]

#include <MAnimUtil.h>

List of all members.

---

Detailed Description

Static class providing common animation helper methods.

MAnimUtil is a static class which provides methods which determine if an object is being animated, which attributes are animated for a given object and which animation curves are used to animate a given attribute.

Note: for purposes of this helper class, "animation" refers to attributes animated by animCurves (i.e. by setting keys). It does not include any animation through expressions or dynamics or timer node connections.

Some helper methods may examine different types of objects. Depending upon how the object is represented, the same object may be examined differently.

If the object is specified as an MObject, then all of its attributes are examined. If the MObject is a hierarchical object (such as a dag node) and you specify that the objects parents should be examined, then all the parents of an instanced object will be examined.

If the object is specified as an MDagPath, then all of its attributes are examined. If you specify that the objects parents should be examined, then only the specified path of the instanced object will be examined.

If the object is specifed as an MPlug and no attribute has been set, then the method will behave as if it was called with an MObject. Otherwise only the specified attribute will be examined. For example, a compound attribute will not have its child attributes examined (i.e. if you specify node.translate, node.translateX will not be examined).

If the object is specified through an MSelectionList, it can also have multiple representations. If the object was added to the MSelectionList as an MObject, then it will be examined as an MObject. If the object was added to the MSelectionList as an MDagPath, then it will be examined as an MDagPath. If the object was added to the MSelectionList as either a component or an MPlug, it will be examined as an MPlug with additional expansion of compound attributes into their child attributes (for example, if specify node.translate is specified, node.translateX will be examined. More importantly, if you specify poly.f[4] then xValue, yValue and zValue will be examined for each vertex).

Below is a summary of how the same object will be examined by MAnimUtil::isAnimated depending upon how it has been represented. If we have the following hierarchical layout:

• group1 (translateX is animated)
  • pTorus1 (instanced and not animated)
    • pTorusShape1 (face[4] is animated)

• group2 (not animated)
  • pTorus1 (another instance of pTorus1 as above)

The MAnimUtil::isAnimated will respond as follows:

isAnimated ( MObject(pTorus1), false ) => false

isAnimated ( MObject(pTorus1), true ) => true

isAnimated ( MDagPath(group2|pTorus1), false ) => false

isAnimated ( MDagPath(group2|pTorus1), true ) => false

isAnimated ( MPlug(pTorus1), false ) => false

isAnimated ( MPlug(pTorus1), true ) => true

isAnimated ( MPlug(group1.translate) ) => false

isAnimated ( MPlug(group1.translateX) ) => true

isAnimated ( MPlug(pTorusShape1.pnts[4]) ) => false

isAnimated ( MPlug(pTorusShape1.pnts[4].xValue) ) => true

The following list assumes that MAnimUtil is called with an MSelectionList named list, and shows the response depending upon how the object has been added to list:

isAnimated ( list.add(MObject(pTorus1)), false ) => false

isAnimated ( list.add(MObject(pTorus1)), true ) => true

isAnimated ( list.add(MDagPath(group2|pTorus1)), false ) => false

isAnimated ( list.add(MDagPath(group2|pTorus1)), true ) => false

isAnimated ( list.add(MPlug(pTorus1)), false ) => false

isAnimated ( list.add(MPlug(pTorus1)), true ) => true

isAnimated ( list.add(MPlug(group1.translate)) ) => true

isAnimated ( list.add(MPlug(group1.translateX) ) => true

isAnimated ( list.add(MPlug(pTorusShape1.pnts[4])) ) => true

isAnimated ( list.add(MPlug(pTorusShape1.pnts[4].xValue)) ) => true

Static Public Member Functions
static bool	isAnimated (const MObject &node, bool checkParent=false, MStatus *ReturnStatus=NULL)
static bool	isAnimated (const MDagPath &path, bool checkParent=false, MStatus *ReturnStatus=NULL)
static bool	isAnimated (const MPlug &plug, bool checkParent=false, MStatus *ReturnStatus=NULL)
static bool	isAnimated (const MSelectionList &selectionList, bool checkParent=false, MStatus *ReturnStatus=NULL)
static bool	findAnimatedPlugs (const MObject &node, MPlugArray &animatedPlugs, bool checkParent=false, MStatus *ReturnStatus=NULL)
static bool	findAnimatedPlugs (const MDagPath &path, MPlugArray &animatedPlugs, bool checkParent=false, MStatus *ReturnStatus=NULL)
static bool	findAnimatedPlugs (const MSelectionList &selectionList, MPlugArray &animatedPlugs, bool checkParent=false, MStatus *ReturnStatus=NULL)
static bool	findAnimation (const MPlug &plug, MObjectArray &animation, MStatus *ReturnStatus=NULL)

---

Member Function Documentation

bool MAnimUtil::isAnimated	(	const MObject &	node,
		bool	checkParent = false,
		MStatus *	ReturnStatus = NULL
	)			[static]

Determine whether or not an MObject is animated. If the MObject is a hierarchical object (such as a dag node) then you may also specify whether or not the MObject's parents are examined. In the case of instanced MObjects, all of the MObject's parents are examined.

Parameters:

[in]	node	the MObject to examine
[in]	checkParent	whether or not to examine if the node's parent is animated
[out]	ReturnStatus	the return status

• MS::kSuccess if the method succeeded
• MS::kNullPointerArgument if the MObject does not represent a valid Maya object
• MS::kInvalidObjectType if the MObject is not a dependency node

Returns:

• true The MObject is animated.
• false The MObject is not animated.

Examples:

animExportUtil.cpp.

bool MAnimUtil::isAnimated	(	const MDagPath &	path,
		bool	checkParent = false,
		MStatus *	ReturnStatus = NULL
	)			[static]

Determine whether or not an MDagPath is animated. You may also specify whether or not the MDagPath's parent is examined. In the case of instanced MDagPath only the specified path is examined.

Parameters:

[in]	path	the MDagPath to examine
[in]	checkParent	whether or not to examine if the path's parent is animated
[out]	ReturnStatus	the return status

• MS::kSuccess if the method succeeded
• MS::kNullPointerArgument if the MDagPath does not represent a valid Maya object
• MS::kInvalidObjectType if the MDagPath is not a dependency node

Returns:

• true The MDagPath is animated.
• false The MDagPath is not animated.

bool MAnimUtil::isAnimated	(	const MPlug &	plug,
		bool	checkParent = false,
		MStatus *	ReturnStatus = NULL
	)			[static]

Determine whether or not an MPlug is animated. If the MPlug does not have an attribute specified, then the entire node is examined. You may also specify whether or not the node's parents are examined. In the case of instanced nodes, all of the node's parents are examined. If an attribute has been specified, the node's parents are not examined.

Parameters:

[in]	plug	the MPlug to examine
[in]	checkParent	whether or not to examine if the node's parent is animated
[out]	ReturnStatus	the return status

• MS::kSuccess if the method succeeded
• MS::kNullPointerArgument if the MPlug does not represent a valid Maya object

Returns:

• true The MPlug is animated.
• false The MPlug is not animated.

bool MAnimUtil::isAnimated	(	const MSelectionList &	selectionList,
		bool	checkParent = false,
		MStatus *	ReturnStatus = NULL
	)			[static]

Determine whether or not any member of an MSelectionList is animated. This is intended to work with an MSelectionList with a single entry since that provides the most useful information.

In addition to normal objects, components such as mesh vertices or faces can be easily described on an MSelectionList, making this a good way to determine if parts of a shape are animated or not.

If a member represents an MDagPath you may also specify whether or not the MDagPath's parent is examined. In the case of instanced MDagPath only the specified path is examined.

If a member represents a hierarchical MObject (such as a dag node) then you may also specify whether or not the MObject's parents are examined. In the case of instanced MObjects, all of the MObject's parents are examined.

Parameters:

[in]	selectionList	the MSelectionList to examine
[in]	checkParent	whether or not to examine if the node's parent is animated
[out]	ReturnStatus	the return status

• MS::kSuccess if the method succeeded

Returns:

• true The MSelectionList has atleast one animated member.
• false No member of the MSelectionList is animated.

bool MAnimUtil::findAnimatedPlugs	(	const MObject &	node,
		MPlugArray &	animatedPlugs,
		bool	checkParent = false,
		MStatus *	ReturnStatus = NULL
	)			[static]

Find the list of attributes (MPlugs) on an MObject that is animated. If the MObject is a hierarchical object (such as a dag node) then you may also specify whether or not the MObject's parents are examined. In the case of instanced MObjects, all of the MObject's parents are examined.

Parameters:

[in]	node	the MObject to examine
[in]	animatedPlugs	the list of attributes which are animated the array is not cleared
[in]	checkParent	whether or not to examine if the node's parent is animated
[out]	ReturnStatus	the return status

• MS::kSuccess if the method succeeded
• MS::kNullPointerArgument if the MObject does not represent a valid Maya object
• MS::kInvalidObjectType if the MObject is not a dependency node

Returns:

• true The MObject is animated.
• false The MObject is not animated.

Examples:

animExportUtil.cpp.

bool MAnimUtil::findAnimatedPlugs	(	const MDagPath &	path,
		MPlugArray &	animatedPlugs,
		bool	checkParent = false,
		MStatus *	ReturnStatus = NULL
	)			[static]

Find the list of attributes (MPlugs) on an MDagPath object that is animated. You may also specify whether or not the MDagPath's parent is examined. In the case of instanced MDagPath only the specified path is examined.

Parameters:

[in]	path	the MDagPath to examine
[in]	animatedPlugs	the list of attributes which are animated the array is not cleared
[in]	checkParent	whether or not to examine if the path's parent is animated
[out]	ReturnStatus	the return status

• MS::kSuccess if the method succeeded
• MS::kNullPointerArgument if the MDagPath does not represent a valid Maya object
• MS::kInvalidObjectType if the MDagPath is not a dependency node

Returns:

• true The MDagPath is animated.
• false The MDagPath is not animated.

bool MAnimUtil::findAnimatedPlugs	(	const MSelectionList &	selectionList,
		MPlugArray &	animatedPlugs,
		bool	checkParent = false,
		MStatus *	ReturnStatus = NULL
	)			[static]

Find the list of attributes (MPlugs) on any member of an MSelectionList that is animated. This is intended to work with an MSelectionList with a single entry since that provides the most useful information.

In addition to normal objects, components such as mesh vertices or faces can be easily described on an MSelectionList, making this a good way to determine if parts of a shape are animated or not.

If a member represents an MDagPath you may also specify whether or not the MDagPath's parent is examined. In the case of instanced MDagPath only the specified path is examined.

If a member represents a hierarchical MObject (such as a dag node) then you may also specify whether or not the MObject's parents are examined. In the case of instanced MObjects, all of the MObject's parents are examined.

Parameters:

[in]	selectionList	the MSelectionList to examine
[in]	animatedPlugs	the list of attributes which are animated the array is not cleared
[in]	checkParent	whether or not to examine if the node's parent is animated
[out]	ReturnStatus	the return status

• MS::kSuccess if the method succeeded

Returns:

• true The MSelectionList has atleast one animated member.
• false No member of the MSelectionList is animated.

bool MAnimUtil::findAnimation	(	const MPlug &	plug,
		MObjectArray &	animation,
		MStatus *	ReturnStatus = NULL
	)			[static]

Find the animCurve(s) that are animating a given attribute (MPlug). In most cases an attribute is animated by a single animCurve and so just that animCurve will be returned. It is possible to setup a series of connections where an attribute is animated by more than one animCurve, although Maya does not currently offer a UI to do so. Compound attributes are not expanded to include any child attributes.

Parameters:

[in]	plug	the plug to examine for animCurve(s)
[in]	animation	the list of animCurves which animate `plug'. The array is not cleared
[out]	ReturnStatus	the return status

• MS::kSuccess if the method succeeded
• MS::kNullPointerArgument if plug is null

Returns:

• true The MPlug is animated.
• false The MPlug is not animated.

Examples:

animExportUtil.cpp.