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

- Class List
- Class Hierarchy
- Class Members

Public Types | Static Public Member Functions

# MMessage Class Reference
OpenMaya - API module for common classes

Search for all occurrences

## Detailed Description

Message base class.

This is the base class for message callbacks. This base class allows the user to remove a message callback. To register a callback, the user must use the addCallback methods in the message classes which inherit from this base class.

When a callback is added a number or id is returned. This id is used to keep track of the callback and is necessary for removing it. A callback id with the value 'NULL' represents an invalid callback. Use the removeCallback member function of this class for removing a callback.

It is the user's responsibility to keep track of the callback id's and remove all callbacks for a plug-in when it is unloaded.

Callbacks During File Read

Care must be taken when a callback executes while Maya is reading a scene file as the scene may be temporarily in an inconsistent state, which could give incorrect results.

For example, consider a scene which has two nodes, X and Y, with a connection from X.out to Y.in. A "node added" message (see MDGMessage::addNodeAddedCallback) will be sent out for Y as soon as it is added to the scene, but before the connection has been made to Y.in. If a callback were to read the value of Y.in at this point it would get the wrong result.

The difficulties are compounded by the fact that Maya's normal Dependency Graph evaluation and dirty propagation mechanisms are disabled during a file read. In our example above, retrieving the value of Y.in will mark the plug as clean. When the connection is from X.out is subsequently made, Y.in won't be marked dirty because dirty propagation is disabled. As a result, when the file read has completed and Maya draws the new scene, Y.in will not be re-evaluated which may produce an error in the draw.

For these reasons, callbacks should avoid querying or modifying the DG in any way during file read. They should not add or remove nodes, make or break connections, change parenting, set or retrieve plug values, etc. Even something as innocuous as a call to MFnDagNode::isIntermediateObject may cause problems since it queries the value of the node's intermediateObject plug. All such actions should be postponed until the file read has completed.

`#include <MMessage.h>`

Inheritance diagram for MMessage:
[legend]

List of all members.

## Public Types
typedef void(* | MBasicFunction )(void *clientData)
| Pointer to a basic callback function.
typedef void(* | MElapsedTimeFunction )(float elapsedTime, float lastTime, void *clientData)
| Pointer to an elapsed time callback function.
typedef void(* | MCheckFunction )(bool *retCode, void *clientData)
| Pointer to callback function which returns a true/false result.
typedef void(* | MCheckFileFunction )(bool *retCode, MFileObject &file, void *clientData)
| Pointer to a callback function which takes a file object and returns a result.
typedef void(* | MCheckPlugFunction )(bool *retCode, MPlug &plug, void *clientData)
| Pointer to a callback function which takes a plug and returns a result.
typedef void(* | MComponentFunction )(MUintArray componentIds[], unsigned int count, void *clientData)
| Pointer to a callback function which takes an array of component ids.
typedef void(* | MNodeFunction )(MObject &node, void *clientData)
| Pointer to a callback function which takes a dependency node.
typedef void(* | MStringFunction )(const MString &str, void *clientData)
| Pointer to callback function which takes a string.
typedef void(* | MStringIntBoolIntFunction )(const MString &str, unsigned int index, bool flag, unsigned int type, void *clientData)
| Pointer to callback function which takes a string, an index, a flag and a type.
typedef void(* | MStringIndexFunction )(const MString &, unsigned int index, void *clientData)
| Pointer to callback function which takes a string and index.
typedef void(* | MNodeStringBoolFunction )(MObject &node, const MString &, bool, void *clientData)
| Pointer to a callback function which takes a node, a string and a boolean.
typedef void(* | MStateFunction )(bool state, void *clientData)
| Pointer to a callback function which takes a boolean state.
typedef void(* | MTimeFunction )(MTime &time, void *clientData)
| Pointer to callback function which takes a time.
typedef void(* | MPlugFunction )(MPlug &srcPlug, MPlug &destPlug, bool made, void *clientData)
| Pointer to plug connection callback function.
typedef void(* | MNodePlugFunction )(MObject &node, MPlug &plug, void *clientData)
| Pointer to a callback function which takes a dependency node and a plug.
typedef void(* | MNodeStringFunction )(MObject &node, const MString &str, void *clientData)
| Pointer to a callback function which takes a dependency node and a string.
typedef void(* | MParentChildFunction )(MDagPath &child, MDagPath &parent, void *clientData)
| Pointer to to a callback function which takes two DAG nodes in a parent/child relationship.
typedef void(* | MModifierFunction )(MDGModifier &modifier, void *clientData)
| Pointer to a callback function which takes a DG modifier.
typedef void(* | MStringArrayFunction )(const MStringArray &strs, void *clientData)
| Pointer to a callback function which takes a string array.
typedef void(* | MNodeModifierFunction )(MObject &node, MDGModifier &modifier, void *clientData)
| Pointer to a callback function which takes a dependency node and a DG modifier.
typedef void(* | MObjArray )(MObjectArray &objects, void *clientData)
| Pointer to a callback function which takes an array of objects.
typedef void(* | MNodeObjArray )(MObject &node, MObjectArray &objects, void *clientData)
| Pointer to a callback function which takes a dependency node and an array of objects.
typedef void(* | MStringNode )(const MString &str, MObject &node, void *clientData)
| Pointer to a callback function which takes a string and a dependency node.
typedef void(* | MCameraLayerFunction )(MObject &cameraSetNode, unsigned int multiIndex, bool added, void *clientData)
| Pointer to a callback function which takes a dependency node, an unsigned integer, and a boolean value.
typedef void(* | MCameraLayerCameraFunction )(MObject &cameraSetNode, unsigned int multiIndex, MObject &oldCamera, MObject &newCamera, void *clientData)
| Pointer to a callback function which takes a dependency node, an unsigned integer, and two camera transform nodes.
typedef void(* | MConnFailFunction )(MPlug &srcPlug, MPlug &destPlug, const MString &srcPlugName, const MString &dstPlugName, void *clientData)
| Pointer to connection-failed callback function.
typedef void(* | MPlugsDGModFunction )(MPlugArray &plugs, MDGModifier &modifier, void *clientData)
| Pointer to a callback function which takes an array of MPlugs and an MDGModifier.
## Static Public Member Functions
static MStatus | removeCallback (MCallbackId id)
| Remove the specified callback from maya.
static MStatus | removeCallbacks (MCallbackIdArray &ids)
| Remove all of the specified callbacks from maya.
static MCallbackId | currentCallbackId (MStatus *ReturnStatus=NULL)
| Return the callback ID of the currently executing callback.
static MStatus | nodeCallbacks (MObject &node, MCallbackIdArray &ids)
| Returns a list of callback IDs associated registered to a given node.
static void | setRegisteringCallableScript ()
| Mark this MMessage object as one that will be passed callbacks defined in script. Search for all occurrences
static bool | registeringCallableScript ()
| Return true if this MMessage object has its callbacks defined in script.
static const char * | className ()
| Returns the name of this class.
static MStatus | removeCallbacks (MIntArray &ids)
| This method is obsolete. This method is not available in Python.
static MStatus | nodeCallbacks (MObject &node, MIntArray &ids)
| This method is obsolete. Search for all occurrences

## Member Typedef Documentation

typedef void(* MBasicFunction)(void *clientData)

Search for all occurrences

Pointer to a basic callback function.

Parameters:

  [in] | clientData | Pointer to user-defined data supplied when the callback was registered.

typedef void(* MElapsedTimeFunction)(float elapsedTime, float lastTime, void *clientData)

Search for all occurrences

Pointer to an elapsed time callback function.

Parameters:

  [in] | elapsedTime | The amount of time since the callback was last called.
  [in] | lastTime | The execution time at the previous call to this callback.
  [in] | clientData | Pointer to user-defined data supplied when the callback was registered.

typedef void(* MCheckFunction)(bool *retCode, void *clientData)

Search for all occurrences

Pointer to callback function which returns a true/false result.

Parameters:

  [in] | retCode | Result of the function. The meaning depends upon the specific message type for which the callback was registered.
  [in] | clientData | Pointer to user-defined data supplied when the callback was registered.

typedef void(* MCheckFileFunction)(bool *retCode, MFileObject &file, void *clientData)

Search for all occurrences

Pointer to a callback function which takes a file object and returns a result.

Parameters:

  [in] | retCode | Result of the function. The meaning depends upon the specific message type for which the callback was registered.
  [in,out] | file | File object. The meaning depends upon the specific message type for which the callback was registered.
  [in] | clientData | Pointer to user-defined data supplied when the callback was registered.

typedef void(* MCheckPlugFunction)(bool *retCode, MPlug &plug, void *clientData)

Search for all occurrences

Pointer to a callback function which takes a plug and returns a result.

Parameters:

  [in] | retCode | Result of the function. The meaning depends upon the specific message type for which the callback was registered.
  [in,out] | plug | The meaning depends upon the specific message type for which the callback was registered.
  [in] | clientData | Pointer to user-defined data supplied when the callback was registered.

typedef void(* MComponentFunction)(MUintArray componentIds[], unsigned int count, void *clientData)

Search for all occurrences

Pointer to a callback function which takes an array of component ids.

Parameters:

  [in] | componentIds | Array of component ids.
  [in] | count | Number of component ids in the array.
  [in] | clientData | Pointer to user-defined data supplied when the callback was registered.

typedef void(* MNodeFunction)(MObject &node, void *clientData)

Search for all occurrences

Pointer to a callback function which takes a dependency node.

Parameters:

  [in,out] | node | The meaning depends upon the specific message type for which the callback was registered.
  [in] | clientData | Pointer to user-defined data supplied when the callback was registered.

typedef void(* MStringFunction)(const MString &str, void *clientData)

Search for all occurrences

Pointer to callback function which takes a string.

Parameters:

  [in] | str | The meaning depends upon the specific message type for which the callback was registered.
  [in] | clientData | Pointer to user-defined data supplied when the callback was registered.

Reimplemented in MUiMessage.

typedef void(* MStringIntBoolIntFunction)(const MString &str, unsigned int index, bool flag, unsigned int type, void *clientData)

Search for all occurrences

Pointer to callback function which takes a string, an index, a flag and a type.

Parameters:

  [in] | str | The meaning depends upon the specific message type for which the callback was registered.
  [in] | index | The meaning depends upon the specific message type for which the callback was registered.
  [in] | flag | The meaning depends upon the specific message type for which the callback was registered.
  [in] | type | The meaning depends upon the specific message type for which the callback was registered.
  [in] | clientData | Pointer to user-defined data supplied when the callback was registered.

typedef void(* MStringIndexFunction)(const MString &, unsigned int index, void *clientData)

Search for all occurrences

Pointer to callback function which takes a string and index.

Parameters:

  [in] | str | The meaning depends upon the specific message type for which the callback was registered.
  [in] | index | The meaning depends upon the specific message type for which the callback was registered.
  [in] | clientData | Pointer to user-defined data supplied when the callback was registered.

typedef void(* MNodeStringBoolFunction)(MObject &node, const MString &, bool, void *clientData)

Search for all occurrences

Pointer to a callback function which takes a node, a string and a boolean.

Parameters:

  [in,out] | node | The meaning depends upon the specific message type for which the callback was registered.
  [in] | str | The meaning depends upon the specific message type for which the callback was registered.
  [in] | clientData | Pointer to user-defined data supplied when the callback was registered.

typedef void(* MStateFunction)(bool state, void *clientData)

Search for all occurrences

Pointer to a callback function which takes a boolean state.

Parameters:

  [in] | state | The meaning depends upon the specific message type for which the callback was registered.
  [in] | clientData | Pointer to user-defined data supplied when the callback was registered.

typedef void(* MTimeFunction)(MTime &time, void *clientData)

Search for all occurrences

Pointer to callback function which takes a time.

Parameters:

  [in,out] | time | The meaning depends upon the specific message type for which the callback was registered.
  [in] | clientData | Pointer to user-defined data supplied when the callback was registered.

typedef void(* MPlugFunction)(MPlug &srcPlug, MPlug &destPlug, bool made, void *clientData)

Search for all occurrences

Pointer to plug connection callback function.

Parameters:

  [in,out] | srcPlug | Plug which is the source of the connection.
  [in,out] | destPlug | Plug which is the destination of the connection.
  [in] | made | True if the connection is being made, false if the connection is being broken.
  [in] | clientData | Pointer to user-defined data supplied when the callback was registered.

typedef void(* MNodePlugFunction)(MObject &node, MPlug &plug, void *clientData)

Search for all occurrences

Pointer to a callback function which takes a dependency node and a plug.

Parameters:

  [in,out] | node | The meaning depends upon the specific message type for which the callback was registered.
  [in,out] | plug | The meaning depends upon the specific message type for which the callback was registered.
  [in] | clientData | Pointer to user-defined data supplied when the callback was registered.

typedef void(* MNodeStringFunction)(MObject &node, const MString &str, void *clientData)

Search for all occurrences

Pointer to a callback function which takes a dependency node and a string.

Parameters:

  [in,out] | node | The meaning depends upon the specific message type for which the callback was registered.
  [in] | str | The meaning depends upon the specific message type for which the callback was registered.
  [in] | clientData | Pointer to user-defined data supplied when the callback was registered.

typedef void(* MParentChildFunction)(MDagPath &child, MDagPath &parent, void *clientData)

Search for all occurrences

Pointer to to a callback function which takes two DAG nodes in a parent/child relationship.

Parameters:

  [in,out] | child | Path to the child node.
  [in,out] | parent | Path to the parent node.
  [in] | clientData | Pointer to user-defined data supplied when the callback was registered.

typedef void(* MModifierFunction)(MDGModifier &modifier, void *clientData)

Search for all occurrences

Pointer to a callback function which takes a DG modifier.

Parameters:

  [in,out] | modifier | The meaning depends upon the specific message type for which the callback was registered.
  [in] | clientData | Pointer to user-defined data supplied when the callback was registered.

typedef void(* MStringArrayFunction)(const MStringArray &strs, void *clientData)

Search for all occurrences

Pointer to a callback function which takes a string array.

Parameters:

  [in] | strs | The meaning depends upon the specific message type for which the callback was registered.
  [in] | clientData | Pointer to user-defined data supplied when the callback was registered.

typedef void(* MNodeModifierFunction)(MObject &node, MDGModifier &modifier, void *clientData)

Search for all occurrences

Pointer to a callback function which takes a dependency node and a DG modifier.

Parameters:

  [in,out] | node | The meaning depends upon the specific message type for which the callback was registered.
  [in,out] | modifier | The meaning depends upon the specific message type for which the callback was registered.
  [in] | clientData | Pointer to user-defined data supplied when the callback was registered.

typedef void(* MObjArray)(MObjectArray &objects, void *clientData)

Search for all occurrences

Pointer to a callback function which takes an array of objects.

Parameters:

  [in,out] | objects | The meaning depends upon the specific message type for which the callback was registered.
  [in] | clientData | Pointer to user-defined data supplied when the callback was registered.

typedef void(* MNodeObjArray)(MObject &node, MObjectArray &objects, void *clientData)

Search for all occurrences

Pointer to a callback function which takes a dependency node and an array of objects.

Parameters:

  [in,out] | node | The meaning depends upon the specific message type for which the callback was registered.
  [in,out] | objects | The meaning depends upon the specific message type for which the callback was registered.
  [in] | clientData | Pointer to user-defined data supplied when the callback was registered.

typedef void(* MStringNode)(const MString &str, MObject &node, void *clientData)

Search for all occurrences

Pointer to a callback function which takes a string and a dependency node.

Parameters:

  [in] | str | The meaning depends upon the specific message type for which the callback was registered.
  [in,out] | node | The meaning depends upon the specific message type for which the callback was registered.
  [in] | clientData | Pointer to user-defined data supplied when the callback was registered.

typedef void(* MCameraLayerFunction)(MObject &cameraSetNode, unsigned int multiIndex, bool added, void *clientData)

Search for all occurrences

Pointer to a callback function which takes a dependency node, an unsigned integer, and a boolean value.

Parameters:

  [in] | node | The node should be a cameraSet node.
  [in] | unsigned | int The integer refers to a camera layer index in the given cameraSet node.
  [in] | bool | The value denotes whether the given camera layer has been added or removed. A value of true means the layer was added.
  [in] | clientData | Pointer to user-defined data supplied when the callback was registered.

typedef void(* MCameraLayerCameraFunction)(MObject &cameraSetNode, unsigned int multiIndex, MObject &oldCamera, MObject &newCamera, void *clientData)

Search for all occurrences

Pointer to a callback function which takes a dependency node, an unsigned integer, and two camera transform nodes.

Parameters:

  [in] | node | The node should be a cameraSet node.
  [in] | unsigned | int The integer refers to a camera layer index in the given cameraSet node.
  [in] | node | The node should be a camera transform previously assigned to the given camera layer.
  [in] | node | The node should be a camera transform newly assigned to the given camera layer.
  [in] | clientData | Pointer to user-defined data supplied when the callback was registered.

typedef void(* MConnFailFunction)(MPlug &srcPlug, MPlug &destPlug, const MString &srcPlugName, const MString &dstPlugName, void *clientData)

Search for all occurrences

Pointer to connection-failed callback function.

Parameters:

  [in,out] | srcPlug | Plug which was to be the source of the connection, or a null plug if the plug did not exist.
  [in,out] | destPlug | Plug which was to be the destination of the connection, or a null plug if the plug did not exist.
  [in] | srcPlugName | The plug name which was used to look up the source plug.
  [in] | dstPlugName | The plug name which was used to look up the destination plug.
  [in] | clientData | Pointer to user-defined data supplied when the callback was registered.

typedef void(* MPlugsDGModFunction)(MPlugArray &plugs, MDGModifier &modifier, void *clientData)

Search for all occurrences

Pointer to a callback function which takes an array of MPlugs and an MDGModifier.

Parameters:

  [in,out] | plugs | The meaning depends upon the specific message type for which the callback was registered.
  [in,out] | modifier | The meaning depends upon the specific message type for which the callback was registered.
  [in] | clientData | Pointer to user-defined data supplied when the callback was registered.

## Member Function Documentation

MStatus removeCallback | ( | MCallbackId | id | ) | `[static]`

Search for all occurrences

Remove the specified callback from maya.

This method must be called for all callbacks registered by a plug-in before that plug-in is unloaded.

Parameters:

  [in] | id | identifier of callback to be removed

Returns:
  Status code

Status Codes:
  - MS::kSuccess The callback was successfully removed.
  - MS::kInvalidParameter An invalid callback id was specfied.
  - MS::kFailure Callback has already been removed.

Examples:
  AshliPluginMain.cpp, cgfxAttrDef.cpp, componentScaleManip.cpp, conditionTest.cpp, customAttrManip.cpp, D3DResourceManager.cpp, D3DViewportRendererPlugin.cpp, dagMessageCmd.cpp, eventTest.cpp, hlslShader.cpp, hwAnisotropicShader_NV20.cpp, hwDecalBumpShader_NV20.cpp, hwPhongShader.cpp, hwReflectBumpShader_NV20.cpp, hwRefractReflectShader_NV20.cpp, hwToonShader_NV20.cpp, hwUnlitShader.cpp, lockEvent.cpp, moveManip.cpp, nodeCreatedCBCmd.cpp, nodeMessageCmd.cpp, NodeMonitor.cpp, pluginCallbacks.cpp, polyMessageCmd.cpp, rotateManip.cpp, ShapeMonitor.cpp, surfaceBumpManip.cpp, and viewCallbackTest.cpp.

MStatus removeCallbacks | ( | MCallbackIdArray & | idList | ) | `[static]`

Search for all occurrences

Remove all of the specified callbacks from maya.

This method must be called for all callbacks registered by a plug-in before that plug-in is unloaded.

Parameters:

  [in] | idList | identifier list of callbacks to be removed

Returns:
  Status code

Status Codes:
  - MS::kSuccess The callback was successfully removed.
  - MS::kInvalidParameter An invalid callback id was specfied.
  - MS::kFailure Callback has already been removed.

Examples:
  cgfxShaderNode.cpp, deletedMsgCmd.cpp, fileIOMsgCmd.cpp, pluginMain.cpp, and undoRedoMsgCmd.cpp.

MCallbackId currentCallbackId | ( | MStatus * | ReturnStatus = `NULL` | ) | `[static]`

Search for all occurrences

Return the callback ID of the currently executing callback.

If called outside of a callback, an invalid MCallbackId and failed status will be returned.

Parameters:

  [in] | ReturnStatus | Status code

Returns:
  Callback ID of currently executing callback

Status Codes:
  - MS::kSuccess The callbackId was successfully retrieved.
  - MS::kFailure This method was executed outside of a user callback.

Examples:
  dagMessageCmd.cpp.

MStatus nodeCallbacks | ( | MObject & | node,
|  | MCallbackIdArray & | ids
| ) |  | `[static]`

Search for all occurrences

Returns a list of callback IDs associated registered to a given node.

Parameters:

  [in] | node | Node to query for callbacks.
  [out] | ids | MCallbackId array to store the list of callback IDs.

Returns:
  Status Code

Status Codes:
  - MS::kSuccess The callback query was successful.
  - MS::kFailure The given node was invalid.

const char * className | ( |  | ) | `[static]`

Search for all occurrences

Returns the name of this class.

Returns:
  The name of this class.

Reimplemented in MAnimMessage, MCameraSetMessage, MCommandMessage, MConditionMessage, MContainerMessage, MDagMessage, MEventMessage, MLockMessage, MModelMessage, MNodeMessage, MObjectSetMessage, MPolyMessage, MSceneMessage, MTimerMessage, MUiMessage, and MUserEventMessage.

MStatus removeCallbacks | ( | MIntArray & | idList | ) | `[static]`

Search for all occurrences

This method is obsolete. This method is not available in Python.

Deprecated:
  Please use the other MMessage::removeCallbacks method.

Remove all of the specified callbacks from maya.

This method must be called for all callbacks registered by a plug-in before that plug-in is unloaded.

Parameters:

  [in] | idList | identifier of callback to be removed

Returns:
  Status code

Status Codes:
  - MS::kSuccess The callback was successfully removed.
  - MS::kInvalidParameter An invalid callback id was specfied.
  - MS::kFailure Callback has already been removed.

MStatus nodeCallbacks | ( | MObject & | node,
|  | MIntArray & | ids
| ) |  | `[static]`

Search for all occurrences

This method is obsolete.

This method is not available in Python.

Deprecated:
  Please use the other MMessage::nodeCallbacks method.

Returns a list of callback IDs associated registered to a given node.

Parameters:

  [in] | node | Node to query for callbacks.
  [out] | ids | Integer array to store the list of callback IDs.

Returns:
  Status Code

Status Codes:
  - MS::kSuccess The callback query was successful.
  - MS::kFailure The given node was invalid.

MMessage MMessage MMessage MMessage MMessage MMessage MMessage MMessage MMessage MMessage
MMessage MMessage MMessage MMessage MMessage MMessage MMessage MMessage MMessage MMessage