MObjectHandle Class Reference

#include <MObjectHandle.h>

Class 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:

Public Member Functions
	MObjectHandle ()
	Class Constructor. More...
	MObjectHandle (const MObject &object)
	Class Constructor. More...
	MObjectHandle (const MObjectHandle &handle)
	Class Copy Constructor. More...
	~MObjectHandle ()
	The class destructor.
MObject	object () const
	Returns the MObject associated with this handle. More...
const MObject &	objectRef () const
	Returns the MObject associated with this handle. More...
unsigned int	hashCode () const
	Returns a hash code for the internal Maya object referenced by the MObject within this MObjectHandle. More...
bool	isValid () const
	Returns the validity of the associated MObject. More...
bool	isAlive () const
	Returns the live state of the associated MObject. More...
bool	operator== (const MObject &object) const
	Returns true if the MObjectHandle is a handle for the given MObject. More...
bool	operator== (const MObjectHandle &object) const
	Returns true if the MObjectHandle handles the same MObject as this MObjectHandle. More...
bool	operator!= (const MObject &object) const
	Returns true if the MObjectHandle is not a handle for the given MObject. More...
bool	operator!= (const MObjectHandle &object) const
	Returns true if the MObjectHandle does not handle the same MObject as this MObjectHandle. More...
MObjectHandle &	operator= (const MObject &object)
	Assigns this MObjectHandle to an MObject instance. More...
MObjectHandle &	operator= (const MObjectHandle &other)
	Assigns this MObjectHandle to an instance of another MObjectHandle. More...

Static Public Member Functions
static unsigned int	objectHashCode (const MObject &)
	Returns a hash code for the provided MObject. More...

Constructor & Destructor Documentation

MObjectHandle

(

)

Class Constructor.

Creates an empty MObjectHandle

MObjectHandle

(

const MObject &

object

)

Class Constructor.

Creates an MObjectHandle. Initializes it with an MObject. The object must be alive at the time of the call otherwise the subsequent state of the MObjectHandle will be incorrect.

Parameters

[in]

object

MObject to be tracked by the handle.

MObjectHandle

(

const MObjectHandle &

handle

)

Class Copy Constructor.

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

Parameters

[in]

handle

MObjectHandle to copy.

Member Function Documentation

MObject 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 & 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 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 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 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 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 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 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 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 & operator=

(

const MObject &

other

)

Assigns this MObjectHandle to an MObject instance.

The MObject must be alive at the time of assignment, otherwise the subsequent state of the handle will be incorrect.

Parameters

[in]

other

MObject to copy.

Returns

A reference to this 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.

unsigned int objectHashCode ( const MObject &  obj )

static

Returns a hash code for the provided MObject.

The user is responsible for the validity of the provided MObject when using this method.

The returned hash code may not be 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.

Note: The construction and destruction of MObjectHandle is not thread safe. If your plug-in requires threading, you should use MObjectHandle::objectHashCode() instead.

Parameters

[in]

obj

MObject whose hash code is requested.

Returns

The hash code.

Examples:

---

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

• MObjectHandle.h
• MObjectHandle.cpp