Public Types | Public Member Functions | Protected Member Functions

MFnUnitAttribute Class Reference

This reference page is linked to from the following overview topics: Communication Between Manipulators and Nodes.


Search for all occurrences

Detailed Description

Unit attribute Function set.

MFnUnitAttribute is the function set for dependency nodes attributes that store one of the fundamental types of Maya data. The currently supported types are MAngle, MDistance, and MTime.

It is possible to set the defaults using a double. This is valid for angles and distances. In the case of angles, the value is assumed to be in radians, and in the case of distances, it is assumed to be in centimeters. Time values should not be set using a double.

It is possible to use unit attributes in place of double attributes when creating numeric compounds (see MFnNumericAttrbute). To create a numeric compound of three distance values, create the three child attributes using MFnUnitAttribute and then pass the children into the create method of MFnNumericAttribute.

Examples:

animCubeNode.cpp, buildRotationNode.cpp, footPrintManip.cpp, footPrintNode.cpp, latticeNoiseNode.cpp, shellNode.cpp, swissArmyManip.cpp, testNobjectNode.cpp, and testNucleusNode.cpp.

#include <MFnUnitAttribute.h>

Inheritance diagram for MFnUnitAttribute:
Inheritance graph
[legend]

List of all members.

Public Types

enum  Type {
  kInvalid, kAngle, kDistance, kTime,
  kLast
}
 

Type of unit represented by attribute values.

More...

Public Member Functions

virtual MFn::Type type () const
 Function set type.
virtual ~MFnUnitAttribute ()
 Destructor.
 MFnUnitAttribute ()
 Default constructor.
 MFnUnitAttribute (MObject &object, MStatus *ReturnStatus=NULL)
 Constructor.
MObject create (const MString &fullName, const MString &briefName, MFnUnitAttribute::Type unitType, double defaultValue=0.0, MStatus *ReturnStatus=NULL)
 Create a new unit attribute and return it as an MObject.
MObject create (const MString &fullName, const MString &briefName, const MTime &defaultValue, MStatus *ReturnStatus=NULL)
 Create a new unit attribute of type time and return it as an MObject.
MObject create (const MString &fullName, const MString &briefName, const MAngle &defaultValue, MStatus *ReturnStatus=NULL)
 Create a new unit attribute of type angle and return it as an MObject.
MObject create (const MString &fullName, const MString &briefName, const MDistance &defaultValue, MStatus *ReturnStatus=NULL)
 Create a new unit attribute of type distance and return it as an MObject.
MFnUnitAttribute::Type unitType (MStatus *ReturnStatus=NULL) const
 Return the unit type of this attribute.
bool hasMin (MStatus *ReturnStatus=NULL) const
 Determine whether or not this attribute has a minimum value set.
bool hasMax (MStatus *ReturnStatus=NULL) const
 Determine whether or not this attribute has a maximum value set.
bool hasSoftMin (MStatus *ReturnStatus=NULL) const
 Determine whether or not this attribute has a soft minimum value set.
bool hasSoftMax (MStatus *ReturnStatus=NULL) const
 Determine whether or not this attribute has a soft maximum value set.
MStatus getMin (double &minValue) const
 Return the minimum value for this attribute.
MStatus getMin (MTime &minValue) const
 Return the minimum value for this attribute.
MStatus getMin (MAngle &minValue) const
 Return the minimum value for this attribute.
MStatus getMin (MDistance &minValue) const
 Return the minimum value for this attribute.
MStatus getMax (double &maxValue) const
 Return the maximum value for this attribute.
MStatus getMax (MTime &maxValue) const
 Return the maximum value for this attribute.
MStatus getMax (MAngle &maxValue) const
 Return the maximum value for this attribute.
MStatus getMax (MDistance &maxValue) const
 Return the maximum value for this attribute.
MStatus getSoftMin (double &minValue) const
 Return the soft minimum value for this attribute.
MStatus getSoftMin (MTime &minValue) const
 Return the soft minimum value for this attribute.
MStatus getSoftMin (MAngle &minValue) const
 Return the soft minimum value for this attribute.
MStatus getSoftMin (MDistance &minValue) const
 Return the soft minimum value for this attribute.
MStatus getSoftMax (double &maxValue) const
 Return the soft maximum value for this attribute.
MStatus getSoftMax (MTime &maxValue) const
 Return the soft maximum value for this attribute.
MStatus getSoftMax (MAngle &maxValue) const
 Return the soft maximum value for this attribute.
MStatus getSoftMax (MDistance &maxValue) const
 Return the soft maximum value for this attribute.
MStatus setMin (double minValue)
 Set the minimum value for this attribute.
MStatus setMin (const MTime &minValue)
 Set the minimum value for this attribute.
MStatus setMin (const MAngle &minValue)
 Set the minimum value for this attribute.
MStatus setMin (const MDistance &minValue)
 Set the minimum value for this attribute.
MStatus setMax (double maxValue)
 Set the maximum value for this attribute.
MStatus setMax (const MTime &maxValue)
 Set the maximum value for this attribute.
MStatus setMax (const MAngle &maxValue)
 Set the maximum value for this attribute.
MStatus setMax (const MDistance &maxValue)
 Set the maximum value for this attribute.
MStatus setSoftMin (double minValue)
 Set the soft minimum value for this attribute.
MStatus setSoftMin (const MTime &minValue)
 Set the soft minimum value for this attribute.
MStatus setSoftMin (const MAngle &minValue)
 Set the soft minimum value for this attribute.
MStatus setSoftMin (const MDistance &minValue)
 Set the soft minimum value for this attribute.
MStatus setSoftMax (double maxValue)
 Set the soft maximum value for this attribute.
MStatus setSoftMax (const MTime &maxValue)
 Set the soft maximum value for this attribute.
MStatus setSoftMax (const MAngle &maxValue)
 Set the soft maximum value for this attribute.
MStatus setSoftMax (const MDistance &maxValue)
 Set the soft maximum value for this attribute.
MStatus getDefault (double &defaultValue)
 Gets the default value for this attribute.
MStatus getDefault (MTime &defaultValue)
 Gets the default value for a time attribute.
MStatus getDefault (MAngle &defaultValue)
 Gets the default value for this attribute.
MStatus getDefault (MDistance &defaultValue)
 Gets the default value for this attribute.
MStatus setDefault (double defaultValue)
 Set a new default value for this attribute.
MStatus setDefault (const MTime &defaultValue)
 Set a new default value for a time attribute.
MStatus setDefault (const MAngle &defaultValue)
 Set a new default value for this attribute.
MStatus setDefault (const MDistance &defaultValue)
 Set a new default value for this attribute.
 MFnUnitAttribute (const MObject &object, MStatus *ReturnStatus=NULL)
 Constructor.

Protected Member Functions

virtual const char * className () const
 Class name.

Member Enumeration Documentation

enum Type

Type of unit represented by attribute values.

Enumerator:
kInvalid 

Invalid unit type.

kAngle 

Angular attribute.

kDistance 

Distance (linear) attribute.

kTime 

Time attribute.

kLast 

Last value, for counting.


Constructor & Destructor Documentation

MFnUnitAttribute ( MObject object,
MStatus ReturnStatus = NULL 
)

Constructor.

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

Parameters:
[in]objectThe MObject to attach the function set to
[out]ReturnStatusthe return status
Status Codes:
MFnUnitAttribute ( const MObject object,
MStatus ReturnStatus = NULL 
)

Constructor.

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

Parameters:
[in]objectThe MObject to attach the function set to
[out]ReturnStatusthe return status
Status Codes:

Member Function Documentation

MFn::Type type ( ) const [virtual]

Function set type.

Return the class type : MFn::kUnitAttribute.

Reimplemented from MFnAttribute.

const char * className ( ) const [protected, virtual]

Class name.

Return the class name : "MFnUnitAttribute".

Reimplemented from MFnAttribute.

MObject create ( const MString full,
const MString brief,
MFnUnitAttribute::Type  unitType,
double  defaultValue = 0.0,
MStatus ReturnStatus = NULL 
)

Create a new unit attribute and return it as an MObject.

For both angle and distance attributes, the attribute is type independent. For example, you define an angular attribute as containing an angle in radians. The defaultValue passed to the create method must be in these units, and the value in those units will be returned by the get and set methods. If this method is used to instantiate a time attribute, the units stored in the attribute will be those of the current default time unit (see MTime).

A unit attribute supports both a hard maximum/minimum and a soft maximum/minimum. The soft maximum/minimum are used by the user interface for limits on sliders, but values within the hard range are still valid.

The create method needs to be called on a per node basis. That means if you want to create and add the same attribute to multiple nodes, you need to call the create method for each node to get a unique MObject back. If you call create just once and add the attribute to multiple nodes, Maya will encounter a fatal error.

Parameters:
[in]fullthe full (or int) name of the attribute
[in]briefthe brief (or short) name of the attribute
[in]unitTypean element of the MFnUnitAttribute::Type enum
[in]defaultValuethe default value for the new attribute
[out]ReturnStatus
Returns:
An MObject representing the new attribute
Examples:
animCubeNode.cpp, buildRotationNode.cpp, footPrintManip.cpp, footPrintNode.cpp, latticeNoiseNode.cpp, shellNode.cpp, swissArmyManip.cpp, testNobjectNode.cpp, and testNucleusNode.cpp.
MObject create ( const MString full,
const MString brief,
const MTime defaultValue,
MStatus ReturnStatus = NULL 
)

Create a new unit attribute of type time and return it as an MObject.

The units of the time value stored in the attribute will be those of the current default time units in effect (see MTime).

Parameters:
[in]fullthe full (or int) name of the attribute
[in]briefthe brief (or short) name of the attribute
[in]defaultValuethe default value for the new attribute
[out]ReturnStatus
Returns:
An MObject representing the new attribute
MObject create ( const MString full,
const MString brief,
const MAngle defaultValue,
MStatus ReturnStatus = NULL 
)

Create a new unit attribute of type angle and return it as an MObject.

Parameters:
[in]fullthe full (or int) name of the attribute
[in]briefthe brief (or short) name of the attribute
[in]defaultValuethe default value for the new attribute
[out]ReturnStatus
Returns:
An MObject representing the new attribute
MObject create ( const MString full,
const MString brief,
const MDistance defaultValue,
MStatus ReturnStatus = NULL 
)

Create a new unit attribute of type distance and return it as an MObject.

Parameters:
[in]fullthe full (or int) name of the attribute
[in]briefthe brief (or short) name of the attribute
[in]defaultValuethe default value for the new attribute
[out]ReturnStatus
Returns:
An MObject representing the new attribute
MFnUnitAttribute::Type unitType ( MStatus ReturnStatus = NULL) const

Return the unit type of this attribute.

Parameters:
[out]ReturnStatus
  • MS::kSuccess the operation succeeded
  • MS::kObjectDoesNotExist this instance is not bound to an MObject
Returns:
An element of the MFnUnitAttribute::Type enum
bool hasMin ( MStatus ReturnStatus = NULL) const

Determine whether or not this attribute has a minimum value set.

Parameters:
[out]ReturnStatus
  • MS::kSuccess the operation succeeded
  • MS::kObjectDoesNotExist this instance is not bound to an MObject
Returns:
true if the attribute has a minimum value, and false otherwise
bool hasMax ( MStatus ReturnStatus = NULL) const

Determine whether or not this attribute has a maximum value set.

Parameters:
[out]ReturnStatus
  • MS::kSuccess the operation succeeded
  • MS::kObjectDoesNotExist this instance is not bound to an MObject
Returns:
true if the attribute has a maximum value, and false otherwise
bool hasSoftMin ( MStatus ReturnStatus = NULL) const

Determine whether or not this attribute has a soft minimum value set.

Parameters:
[out]ReturnStatus
  • MS::kSuccess the operation succeeded
  • MS::kObjectDoesNotExist this instance is not bound to an MObject
Returns:
true if the attribute has a minimum value, and false otherwise
bool hasSoftMax ( MStatus ReturnStatus = NULL) const

Determine whether or not this attribute has a soft maximum value set.

Parameters:
[out]ReturnStatus
  • MS::kSuccess the operation succeeded
  • MS::kObjectDoesNotExist this instance is not bound to an MObject
Returns:
true if the attribute has a maximum value, and false otherwise
MStatus getMin ( double &  minValue) const

Return the minimum value for this attribute.

This routine simply returns the numerical value of the attribute. It is up to the programmer to know the units used by this attribute (eg. radians for angular data, centimeters for distance data, etc.) and interpret the response appropriately.

Parameters:
[out]minValuethe minimum value for this attribute
Returns:
MStatus getMin ( MTime minValue) const

Return the minimum value for this attribute.

Parameters:
[out]minValuethe minimum value for this attribute
Returns:
MStatus getMin ( MAngle minValue) const

Return the minimum value for this attribute.

Parameters:
[out]minValuethe minimum value for this attribute
Returns:
MStatus getMin ( MDistance minValue) const

Return the minimum value for this attribute.

Parameters:
[out]minValuethe minimum value for this attribute
Returns:
MStatus getMax ( double &  maxValue) const

Return the maximum value for this attribute.

This routine simply returns the numerical value of the attribute. It is up to the programmer to know the units used by this attribute (eg. radians for angular data, centimeters for distance data, etc.) and interpret the response appropriately.

Parameters:
[out]maxValuethe maximum value for this attribute
Returns:
MStatus getMax ( MTime maxValue) const

Return the maximum value for this attribute.

Parameters:
[out]maxValuethe maximum value for this attribute
Returns:
MStatus getMax ( MAngle maxValue) const

Return the maximum value for this attribute.

Parameters:
[out]maxValuethe maximum value for this attribute
Returns:
MStatus getMax ( MDistance maxValue) const

Return the maximum value for this attribute.

Parameters:
[out]maxValuethe maximum value for this attribute
Returns:
MStatus getSoftMin ( double &  minValue) const

Return the soft minimum value for this attribute.

This routine simply returns the numerical value of the attribute. It is up to the programmer to know the units used by this attribute (eg. radians for angular data, centimeters for distance data, etc.) and interpret the response appropriately.

Parameters:
[out]minValuethe soft minimum value for this attribute
Returns:
MStatus getSoftMin ( MTime minValue) const

Return the soft minimum value for this attribute.

Parameters:
[out]minValuethe soft minimum value for this attribute
Returns:
MStatus getSoftMin ( MAngle minValue) const

Return the soft minimum value for this attribute.

Parameters:
[out]minValuethe soft minimum value for this attribute
Returns:
MStatus getSoftMin ( MDistance minValue) const

Return the soft minimum value for this attribute.

Parameters:
[out]minValuethe soft minimum value for this attribute
Returns:
MStatus getSoftMax ( double &  maxValue) const

Return the soft maximum value for this attribute.

This routine simply returns the numerical value of the attribute. It is up to the programmer to know the units used by this attribute (eg. radians for angular data, centimeters for distance data, etc.) and interpret the response appropriately.

Parameters:
[out]maxValuethe soft maximum value for this attribute
Returns:
MStatus getSoftMax ( MTime maxValue) const

Return the soft maximum value for this attribute.

Parameters:
[out]maxValuethe soft maximum value for this attribute
Returns:
MStatus getSoftMax ( MAngle maxValue) const

Return the soft maximum value for this attribute.

Parameters:
[out]maxValuethe soft maximum value for this attribute
Returns:
MStatus getSoftMax ( MDistance maxValue) const

Return the soft maximum value for this attribute.

Parameters:
[out]maxValuethe soft maximum value for this attribute
Returns:
MStatus setMin ( double  minValue)

Set the minimum value for this attribute.

This routine simply stores the given double as the numerical value of the attribute. It is up to the programmer to know the units used by this attribute (eg. radians for angular data, centimeters for distance data, etc.) and provide the appropriate value.

Parameters:
[in]minValuethe new minimum value for this attribute
Returns:
  • MS::kSuccess the operation succeeded
  • MS::kObjectDoesNotExist this instance is not bound to an MObject
MStatus setMin ( const MTime minValue)

Set the minimum value for this attribute.

Parameters:
[in]minValuethe new minimum value for this attribute
Returns:
MStatus setMin ( const MAngle minValue)

Set the minimum value for this attribute.

Parameters:
[in]minValuethe new minimum value for this attribute
Returns:
MStatus setMin ( const MDistance minValue)

Set the minimum value for this attribute.

Parameters:
[in]minValuethe new minimum value for this attribute
Returns:
MStatus setMax ( double  maxValue)

Set the maximum value for this attribute.

This routine simply stores the given double as the numerical value of the attribute. It is up to the programmer to know the units used by this attribute (eg. radians for angular data, centimeters for distance data, etc.) and provide the appropriate value.

Parameters:
[in]maxValuethe new maximum value for this attribute
Returns:
  • MS::kSuccess the operation succeeded
  • MS::kObjectDoesNotExist this instance is not bound to an MObject
MStatus setMax ( const MTime maxValue)

Set the maximum value for this attribute.

Parameters:
[in]maxValuethe new maximum value for this attribute
Returns:
MStatus setMax ( const MAngle maxValue)

Set the maximum value for this attribute.

Parameters:
[in]maxValuethe new maximum value for this attribute
Returns:
MStatus setMax ( const MDistance maxValue)

Set the maximum value for this attribute.

Parameters:
[in]maxValuethe new maximum value for this attribute
Returns:
MStatus setSoftMin ( double  minValue)

Set the soft minimum value for this attribute.

This routine simply stores the given double as the numerical value of the attribute. It is up to the programmer to know the units used by this attribute (eg. radians for angular data, centimeters for distance data, etc.) and provide the appropriate value.

Parameters:
[in]minValuethe new soft minimum value for this attribute
Returns:
  • MS::kSuccess the operation succeeded
  • MS::kObjectDoesNotExist this instance is not bound to an MObject
MStatus setSoftMin ( const MTime minValue)

Set the soft minimum value for this attribute.

Parameters:
[in]minValuethe new soft minimum value for this attribute
Returns:
MStatus setSoftMin ( const MAngle minValue)

Set the soft minimum value for this attribute.

Parameters:
[in]minValuethe new soft minimum value for this attribute
Returns:
MStatus setSoftMin ( const MDistance minValue)

Set the soft minimum value for this attribute.

Parameters:
[in]minValuethe new soft minimum value for this attribute
Returns:
MStatus setSoftMax ( double  maxValue)

Set the soft maximum value for this attribute.

This routine simply stores the given double as the numerical value of the attribute. It is up to the programmer to know the units used by this attribute (eg. radians for angular data, centimeters for distance data, etc.) and provide the appropriate value.

Parameters:
[in]maxValuethe new soft maximum value for this attribute
Returns:
  • MS::kSuccess the operation succeeded
  • MS::kObjectDoesNotExist this instance is not bound to an MObject
MStatus setSoftMax ( const MTime maxValue)

Set the soft maximum value for this attribute.

Parameters:
[in]maxValuethe new soft maximum value for this attribute
Returns:
MStatus setSoftMax ( const MAngle maxValue)

Set the soft maximum value for this attribute.

Parameters:
[in]maxValuethe new soft maximum value for this attribute
Returns:
MStatus setSoftMax ( const MDistance maxValue)

Set the soft maximum value for this attribute.

Parameters:
[in]maxValuethe new soft maximum value for this attribute
Returns:
MStatus getDefault ( double &  defaultValue)

Gets the default value for this attribute.

This routine simply returns the given double which represents the default value for the attribute.

Parameters:
[out]defaultValuereturns the default value for this attribute. This method simply returns the given default value of the attribute as a double. It is up to the programmer to know the units used by this attribute (eg. radians for angular data, centimeters for distance data, etc.).
Returns:
MStatus getDefault ( MTime defaultValue)

Gets the default value for a time attribute.

Parameters:
[out]defaultValuereturns the default value for this attribute
Returns:
MStatus getDefault ( MAngle defaultValue)

Gets the default value for this attribute.

Parameters:
[out]defaultValuereturns the default value for this attribute in radians
Returns:
MStatus getDefault ( MDistance defaultValue)

Gets the default value for this attribute.

Parameters:
[out]defaultValuereturns the default value for this attribute in centimeters
Returns:
MStatus setDefault ( double  defaultValue)

Set a new default value for this attribute.

This routine simply stores the given double as the new default value of the attribute. It is up to the programmer to know the units used by this attribute (eg. radians for angular data, centimeters for distance data, etc.) and provide the appropriate value.

Parameters:
[in]defaultValuethe new default value for this attribute
Returns:
MS::kSuccess the operation succeeded
Examples:
footPrintManip.cpp, footPrintNode.cpp, and swissArmyManip.cpp.
MStatus setDefault ( const MTime defaultValue)

Set a new default value for a time attribute.

Parameters:
[in]defaultValuethe new default value for this attribute
Returns:
MStatus setDefault ( const MAngle defaultValue)

Set a new default value for this attribute.

Parameters:
[in]defaultValuethe new default value for this attribute
Returns:
MStatus setDefault ( const MDistance defaultValue)

Set a new default value for this attribute.

Parameters:
[in]defaultValuethe new default value for this attribute
Returns:

MFnUnitAttribute MFnUnitAttribute MFnUnitAttribute MFnUnitAttribute MFnUnitAttribute MFnUnitAttribute MFnUnitAttribute MFnUnitAttribute MFnUnitAttribute MFnUnitAttribute
MFnUnitAttribute MFnUnitAttribute MFnUnitAttribute MFnUnitAttribute MFnUnitAttribute MFnUnitAttribute MFnUnitAttribute MFnUnitAttribute MFnUnitAttribute MFnUnitAttribute