- Main Page
- Related Pages
- Modules
- Namespaces
- Classes
- Examples

- Class List
- Class Hierarchy
- Class Members

Static Public Member Functions

# MUserEventMessage Class Reference
OpenMaya - API module for common classes

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:
[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]`

Search for all occurrences

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 isUserEvent | ( | const MString & | eventName | ) | `[static]`

Search for all occurrences

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 deregisterUserEvent | ( | const MString & | eventName | ) | `[static]`

Search for all occurrences

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 addUserEventCallback | ( | const MString & | eventName,
|  | MMessage::MBasicFunction | func,
|  | void * | clientData = `NULL`,
|  | MStatus * | ReturnStatus = `NULL`
| ) |  | `[static]`

Search for all occurrences

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 postUserEvent | ( | const MString & | eventName,
|  | void * | clientData = `NULL`
| ) |  | `[static]`

Search for all occurrences

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

const char * className | ( |  | ) | `[static]`

Search for all occurrences

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