- Main Page
- Related Pages
- Modules
- Namespaces
- Classes
- Examples

- Class List
- Class Hierarchy
- Class Members

Public Member Functions

# MObjectHandle Class Reference
OpenMaya - API module for common classes

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 MObject & | objectRef () 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.
MObjectHandle & | operator= (const MObject &object)
| Assigns this MObjectHandle to an MObject instance.
MObjectHandle & | operator= (const MObjectHandle &other)
| Assigns this MObjectHandle to an instance of another MObjectHandle.

## 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

Search for all occurrences

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

Search for all occurrences

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

Search for all occurrences

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

Search for all occurrences

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

Search for all occurrences

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.

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