#include <MUserEventMessage.h>

Class Description

User defined Message Types.

This class is used to register user-defined event types, register callbacks with the user-defined event types, and to post user-defined messages.

The registerUserEvent and deregisterUserEvent methods allow user event types to be created and destroyed. User events are identified by a unique string identifier.

The addCallback method registers a function that will be executed whenever the specified message occurs. An id is returned and is used to remove the callback.

The postUserEvent notifies all registered callbacks of the occurence of the user-defined event.

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.

Inheritance diagram for MUserEventMessage:

Static Public Member Functions
static MStatus	registerUserEvent (const MString &event)
	Adds a new event type with the given string identifier. More...

static bool	isUserEvent (const MString &event)
	Checks if an event type exists with the given event name. More...

static MStatus	deregisterUserEvent (const MString &event)
	Removes the event type with the given event name. More...

static MCallbackId	addUserEventCallback (const MString &event, MMessage::MBasicFunction func, void clientData=NULL, MStatus ReturnStatus=NULL)
	This method registers a callback for user-defined messages. More...

static MStatus	postUserEvent (const MString &event, void *clientData=NULL)
	Notifies all callbacks attached to the given event type of the occurence of the event. More...

static const char *	className ()
	Returns the name of this class. 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...

Additional Inherited Members
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...

Member Function Documentation

MStatus registerUserEvent ( const MString & eventName )

static

Adds a new event type with the given string identifier.

The string identifier can then be used in all other MUserEventMessage methods to operate on the new event type.

Parameters

[in] eventName the name of the new event to register. Any non-empty string may be used as an event name.

Returns

MS::kSuccess Operation succeeded
MS::kInsufficientMemory No memory available
MS::kInvalidParameter Empty string passed for eventName
MS::kFailure Event type already exists

Examples:: userMsgCmd/userMsgCmd.cpp.

bool isUserEvent ( const MString & eventName )

static

Checks if an event type exists with the given event name.

Parameters

[in] eventName the event name

Returns

true Event type exists
false Event type does not exist

Examples:: userMsgCmd/userMsgCmd.cpp.

MStatus deregisterUserEvent ( const MString & eventName )

static

Removes the event type with the given event name.

If callbacks have been registered with this event type, they will become invalid after a successful call to this method.

Parameters

[in] eventName the event name

Returns

MS::kSuccess Operation succeeded
MS::kFailure Event type does not exist

Examples:: userMsgCmd/userMsgCmd.cpp.

MCallbackId addUserEventCallback	(	const MString &	eventName,
		MMessage::MBasicFunction	func,
		void *	clientData = `NULL`,
		MStatus *	ReturnStatus = `NULL`
	)

static

This method registers a callback for user-defined messages.

The parameter clientData will be passed to callbacks registered for this event whenever the event is triggered. To override the data that is passed to the callback whenever the event is posted, you can supply a clientData pointer to postUserEvent().

Parameters

[in]	eventName	the event name to register the callback for
[in]	func	the callback function

clientData User defined data passed to the callback function

Parameters

[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::kUnknownParameter The named event could not be found
MS::kInsufficientMemory No memory available
MS::kFailure Error adding callback

Examples:: userMsgCmd/userMsgCmd.cpp.

MStatus postUserEvent	(	const MString &	eventName,
		void *	clientData = `NULL`
	)

static

Notifies all callbacks attached to the given event type of the occurence of the event.

If clientData is specified, this data will be passed to all callbacks that receive the event. If clientData is NULL (the default), the clientData registered with addUserEventCallback will be passed to the callbacks.

Parameters

[in]	eventName	the event name
[in]	clientData	caller-defined data to be passed to the callback

Returns

MS::kSuccess Operation succeeded
MS::kFailure Event type does not exist

Examples:: userMsgCmd/userMsgCmd.cpp.

const char * className ( )

static

Returns the name of this class.

Returns: The name of this class.

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

MUserEventMessage.h
MUserEventMessage.cpp

MUserEventMessage Class Reference

Class Description

Static Public Member Functions

Additional Inherited Members

Member Function Documentation