MMessage Class Reference

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:

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(*	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.
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(* 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 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.

---

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.