Static Public Member Functions

MUserEventMessage Class Reference

This reference page is linked to from the following overview topics: Overview of example plug-ins.


Search for all occurrences

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.

#include <MUserEventMessage.h>

Inheritance diagram for MUserEventMessage:
Inheritance graph
[legend]

List of all members.

Static Public Member Functions

static MStatus registerUserEvent (const MString &event)
 Adds a new event type with the given string identifier.
static bool isUserEvent (const MString &event)
 Checks if an event type exists with the given event name.
static MStatus deregisterUserEvent (const MString &event)
 Removes the event type with the given event name.
static MCallbackId addUserEventCallback (const MString &event, MMessage::MBasicFunction func, void *clientData=NULL, MStatus *ReturnStatus=NULL)
 This method registers a callback for user-defined messages.
static MStatus postUserEvent (const MString &event, void *clientData=NULL)
 Notifies all callbacks attached to the given event type of the occurence of the event.
static const char * className ()
 Returns the name of this class.

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]eventNamethe name of the new event to register. Any non-empty string may be used as an event name.
Returns:
Examples:
userMsgCmd.cpp.
bool isUserEvent ( const MString eventName) [static]

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

Parameters:
[in]eventNamethe event name
Returns:
  • true Event type exists
  • false Event type does not exist
Examples:
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]eventNamethe event name
Returns:
Examples:
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]eventNamethe event name to register the callback for
[in]functhe callback function
  • clientData User defined data passed to the callback function
Parameters:
[in]clientDataUser defined data that will be passed to the callback function
[out]ReturnStatusstatus code
Returns:
Identifier used for removing the callback.
Status Codes:
Examples:
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]eventNamethe event name
[in]clientDatacaller-defined data to be passed to the callback
Returns:
Examples:
userMsgCmd.cpp.
const char * className ( ) [static]

Returns the name of this class.

Returns:
The name of this class.

Reimplemented from MMessage.


MUserEventMessage MUserEventMessage MUserEventMessage MUserEventMessage MUserEventMessage MUserEventMessage MUserEventMessage MUserEventMessage MUserEventMessage MUserEventMessage
MUserEventMessage MUserEventMessage MUserEventMessage MUserEventMessage MUserEventMessage MUserEventMessage MUserEventMessage MUserEventMessage MUserEventMessage MUserEventMessage