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

#include <MTimerMessage.h>

Inheritance diagram for MTimerMessage:

Inheritance graph
[legend]
Collaboration diagram for MTimerMessage:

Collaboration graph
[legend]

List of all members.


Detailed Description

Register callbacks that are based on a fixed time interval.

This class is used to register callbacks that are called at fixed time intervals. Unlike other callbacks, a timer callback is executed with the highest priority within Maya and take precidence over *all* other Maya events. Use with care as it is possible to construct a callback that will prevent any other part of Maya from running.

The add callback method returns an id which is used to remove the callback.

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.

Public Types

typedef void(* sleepCallbackPtr )()
 Pointer to a sleep callback function.

Static Public Member Functions

static MCallbackId addTimerCallback (float period, MMessage::MElapsedTimeFunction func, void *clientData=NULL, MStatus *ReturnStatus=NULL)
static MStatus setSleepCallback (sleepCallbackPtr sleepFunc)
static
MTimerMessage::sleepCallbackPtr 
sleepCallback ()


Member Function Documentation

MCallbackId MTimerMessage::addTimerCallback ( float  period,
MMessage::MElapsedTimeFunction  func,
void *  clientData = NULL,
MStatus ReturnStatus = NULL 
) [static]

This method registers a callback for timed messages. The maximum resolution for this callback is about 1ms. The response is, however, not guaranteed because while multitasking, the OS may delay for an unspecified length of time before returning control to Maya.

If the execution time of a callback exceeds its period/2 the timer will be reset. This will give Maya 1 period in which to do other things.

The callback function will be passed any client data that was provided when the callback was registered.

Parameters:
[in] period the period at which the callback will be executed (Measured in seconds)
[in] func the callback function
  • elapsedTime The elapsed time since this function was last called
  • lastTime The execution time of this function the the last time it was called
  • clientData User defined data passed to the callback function
[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:

MStatus MTimerMessage::setSleepCallback ( sleepCallbackPtr  sleepFunc  )  [static]

The sleep function is a mechanism that allows the user to limit the ammount of CPU time that Maya uses while a timer callback is registered. Normally, registering a timer callback will cause Maya's event loop to run continuously and consume 100% of the available processor time. In some cases it may be desireable to use a sleep callback that will put Maya's event loop to sleep for a few miliseconds if there are no pending events. This will give another process time to do some other task.

The sleep function is optional.

Maya will not execute any faster when using a sleep function.

The sleep function is global and used when any timer message callbacks are registered.

Nanosleep() is a good candidate to achieve the desired results, however other platform dependent methods may be used to achieve finer sleep resolution if available.

Using this method will limit the response time of all timer callbacks to slightly more than the length of the sleep function. So if your sleep function sleeps for 20ms, any timer that is smaller than 20ms will be called at 20ms intervals.

Always use this method to set the sleep function to NULL when unloading your plugin. You can also use sleepCallback() to check if your sleep function is currently active to avoid conflicts with another plugin that has overridden your sleep function

Parameters:
[in] sleepFunc a function pointer to a function that will cause the current process to sleep
Returns:

MTimerMessage::sleepCallbackPtr MTimerMessage::sleepCallback (  )  [static]

Returns the currently registered sleep callback function


Autodesk® Maya® 2009 © 1997-2008 Autodesk, Inc. All rights reserved. Generated with doxygen 1.5.6