MMessage Class Reference
[OpenMaya - API module for common classes]

#include <MMessage.h>

Inheritance diagram for MMessage:

[legend]

List of all members.

---

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.

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)
static MStatus	removeCallbacks (MCallbackIdArray &ids)
static MCallbackId	currentCallbackId (MStatus *ReturnStatus=NULL)
static MStatus	nodeCallbacks (MObject &node, MCallbackIdArray &ids)
static void	setRegisteringCallableScript ()
static bool	registeringCallableScript ()
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. This method is not available in Python.

---

Member Typedef Documentation

typedef void(* MMessage::MBasicFunction)(void *clientData)

Pointer to a basic callback function.

Parameters:

[in]

clientData

Pointer to user-defined data supplied when the callback was registered.

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

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(* MMessage::MCheckFunction)(bool *retCode, void *clientData)

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(* MMessage::MCheckFileFunction)(bool *retCode, MFileObject &file, void *clientData)

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(* MMessage::MCheckPlugFunction)(bool *retCode, MPlug &plug, void *clientData)

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(* MMessage::MComponentFunction)(MUintArray componentIds[], unsigned int count, void *clientData)

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(* MMessage::MNodeFunction)(MObject &node, void *clientData)

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(* MMessage::MStringFunction)(const MString &str, void *clientData)

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(* MMessage::MStringIndexFunction)(const MString &, unsigned int index, void *clientData)

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(* MMessage::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]	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(* MMessage::MStateFunction)(bool state, void *clientData)

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(* MMessage::MTimeFunction)(MTime &time, void *clientData)

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(* MMessage::MPlugFunction)(MPlug &srcPlug, MPlug &destPlug, bool made, void *clientData)

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(* MMessage::MNodePlugFunction)(MObject &node, MPlug &plug, void *clientData)

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(* MMessage::MNodeStringFunction)(MObject &node, const MString &str, void *clientData)

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(* MMessage::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]	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(* MMessage::MModifierFunction)(MDGModifier &modifier, void *clientData)

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(* MMessage::MStringArrayFunction)(const MStringArray &strs, void *clientData)

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(* MMessage::MNodeModifierFunction)(MObject &node, MDGModifier &modifier, void *clientData)

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(* MMessage::MObjArray)(MObjectArray &objects, void *clientData)

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(* MMessage::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]	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(* MMessage::MStringNode)(const MString &str, MObject &node, void *clientData)

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(* MMessage::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]	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(* MMessage::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]	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 MMessage::removeCallback

(

MCallbackId

id

)

[static]

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 MMessage::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]

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 MMessage::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]

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 MMessage::nodeCallbacks	(	MObject &	node,
		MCallbackIdArray &	ids
	)			[static]

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.

void MMessage::setRegisteringCallableScript

(

)

[static]

Mark this MMessage object as one that will be passed callbacks defined in script.

bool MMessage::registeringCallableScript

(

)

[static]

Return true if this MMessage object has its callbacks defined in script.

MStatus MMessage::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]

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 MMessage::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]	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.