Public Member Functions

MObjectHandle Class Reference

This reference page is linked to from the following overview topics: MObject.


Search for all occurrences

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.

#include <MObjectHandle.h>

List of all members.

Public Member Functions

 MObjectHandle ()
 Class Constructor.
 MObjectHandle (const MObject &object)
 Class Constructor.
 MObjectHandle (const MObjectHandle &handle)
 Class Copy Constructor.
 ~MObjectHandle ()
 The class destructor.
MObject object () const
 Returns the MObject associated with this handle.
const MObjectobjectRef () const
 Returns the 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.
bool isValid () const
 Returns the validity of the associated MObject.
bool isAlive () const
 Returns the live state of the associated MObject.
bool operator== (const MObject &object) const
 Returns true if the MObjectHandle is a handle for the given MObject.
bool operator== (const MObjectHandle &object) const
 Returns true if the MObjectHandle handles the same MObject as this MObjectHandle.
bool operator!= (const MObject &object) const
 Returns true if the MObjectHandle is not a handle for the given MObject.
bool operator!= (const MObjectHandle &object) const
 Returns true if the MObjectHandle does not handle the same MObject as this MObjectHandle.
MObjectHandleoperator= (const MObject &object)
 Assigns this MObjectHandle to an MObject instance.
MObjectHandleoperator= (const MObjectHandle &other)
 Assigns this MObjectHandle to an instance of another MObjectHandle.

Constructor & Destructor Documentation

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]objectMObject 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]handleMObjectHandle 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]objMObject 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]handleMObjectHandle 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]objMObject 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]handleMObjectHandle 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]otherMObject to copy.
Returns:
A reference to this MObjectHandle.
MObjectHandle & operator= ( const MObjectHandle other)

Assigns this MObjectHandle to an instance of another MObjectHandle.

Parameters:
[in]otherMObjectHandle to copy.
Returns:
A reference to this MObjectHandle.

MObjectHandle MObjectHandle MObjectHandle MObjectHandle MObjectHandle MObjectHandle MObjectHandle MObjectHandle MObjectHandle MObjectHandle
MObjectHandle MObjectHandle MObjectHandle MObjectHandle MObjectHandle MObjectHandle MObjectHandle MObjectHandle MObjectHandle MObjectHandle