MDistance Class Reference
[OpenMaya - API module for common classes]

#include <MDistance.h>

List of all members.

---

Detailed Description

Manipulate Linear Data.

The MDistance class provides a fundamental type for the Maya API to hold and manipulate linear data. All API methods that require or return distance information do so through variables of this type.

Examples:

animFileExport.cpp, animFileUtils.cpp, cgfxAttrDef.cpp, footPrintManip.cpp, footPrintNode.cpp, and swissArmyManip.cpp.

Public Types
enum	Unit { ,    kInches, kFeet, kYards, kMiles,    kMillimeters, kCentimeters, kKilometers, kMeters }
	Available Unit Systems. More...
Public Member Functions
	MDistance ()
	MDistance (double value, Unit unitSystem=kCentimeters)
	MDistance (const MDistance &src)
	~MDistance ()
MDistance &	operator= (const MDistance &src)
Unit	unit () const
double	value () const
MStatus	setUnit (Unit newUnit)
MStatus	setValue (double newValue)
double	as (Unit newUnit, MStatus *ReturnStatus=NULL) const
double	asUnits (Unit newUnit, MStatus *ReturnStatus=NULL) const
double	asInches () const
double	asFeet () const
double	asYards () const
double	asMiles () const
double	asMillimeters () const
double	asCentimeters () const
double	asKilometers () const
double	asMeters () const
Static Public Member Functions
static Unit	uiUnit ()
static MStatus	setUIUnit (Unit newUnit)
static Unit	internalUnit ()
static double	internalToUI (double internalValue)
static double	uiToInternal (double uiValue)
static MStatus	setInternalUnit (Unit internalUnit)
	This method is obsolete.

---

Member Enumeration Documentation

enum MDistance::Unit

Available Unit Systems.

Enumerator:

kInches	Inches.
kFeet	Feet.
kYards	Yards.
kMiles	Miles.
kMillimeters	Millimeters.
kCentimeters	Centimeters.
kKilometers	Kilometers.
kMeters	Meters.

---

Constructor & Destructor Documentation

MDistance::MDistance

(

)

The default class constructor. Initialize the MDistance instance to 0 in the current internal units. (See setInternalUnit and internalUnit below).

MDistance::MDistance	(	double	newValue,
		MDistance::Unit	newUnit = kCentimeters
	)

Class constructor. Initialize the MDistance instance to the given value in the given unit system

Parameters:

[in]	newValue	the initial value of the instance
[in]	newUnit	the unit system for the initial value

MDistance::MDistance

(

const MDistance &

src

)

Copy constructor.

Parameters:

[in]

src

Existing MDistance object from which to initialize the new one.

MDistance::~MDistance

(

)

The class destructor.

---

Member Function Documentation

MDistance & MDistance::operator=

(

const MDistance &

src

)

The assignment operator.

Parameters:

[in]

src

Existing MDistance object from which to set the value of this one.

Returns:

Reference to this MDistance instance.

MDistance::Unit MDistance::unit

(

)

const

Return the units currently in effect for this instance.

Returns:

An element of the MDistance::Unit enum

double MDistance::value

(

)

const

Return the value of the current instance in the currently set units.

Returns:

The current value of the instance

MStatus MDistance::setUnit

(

MDistance::Unit

newUnit

)

Set the units used by this instance.

Parameters:

[in]

newUnit

an element of the MDistance::Unit enum

Returns:

MS::kSuccess if a valid unit was provided, MS::kFailure otherwise

MStatus MDistance::setValue

(

double

newValue

)

Set the value of this instance

Parameters:

[in]

newValue

the new value in the units currently in effect

Returns:

Always returns MS::kSuccess

double MDistance::as	(	MDistance::Unit	otherUnit,
		MStatus *	ReturnStatus = NULL
	)			const

Return the current value of this instance in the provided units.

Parameters:

[in]	otherUnit	an element of the MDistance::Unit enum specifying the desired units
[out]	ReturnStatus	return status

Returns:

The current value in the given units

Status Codes:

• MS::kSuccess operation successful
• MS::kFailure operation failed

double MDistance::asUnits	(	MDistance::Unit	otherUnit,
		MStatus *	ReturnStatus = NULL
	)			const

Return the current value of this instance in the provided units.

Parameters:

[in]	otherUnit	an element of the MDistance::Unit enum specifying the desired units
[out]	ReturnStatus	return status

Returns:

The current value in the given units

Status Codes:

• MS::kSuccess operation successful
• MS::kFailure operation failed

double MDistance::asInches

(

)

const

Return the current value of this instance in inches.

Returns:

The current value in the inches

double MDistance::asFeet

(

)

const

Return the current value of this instance in feet.

Returns:

The current value in the feet

double MDistance::asYards

(

)

const

Return the current value of this instance in yards.

Returns:

The current value in the yards

double MDistance::asMiles

(

)

const

Return the current value of this instance in miles.

Returns:

The current value in the miles

double MDistance::asMillimeters

(

)

const

Return the current value of this instance in millimeters.

Returns:

The current value in the millimeters

double MDistance::asCentimeters

(

)

const

Return the current value of this instance in centimeters.

Returns:

The current value in the centimeters

Examples:

footPrintManip.cpp, footPrintNode.cpp, and swissArmyManip.cpp.

double MDistance::asKilometers

(

)

const

Return the current value of this instance in kilometers.

Returns:

The current value in the kilometers

double MDistance::asMeters

(

)

const

Return the current value of this instance in meters.

Returns:

The current value in the meters

MDistance::Unit MDistance::uiUnit

(

)

[static]

Returns the Working Units (or UI units) chosen in the settings of the prefs window.

Returns:

An element of the MDistance::Unit enum

Examples:

animFileExport.cpp, animFileUtils.cpp, and objExport.cpp.

MStatus MDistance::setUIUnit

(

MDistance::Unit

newUnit

)

[static]

Set the unit system to be used by the user in the UI.

Parameters:

[in]

newUnit

and element of the MDistance::Unit enum.

Returns:

MS::kSuccess if a valid unit was provided, MS::kFailure otherwise

Examples:

animFileUtils.cpp.

MDistance::Unit MDistance::internalUnit

(

)

[static]

Returns the internal unit system.

Returns:

The internal unit for distance

Examples:

animFileUtils.cpp, and cgfxAttrDef.cpp.

double MDistance::internalToUI

(

double

internalValue

)

[static]

Converts a value from internal units to UI units.

Parameters:

[in]

internalValue

a value in internal units

Returns:

The value in UI units

Examples:

objExport.cpp.

double MDistance::uiToInternal

(

double

uiValue

)

[static]

Converts a value from UI units to internal units.

Parameters:

[in]

uiValue

a value in UI units

Returns:

The value in internal units.

MStatus MDistance::setInternalUnit

(

MDistance::Unit

internalUnit

)

[static]

This method is obsolete.

Deprecated:

Changing the internal units is generally not a good idea and using the method may often produce unexpected results. It is recommended to just read the values and convert them to the units desired.

Set the internal unit system.

Parameters:

[in]

internalUnit

the internal unit to be used by distance

Returns:

Status code

Status Codes:

• MS::kSuccess a valid unit was provided
• MS::kFailure a valid unit was not provided