Public Types | Static Public Member Functions

MMessage Class Reference

This reference page is linked to from the following overview topics: Differences between the Maya .NET API and the Maya C++ API, Appendix D: Frequently asked questions.


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:
Inheritance graph
[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.
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.

Member Typedef Documentation

typedef void(* MBasicFunction)(void *clientData)

Pointer to a basic callback function.

Parameters:
[in]clientDataPointer to user-defined data supplied when the callback was registered.
typedef void(* MElapsedTimeFunction)(float elapsedTime, float lastTime, void *clientData)

Pointer to an elapsed time callback function.

Parameters:
[in]elapsedTimeThe amount of time since the callback was last called.
[in]lastTimeThe execution time at the previous call to this callback.
[in]clientDataPointer to user-defined data supplied when the callback was registered.
typedef void(* MCheckFunction)(bool *retCode, void *clientData)

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

Parameters:
[in]retCodeResult of the function. The meaning depends upon the specific message type for which the callback was registered.
[in]clientDataPointer to user-defined data supplied when the callback was registered.
typedef void(* MCheckFileFunction)(bool *retCode, MFileObject &file, void *clientData)

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

Parameters:
[in]retCodeResult of the function. The meaning depends upon the specific message type for which the callback was registered.
[in,out]fileFile object. The meaning depends upon the specific message type for which the callback was registered.
[in]clientDataPointer to user-defined data supplied when the callback was registered.
typedef void(* MCheckPlugFunction)(bool *retCode, MPlug &plug, void *clientData)

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

Parameters:
[in]retCodeResult of the function. The meaning depends upon the specific message type for which the callback was registered.
[in,out]plugThe meaning depends upon the specific message type for which the callback was registered.
[in]clientDataPointer to user-defined data supplied when the callback was registered.
typedef void(* MComponentFunction)(MUintArray componentIds[], unsigned int count, void *clientData)

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

Parameters:
[in]componentIdsArray of component ids.
[in]countNumber of component ids in the array.
[in]clientDataPointer to user-defined data supplied when the callback was registered.
typedef void(* MNodeFunction)(MObject &node, void *clientData)

Pointer to a callback function which takes a dependency node.

Parameters:
[in,out]nodeThe meaning depends upon the specific message type for which the callback was registered.
[in]clientDataPointer to user-defined data supplied when the callback was registered.
typedef void(* MStringFunction)(const MString &str, void *clientData)

Pointer to callback function which takes a string.

Parameters:
[in]strThe meaning depends upon the specific message type for which the callback was registered.
[in]clientDataPointer 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)

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

Parameters:
[in]strThe meaning depends upon the specific message type for which the callback was registered.
[in]indexThe meaning depends upon the specific message type for which the callback was registered.
[in]flagThe meaning depends upon the specific message type for which the callback was registered.
[in]typeThe meaning depends upon the specific message type for which the callback was registered.
[in]clientDataPointer to user-defined data supplied when the callback was registered.
typedef void(* MStringIndexFunction)(const MString &, unsigned int index, void *clientData)

Pointer to callback function which takes a string and index.

Parameters:
[in]strThe meaning depends upon the specific message type for which the callback was registered.
[in]indexThe meaning depends upon the specific message type for which the callback was registered.
[in]clientDataPointer to user-defined data supplied when the callback was registered.
typedef void(* MNodeStringBoolFunction)(MObject &node, const MString &, bool, void *clientData)

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

Parameters:
[in,out]nodeThe meaning depends upon the specific message type for which the callback was registered.
[in]strThe meaning depends upon the specific message type for which the callback was registered.
[in]clientDataPointer to user-defined data supplied when the callback was registered.
typedef void(* MStateFunction)(bool state, void *clientData)

Pointer to a callback function which takes a boolean state.

Parameters:
[in]stateThe meaning depends upon the specific message type for which the callback was registered.
[in]clientDataPointer to user-defined data supplied when the callback was registered.
typedef void(* MTimeFunction)(MTime &time, void *clientData)

Pointer to callback function which takes a time.

Parameters:
[in,out]timeThe meaning depends upon the specific message type for which the callback was registered.
[in]clientDataPointer to user-defined data supplied when the callback was registered.
typedef void(* MPlugFunction)(MPlug &srcPlug, MPlug &destPlug, bool made, void *clientData)

Pointer to plug connection callback function.

Parameters:
[in,out]srcPlugPlug which is the source of the connection.
[in,out]destPlugPlug which is the destination of the connection.
[in]madeTrue if the connection is being made, false if the connection is being broken.
[in]clientDataPointer to user-defined data supplied when the callback was registered.
typedef void(* MNodePlugFunction)(MObject &node, MPlug &plug, void *clientData)

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

Parameters:
[in,out]nodeThe meaning depends upon the specific message type for which the callback was registered.
[in,out]plugThe meaning depends upon the specific message type for which the callback was registered.
[in]clientDataPointer to user-defined data supplied when the callback was registered.
typedef void(* MNodeStringFunction)(MObject &node, const MString &str, void *clientData)

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

Parameters:
[in,out]nodeThe meaning depends upon the specific message type for which the callback was registered.
[in]strThe meaning depends upon the specific message type for which the callback was registered.
[in]clientDataPointer to user-defined data supplied when the callback was registered.
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.

Parameters:
[in,out]childPath to the child node.
[in,out]parentPath to the parent node.
[in]clientDataPointer to user-defined data supplied when the callback was registered.
typedef void(* MModifierFunction)(MDGModifier &modifier, void *clientData)

Pointer to a callback function which takes a DG modifier.

Parameters:
[in,out]modifierThe meaning depends upon the specific message type for which the callback was registered.
[in]clientDataPointer to user-defined data supplied when the callback was registered.
typedef void(* MStringArrayFunction)(const MStringArray &strs, void *clientData)

Pointer to a callback function which takes a string array.

Parameters:
[in]strsThe meaning depends upon the specific message type for which the callback was registered.
[in]clientDataPointer to user-defined data supplied when the callback was registered.
typedef void(* MNodeModifierFunction)(MObject &node, MDGModifier &modifier, void *clientData)

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

Parameters:
[in,out]nodeThe meaning depends upon the specific message type for which the callback was registered.
[in,out]modifierThe meaning depends upon the specific message type for which the callback was registered.
[in]clientDataPointer to user-defined data supplied when the callback was registered.
typedef void(* MObjArray)(MObjectArray &objects, void *clientData)

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

Parameters:
[in,out]objectsThe meaning depends upon the specific message type for which the callback was registered.
[in]clientDataPointer to user-defined data supplied when the callback was registered.
typedef void(* MNodeObjArray)(MObject &node, MObjectArray &objects, void *clientData)

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

Parameters:
[in,out]nodeThe meaning depends upon the specific message type for which the callback was registered.
[in,out]objectsThe meaning depends upon the specific message type for which the callback was registered.
[in]clientDataPointer to user-defined data supplied when the callback was registered.
typedef void(* MStringNode)(const MString &str, MObject &node, void *clientData)

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

Parameters:
[in]strThe meaning depends upon the specific message type for which the callback was registered.
[in,out]nodeThe meaning depends upon the specific message type for which the callback was registered.
[in]clientDataPointer to user-defined data supplied when the callback was registered.
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.

Parameters:
[in]nodeThe node should be a cameraSet node.
[in]unsignedint The integer refers to a camera layer index in the given cameraSet node.
[in]boolThe value denotes whether the given camera layer has been added or removed. A value of true means the layer was added.
[in]clientDataPointer to user-defined data supplied when the callback was registered.
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.

Parameters:
[in]nodeThe node should be a cameraSet node.
[in]unsignedint The integer refers to a camera layer index in the given cameraSet node.
[in]nodeThe node should be a camera transform previously assigned to the given camera layer.
[in]nodeThe node should be a camera transform newly assigned to the given camera layer.
[in]clientDataPointer 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)

Pointer to connection-failed callback function.

Parameters:
[in,out]srcPlugPlug which was to be the source of the connection, or a null plug if the plug did not exist.
[in,out]destPlugPlug which was to be the destination of the connection, or a null plug if the plug did not exist.
[in]srcPlugNameThe plug name which was used to look up the source plug.
[in]dstPlugNameThe plug name which was used to look up the destination plug.
[in]clientDataPointer to user-defined data supplied when the callback was registered.
typedef void(* MPlugsDGModFunction)(MPlugArray &plugs, MDGModifier &modifier, void *clientData)

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

Parameters:
[in,out]plugsThe meaning depends upon the specific message type for which the callback was registered.
[in,out]modifierThe meaning depends upon the specific message type for which the callback was registered.
[in]clientDataPointer to user-defined data supplied when the callback was registered.

Member Function Documentation

MStatus removeCallback ( MCallbackId  id) [static]
MStatus removeCallbacks ( MCallbackIdArray idList) [static]

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]idListidentifier list of callbacks to be removed
Returns:
Status code
Status Codes:
Examples:
cgfxShaderNode.cpp, deletedMsgCmd.cpp, fileIOMsgCmd.cpp, pluginMain.cpp, and undoRedoMsgCmd.cpp.
MCallbackId currentCallbackId ( MStatus ReturnStatus = NULL) [static]

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]ReturnStatusStatus 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]

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

Parameters:
[in]nodeNode to query for callbacks.
[out]idsMCallbackId array to store the list of callback IDs.
Returns:
Status Code
Status Codes:
const char * className ( ) [static]
MStatus removeCallbacks ( MIntArray idList) [static]

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]idListidentifier of callback to be removed
Returns:
Status code
Status Codes:
MStatus nodeCallbacks ( MObject node,
MIntArray ids 
) [static]

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]nodeNode to query for callbacks.
[out]idsInteger array to store the list of callback IDs.
Returns:
Status Code
Status Codes:

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