MFnDependencyNode Class Reference

#include <MFnDependencyNode.h>

Class Description

Dependency node function set.

MFnDependencyNode allows the creation and manipulation of dependency graph nodes. Traversal of the dependency graph is possible using the getConnections method.

This function set does not support creation or removal of connections. MDGModifier should be used for that purpose.

Examples:

Inheritance diagram for MFnDependencyNode:

Public Types
enum	MAttrClass { kLocalDynamicAttr = 1, kNormalAttr, kExtensionAttr, kInvalidAttr }
	Specifies the scope of the attribute. More...
enum	MdgTimerState { kTimerOff, kTimerOn, kTimerUninitialized, kTimerInvalidState }
	Possible states for the node's timer. More...
enum	MdgTimerMetric {   kTimerMetric_callback, kTimerMetric_compute, kTimerMetric_dirty, kTimerMetric_draw,   kTimerMetric_fetch, kTimerMetric_callbackViaAPI, kTimerMetric_callbackNotViaAPI, kTimerMetric_computeDuringCallback,   kTimerMetric_computeNotDuringCallback, kTimerMetrics }
	The different timer metrics which can be queried. More...
enum	MdgTimerType { kTimerType_self, kTimerType_inclusive, kTimerType_count, kTimerTypes }
	The types of timers which can be queried. More...

Public Member Functions
virtual MFn::Type	type () const
	Function set type. More...
virtual	~MFnDependencyNode ()
	Destructor.
	MFnDependencyNode ()
	Default constructor.
	MFnDependencyNode (MObject &object, MStatus *ReturnStatus=NULL)
	Constructor. More...
MObject	create (const MTypeId &typeId, MStatus *ReturnStatus=NULL)
	Creates a new dependency node with the given type tag. More...
MObject	create (const MTypeId &typeId, const MString &name, MStatus *ReturnStatus=NULL)
	Creates a new dependency node with the given type tag. More...
MObject	create (const MString &type, MStatus *ReturnStatus=NULL)
	Creates a new dependency node with the given type. More...
MObject	create (const MString &type, const MString &name, MStatus *ReturnStatus=NULL)
	Creates a new dependency node with the given type. More...
MTypeId	typeId (MStatus *ReturnStatus=NULL) const
	Returns the type id of this node. More...
MString	typeName (MStatus *ReturnStatus=NULL) const
	Returns the type name of this node. More...
MString	name (MStatus *ReturnStatus=NULL) const
	Returns the name of this node. More...
MString	absoluteName (MStatus *ReturnStatus=NULL) const
	Returns the absolute name of this node. More...
MString	pluginName (MStatus *ReturnStatus=NULL) const
	Returns the name of the plug-in this MFnDependendencyNode was defined in. More...
MString	setName (const MString &name, bool createNamespace=false, MStatus *ReturnStatus=NULL)
	Sets the name of this node. More...
MUuid	uuid (MStatus *ReturnStatus=NULL) const
	Returns the node's UUID. More...
void	setUuid (const MUuid &uuid, MStatus *ReturnStatus=NULL)
	Sets the node's UUID. More...
MStatus	getConnections (MPlugArray &array) const
	Get all of the current connections to this node as an array of plugs. More...
unsigned int	attributeCount (MStatus *ReturnStatus=NULL) const
	Returns the number of attributes that this node has. More...
MObject	attribute (unsigned int index, MStatus *ReturnStatus=NULL) const
	Finds the attribute of this node at the given index. More...
MObject	reorderedAttribute (unsigned int index, MStatus *ReturnStatus=NULL) const
	Some nodes, such as the various animCurve nodes, require that their attributes be set in a specific order for proper operation. More...
MObject	attribute (const MString &attrName, MStatus *ReturnStatus=NULL) const
	Finds the attribute of this node that has the given name. More...
MAttrClass	attributeClass (const MObject &attr, MStatus *ReturnStatus=NULL) const
	Returns the class (normal, dynamic, extension) of the specified attribute. More...
MStatus	getAffectedAttributes (const MObject &attr, MObjectArray &affectedAttributes) const
	Returns an array of attributes that are affected by the attribute passed in. More...
MStatus	getAffectedByAttributes (const MObject &attr, MObjectArray &affectedByAttributes) const
	Returns an array of attributes that affect the attribute passed in, attr. More...
MPlug	findPlug (const MObject &attr, bool wantNetworkedPlug, MStatus *ReturnStatus=NULL) const
	Attempt to find a plug for the given attribute. More...
MPlug	findPlug (const MString &attrName, bool wantNetworkedPlug, MStatus *ReturnStatus=NULL) const
	Attempt to find a plug for the given attribute. More...
MPlug	findPlug (const MObject &attr, MStatus *ReturnStatus=NULL) const
	This method is obsolete. More...
MPlug	findPlug (const MString &attrName, MStatus *ReturnStatus=NULL) const
	This method is obsolete. More...
MStatus	addAttribute (const MObject &attr)
	Add a new dynamic attibute to this node. More...
MStatus	removeAttribute (const MObject &attr)
	Remove a dynamic attribute from a node. More...
MPxNode *	userNode (MStatus *ReturnStatus=NULL) const
	If the function set's node is a plug-in node, then this method will extract the MPxNode pointer from it. More...
bool	isFromReferencedFile (MStatus *ReturnStatus=NULL) const
	Indicates whether or not this node came from a referenced file. More...
bool	isShared (MStatus *ReturnStatus=NULL) const
	Indicates whether or not this node is shared. More...
bool	isTrackingEdits (MStatus *ReturnStatus=NULL) const
	Returns whether or not edits on the given node are being tracked by the generalized edit system. More...
bool	hasUniqueName (MStatus *ReturnStatus=NULL) const
	Indicates whether or not this node's name is unique within the scene. More...
MString	parentNamespace (MStatus *ReturnStatus=NULL) const
	Returns the name of the namespace in which this node resides. More...
bool	isLocked (MStatus *ReturnStatus=NULL) const
	Indicates whether or not this node is locked. More...
MStatus	setLocked (bool locked)
	Locks or unlocks this node. More...
bool	isNewAttribute (const MObject &attr, MStatus *ReturnStatus=NULL) const
	Indicates whether or not the specified attribute was added to this node within the current scene. More...
MStatus	setFlag (unsigned int flag, bool state)
	Sets the state of the specified flag for the node. More...
bool	isFlagSet (unsigned int flag, MStatus *ReturnStatus=NULL) const
	Retrieves the current state of the specified flag for a node. More...
bool	isDefaultNode (MStatus *ReturnStatus=NULL) const
	Returns true if the node is a default node. More...
MStatus	setDoNotWrite (bool flag)
	Use this method to mark the "do not write" state of this node. More...
bool	canBeWritten (MStatus *ReturnStatus=NULL) const
	Returns the do not write state of the node. More...
bool	hasAttribute (const MString &name, MStatus *ReturnStatus=NULL) const
	Returns true if the node already has an attribute with the given name. More...
MObject	getAliasAttr (bool force, MStatus *ReturnStatus=NULL)
	Returns the node's alias attribute, which is a special attribute used to store information about the node's attribute aliases. More...
bool	setAlias (const MString &alias, const MString &name, const MPlug &plug, bool add=true, MStatus *ReturnStatus=NULL)
	Sets or removes an alias (i.e. More...
bool	findAlias (const MString &alias, MObject &attrObj, MStatus *ReturnStatus=NULL) const
	Retrieves the attribute with the given alias. More...
bool	getAliasList (MStringArray &strArray, MStatus *ReturnStatus=NULL)
	Returns a list of all attribute aliases for this node. More...
MString	plugsAlias (const MPlug &plug, MStatus *ReturnStatus=NULL)
	Returns the alias for the plug's attribute or the empty string if that attribute has no alias. More...
MStatus	setIcon (const MString &filename)
	Associates a custom icon with the node for display in the Maya UI. More...
MString	icon (MStatus *ReturnStatus=NULL) const
	Returns the custom icon filename associated with the node. More...
MStatus	getExternalContent (MExternalContentInfoTable &table) const
	Returns the external content (files) that this node depends on. More...
MStatus	addExternalContentForFileAttr (MExternalContentInfoTable &table, const MObject &attr) const
	Adds content info to the specified table from a file path attribute. More...
MStatus	setExternalContentForFileAttr (const MObject &attr, const MExternalContentLocationTable &table)
	Sets content info in the specified attribute from the table. More...
MStatus	setExternalContent (const MExternalContentLocationTable &table)
	Changes the location of external content. More...
MString	setName (const MString &name, MStatus *ReturnStatus)
	OBSOLETE FUNCTION, NO SCRIPT SUPPORT. More...
	MFnDependencyNode (const MObject &object, MStatus *ReturnStatus=NULL)
	NO SCRIPT SUPPORT. More...
bool	getPlugsAlias (const MPlug &plug, MString &aliasName, MStatus *ReturnStatus=NULL)
	NO SCRIPT SUPPORT. More...
virtual const adsk::Data::Associations *	metadata (MStatus *ReturnStatus=NULL) const
	This method is not available in Python. More...
virtual MStatus	setMetadata (const adsk::Data::Associations &)
	This method is not available in Python. More...
virtual MStatus	deleteMetadata ()
	This method is not available in Python. More...
virtual MStatus	validateMetadata (MString &errors) const
	This method is not available in Python. More...
MStatus	dgTimerOn ()
	Indicates that this node should collect DG timing data whenever DG timing is enabled. More...
MStatus	dgTimerOff ()
	Indicates that this node should no longer collect DG timing data when DG timing is enabled. More...
MdgTimerState	dgTimerQueryState (MStatus *ReturnStatus=NULL)
	The function returns the current on/off state of the node's timer. More...
MStatus	dgTimerReset ()
	The function resets the dependency graph timers and counters for this node to zero. More...
double	dgTimer (const MdgTimerMetric timerMetric, const MdgTimerType timerType, MStatus *ReturnStatus=NULL) const
	The function returns the specified timer value for the current node. More...
MStatus	dgCallbacks (const MdgTimerType type, MStringArray &callbackName, MDoubleArray &value)
	Node callbacks that occur when timing is enabled get logged with the node and can be queried via this method. More...
MStatus	dgCallbackIds (const MdgTimerType type, const MString &callbackName, MCallbackIdArray &callbackId, MDoubleArray &value)
	This method provides a further breakdown of the per-callback time returned via dgCallbacks() by returning the data on a per-callbackId basis. More...
MStatus	addAttribute (const MObject &attr, MAttrClass type)
	This method is obsolete. More...
MStatus	removeAttribute (const MObject &attr, MAttrClass type)
	This method is obsolete. More...
Public Member Functions inherited from MFnBase
virtual	~MFnBase ()
	Class Destructor. More...
bool	hasObj (MFn::Type) const
	Determines whether or not the Function Set is compatible with the specified Maya Object within the API RTTI system. More...
bool	hasObj (const MObject &) const
	Determines whether or not the Function Set is compatible with the specified Maya Object within the API RTTI system. More...
MObject	object (MStatus *ReturnStatus=NULL) const
	Returns the MObject that is attached to the Function Set. More...
virtual MStatus	setObject (MObject &object)
	Attaches the Function Set to the specified Maya Object. More...
virtual MStatus	setObject (const MObject &object)
	NO SCRIPT SUPPORT. More...

Static Public Member Functions
static MString	classification (const MString &nodeTypeName)
	Retrieves the classification string for a node type. More...
static unsigned int	allocateFlag (const MString pluginName, MStatus *ReturnStatus=NULL)
	Allocates a node flag for sole use by the caller. More...
static MStatus	deallocateFlag (const MString pluginName, unsigned int flag)
	Deallocates a node flag which was previously allocated by a call to allocateFlag. More...
static MStatus	deallocateAllFlags (const MString pluginName)
	Deallocates all of the node flags which are currently allocated to the specified plugin. More...
static void	enableDGTiming (bool enable)
	Globally enables or disables the DG node timing mechanism. More...
Static Public Member Functions inherited from MFnBase
static const char *	className ()
	Returns the name of this class. More...

Protected Member Functions
virtual const char *	className () const
	Class name. More...

Member Enumeration Documentation

enum MAttrClass

Specifies the scope of the attribute.

Enumerator
kLocalDynamicAttr	Dynamically added, applies to this specific node.
kNormalAttr	Static attribute which is part of the original definition for this node type.
kExtensionAttr	Extension attribute which is part of all nodes of this or derived node types.
kInvalidAttr	None of the above.

enum MdgTimerState

Possible states for the node's timer.

Enumerator
kTimerOff
kTimerOn
kTimerUninitialized
kTimerInvalidState

enum MdgTimerMetric

The different timer metrics which can be queried.

Enumerator
kTimerMetric_callback	Time spent within node callbacks for this node.
kTimerMetric_compute	Time spent within the compute method for this node.
kTimerMetric_dirty	Time spent propogating dirty messages from this node.
kTimerMetric_draw	Time spent drawing this node.
kTimerMetric_fetch	Time spent fetching data from plugs.
kTimerMetric_callbackViaAPI	Time spent in callbacks which were registered through the API.
kTimerMetric_callbackNotViaAPI	Time spent in callbacks not registered through the API (i.e internal Maya callbacks).
kTimerMetric_computeDuringCallback	Time spent in this node's compute while executing node callbacks on any node.
kTimerMetric_computeNotDuringCallback	Time spent in this nodes compute when not executing any node callbacks on any nodes.
kTimerMetrics	Total number of metrics available.

enum MdgTimerType

The types of timers which can be queried.

Enumerator
kTimerType_self	Time spent performing an operation, not including any time spent by child operations. For example, if we are drawing a node and that requires a compute, self time will only include the time spent drawing and not the compute time. Self time measures wall-clock time as opposed to CPU time and the values are in seconds.
kTimerType_inclusive	Time spent performing an operation including all time spent by child operations. For example, if we are drawing a node and that requires a compute, inclusive time is the time for the draw plus compute. Inclusive time measure wall-clock time as opposed to CPU time and the values are in seconds.
kTimerType_count	The number of operations that occurred. Ideally we should return an integer when this timer type is queried, but there are two advantages to using a double. 1) it keeps the interface consistent and 2) integer has a fixed upper bound of roughly four billion so using a double allows us to exceed this.
kTimerTypes	The total number of timer types supported.

Constructor & Destructor Documentation

MFnDependencyNode	(	MObject &	object,
		MStatus *	ReturnStatus = NULL
	)

Constructor.

Class constructor that initializes the function set to the given MObject.

Parameters

[in]	object	The MObject to attach the function set to
[out]	ReturnStatus	the return status

Status Codes:

• MS::kSuccess if the function set is successfully attached
• MS::kInvalidParameter if the MObject does not represent a valid Maya object or if the function set is not allowed to attach to this MObject

MFnDependencyNode	(	const MObject &	object,
		MStatus *	ReturnStatus = NULL
	)

NO SCRIPT SUPPORT.

Class constructor that initializes the function set to the given MObject.

Constructor

Parameters

[in]	object	The MObject to attach the function set to
[out]	ReturnStatus	the return status

Status Codes:

• MS::kSuccess if the function set is successfully attached
• MS::kInvalidParameter if the MObject does not represent a valid Maya object or if the function set is not allowed to attach to this MObject

Member Function Documentation

MFn::Type type ( ) const

virtual

Function set type.

Return the class type : MFn::kDependencyNode.

Reimplemented from MFnBase.

Reimplemented in MFnSubd, MFnAnimCurve, MFnMesh, MFnTransform, MFnNurbsSurface, MFnClip, MFnCharacter, MFnNurbsCurve, MFnParticleSystem, MFnAssembly, MFnBlendShapeDeformer, MFnIkJoint, MFnWeightGeometryFilter, MFnLatticeDeformer, MFnSkinCluster, MFnCameraSet, MFnLattice, MFnSet, MFnGeometryFilter, MFnDagNode, MFnMotionPath, MFnPartition, MFnFluid, MFnImageSource, MFnWireDeformer, MFnContainerNode, MFnRotateManip, MFnScaleManip, MFnLight, MFnRenderLayer, MFnToggleManip, MFnCircleSweepManip, MFnDirectionManip, MFnDiscManip, MFnRenderPass, MFnStateManip, MFnCurveSegmentManip, MFnField, MFnFreePointTriadManip, MFnHikEffector, MFnInstancer, MFnLayeredShader, MFnPhongEShader, MFnPointOnCurveManip, MFnPointOnSurfaceManip, MFnPointLight, MFnReflectShader, MFnSpotLight, MFnVolumeLight, MFnAnisotropyShader, MFnExpression, MFnIkHandle, MFnLambertShader, MFnPfxGeometry, MFnPhongShader, MFnDistanceManip, MFnIkEffector, MFnIkSolver, MFnDragField, MFnNewtonField, MFnNonAmbientLight, MFnNonExtendedLight, MFnRadialField, MFnVortexField, MFnAmbientLight, MFnAreaLight, MFnDirectionalLight, MFnGravityField, MFnTurbulenceField, MFnUniformField, MFnVolumeAxisField, MFnAirField, MFnBlinnShader, MFnCamera, MFnReference, and MFnManip3D.

const char * className ( ) const

protectedvirtual

Class name.

Return the class name : "MFnDependencyNode".

Reimplemented in MFnSubd, MFnAnimCurve, MFnMesh, MFnTransform, MFnNurbsSurface, MFnClip, MFnCharacter, MFnNurbsCurve, MFnParticleSystem, MFnAssembly, MFnBlendShapeDeformer, MFnIkJoint, MFnWeightGeometryFilter, MFnLatticeDeformer, MFnSkinCluster, MFnCameraSet, MFnLattice, MFnSet, MFnGeometryFilter, MFnDagNode, MFnMotionPath, MFnPartition, MFnFluid, MFnImageSource, MFnWireDeformer, MFnContainerNode, MFnRotateManip, MFnScaleManip, MFnLight, MFnRenderLayer, MFnToggleManip, MFnCircleSweepManip, MFnDirectionManip, MFnDiscManip, MFnRenderPass, MFnStateManip, MFnCurveSegmentManip, MFnField, MFnFreePointTriadManip, MFnHikEffector, MFnInstancer, MFnLayeredShader, MFnPhongEShader, MFnPointOnCurveManip, MFnPointOnSurfaceManip, MFnPointLight, MFnReflectShader, MFnSpotLight, MFnVolumeLight, MFnAnisotropyShader, MFnExpression, MFnIkHandle, MFnLambertShader, MFnPfxGeometry, MFnPhongShader, MFnDistanceManip, MFnIkEffector, MFnIkSolver, MFnDragField, MFnNewtonField, MFnNonAmbientLight, MFnNonExtendedLight, MFnRadialField, MFnVortexField, MFnAmbientLight, MFnAreaLight, MFnDirectionalLight, MFnGravityField, MFnTurbulenceField, MFnUniformField, MFnVolumeAxisField, MFnAirField, MFnBlinnShader, MFnCamera, MFnReference, and MFnManip3D.

MObject create	(	const MTypeId &	typeId,
		MStatus *	ReturnStatus = NULL
	)

Creates a new dependency node with the given type tag.

The new node is placed into the dependency graph.

If the node is a DAG node, it will be parented to a transform.

The initial name for the node will be the node's "typeName" followed by a number to make the instance unique. For example, the first transform node created will be named "transform1".

Parameters

[in]	typeId	type id of node to be created
[out]	ReturnStatus	return status

Returns

A pointer to the new dependency node object

Status Codes:

• MS::kSuccess operation successful
• MS::kFailure node type is not recognised
• MS::kLicenseFailure application not licensed for attempted operation
• MS::kInsufficientMemory out of memory

Examples:

MObject create	(	const MTypeId &	typeId,
		const MString &	name,
		MStatus *	ReturnStatus = NULL
	)

Creates a new dependency node with the given type tag.

The new node is placed into the dependency graph.

If the node is a DAG node, it will be parented to a transform.

Parameters

[in]	typeId	type id of node to be created
[in]	name	the name to be assigned to the new node If the node's name is not unique, it will be given a unique name by changing its numerical suffix. For example, if this node is called "myNode" and a node by the same name exists, this node will be renamed to "myNode1".
[out]	ReturnStatus	return status

Returns

A pointer to the new dependency node object

Status Codes:

• MS::kSuccess operation successful
• MS::kFailure node type is not recognised
• MS::kLicenseFailure application not licensed for attempted operation
• MS::kInsufficientMemory out of memory

MObject create	(	const MString &	type,
		MStatus *	ReturnStatus = NULL
	)

Creates a new dependency node with the given type.

The new node is placed into the dependency graph.

If the node is a DAG node, it will be parented to a transform.

The initial name for the node will be the node's "typeName" followed by a number to make the instance unique. For example, the first transform node created will be named "transform1".

Parameters

[in]	type	int name for the type of dependency node
[out]	ReturnStatus	return status

Returns

A pointer to the new dependency node object

Status Codes:

• MS::kSuccess operation successful
• MS::kFailure node type is not recognised
• MS::kLicenseFailure application not licensed for attempted operation
• MS::kInsufficientMemory out of memory

MObject create	(	const MString &	type,
		const MString &	name,
		MStatus *	ReturnStatus = NULL
	)

Creates a new dependency node with the given type.

The new node is placed into the dependency graph.

If the node is a DAG node, it will be parented to a transform.

Parameters

[in]	type	int name for the type of dependency node
[in]	name	the name to be assigned to the new node If the node's name is not unique, it will be given a unique name by changing its numerical suffix. For example, if this node is called "myNode" and a node by the same name exists, this node will be renamed to "myNode1".
[out]	ReturnStatus	return status

Returns

A pointer to the new dependency node object

Status Codes:

• MS::kSuccess operation successful
• MS::kFailure node type is not recognised
• MS::kLicenseFailure application not licensed for attempted operation
• MS::kInsufficientMemory out of memory

MTypeId typeId

(

MStatus *

ReturnStatus = NULL

)

const

Returns the type id of this node.

The type is is the 4 byte code that is used in the binary file format to identify the type of this node.

Parameters

[out]

ReturnStatus

return status

Returns

The type id of this node

Status Codes:

• MS::kSuccess operation successful
• MS::kFailure function set does not have a valid node

Examples:

MString typeName

(

MStatus *

ReturnStatus = NULL

)

const

Returns the type name of this node.

The string returned is the name of the node type as it is used in the ascii file format.

Parameters

[out]

ReturnStatus

return status

Returns

The type name of this node

Status Codes:

• MS::kSuccess operation successful
• MS::kFailure function set does not have a valid node

Examples:

MString name

(

MStatus *

ReturnStatus = NULL

)

const

Returns the name of this node.

Note that if the object the instance of this class is attached to is data instead of being in the graph (ie. the object was created by one of the MFn*Data function sets, or was passed to an MPxNode::compute function in a data block) then the name method will not work.

Parameters

[out]

ReturnStatus

return status

Returns

The name of this node

Status Codes:

• MS::kSuccess operation successful
• MS::kFailure function set does not have a valid node

Examples:

MString absoluteName

(

MStatus *

ReturnStatus = NULL

)

const

Returns the absolute name of this node.

The absolute name of a node is the full namespace path starting at (and including) the root namespace, down to (and including) the node itself. Regardless of relative name mode, absoluteName() will always return a full namespace path prefixed with a leading colon (the root namespace).

See MFnDependencyNode::name() comments for MFn*Data restrictions.

Parameters

[out]

ReturnStatus

return status

Returns

The absolute name of this node.

Status Codes:

• MS::kSuccess operation successful
• MS::kFailure function set does not have a valid node

MString pluginName

(

MStatus *

ReturnStatus = NULL

)

const

Returns the name of the plug-in this MFnDependendencyNode was defined in.

The name returned is the name of the plug-in on disk, and may contain pathname separators (such as `/') and drive letters (e.g. C:). If this object is not an MFnDependency node, then MS::kFailure is returned instead.

Parameters

[out]

ReturnStatus

return status

Returns

The name of the plug-in

Status Codes:

• MS::kSuccess operation successful
• MS::kFailure function set does not have a valid node

MString setName	(	const MString &	name,
		bool	createNamespace = false,
		MStatus *	ReturnStatus = NULL
	)

Sets the name of this node.

If the new name conflicts with the name of an existing node then the object will be given a unique name based on the supplied name. If the new name ends in a single '#' it will be replaced with a number that ensures the new name is unique.

The name can also have a namespace path, for example "ns:ball". If the namespace already exists, the object will be be moved into that namespace (in addition to being renamed). If the namespace does not exist then the 'createNamespace' parameter will determine how to handle it. If the parameter is true then the namespace will be created (under the root if the namespace name is absolute, or under the current namespace if not) and the object will be moved into the new namespace. If the parameter is false then the object will be moved into the current namespace.

When a transform is renamed, any shape nodes beneath the transform that have the same prefix as the old transform name are also renamed. For example, "rename nurbsSphere1 ball" would rename "nurbsSphere1|nurbsSphereShape1" to "ball|ballShape".

The unique name set for the node is returned.

Note that if the object to which the functionset is attached is data rather than a node (ie. the object was created by one of the MFn*Data function sets, or was passed to an MPxNode::compute function in a data block) then the setName method will not work.

Parameters

[in]	name	the new name for the node
[in]	createNamespace	determine whether or not to create a new namespace when the given name includes a namespace which does not exist.
[out]	ReturnStatus	return status

Returns

The new name of the node.

Status Codes:

• MS::kSuccess operation successful
• MS::kFailure function set does not have a valid node
• MS::kInvalidParameter name is the empty string

Examples:

MUuid uuid

(

MStatus *

ReturnStatus = NULL

)

const

Returns the node's UUID.

Parameters

[out]

ReturnStatus

return status

Returns

The node's UUID.

Status Codes:

• MS::kSuccess operation successful
• MS::kFailure function set does not have a valid node

void setUuid	(	const MUuid &	muuid,
		MStatus *	ReturnStatus = NULL
	)

Sets the node's UUID.

If the node is in the dependency graph, this operation will fail if another node in the graph already has the given UUID.

Parameters

[in]	muuid	the new UUID for the node
[out]	ReturnStatus	return status

Status Codes:

• MS::kSuccess operation successful
• MS::kFailure function set does not have a valid node
• MS::kInvalidParameter the UUID was invalid or already in use

MStatus getConnections

(

MPlugArray &

array

)

const

Get all of the current connections to this node as an array of plugs.

Parameters

[out]

array

storage for the array of plugs

Returns

Status code

Status Codes:

• MS::kSuccess operation successful
• MS::kFailure node has no connections

unsigned int attributeCount

(

MStatus *

ReturnStatus = NULL

)

const

Returns the number of attributes that this node has.

Parameters

[out]

ReturnStatus

return status

Returns

The attribute count

Status Codes:

• MS::kSuccess operation successful
• MS::kFailure function set does not have a valid object

Examples:

MObject attribute	(	unsigned int	index,
		MStatus *	ReturnStatus = NULL
	)		const

Finds the attribute of this node at the given index.

Index order is based on the order in which the attributes were added to the node.

Parameters

[in]	index	the index of the attribute
[out]	ReturnStatus	return status

Returns

A pointer to the attribute

Status Codes:

• MS::kSuccess operation successful
• MS::kFailure function set does not have a valid object, or the index is out of range

Examples:

MObject reorderedAttribute	(	unsigned int	index,
		MStatus *	ReturnStatus = NULL
	)		const

Some nodes, such as the various animCurve nodes, require that their attributes be set in a specific order for proper operation.

Usually this ordering is only important when the node is being created during file I/O.

The attribute(index) method above returns the attributes according to the order in which they were originally added to the node.

This method returns the attributes according to the reordering, if any, which is required by the node.

Parameters

[in]	index	the reordered index of the attribute
[out]	ReturnStatus	return status

Returns

A pointer to the attribute

Status Codes:

• MS::kSuccess operation successful
• MS::kFailure function set does not have a valid object, or the index is out of range

MObject attribute	(	const MString &	attrName,
		MStatus *	ReturnStatus = NULL
	)		const

Finds the attribute of this node that has the given name.

Parameters

[in]	attrName	name of the attribute to find
[out]	ReturnStatus	return status

Returns

A pointer to the attribute

Status Codes:

• MS::kSuccess operation successful
• MS::kInvalidParameter the named attribute was not found
• MS::kFailure function set does not have a valid object

MFnDependencyNode::MAttrClass attributeClass	(	const MObject &	attribute,
		MStatus *	ReturnStatus = NULL
	)		const

Returns the class (normal, dynamic, extension) of the specified attribute.

Parameters

[in]	attribute	the attribute to check
[out]	ReturnStatus	return status

Returns

The class of the attribute. If the node does not have the specified attribute, then kInvalidAttr is returned as the class.

Status Codes:

• MS::kSuccess operation successful
• MS::kFailure function set does not have a valid object

MStatus getAffectedAttributes	(	const MObject &	attr,
		MObjectArray &	affectedAttributes
	)		const

Returns an array of attributes that are affected by the attribute passed in.

That is, when the given attribute, attr is marked dirty (changed) all the affectedAttributes attributes will also be marked dirty. For nodes defined in plug-ins this call returns all those attributes that were marked as being affected by the given one via the MPxNode::attributeAffects call.

It should be noted that dynamic attributes cannot be handled by this method. This is because the attribute affects dependencies are statically defined when the node is created. An alternate approach which works for dynamic as well as non-dynamic attributes is available through MPxNode::setDependentsDirty override.

Parameters

[in]	attr	the attribute to check
[out]	affectedAttributes	an array of attributes affected by attr

Returns

Status code

Status Codes:

• MS::kSuccess operation successful
• MS::kFailure operation failed
• MS::kInvalidParameter function set is not bound to a dependency node or the first parameter is not an attribute

MStatus getAffectedByAttributes	(	const MObject &	attr,
		MObjectArray &	affectedByAttributes
	)		const

Returns an array of attributes that affect the attribute passed in, attr.

That is, when one of the attributes in affectedByAttributes is marked dirty (changed) then attr will also be marked dirty. For nodes defined in plug-ins this call returns all those attributes that were marked as affecting the given one via the MPxNode::attributeAffects call.

It should be noted that dynamic attributes cannot be handled by this method. This is because the attribute affects dependencies are statically defined when the node is created. An alternate approach which works for dynamic as well as non-dynamic attributes is available through MPxNode::setDependentsDirty override.

Parameters

[in]	attr	the attribute to check
[out]	affectedByAttributes	an array of attributes affected by attr

Returns

Status code

Status Codes:

• MS::kSuccess operation successful
• MS::kFailure operation failed
• MS::kInvalidParameter function set is not bound to a dependency node or the first parameter is not an attribute

MPlug findPlug	(	const MObject &	attr,
		bool	wantNetworkedPlug,
		MStatus *	ReturnStatus = NULL
	)		const

Attempt to find a plug for the given attribute.

This method will first try to find the networked version of the plug if requested. The networked version of a plug is one that currently exists in the dependency graph at a particular connection point. If a networked version is not found, then a standard non-networked plug is returned.

A non-networked plug is not actually used by the dependency graph, but is used to represent the same connections. Every time an operation is performed on a non-networked plug, a search is made for the networked version of the plug.

Networked and non-networked plugs behave the same, but networked plugs are much more efficient if used for multiple operations.

Networked plugs should be avoided if you will be deleting connections to the plug.

Parameters

[in]	attr	attribute whose plug we wish to find
[in]	wantNetworkedPlug	if true, request a networked plug if it is available
[out]	ReturnStatus	return status

Returns

The plug

Status Codes:

• MS::kSuccess operation successful
• MS::kFailure function set does not have a valid object, or the plug could not be found

Examples:

MPlug findPlug	(	const MString &	attrName,
		bool	wantNetworkedPlug,
		MStatus *	ReturnStatus = NULL
	)		const

Attempt to find a plug for the given attribute.

This method will first try to find the networked version of the plug if requested. The networked version of a plug is one that currently exists in the dependency graph at a particular connection point. If a networked version is not found, then a standard non-networked plug is returned.

A non-networked plug is not actually used by the dependency graph, but is used to represent the same connections. Every time an operation is performed on a non-networked plug, a search is made for the networked version of the plug.

Networked and non-networked plugs behave the same, but networked plugs are much more efficient if used for multiple operations.

Networked plugs should be avoided if you will be deleting connections to the plug.

Parameters

[in]	attrName	name of attribute whose plug we wish to find
[in]	wantNetworkedPlug	if true, request a networked plug if it is available
[out]	ReturnStatus	return status

Returns

The plug

Status Codes:

• MS::kSuccess operation successful
• MS::kInvalidParameter the named attribute could not be found
• MS::kFailure function set does not have a valid object, or the plug could not be found

MPlug findPlug	(	const MObject &	attr,
		MStatus *	ReturnStatus = NULL
	)		const

This method is obsolete.

Deprecated:

Use the MFnDependencyNode::findPlug( MObject&, bool, MStatus* ) method instead.

Parameters

[in]	attr	Attribute to return a plug for.
[out]	ReturnStatus	Status code.

MPlug findPlug	(	const MString &	attrName,
		MStatus *	ReturnStatus = NULL
	)		const

This method is obsolete.

Deprecated:

Use the MFnDependencyNode::findPlug( MString&, bool, MStatus* ) method instead.

Parameters

[in]	attrName	Name of attribute to return a plug for.
[out]	ReturnStatus	Status code.

MStatus addAttribute

(

const MObject &

attr

)

Add a new dynamic attibute to this node.

Parameters

[in]

attr

new attribute

Returns

Status code

Status Codes:

• MS::kSuccess operation successful
• MS::kInvalidParameter attr is not a valid attribute object
• MS::kFailure function set does not have a valid object, or the addition of the new attribute failed

Examples:

MStatus removeAttribute

(

const MObject &

attribute

)

Remove a dynamic attribute from a node.

Note: After a successful call to this method, the MObject passed to it 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]

attribute

attribute to remove

Returns

Status code

Status Codes:

• MS::kSuccess operation successful
• MS::kInvalidParameter attr is not a valid attribute object
• MS::kFailure function set does not have a valid object, or the removal of the attribute failed

MPxNode * userNode

(

MStatus *

ReturnStatus = NULL

)

const

If the function set's node is a plug-in node, then this method will extract the MPxNode pointer from it.

This method should only be used on node types that are provided by the plug-in calling this method.

Parameters

[out]

ReturnStatus

return status

Returns

A pointer to the user data (NULL if not a plug-in node)

Status Codes:

• MS::kSuccess operation successful
• MS::kFailure function set does not have a valid object, or the removal of the attribute failed

Examples:

bool isFromReferencedFile

(

MStatus *

ReturnStatus = NULL

)

const

Indicates whether or not this node came from a referenced file.

If it did, the node will be marked as read-only in the scene and changes to the node's attributes will be saved in the main scene file, not the referenced file from which the node came.

Parameters

[out]

ReturnStatus

return status

Returns

true if the node came from a referenced file, false otherwise.

Status Codes:

• MS::kSuccess operation successful
• MS::kFailure function set does not have a valid node

bool isShared

(

MStatus *

ReturnStatus = NULL

)

const

Indicates whether or not this node is shared.

This comes into play when you attempt to create a new node with the same name as an existing node. If the existing node is shared, then no new node will be created. If the existing node is not shared, then the new node will be created and given a different name.

For example, if you import several scene files into a single scene, they may all attempt to create their own 'defaultResolution' node. However, since this node is shared, only one such node will be created and the other requests will be ignored.

The concept of "sharing" can also be found in the "createNode -shared" flag found in MEL which, if specified causes an implicit node to be created (or not created, if it is already present).

Parameters

[out]

ReturnStatus

return status

Returns

true if the node is shared, false otherwise.

Status Codes:

• MS::kSuccess operation successful
• MS::kFailure function set does not have a valid node

bool isTrackingEdits

(

MStatus *

ReturnStatus = NULL

)

const

Returns whether or not edits on the given node are being tracked by the generalized edit system.

Referenced nodes and nodes in assemblies that are tracking edits will return true.

Parameters

[out]

ReturnStatus

Status code

Returns

true if edits on the given node are being tracked, false otherwise.

Status Codes:

• MS::kSuccess Success
• MS::kFailure No valid node attached to Function Set

bool hasUniqueName

(

MStatus *

ReturnStatus = NULL

)

const

Indicates whether or not this node's name is unique within the scene.

Parameters

[out]

ReturnStatus

return status

Returns

true if the node's name is unique within scene, false otherwise.

Status Codes:

• MS::kSuccess operation successful
• MS::kFailure function set does not have a valid node

MString parentNamespace

(

MStatus *

ReturnStatus = NULL

)

const

Returns the name of the namespace in which this node resides.

Namespaces are often used when importing files to prevent name collisions.

Parameters

[out]

ReturnStatus

return status

Returns

The name of the namespace in which this node exists. This will be a colon separated path. If the object is in the root namespace, then an empty string will be returned.

Status Codes:

• MS::kSuccess operation successful
• MS::kFailure function set does not have a valid node

bool isLocked

(

MStatus *

ReturnStatus = NULL

)

const

Indicates whether or not this node is locked.

See the setLocked method for more information on what it means for a node to be locked.

Parameters

[out]

ReturnStatus

return status

Returns

true if the node is locked, false otherwise.

Status Codes:

• MS::kSuccess operation successful
• MS::kFailure function set does not have a valid node

MStatus setLocked

(

bool

lock

)

Locks or unlocks this node.

If a node is locked, it may not be deleted, renamed, or reparented; it may not have attributes added or removed; attributes which are unlocked may not be locked and those which are already locked may not be unlocked.

Parameters

[in]

lock

If true then node will be locked.

Returns

Status code

Status Codes:

• MS::kSuccess operation successful
• MS::kFailure function set does not have a valid node

MString classification ( const MString &  nodeTypeName )

static

Retrieves the classification string for a node type.

This is a string that is used in dependency nodes that are also shaders to provide more detailed type information to the rendering system. See the documentation for the MEL commands getClassification and listNodeTypes for information on the strings that can be provided.

User-defined nodes set this value through a parameter to MFnPlugin::registerNode.

Parameters

[in]

nodeTypeName

The name of the node for which a classification should be retrieved. Since this is a static method, the typeName method of this class can be used for this parameter if it is desired to get the classification for the attached node.

Returns

The classification string. If the node does not have an associated classification, an empty string will be returned.

Examples:

bool isNewAttribute	(	const MObject &	attr,
		MStatus *	ReturnStatus = NULL
	)		const

Indicates whether or not the specified attribute was added to this node within the current scene.

For nodes from referenced files, this method will only return true if the attribute was added to the node after the reference file was loaded into the scene.

For all other nodes, this method will return true if the attribute is dynamic (i.e. not one of the node's original, permanent attributes).

Parameters

[in]	attr	Attribute to check.
[out]	ReturnStatus	return status

Returns

true if the attribute was added within the current scene, false if the attribute is permanent or was added within a referenced file.

Status Codes:

• MS::kSuccess operation successful
• MS::kInvalidParameter no such attribute on this node
• MS::kFailure function set does not have a valid node

unsigned int allocateFlag ( const MString  pluginName, MStatus *  ReturnStatus = NULL  )

static

Allocates a node flag for sole use by the caller.

Note that the flag is not specific to any one node but is made available to the caller on all nodes. Furthermore, node flags only persist for the duration of the current Maya session: they are not saved with the scene.

deallocateFlag must be called when a flag is no longer needed.

There are a total of just 8 flags available, so plugins should strive not to hold onto flags for extended periods of time as that might interfere with the needs of other plugins.

When a plugin is unloaded, deallocateAllFlags is automatically invoked to free up any node flags still held by the plugin.

Parameters

[in]	pluginName	The name of the plugin which is allocating the flag. A plugin's name can be retrieved by calling MFnPlugin::name() within its initializePlugin() or uninitializePlugin() functions.
[out]	ReturnStatus	Return status.

Returns

The newly-allocated flag.

Status Codes:

• MS::kSuccess Operation successful.
• MS::kNotFound No unallocated flags are available.
• MS::kInvalidParameter The specified plugin is not loaded.

Examples:

MStatus deallocateFlag ( const MString  pluginName, unsigned int  flag  )

static

Deallocates a node flag which was previously allocated by a call to allocateFlag.

The flag subsequently becomes available for reallocation and use by someone else.

Parameters

[in]	pluginName	The name of the plugin which allocated the flag. A plugin's name can be retrieved by calling MFnPlugin::name() within its initializePlugin() or uninitializePlugin() functions.
[in]	flag	Flag to deallocate.

Returns

Status code.

Status Codes:

• MS::kSuccess Operation successful.
• MS::kInvalidParameter Flag number is out of range.
• MS::kNotFound Flag was not allocated by the plugin.

Examples:

MStatus deallocateAllFlags ( const MString  pluginName )

static

Deallocates all of the node flags which are currently allocated to the specified plugin.

The deallocated flags immediately become available for use by any plugin.

Parameters

[in]

pluginName

The name of the plugin whose flags are to be deallocated. A plugin's name can be retrieved by calling MFnPlugin::name() within its initializePlugin() or uninitializePlugin() functions.

Returns

Status code.

Status Codes:

• MS::kSuccess Operation successful.
• MS::kInvalidParemeter The pluginName was invalid.

MStatus setFlag	(	unsigned int	flag,
		bool	state
	)

Sets the state of the specified flag for the node.

The flag number must have been previously obtained through a call to allocateFlag.

Parameters

[in]	flag	flag to set
[in]	state	new state to which the flag will be set

Returns

Status code.

Status Codes:

• MS::kSuccess operation successful
• MS::kInvalidParameter flag number is out of range
• MS::kNotFound flag has not been properly allocated
• MS::kFailure function set does not have a valid node

Examples:

bool isFlagSet	(	unsigned int	flag,
		MStatus *	ReturnStatus = NULL
	)		const

Retrieves the current state of the specified flag for a node.

The flag must have been previously obtained through a call to allocateFlag.

Parameters

[in]	flag	number of the flag to retrieve.
[out]	ReturnStatus	return status

Returns

Current state of the flag

Status Codes:

• MS::kSuccess operation successful
• MS::kInvalidParameter flag number is out of range
• MS::kNotFound flag has not been properly allocated
• MS::kFailure function set does not have a valid node

bool isDefaultNode

(

MStatus *

ReturnStatus = NULL

)

const

Returns true if the node is a default node.

A default node is one that Maya creates automatically and does not get saved out with the scene, although some of its attribute values may.

Parameters

[out]

ReturnStatus

return status

Returns

true if the node is default, false otherwise.

Status Codes:

• MS::kSuccess operation successful
• MS::kFailure function set does not have a valid node

MStatus setDoNotWrite

(

bool

flag

)

Use this method to mark the "do not write" state of this node.

If set, this node will not be saved when the Maya model is written out.

NOTES: 1. If this node is a DAG and has a parent or children, the "do not write" flag of the parent or children will not be set. It is the developer's responsibility to ensure that the resulting scene file is capable of being read in without errors due to unwritten nodes.

Parameters

[in]

flag

True if the node should not be saved.

bool canBeWritten

(

MStatus *

ReturnStatus = NULL

)

const

Returns the do not write state of the node.

Will be true if the node can be written/exported to scene files.

Note that if a node is marked as being shared (see MFnDependencyNode::isShared) that overrides being marked as not writable. So shared nodes can be written, even if not marked as writable.

Parameters

[out]

ReturnStatus

return status

Returns

true if the node can be written, false otherwise.

Status Codes:

• MS::kSuccess operation successful
• MS::kFailure function set does not have a valid node

bool hasAttribute	(	const MString &	attrName,
		MStatus *	ReturnStatus = NULL
	)		const

Returns true if the node already has an attribute with the given name.

Parameters

[in]	attrName	Name of attribute to be checked.
[out]	ReturnStatus	return status

Returns

true if the node has attribute, false otherwise.

Status Codes:

• MS::kSuccess if method is successful.
• MS::kFailure if an object error occurs.

MObject getAliasAttr	(	bool	force,
		MStatus *	ReturnStatus = NULL
	)

Returns the node's alias attribute, which is a special attribute used to store information about the node's attribute aliases.

If the node doesn't have an alias attribute and the 'force' parameter is true, then an alias attribute will be created and returned, otherwise MObject::kNullObj will be returned.

Parameters

[in]	force	To indicate whether the alias attr should be created.
[out]	ReturnStatus	return status

Returns

The MObject corresponding to the alias attribute.

Status Codes:

• MS::kSuccess if method is successful.
• MS::kFailure if an object error occurs.

bool setAlias	(	const MString &	alias,
		const MString &	name,
		const MPlug &	plug,
		bool	add = true,
		MStatus *	ReturnStatus = NULL
	)

Sets or removes an alias (i.e.

an alternative name) for an attribute.

A node can have at most one alias per attribute, so if there is already an alias on the specified attribute it will be replaced by the new one.

Parameters

[in]	alias	alternative name for the attribute
[in]	name	real name of the attribute
[in]	plug	plug to the attribute
[in]	add	true to add the alias, false to remove it
[out]	ReturnStatus	return status

Returns

True on success, false on failure. If the ReturnStatus indicates success then false means either that the alias to be added already exists, or the alias to be removed does not exist.

Status Codes:

• MS::kSuccess if method is successful.
• MS::kFailure if an object error occurs.

bool findAlias	(	const MString &	alias,
		MObject &	attrObj,
		MStatus *	ReturnStatus = NULL
	)		const

Retrieves the attribute with the given alias.

If there is no attribute with the given alias, the method will return false and the value of 'attrObj' will be undefined.

Parameters

[in]	alias	alternative name of the attribute
[out]	attrObj	the attribute having the specified alias
[out]	ReturnStatus	return status

Returns

True if the alias was found.

Status Codes:

• MS::kSuccess if method is successful.
• MS::kFailure if an object error occurs.

bool getAliasList	(	MStringArray &	strArray,
		MStatus *	ReturnStatus = NULL
	)

Returns a list of all attribute aliases for this node.

The aliases are pairs of strings with the first being the alias and the second being the attribute's real name.

Parameters

[out]	strArray	list of aliases
[out]	ReturnStatus	return status

Returns

true if any alias was found, false otherwise.

Status Codes:

• MS::kSuccess if method is successful.
• MS::kFailure if an object error occurs.

MString plugsAlias	(	const MPlug &	plug,
		MStatus *	ReturnStatus = NULL
	)

Returns the alias for the plug's attribute or the empty string if that attribute has no alias.

Parameters

[in]	plug	plug for whose attribute we want the alias
[out]	ReturnStatus	return status. See below.

Returns

Alternative name for the attribute, if any.

Status Codes:

• MS::kSuccess if the method is successful.
• MS::kFailure if an object error occurs.

MStatus setIcon

(

const MString &

filename

)

Associates a custom icon with the node for display in the Maya UI.

Currently the icon only shows up in Outliner panels (the DAG Outliner, Graph Editor and Dope Sheet).

Parameters

[in]

filename

specifies the name of the image file defining the icon, or the empty string (i.e. "") to revert to using Maya's default. The filename must be a PNG file (.png) and may either be an absolute pathname or be relative to the XBMLANGPATH environment variable.

Returns

Status code

Status Codes:

• MS::kSuccess if the method is successful.
• MS::kFailure if an object error occurs.
• MS::kInvalidParameter the filename did not exist, or was not readable, or did not have a .png or .PNG extension.

MString icon

(

MStatus *

ReturnStatus = NULL

)

const

Returns the custom icon filename associated with the node.

The icon can be assigned using setIcon().

Parameters

[out]

ReturnStatus

return status

Returns

The custom icon filename, or the empty string (i.e. "") if the node is using Maya's default.

Status Codes:

• MS::kSuccess if the method is successful
• MS::kFailure function set does not have a valid node

MStatus getExternalContent

(

MExternalContentInfoTable &

table

)

const

Returns the external content (files) that this node depends on.

The table populated by this method must include the location of all the content (files) used by this node, including those that do not exist. See MExternalContentInfoTable for details.

Keys used to add items to this table will be the same that get passed to setExternalContent through its MExternalContentLocationTable parameter to perform a batched change of content location.

The default implementation does nothing.

Parameters

[out]

table

Content information table that this method must populate.

Returns

Status code

Status Codes:

• MS::kSuccess if the method is successful.
• MS::kFailure if an object error occurs.

MStatus addExternalContentForFileAttr	(	MExternalContentInfoTable &	table,
		const MObject &	attr
	)		const

Adds content info to the specified table from a file path attribute.

This method is a helper for derived clases implementing getExternalContent(). It augments the external content info table passed in with an entry describing external content whose location is described by the specified attribute.

The method will not overwrite existing items, i.e. items with the same key (attribute name). If this function is called twice with the same attribute, or two separate but identically named attributes are used, the table stays unchanged and false is returned. If replacing an entry is the desired effect, it is the caller's responsibility to erase the previous item first.

Parameters

[out]	table	The table in which the new entry will be added.
[in]	attr	The attribute for which the plug value will be queried for a location.

Returns

Status code

Status Codes:

• MS::kSuccess if an item was sucessfully added to the table.
• MS::kFailure if an object error occurs.
• MS::kInvalidParameter if the attribute does not describe a non-empty location, or an item with the same key was already present in the table

MStatus setExternalContentForFileAttr	(	const MObject &	attr,
		const MExternalContentLocationTable &	table
	)

Sets content info in the specified attribute from the table.

This method is a helper for derived clases implementing setExternalContent(). It assigns a value to a plug with the one from the table whose key is the same as the passed in attribute name.

The method will not write to the plug if the attribute is not found in the table.

Parameters

[in]	attr	The attribute of the plug we want to write to.
[in]	table	A table which may hold or not the value for a given plug.

Returns

Status code

Status Codes:

• MS::kSuccess if the plug was successfully written to.
• MS::kFailure if an object error occurs
• MS::kNotFound if no entry in the table was named after the attribute or if no plug was found.

MStatus setExternalContent

(

const MExternalContentLocationTable &

table

)

Changes the location of external content.

This is useful in the context of content relocation. This will be called while the scene is being loaded to apply path changes performed externally. Consequently, interaction with the rest of the scene must be kept to a minimum. It is however valid to call this method outside of scene loading contexts.

The keys in the map must be the same as the ones provided by the node in getExternalContent. The values are the new locations.

Parameters

[in]

table

Key->location table with new content locations.

Returns

Status code

Status Codes:

• MS::kSuccess if the method is successful.
• MS::kFailure if an object error occurs.

MString setName	(	const MString &	name,
		MStatus *	ReturnStatus
	)

OBSOLETE FUNCTION, NO SCRIPT SUPPORT.

This method is obsolete. This method is not available in Python.

Deprecated:

This function is obsolete, please use the other 'setName' instead

Parameters

[in]	name
[out]	ReturnStatus

bool getPlugsAlias	(	const MPlug &	plug,
		MString &	aliasName,
		MStatus *	ReturnStatus = NULL
	)

NO SCRIPT SUPPORT.

Returns the alias for the plug's attribute or the empty string if that attribute has no alias.

Python Notes

This method is not supported in Python. Please see plugsAlias()

Parameters

[in]	plug	plug for whose attribute we want the alias
[out]	aliasName	alternative name for the attribute
[out]	ReturnStatus	return status

Returns

true if the alias was found, false otherwise.

Status Codes:

• MS::kSuccess if the method is successful.
• MS::kFailure if an object error occurs.

const adsk::Data::Associations * metadata ( MStatus *  ReturnStatus = NULL ) const

virtual

This method is not available in Python.

Get the current metadata associated with this node.

Parameters

[out]

ReturnStatus

Status code. See below.

Returns

Metadata associated with the node, NULL if there isn't any

Status Codes:

• MS::kSuccess The method was successful.
• MS::kFailure An object error has occurred.

Reimplemented in MFnMesh.

MStatus setMetadata ( const adsk::Data::Associations &  newMetadata )

virtual

This method is not available in Python.

Replace the existing metadata with the given values.

Parameters

[in]

newMetadata

The new associated metadata for this node

Returns

Status code

Status Codes:

• MS::kSuccess The method was successful.
• MS::kFailure The metadata could not be set onto this node.

Reimplemented in MFnMesh.

MStatus deleteMetadata ( )

virtual

This method is not available in Python.

Remove all metadata from this node.

Returns

Status code

Status Codes:

• MS::kSuccess The method was successful.
• MS::kFailure The metadata could not be removed from this node.

MStatus validateMetadata ( MString &  errors ) const

virtual

This method is not available in Python.

Verify consistency in all of the existing metadata channels The intended use of this method is to check that the metadata channels are still internally consistent after operations have been performed on any underlying associated data.

It's not meant to provide data validation (e.g. make sure a certain data in a channel is within it's legal range).

Parameters

[out]

errors

String containing information about what went wrong

Returns

Status code

Status Codes:

• MS::kSuccess The method was successful.
• MS::kFailure A consistency error was found. Check error string for details.

Reimplemented in MFnMesh.

void enableDGTiming ( bool  enable )

static

Globally enables or disables the DG node timing mechanism.

There are two levels of control for DG node timing. dgTimerOn() and dgTimerOff() are used to determine which nodes are eligible for timer data collection and this method is used to globally enable or disable the DG node timing mechanism.

For example, if you want to collect timing information for nodes X and Y you would call their dgTimerOn() methods and then call this method to enable timing. Those two nodes would then begin collecting timing data.

If you subsequently call this method to disable timing then X and Y will cease collecting timing data but the data already collected would still be available (e.g. using dgTimer()).

If you later use this method to re-enable timing then X and Y would resume collecting data. Note that this method does not clear the nodes' timing data. If you want a clean start you would have to call dgTimerReset() individually on X and Y.

Parameters

[in]

enable

flag to turn timing on or off.

MStatus dgTimerOn

(

)

Indicates that this node should collect DG timing data whenever DG timing is enabled.

See enableDGTiming() for more details.

Note that this method does not reset the timers and counters on the node, it merely enables (or re-enables) timer data collection for the node and subsequent timing values are added to the current timer and counter values. If you want the counters to be reset, use the method dgTimerReset().

To stop the node from collecting further timing data, use dgTimerOff().

Calls to dgTimerOn() and dgTimerOff() are not cumulative. Even if you call dgTimerOn() three times for a node it still only takes a single call to dgTimerOff() to disable its data collection.

Returns

Status code

Status Codes:

• MS::kSuccess if the method is successful.
• MS::kFailure if an object error occurs.

MStatus dgTimerOff

(

)

Indicates that this node should no longer collect DG timing data when DG timing is enabled.

See dgTimerOn() and enableDGTiming() for more details.

Any timing data which has already been collected remains available, for example, using the dgTimer() method.

Returns

Status code

Status Codes:

• MS::kSuccess if the method is successful.
• MS::kFailure if an object error occurs.

MFnDependencyNode::MdgTimerState dgTimerQueryState

(

MStatus *

ReturnStatus = NULL

)

The function returns the current on/off state of the node's timer.

Parameters

[out]

ReturnStatus

return status.

Returns

The node's timer's current on/off state.

Status Codes:

• MS::kSuccess if the method is successful.
• MS::kFailure if an object error occurs.

MStatus dgTimerReset

(

)

The function resets the dependency graph timers and counters for this node to zero.

Note that this method does not start or stop timing, it only resets the values to zero. If you want to turn on timing, use the method dgTimerOn(). If you want to turn off timing, use dgTimerOff().

Returns

Status code

Status Codes:

• MS::kSuccess if the method is successful.
• MS::kFailure if an object error occurs.

double dgTimer	(	const MdgTimerMetric	timerMetric,
		const MdgTimerType	timerType,
		MStatus *	ReturnStatus = NULL
	)		const

The function returns the specified timer value for the current node.

This is the total amount of time spent performing the requested operation since the timer was last reset (see dgTimerReset() for details). There are numerous timers per node and these are referenced by the metric and the timer type.

Parameters

[in]	timerMetric	The timing metric we wish to query.
[in]	timerType	The timer type we wish to query.
[out]	ReturnStatus	return status

Returns

Value of the timer in seconds for types of kTimerType_self and kTimerType_inclusive, and as a simple count for kTimerType_count.

Status Codes:

• MS::kSuccess if the method is successful.
• MS::kInvalidParameter if `timerMetric' or `timerType' is invalid.

MStatus dgCallbacks	(	const MdgTimerType	timerType,
		MStringArray &	callbackName,
		MDoubleArray &	value
	)

Node callbacks that occur when timing is enabled get logged with the node and can be queried via this method.

See the dgCallbackIds method for getting a further breakdown of the time for an individual callback on this node.

There are several important items of note:

• 1 Due to the large number of node types which exist within Maya, the "internal name" is used instead of the API name. For example, a message the user declares to be of type MDagMessage::kParentRemoved will report as "parentRemovedMsg". In general it should be obvious as to the meaning of the callback name.
• 2 Timing is reported by callback type and is not further broken down by the individual callback methods that are registered against that callback type. Therefore if you note a high-cost callback type, the majority of cost may not be expended in your callback method but rather in other registered callbacks on that type.
• 3 Not all callback types inside Maya that deal with nodes are currently tracked using the node callback timing mechanism. Only the most frequently encountered message types are currently recorded.

The result of calling this method is an array of names and an array of values. There is a one-to-one correspondence between the two arrays.

Parameters

[in]	timerType	The timer we want to query, e.g. kTimerType_self for self time.
[in]	callbackName	Returns an array of callback names that were invoked for this node since the last timer reset.
[in]	value	Returns an array of timing values. There is a one-to-one correspondence with the `callbackName' array.

Returns

Status code

Status Codes:

• MS::kSuccess if the method is successful.
• MS::kInvalidParameter if `timerType' is invalid.

MStatus dgCallbackIds	(	const MdgTimerType	timerType,
		const MString &	callbackName,
		MCallbackIdArray &	callbackId,
		MDoubleArray &	value
	)

This method provides a further breakdown of the per-callback time returned via dgCallbacks() by returning the data on a per-callbackId basis.

We define a "callback" to be an event withing Maya that "callback methods" can be registered with to be invoked when the given event occurs. The registered client information is called a "callbackId". There can be multiple callbackIds registered with a given callback, and a callbackId can be shared amongst multiple nodes or multiple callbacks.

An example of a callback is "attributeChangedMsg", which the user can register callback methods against via MNodeMessage::addAttributeChangedCallback(). The process of registering a callback method returns a callbackId, thus there can be multiple callbacksIds per callback.

The general approach when querying callbackIds is as follows:

• 1 Query the callbacks associated with a given node using MFnDependencyNode::dgCallbacks(). This returns the list of callbacks by name.
• 2 Use this method to query the callbackIds for a given callback on the given node.

The result of calling this method is an array of names and an array of values. There is a one-to-one correspondence between the two arrays.

Parameters

[in]	timerType	The timer we want to query, e.g. kTimerType_self for self time.
[in]	callbackName	Name of the callback to query the callbackIds for. This should be one of the callback names that was returned from MFnDependencyNode::dgCallbacks().
[in]	callbackId	Returns an array of callbackIds which were invoked for this node and `callbackName' since the last timer reset. There is a one-to-one correspondence with the `value' array. The entries in the list can include callbackIds that are no longer active (e.g. if you unregistered the callbackId), so be careful not to treat these as active callbackIds – they are for informational purposes only.
[in]	value	Returns an array of timing values. There is a one-to-one correspondence with the `name' array.

Returns

Status code

Status Codes:

• MS::kSuccess if the method is successful.
• MS::kInvalidParameter if `timerType' is invalid.
• MS::kNotFound if `callbackName' was not one of the callbacks that was invoked for this node since the last timer reset.

MStatus addAttribute	(	const MObject &	attr,
		MFnDependencyNode::MAttrClass	type
	)

This method is obsolete.

Deprecated:

Use the MFnDependencyNode::addAttribute( const MObject& ) method instead.

Add a new attibute to this node. Note that this operation will fail if the given type parameter is not MFnDependencyNode::kLocalDynamicAttr. See MNodeClass for adding or removing extension attributes.

Parameters

[in]	attr	new attribute
[in]	type	class of attribute to add

Returns

Status code

Status Codes:

• MS::kSuccess operation successful
• MS::kInvalidParameter attr is not a valid attribute object, or type did not specify a local dynamic attribute type.
• MS::kFailure function set does not have a valid object, or the addition of the new attribute failed

MStatus removeAttribute	(	const MObject &	attribute,
		MFnDependencyNode::MAttrClass	type
	)

This method is obsolete.

Deprecated:

Use the MFnDependencyNode::removeAttribute( const MObject& ) method instead. Remove an attribute from a node.

Note: After a successful call to this method, the MObject passed to it 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]	attribute	attribute to remove
[in]	type	class of attribute to remove (must be MFnDependencyNode::kLocalDynamicAttr) See MNodeClass for adding or removing extension attributes.

Returns

Status code

Status Codes:

• MS::kSuccess operation successful
• MS::kInvalidParameter attr is not a valid attribute object, or type did not specify a dynamic attribute type.
• MS::kFailure function set does not have a valid object, or the removal of the attribute failed

---

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

• MFnDependencyNode.h
• MFnDependencyNode.cpp