#include <MCommandMessage.h>

Class Description

Helper class to handle MEL output.

This class is used to register for a callback for when certain MEL command related messages are generated.

The add callback method returns an id which is used to remove the callback.

To remove a callback use MMessage::removeCallback.

All callbacks that are registered by a plug-in must be removed by that plug-in when it is unloaded. Failure to do so will result in a fatal error.

Note: Setting up a callback using the addCommandCallback() method may degrade the performance of Maya since the installed callback will be invoked repeatedly as MEL operations are processed.

Inheritance diagram for MCommandMessage:

Public Types
enum	MessageType { kHistory, kDisplay, kInfo, kWarning, kError, kResult, kStackTrace }
	Types of output messages. More...

typedef void(*	MMessageFunction) (const MString &message, MCommandMessage::MessageType messageType, void *clientData)
	Pointer to a message function. More...

typedef void(*	MMessageFilterFunction) (const MString &message, MCommandMessage::MessageType messageType, bool &filterOutput, void *clientData)
	Pointer to a message filter function. More...

Public Types inherited from MMessage
enum	Action { kDefaultAction, kDoNotDoAction, kDoAction }
	Callback result action codes. More...

typedef void(*	MBasicFunction) (void *clientData)
	Pointer to a basic callback function. More...

typedef void(*	MElapsedTimeFunction) (float elapsedTime, float lastTime, void *clientData)
	Pointer to an elapsed time callback function. More...

typedef void(*	MCheckFunction) (bool retCode, void clientData)
	Pointer to callback function which returns a true/false result. More...

typedef void(*	MCheckFileFunction) (bool retCode, MFileObject &file, void clientData)
	Pointer to a callback function which takes a file object and returns a result. More...

typedef void(*	MCheckPlugFunction) (bool retCode, MPlug &plug, void clientData)
	Pointer to a callback function which takes a plug and returns a result. More...

typedef void(*	MComponentFunction) (MUintArray componentIds[], unsigned int count, void *clientData)
	Pointer to a callback function which takes an array of component ids. More...

typedef void(*	MNodeFunction) (MObject &node, void *clientData)
	Pointer to a callback function which takes a dependency node. More...

typedef void(*	MStringFunction) (const MString &str, void *clientData)
	Pointer to callback function which takes a string. More...

typedef void(*	MTwoStringFunction) (const MString &str1, const MString &str2, void *clientData)
	Pointer to a callback function which takes two strings. More...

typedef void(*	MThreeStringFunction) (const MString &str1, const MString &str2, const MString &str3, void *clientData)
	Pointer to a callback function which takes three strings. More...

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. More...

typedef void(*	MStringIndexFunction) (const MString &, unsigned int index, void *clientData)
	Pointer to callback function which takes a string and index. More...

typedef void(*	MNodeStringBoolFunction) (MObject &node, const MString &, bool, void *clientData)
	Pointer to a callback function which takes a node, a string and a boolean. More...

typedef void(*	MStateFunction) (bool state, void *clientData)
	Pointer to a callback function which takes a boolean state. More...

typedef void(*	MTimeFunction) (MTime &time, void *clientData)
	Pointer to callback function which takes a time. More...

typedef void(*	MPlugFunction) (MPlug &srcPlug, MPlug &destPlug, bool made, void *clientData)
	Pointer to plug connection callback function. More...

typedef void(*	MNodePlugFunction) (MObject &node, MPlug &plug, void *clientData)
	Pointer to a callback function which takes a dependency node and a plug. More...

typedef void(*	MNodeStringFunction) (MObject &node, const MString &str, void *clientData)
	Pointer to a callback function which takes a dependency node and a string. More...

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. More...

typedef void(*	MModifierFunction) (MDGModifier &modifier, void *clientData)
	Pointer to a callback function which takes a DG modifier. More...

typedef void(*	MStringArrayFunction) (const MStringArray &strs, void *clientData)
	Pointer to a callback function which takes a string array. More...

typedef void(*	MNodeModifierFunction) (MObject &node, MDGModifier &modifier, void *clientData)
	Pointer to a callback function which takes a dependency node and a DG modifier. More...

typedef void(*	MObjArray) (MObjectArray &objects, void *clientData)
	Pointer to a callback function which takes an array of objects. More...

typedef void(*	MNodeObjArray) (MObject &node, MObjectArray &objects, void *clientData)
	Pointer to a callback function which takes a dependency node and an array of objects. More...

typedef void(*	MStringNode) (const MString &str, MObject &node, void *clientData)
	Pointer to a callback function which takes a string and a dependency node. More...

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. More...

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. More...

typedef void(*	MConnFailFunction) (MPlug &srcPlug, MPlug &destPlug, const MString &srcPlugName, const MString &dstPlugName, void *clientData)
	Pointer to connection-failed callback function. More...

typedef void(*	MPlugsDGModFunction) (MPlugArray &plugs, MDGModifier &modifier, void *clientData)
	Pointer to a callback function which takes an array of MPlugs and an MDGModifier. More...

typedef void(*	MNodeUuidFunction) (MObject &node, const MUuid &uuid, void *clientData)
	Pointer to a callback function which takes a dependency node and a UUID. More...

typedef Action(*	MCheckNodeUuidFunction) (bool doAction, MObject &node, MUuid &uuid, void *clientData)
	Pointer to a callback function which takes a dependency node and a UUID, and returns a result. More...

typedef void(*	MObjectFileFunction) (const MObject &object, const MFileObject &file, void *clientData)
	Pointer to a callback function which takes an object and a file object. More...

typedef void(*	MCheckObjectFileFunction) (bool retCode, const MObject &referenceNode, MFileObject &file, void clientData)
	Pointer to a callback function which takes an object and a file object and returns a result. More...

typedef void(*	MRenderTileFunction) (int originX, int originY, int tileMaxX, int tileMaxY, const void *tileData)
	Pointer to a callback function which receives origin, size and image data. More...

Static Public Member Functions
static MCallbackId	addCommandCallback (MMessage::MStringFunction func, void clientData=NULL, MStatus ReturnStatus=NULL)
	This method registers a callback for command messages that are issued every time a MEL command is executed. More...

static MCallbackId	addCommandOutputCallback (MCommandMessage::MMessageFunction func, void clientData=NULL, MStatus ReturnStatus=NULL)
	This method registers a callback for whenever commands generate output such as that which is printed into the command window. More...

static MCallbackId	addCommandOutputFilterCallback (MCommandMessage::MMessageFilterFunction func, void clientData=NULL, MStatus ReturnStatus=NULL)
	This method registers a callback for whenever commands generate output such as that which is printed into the command window. More...

static const char *	className ()
	Returns the name of this class. More...

static MCallbackId	addProcCallback (MMessage::MStringIntBoolIntFunction func, void clientData, MStatus ReturnStatus)
	This method registers a callback that is executed every time a MEL procedure is run. More...

Static Public Member Functions inherited from MMessage
static MStatus	removeCallback (MCallbackId id)
	Remove the specified callback from maya. More...

static MStatus	removeCallbacks (MCallbackIdArray &ids)
	Remove all of the specified callbacks from maya. More...

static MCallbackId	currentCallbackId (MStatus *ReturnStatus=NULL)
	Return the callback ID of the currently executing callback. More...

static MStatus	nodeCallbacks (MObject &node, MCallbackIdArray &ids)
	Returns a list of callback IDs associated registered to a given node. More...

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. More...

static MStatus	removeCallbacks (MIntArray &ids)
	This method is obsolete. This method is not available in Python. More...

static MStatus	nodeCallbacks (MObject &node, MIntArray &ids)
	This method is obsolete. More...

Member Typedef Documentation

typedef void(* MMessageFunction) (const MString &message, MCommandMessage::MessageType messageType, void *clientData)

Pointer to a message function.

Parameters

[in]	message	The command that was executed.
[in]	messageType	The type of message.
[in,out]	clientData	User defined data passed to the callback function.

typedef void(* MMessageFilterFunction) (const MString &message, MCommandMessage::MessageType messageType, bool &filterOutput, void *clientData)

Pointer to a message filter function.

Parameters

[in]	message	The command that was executed.
[in]	messageType	The type of message.
[out]	filter	Bool that causes Maya to filter this message if set to true.
[in,out]	clientData	User defined data passed to the callback function.

Member Enumeration Documentation

enum MessageType

Types of output messages.

Enumerator
kHistory	Command history.
kDisplay	String to display unmodified.
kInfo	General information.
kWarning	Warning message.
kError	Error message.
kResult	Result from a command execution in the command window.
kStackTrace	Stack trace.

Member Function Documentation

OPENMAYA_MAJOR_NAMESPACE_OPEN MCallbackId addCommandCallback	(	MMessage::MStringFunction	func,
		void *	clientData = `NULL`,
		MStatus *	ReturnStatus = `NULL`
	)

static

This method registers a callback for command messages that are issued every time a MEL command is executed.

It is only called when actual commands are executed and not when scripts are executed.

The callback function will be passed the any client data that was provided when the callback was registered.

NOTE: Setting up a callback using this method will degrade the performance of Maya since the installed callback will be invoked repeatedly as MEL operations are processed.

Parameters

[in]	func	The callback function.
[in]	clientData	User defined data that will be passed to the callback function.
[out]	ReturnStatus	Status code.

Returns: Identifier used for removing the callback.

Status Codes:

MS::kSuccess Operation succeeded
MS::kInsufficientMemory No memory available
MS::kFailure Error adding callback

MCallbackId addCommandOutputCallback	(	MCommandMessage::MMessageFunction	func,
		void *	clientData = `NULL`,
		MStatus *	ReturnStatus = `NULL`
	)

static

This method registers a callback for whenever commands generate output such as that which is printed into the command window.

The callback function will be passed the any client data that was provided when the callback was registered.

Parameters

[in]	func	The callback function.
[in]	clientData	User defined data that will be passed to the callback function.
[out]	ReturnStatus	Status code.

Returns: Identifier used for removing the callback.

Status Codes:

MS::kSuccess Operation succeeded
MS::kInsufficientMemory No memory available
MS::kFailure Error adding callback

MCallbackId addCommandOutputFilterCallback	(	MCommandMessage::MMessageFilterFunction	func,
		void *	clientData = `NULL`,
		MStatus *	ReturnStatus = `NULL`
	)

static

This method registers a callback for whenever commands generate output such as that which is printed into the command window.

This callback includes a boolean filter option which allows the callback to prevent the output of the message to the script editor and command line output. Setting the 'filterOutput' parameter to true, inside your callback will filter the output from the script editor and command line output.

The callback function will be passed the any client data that was provided when the callback was registered.

Parameters

[in]	func	The callback function.
[in]	clientData	User defined data that will be passed to the callback function.
[out]	ReturnStatus	Status code.

Returns: Identifier used for removing the callback.

Status Codes:

MS::kSuccess Operation succeeded
MS::kInsufficientMemory No memory available
MS::kFailure Error adding callback

const char * className ( )

static

Returns the name of this class.

Returns: The name of this class.

MCallbackId addProcCallback	(	MMessage::MStringIntBoolIntFunction	func,
		void *	clientData,
		MStatus *	ReturnStatus
	)

static

This method registers a callback that is executed every time a MEL procedure is run.

The callback will be executed once when the procedure is about to be executed, and again when it has exited. If a non-existent procedure is called the callback will be called once for entry but there will be no call on exit.

The callback function should have the following parameters:

func(const MString& procName, unsigned int procID, bool isProcEntry, unsigned int type, void* clientData)

Where: procName will be the name of the procedure being invoked procID is the ID for the procedure's invocation isProcEntry is true if the procedure is being entered, false otherwise type is an MCommandMessage::ProcType value, and denotes the type of call this is, a MEL Proc, or MEL Command clientData is a pointer to an unsigned integer which is the invocation ID of the procedure

The callback cannot be registered multiple times. To register a new callback function for this, please de-register the original callback first.

NOTE: Setting up a callback using this method can potentially degrade the performance of Maya since the installed callback will be invoked repeatedly as MEL procedures are executed.

Parameters

[in]	func	The callback function.
[in]	clientData	User defined data that will be passed to the callback function.
[out]	ReturnStatus	Status code.

Returns: Identifier used for removing the callback.

Status Codes:

MS::kSuccess Operation succeeded
MS::kInvalidParameter Callback already registered
MS::kFailure Error adding callback

The documentation for this class was generated from the following files:

MCommandMessage.h
MCommandMessage.cpp

MCommandMessage Class Reference

Class Description

Public Types

Static Public Member Functions

Member Typedef Documentation

Member Enumeration Documentation

Member Function Documentation