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

#include <MUserEventMessage.h>

Inheritance diagram for MUserEventMessage:

[legend]

Collaboration diagram for MUserEventMessage:

[legend]

List of all members.

---

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

Static Public Member Functions
static MStatus	registerUserEvent (const MString &event)
static bool	isUserEvent (const MString &event)
static MStatus	deregisterUserEvent (const MString &event)
static MCallbackId	addUserEventCallback (const MString &event, MMessage::MBasicFunction func, void *clientData=NULL, MStatus *ReturnStatus=NULL)
static MStatus	postUserEvent (const MString &event, void *clientData=NULL)

---

Member Function Documentation

MStatus MUserEventMessage::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.cpp.

bool MUserEventMessage::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.cpp.

MStatus MUserEventMessage::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.cpp.

MCallbackId MUserEventMessage::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.cpp.

MStatus MUserEventMessage::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

Returns:

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

Examples:

userMsgCmd.cpp.