class MUserEventMessage

Jump to documentation

Inheritance:

MUserEventMessage < MMessage

public members:

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 )

Inherited from MMessage:

public members:

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 )
static MStatus	nodeCallbacks ( MObject & node, MIntArray & ids )

Documentation

Description

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.

Functions

MStatus MUserEventMessage:: registerUserEvent ( const MString & eventName )

Description

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.

Arguments

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

Return Value

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

bool MUserEventMessage:: isUserEvent ( const MString & eventName )

Description

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

Arguments

• eventName the event name

Return Value

• true Event type exists
• false Event type does not exist

MStatus MUserEventMessage:: deregisterUserEvent ( const MString & eventName )

Description

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.

Arguments

• eventName the event name

Return Value

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

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

Description

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

Arguments

• event the event to register the callback for
• func the callback function
  • clientData User defined data passed to the callback function
• clientData User defined data that will be passed to the callback function
• ReturnStatus status code

Return Value

• 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

MStatus MUserEventMessage:: postUserEvent ( const MString & eventName, void* clientData )

Description

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.

Arguments

• event the event name

Return Value

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

This class has no child classes.