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

#include <MObjectHandle.h>

Collaboration diagram for MObjectHandle:

[legend]

List of all members.

---

Detailed Description

Generic Class for validating MObjects.

MObjectHandle is a wrapper class for the MObject class. An MObjectHandle will provide a user with added information on the validity of an MObject. Each MObjectHandle that is created registers an entry into a table to maintain state tracking of the MObject that the handle was created for. This will help users track when an MObject is invalid and should be re-retrieved.

Examples:

cgfxEffectDef.h, and D3DTextureItem.h.

Public Member Functions
	MObjectHandle ()
	MObjectHandle (const MObject &object)
	MObjectHandle (const MObjectHandle &handle)
	~MObjectHandle ()
MObject	object () const
const MObject &	objectRef () const
unsigned int	hashCode () const
bool	isValid () const
bool	isAlive () const
bool	operator== (const MObject &object) const
bool	operator== (const MObjectHandle &object) const
bool	operator!= (const MObject &object) const
bool	operator!= (const MObjectHandle &object) const
MObjectHandle &	operator= (const MObject &object)
MObjectHandle &	operator= (const MObjectHandle &other)

---

Constructor & Destructor Documentation

MObjectHandle::MObjectHandle

(

)

Class Constructor

Creates an empty MObjectHandle

MObjectHandle::MObjectHandle

(

const MObject &

object

)

Class Constructor

Creates an MObjectHandle. Initializes it with an MObject.

MObjectHandle::MObjectHandle

(

const MObjectHandle &

handle

)

Class Copy Constructor

Creates an MObjectHandle. Initializes it with a copy of MObjectHandle.

MObjectHandle::~MObjectHandle

(

)

The class destructor.

---

Member Function Documentation

MObject MObjectHandle::object

(

)

const

Returns the MObject associated with this handle. The returned MObject will be MObject::kNullObj if the object is invalid.

Returns:

MObject associated with this handle.

const MObject & MObjectHandle::objectRef

(

)

const

Returns the MObject associated with this handle. This provides read-only access to the MObject that MObjectHandle holds onto. This method will always return the object that belongs to MObjectHandle regardless of its validity. API users should use caution when using MObject data when it is not valid, and should never use the data when MObjectHandle indicates that the MObject is NOT alive.

Returns:

Read-only MObject associated with this handle.

unsigned int MObjectHandle::hashCode

(

)

const

Returns a hash code for the internal Maya object referenced by the MObject within this MObjectHandle. If the MObject is null or no longer alive then 0 will be returned, otherwise the hash code is guaranteed to be non-zero.

The returned hash code is not unique: several internal Maya objects may return the same code. However different MObjectHandles whose MObjects refer to the same internal Maya object will return the same hash code.

This provides a way for using internal Maya objects as keys in hash-based lookups.

For example, Python dictionaries use a hash lookup, based on the key's __hash__() method. If you try to use MObjectHandles as keys in a dictionary you will find that two different MObjectHandles which refer to the same internal Maya object will not match. This is because Python's default __hash__() method is only looking at the MObjectHandles themselves, not what they contain. So different MObjectHandles can produce different __hash__() values even if they refer to the same internal Maya object.

To get around this you can create a container class or a derived class which defines its own __hash__() method which returns the MObjectHandle's hashCode():

class MyObjHandle(maya.OpenMaya.MObjectHandle):
    def __hash__(self):
        return self.hashCode()

bodyParts = {
    MyObjHandle(leftThumbObj): "hand",
    MyObjHandle(rightThumbObj): "hand",
    MyObjHandle(leftToeObj): "foot",
    MyObjHandle(rightToeObj): "foot",
    ...
}

node = maya.OpenMaya.MObject()
selectionList.getDependNode(0, node)

if bodyParts[MyObjHandle(node)] == "foot":
    ...

An object's hash code is not guaranteed to remain the same from one Maya session to another, nor if it is removed from the scene and subsequently restored in any way, such as deleting a node and then undoing the deletion, reloading the scene file, etc.

Returns:

The hash code.

bool MObjectHandle::isValid

(

)

const

Returns the validity of the associated MObject.

Returns:

true if the MObject is still pointing to a valid internal object, false otherwise.

bool MObjectHandle::isAlive

(

)

const

Returns the live state of the associated MObject. An object can still be 'alive' but not 'valid' (eg. a deleted object that resides in the undo queue).

Returns:

true if the MObject is still pointing to a live internal object, false otherwise.

bool MObjectHandle::operator==

(

const MObject &

obj

)

const

Returns true if the MObjectHandle is a handle for the given MObject.

Parameters:

[in]

obj

MObject to test.

Returns:

true if the MObject is handled by the MObjectHandle, false otherwise.

bool MObjectHandle::operator==

(

const MObjectHandle &

handle

)

const

Returns true if the MObjectHandle handles the same MObject as this MObjectHandle.

Parameters:

[in]

handle

MObjectHandle to test.

Returns:

true if the MObjectHandles are the same, false otherwise.

bool MObjectHandle::operator!=

(

const MObject &

obj

)

const

Returns true if the MObjectHandle is not a handle for the given MObject.

Parameters:

[in]

obj

MObject to test.

Returns:

true if the MObject is not handled by the MObjectHandle, false otherwise.

bool MObjectHandle::operator!=

(

const MObjectHandle &

handle

)

const

Returns true if the MObjectHandle does not handle the same MObject as this MObjectHandle.

Parameters:

[in]

handle

MObjectHandle to test.

Returns:

true MObjectHandles are not the same, false otherwise.

MObjectHandle & MObjectHandle::operator=

(

const MObject &

other

)

Assigns this MObjectHandle to an MObject instance.

Parameters:

[in]

other

MObject to copy.

Returns:

A reference to this MObjectHandle.

MObjectHandle & MObjectHandle::operator=

(

const MObjectHandle &

other

)

Assigns this MObjectHandle to an instance of another MObjectHandle.

Parameters:

[in]

other

MObjectHandle to copy.

Returns:

A reference to this MObjectHandle.