class MDataHandle

Jump to documentation

public members:

	MDataHandle ()
bool	isNumeric () const
bool	isGeneric ( bool& isNumeric , bool& isNull ) const
MFnNumericData::Type	numericType () const
MFnData::Type	type () const
MTypeId	typeId () const
MStatus	acceptedTypeIds ( MUintArray &) const
MObject	data ()
MStatus	copy ( const MDataHandle & src )
void	setClean ()
bool&	asBool () const
char&	asChar () const
unsigned char&	asUChar () const
short&	asShort () const
int&	asLong () const OBSOLETE
int&	asInt () const
void*&	asAddr () const
float&	asFloat () const
double&	asDouble () const
MDistance	asDistance () const
MAngle	asAngle () const
MTime	asTime () const
short2&	asShort2 () const
long2&	asLong2 () const OBSOLETE
int2&	asInt2 () const
float2&	asFloat2 () const
double2&	asDouble2 ()const
short3&	asShort3 () const
long3&	asLong3 () const OBSOLETE
int3&	asInt3 () const
float3&	asFloat3 () const
double3&	asDouble3 () const
MVector &	asVector () const
MFloatVector &	asFloatVector () const
MMatrix &	asMatrix () const
MFloatMatrix &	asFloatMatrix () const
MString &	asString () const
MObject	asNurbsCurve () const
MObject	asNurbsSurface () const
MObject	asMesh () const
MObject	asSubdSurface () const
MObject	asNurbsCurveTransformed () const
MObject	asNurbsSurfaceTransformed () const
MObject	asMeshTransformed () const
MObject	asSubdSurfaceTransformed () const
const MMatrix &	geometryTransformMatrix () const
MPxData *	asPluginData () const
void	set ( bool )
void	set ( char )
void	set ( short )
void	set ( int )
void	set ( float )
void	set ( double )
void	set ( const MMatrix & )
void	set ( const MFloatMatrix & )
void	set ( const MVector & )
void	set ( const MFloatVector & )
void	set ( const MDistance & )
void	set ( const MAngle & )
void	set ( const MTime & )
void	set ( short, short )
void	set ( int, int )
void	set ( float, float )
void	set ( double, double )
void	set ( short, short, short )
void	set ( int, int, int )
void	set ( float, float, float )
void	set ( double, double, double )
void	set ( const MString &)
MStatus	set ( const MObject & data )
MStatus	set ( MPxData * data )
bool	asGenericBool () const
unsigned char	asGenericChar () const
double	asGenericDouble () const
float	asGenericFloat () const
short	asGenericShort () const
int	asGenericInt () const
void	setGenericBool ( bool value, bool force )
void	setGenericChar ( unsigned char value, bool force )
void	setGenericDouble ( double value, bool force )
void	setGenericFloat ( float value, bool force )
void	setGenericShort ( short value, bool force )
void	setGenericInt ( int value, bool force )
MDataHandle	child ( const MPlug & plug )
MDataHandle	child ( const MObject & attribute )
MDataHandle &	operator= ( const MDataHandle & other )
	MDataHandle ( const MDataHandle & )

Documentation

Description

An MDataHandle is a smart pointer into a data block (MDataBlock). A data handle corresponds to the data for a particular attribute or plug. For array data (eg CVs of a curve) use an MArrayDataHandle. To get a data handle, request it from the data block.

Some simple numeric data is handled directly by the dependency graph. If the data is more complicated (eg surface geometry), then the data handle can supply a pointer that should be given to the appropriate data function set.

MDataHandle allows the manipulation and setting of generic attributes as created by the MFnGenericAttribute class. It is possible to create numeric generic attributes using two scenarios. A plug-in may request that the generic attribute support singleton types such as MFnNumericData::kFloat or kChar. Or a plug-in may request array types such as MFnNumericData::k2Float k2Double. In the singleton case, getting and setting the attribute using MDataHandle is done with the asGeneric*() or setGeneric*() methods. In the case of the array types, the MDataHandle.data() method can be used to retrieve the MObject for the attribute and to initialize the MFnNumericData function set. A call to MDataHandle::setData() on the updated attribute must be made to pass the information back to Maya. NOTE: It is not possible to distinguish the singleton generic types from one another. There is no method that can be called to return if the singleton generic attribute is a float, char etc.

Functions

MDataHandle:: MDataHandle ()

Description

Constructor for MDataHandle.

Typically, data handles will be obtained from the data block (MDataBlock). A user constructed MDataHandle should not be used until a valid data handle has been assigned to it (ie. using the assignment operator).

bool MDataHandle:: isNumeric () const

Description

Returns true if this handle is for simple numeric data. That means that the numeric data is directly accessible through the non-generic as*() and set*() methods of this handle. For example, depending on handle initialization, the asBool() may be called but the asGenericBool() should not be called.

Return Value

• whether this handle points to simple numeric data

bool MDataHandle:: isGeneric ( bool& isNumeric , bool& isNull ) const

Description Returns true if this handle is for generic data. There are 2 forms of generic data. The first is for simple data and is used if the isNumeric parameter returns true. In this case, the asGeneric*() and setGeneric*() methods of this class are used to query and set values. The second form of generic data is for more complex attribute types. As a result the type of the object must be checked and an appropriate attribute function set initialized with the object.

Arguments

• isNumeric returns true if this handle is for simple generic numeric data
• isNull returns true if this handle is not set

Return Value

• true will be returned if this handle points to a generic attribute

MFnNumericData::Type MDataHandle:: numericType () const

Description

Returns the type of data represented by this handle. This method is only valid for data handles of simple numeric types.

Return Value

• the numeric type

MFnData::Type MDataHandle:: type () const

Description

Returns the type of data represented by this handle.

Return Value

• the data type

MTypeId MDataHandle:: typeId () const

Description

Returns the type of data represented by this handle as a type id. A type id is a four character code that is used to identify the data type. If no data exists for this handle, the type id will be 0x0.

Return Value

• the data type

MStatus MDataHandle:: acceptedTypeIds ( MUintArray &typids ) const

Description

This method returns an array of MTypeId ids that the data handle can accept. The MTypeId can be reconstructed using the unsigned int in id.

Arguments

• typids an unsigned int array to copy the ids to

Return Value

• status code

Status Codes

• MS::kSuccess The method was successful
• MS::kFailure The method failed

MObject MDataHandle:: data ()

Description

Returns the data object from this handle. The object returned should be used with the appropriate data function set. This method is not valid for simple numeric types.

Return Value

• the data object

MStatus MDataHandle:: copy ( const MDataHandle & src )

Description

Copies the attribute from the src attribute to the attribute referenced by this handle. This is the only method which can completely copy a compound attribute from one handle to another. The construct outputHandle.set (inputHandle.data()) will not work for compound or multi attributes.

Arguments

• src the handle to the attribute to copy

Return Value

• status code

Status Codes

• MS::kSuccess The method was successful
• MS::kFailure The method failed

void MDataHandle:: setClean ()

Description

Marks the data that is represented by this handle as being clean. This should be done after recalculating the data from the inputs.

Return Value

• None

bool& MDataHandle:: asBool () const

Description

Returns the data represented by this handle in the data block.

Return Value

• the handle's data as a boolean

char& MDataHandle:: asChar () const

Description

Returns the data represented by this handle in the data block.

Return Value

• the handle's data as a char

unsigned char& MDataHandle:: asUChar () const

Description

Returns the data represented by this handle in the data block.

Return Value

• the handle's data as an unsigned char

short& MDataHandle:: asShort () const

Description

Returns the data represented by this handle in the data block.

Return Value

• the handle's data as a short integer

int& MDataHandle:: asInt () const

Description

Returns the data represented by this handle in the data block.

Return Value

• the handle's data as a int integer

void*& MDataHandle:: asAddr () const

Description

Returns the data represented by this handle in the data block.

Return Value

• the handle's data as an address

int& MDataHandle:: asLong () const

Description

This method is Obsolete. Use "asInt" instead.

Return Value

• the handle's data as a int integer

float& MDataHandle:: asFloat () const

Description

Returns the data represented by this handle in the data block.

Return Value

• the handle's data as a float

double& MDataHandle:: asDouble () const

Description

Returns the data represented by this handle in the data block.

Return Value

• the handle's data as a double

MDistance MDataHandle:: asDistance () const

Description

Returns the data represented by this handle in the data block.

Return Value

• the handle's data as an Distance

MAngle MDataHandle:: asAngle () const

Description

Returns the data represented by this handle in the data block.

Return Value

• the handle's data as an MAngle

MTime MDataHandle:: asTime () const

Description

Returns the data represented by this handle in the data block. Even though this method does not return a reference to an MTime, modifications to the MTime instance will update the contents of the handle in the data block. The method MDataHandle::setClean should be called after the data block has been modified.

Return Value

• the handle's data as an MTime

short2& MDataHandle:: asShort2 () const

Description

Returns the data represented by this handle in the data block.

Return Value

• the handle's data as an array of two short integers

int2& MDataHandle:: asInt2 () const

Description

Returns the data represented by this handle in the data block.

Return Value

• the handle's data as an array of two int integers

long2& MDataHandle:: asLong2 () const

Description

This method is Obsolete. Use "asInt2" instead.

Return Value

• the handle's data as an array of two int integers

float2& MDataHandle:: asFloat2 () const

Description

Returns the data represented by this handle in the data block.

Return Value

• the handle's data as an array of two floats

double2& MDataHandle:: asDouble2 () const

Description

Returns the data represented by this handle in the data block.

Return Value

• the handle's data as an array of two doubles

short3& MDataHandle:: asShort3 () const

Description

Returns the data represented by this handle in the data block.

Return Value

• the handle's data as an array of three short integers

int3& MDataHandle:: asInt3 () const

Description

Returns the data represented by this handle in the data block.

Return Value

• the handle's data as an array of three int integers

long3& MDataHandle:: asLong3 () const

Description

This method is Obsolete. Use "asInt3" instead.

Return Value

• the handle's data as an array of three int integers

float3& MDataHandle:: asFloat3 () const

Description

Returns the data represented by this handle in the data block.

Return Value

• the handle's data as an array of three float values

double3& MDataHandle:: asDouble3 () const

Description

Returns the data represented by this handle in the data block.

Return Value

• the handle's data as an array array of three doubles

MVector & MDataHandle:: asVector () const

Description

Returns the data represented by this handle in the data block.

Return Value

• the handle's data as a vector

MFloatVector & MDataHandle:: asFloatVector () const

Description

Returns the data represented by this handle in the data block.

Return Value

• the handle's data as a vector

MMatrix & MDataHandle:: asMatrix () const

Description

Returns the data represented by this handle in the data block. This method is only valid for attributes created using the MFnMatrixAttribute function set.

Return Value

• the handle's data as a matrix

MFloatMatrix & MDataHandle:: asFloatMatrix () const

Description

Returns the data represented by this handle in the data block. This method is only valid for attributes created using the MFnMatrixAttribute function set.

Return Value

• the handle's data as a matrix of floats

MString & MDataHandle:: asString () const

Description

Returns the data represented by this handle in the data block.

Return Value

• the handle's data as a string

MObject MDataHandle:: asNurbsCurve () const

Description

Returns the data represented by this handle in the data block. The object returned by this call may be used directly with the nurbs curve function set and iterator. Even though this method does not return a reference to an MObject, modifications to the MObject instance will update the contents of the handle in the data block. The method MDataHandle::setClean should be called after the data block has been modified.

The curve returned by this method will be in local space even if the connection is supplying world space geometry. This occurs mostly for efficiency reasons. In the case of a world space geometry connection, the MObject returned by this method will also contain the world space transformation matrix. This means that world space operations may be performed on this object using the nurbs curve function set and iterator.

It is possible to get the matrix that defines the local to world transformation for this geometry using the MDataHandle::asGeometryTransformMatrix() method.

Return Value

• the handle's data as a nurbs curve

MObject MDataHandle:: asNurbsSurface () const

Description

Returns the data represented by this handle in the data block. The object returned by this call may be used directly with the nurbs surface function set and iterator. Even though this method does not return a reference to an MObject, modifications to the MObject instance will update the contents of the handle in the data block. The method MDataHandle::setClean should be called after the data block has been modified.

The surface returned by this method will be in local space even if the connection is supplying world space geometry. This occurs mostly for efficiency reasons. In the case of a world space geometry connection, the MObject returned by this method will also contain the world space transformation matrix. This means that world space operations may be performed on this object using the nurbs surface function set and iterator.

It is possible to get the matrix that defines the local to world transformation for this geometry using the MDataHandle::asGeometryTransformMatrix() method.

Return Value

• the handle's data as a nurbs surface

MObject MDataHandle:: asMesh () const

Description

Returns the data represented by this handle in the data block. The object returned by this call may be used directly with the mesh function set and iterators. Even though this method does not return a reference to an MObject, modifications to the MObject instance will update the contents of the handle in the data block. The method MDataHandle::setClean should be called after the data block has been modified.

The surface returned by this method will be in local space even if the connection is supplying world space geometry. This occurs mostly for efficiency reasons. In the case of a world space geometry connection, the MObject returned by this method will also contain the world space transformation matrix. This means that world space operations may be performed on this object using the mesh function set and iterators.

It is possible to get the matrix that defines the local to world transformation for this geometry using the MDataHandle::asGeometryTransformMatrix() method.

Return Value

• the handle's data as a mesh (polygonal surface)

MObject MDataHandle:: asSubdSurface () const

Description

Returns the data represented by this handle in the data block. The object returned by this call may be used directly with the subdivision surface function set and iterator. Even though this method does not return a reference to an MObject, modifications to the MObject instance will update the contents of the handle in the data block. The method MDataHandle::setClean should be called after the data block has been modified.

The subdivision surface returned by this method will be in local space even if the connection is supplying world space geometry. This occurs mostly for efficiency reasons. In the case of a world space geometry connection, the MObject returned by this method will also contain the world space transformation matrix. This means that world space operations may be performed on this object using the subdivision surface function set and iterator.

It is possible to get the matrix that defines the local to world transformation for this geometry using the MDataHandle::asGeometryTransformMatrix() method.

Return Value

• the handle's data as a subdivision surface

MObject MDataHandle:: asNurbsSurfaceTransformed () const

Description

Returns the data represented by this handle in the data block. The object returned by this call may be used directly with the nurbs surface function set (MFnNurbsSurface) or the nurbs surface CV iterator (MItSurfaceCV).

If the incoming surface comes with world space transformation data, then it will be applied to the data that is returned. In other words, the surface that is returned will be the surface as it exists in world space.

The surface that is returned from this method should not be modified. This method is only provided to make it easier to take world space geometry as input.

Return Value

• the handle's data as a nurbs surface

MObject MDataHandle:: asNurbsCurveTransformed () const

Description

Returns the data represented by this handle in the data block. The object returned by this call may be used directly with the nurbs curve function set (MFnNurbsCurve) or the nurbs curve CV iterator (MItCurveCV).

If the incoming curve comes with world space transformation data, then it will be applied to the data that is returned. In other words, the curve that is returned will be the curve as it exists in world space.

The curve that is returned from this method should not be modified. This method is only provided to make it easier to take world space geometry as input.

Return Value

• the handle's data as a nurbs curve

MObject MDataHandle:: asMeshTransformed () const

Description

Returns the data represented by this handle in the data block. The object returned by this call may be used directly with the mesh function set (MFnMesh) or any of the mesh iterators.

If the incoming mesh comes with world space transformation data, then it will be applied to the data that is returned. In other words, the mesh that is returned will be the mesh as it exists in world space.

The mesh that is returned from this method should not be modified. This method is only provided to make it easier to take world space geometry as input.

Return Value

• the handle's data as a mesh

MObject MDataHandle:: asSubdSurfaceTransformed () const

Description

Returns the data represented by this handle in the data block. The object returned by this call may be used directly with the subdivision surface function set (MFnSubdSurface) or the subdivision surface iterators (MItSubdVertex, MItSubdFace, MItSubdEdge).

If the incoming surface comes with world space transformation data, then it will be applied to the data that is returned. In other words, the surface that is returned will be the surface as it exists in world space.

The surface that is returned from this method should not be modified. This method is only provided to make it easier to take world space geometry as input.

Return Value

• the handle's data as a subdivision surface

const MMatrix & MDataHandle:: geometryTransformMatrix () const

Description

This method returns a reference to the local-to-world transformation matrix that can accompany a geometry data object. Only use this method on handles to geometry data (curves, surfaces, and meshes).

If no local-to-world transformation information has been provided then this will be an identity matrix.

Return Value

• the handle's transform data as a 4x4 matrix

MPxData * MDataHandle:: asPluginData () const

Description

Returns the data represented by this handle in the data block. The object is returned as plugin data. This should be used to access data types defined by plugins.

Return Value

• the handle's data

void MDataHandle:: set ( bool val )

Description

Set the data that this handle represents in the data block.

Arguments

• val the new value

Return Value

• None

void MDataHandle:: set ( char val )

Description

Set the data that this handle represents in the data block.

Arguments

• val the new value

Return Value

• None

void MDataHandle:: set ( short val )

Description

Set the data that this handle represents in the data block.

Arguments

• val the new value

Return Value

• None

void MDataHandle:: set ( int val )

Description

Set the data that this handle represents in the data block.

Arguments

• val the new value

Return Value

• None

void MDataHandle:: set ( float val )

Description

Set the data that this handle represents in the data block.

Arguments

• val the new value

Return Value

• None

void MDataHandle:: set ( double val )

Description

Set the data that this handle represents in the data block.

Arguments

• val the new value

Return Value

• None

void MDataHandle:: set ( const MMatrix & val )

Description

Set the data that this handle represents in the data block. This method is only valid for attributes created using the MFnMatrixAttribute function set.

Arguments

• val the new value

Return Value

• None

void MDataHandle:: set ( const MFloatMatrix & val )

Description

Set the data that this handle represents in the data block.

Arguments

• val the new value

Return Value

• None

void MDataHandle:: set ( const MVector & val )

Description

Set the data that this handle represents in the data block.

Arguments

• val the new value

Return Value

• None

void MDataHandle:: set ( const MFloatVector & val )

Description

Set the data that this handle represents in the data block.

Arguments

• val the new value

Return Value

• None

void MDataHandle:: set ( const MDistance & val )

Description

Set the data that this handle represents in the data block.

Arguments

• val the new value

Return Value

• None

void MDataHandle:: set ( const MAngle & val )

Description

Set the data that this handle represents in the data block.

Arguments

• val the new value

Return Value

• None

void MDataHandle:: set ( const MTime & val )

Description

Set the data that this handle represents in the data block.

Arguments

• val the new value

Return Value

• None

void MDataHandle:: set ( short val1, short val2 )

Description

Set the data that this handle represents in the data block.

Arguments

• val1 the first value in the two element array
• val2 the second value in the two element array

Return Value

• None

void MDataHandle:: set ( int val1, int val2 )

Description

Set the data that this handle represents in the data block.

Arguments

• val1 the first value in the two element array
• val2 the second value in the two element array

Return Value

• None

void MDataHandle:: set ( float val1, float val2 )

Description

Set the data that this handle represents in the data block.

Arguments

• val1 the first value in the two element array
• val2 the second value in the two element array

Return Value

• None

void MDataHandle:: set ( double val1, double val2 )

Description

Set the data that this handle represents in the data block.

Arguments

• val1 the first value in the two element array
• val2 the second value in the two element array

Return Value

• None

void MDataHandle:: set ( short val1, short val2, short val3 )

Description

Set the data that this handle represents in the data block.

Arguments

• val1 the first value in the three element array
• val2 the second value in the three element array
• val3 the third value in the three element array

Return Value

• None

void MDataHandle:: set ( int val1, int val2, int val3 )

Description

Set the data that this handle represents in the data block.

Arguments

• val1 the first value in the three element array
• val2 the second value in the three element array
• val3 the third value in the three element array

Return Value

• None

void MDataHandle:: set ( float val1, float val2, float val3 )

Description

Set the data that this handle represents in the data block.

Arguments

• val1 the first value in the three element array
• val2 the second value in the three element array
• val3 the third value in the three element array

Return Value

• None

void MDataHandle:: set ( double val1, double val2, double val3 )

Description

Set the data that this handle represents in the data block.

Arguments

• val1 the first value in the three element array
• val2 the second value in the three element array
• val3 the third value in the three element array

Return Value

• None

void MDataHandle:: set ( const MString & val )

Description

Set the data that this handle represents in the data block.

Arguments

• val the new string value

Return Value

• None

MStatus MDataHandle:: set ( const MObject & data )

Description

Set the data that this handle represents in the data block. This method assumes that the MObject is a dependency graph data object. These objects can be created using the appropriate MFn..Data function set. Note that this method cannot be used to copy compound or multi attributes from one handle to another via the construct outputHandle.set (inputHandle.data()). To copy these user defined attributes, the method MDataHandle::copy must be used.

Arguments

• data the data object

Return Value

• status code

Status Codes

• MS::kSuccess The method was successful
• MS::kInvalidParameter Invalid object passed in

MStatus MDataHandle:: set ( MPxData * data )

Description

Set the data that this handle represents in the data block. This method takes a pointer to a user defined data object. The data block will become the new owner of the data object that you pass in. Do not delete it.

Arguments

• data the data object

Return Value

• status code

Status Codes

• MS::kSuccess The method was successful
• MS::kInvalidParameter Invalid data

bool MDataHandle:: asGenericBool () const

Description

Returns the generic data represented by this handle in the data block.

Return Value

• the generic handle's data as a bool

unsigned char MDataHandle:: asGenericChar () const

Description

Returns the generic data represented by this handle in the data block.

Return Value

• the generic handle's data as a char

double MDataHandle:: asGenericDouble () const

Description

Returns the generic data represented by this handle in the data block.

Return Value

• the generic handle's data as a double

float MDataHandle:: asGenericFloat () const

Description

Returns the generic data represented by this handle in the data block.

Return Value

• the generic handle's data as a float

short MDataHandle:: asGenericShort () const

Description

Returns the generic data represented by this handle in the data block.

Return Value

• the generic handle's data as a short

int MDataHandle:: asGenericInt () const

Description

Returns the generic data represented by this handle in the data block.

Return Value

• the generic handle's data as a int

void MDataHandle:: setGenericBool ( bool value, bool force )

Description

Set the data that this handle represents in the data block.

Arguments

• val the new bool value
• force force the new type of the attribute to be bool

Return Value

• None

void MDataHandle:: setGenericChar ( unsigned char value, bool force )

Description

Set the data that this handle represents in the data block.

Arguments

• val the new char value
• force force the new type of the attribute to be char

Return Value

• None

void MDataHandle:: setGenericDouble ( double value, bool force )

Description

Set the data that this handle represents in the data block.

Arguments

• val the new double value
• force force the new type of the attribute to be double

Return Value

• None

void MDataHandle:: setGenericFloat ( float value, bool force )

Description

Set the data that this handle represents in the data block.

Arguments

• val the new float value
• force force the new type of the attribute to be float

Return Value

• None

void MDataHandle:: setGenericShort ( short value, bool force )

Description

Set the data that this handle represents in the data block.

Arguments

• val the new short value
• force force the new type of the attribute to be short

Return Value

• None

void MDataHandle:: setGenericInt ( int value, bool force )

Description

Set the data that this handle represents in the data block.

Arguments

• val the new int value
• force force the new type of the attribute to be int

Return Value

• None

MDataHandle MDataHandle:: child ( const MPlug & plug )

Description

Get a handle to a child of this handle. This is used if you have a handle to a compound attribute.

Arguments

• plug the plug of the child

Return Value

• the data handle for the child

MDataHandle MDataHandle:: child ( const MObject & attribute )

Description

Get a handle to a child of this handle. This is used if you have a handle to a compound attribute.

Arguments

• plug the attribute of the child

Return Value

• the data handle for the child

MDataHandle:: MDataHandle ( const MDataHandle & other )

Description

Copy constructor.

MDataHandle & MDataHandle:: operator= ( const MDataHandle & other )

Description

Assignment operator.

This class has no child classes.