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

#include <MSceneMessage.h>
Inheritance diagram for MSceneMessage:
Inheritance graph
[legend]
Collaboration diagram for MSceneMessage:
Collaboration graph
[legend]

List of all members.


Detailed Description

Scene messages.

This class is used to register callbacks for scene related messages.

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.

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

enum   Message {
   kSceneUpdate, kBeforeNew, kAfterNew, kBeforeImport,
   kAfterImport, kBeforeOpen, kAfterOpen, kBeforeExport,
   kAfterExport, kBeforeSave, kAfterSave, kBeforeReference,
   kAfterReference, kBeforeRemoveReference, kAfterRemoveReference, kBeforeImportReference,
   kAfterImportReference, kBeforeExportReference, kAfterExportReference, kBeforeUnloadReference,
   kAfterUnloadReference, kBeforeSoftwareRender, kAfterSoftwareRender, kBeforeSoftwareFrameRender,
   kAfterSoftwareFrameRender, kSoftwareRenderInterrupted, kMayaInitialized, kMayaExiting,
   kBeforeNewCheck, kBeforeOpenCheck, kBeforeSaveCheck, kBeforeImportCheck,
   kBeforeExportCheck, kBeforeLoadReference, kAfterLoadReference, kBeforeLoadReferenceCheck,
   kBeforeReferenceCheck, kBeforeCreateReferenceCheck = kBeforeReferenceCheck, kBeforePluginLoad, kAfterPluginLoad,
   kBeforePluginUnload, kAfterPluginUnload, kBeforeCreateReference, kAfterCreateReference,
   kLast
}
  Events to which messages can be attached. More...

Static Public Member Functions

static MCallbackId  addCallback (Message msg, MMessage::MBasicFunction func, void *clientData=NULL, MStatus *ReturnStatus=NULL)
static MCallbackId  addCheckCallback (Message msg, MMessage::MCheckFunction func, void *clientData=NULL, MStatus *ReturnStatus=NULL)
static MCallbackId  addCheckFileCallback (Message msg, MMessage::MCheckFileFunction func, void *clientData=NULL, MStatus *ReturnStatus=NULL)
static MCallbackId  addStringArrayCallback (Message msg, MMessage::MStringArrayFunction func, void *clientData=NULL, MStatus *ReturnStatus=NULL)
static MCallbackId  addCallback (Message, void(*func)(bool *retCode, void *clientData), void *clientData=NULL, MStatus *ReturnStatus=NULL)
  This method is obsolete. This method is not available in Python.
static MCallbackId  addCallback (Message, void(*func)(bool *retCode, MFileObject &file, void *clientData), void *clientData=NULL, MStatus *ReturnStatus=NULL)
  This method is obsolete. This method is not available in Python.
static MCallbackId  addCallback (Message, void(*func)(const MStringArray &, void *), void *clientData, MStatus *ReturnStatus)
  This method is obsolete. This method is not available in Python.

Member Enumeration Documentation

Events to which messages can be attached.

Enumerator:
kSceneUpdate  Called after any operation that changes which files are loaded.
kBeforeNew  Called before a File > New operation.
kAfterNew  Called after a File > New operation.
kBeforeImport  Called before a File > Import operation.
kAfterImport  Called after a File > Import operation.
kBeforeOpen  Called before a File > Open operation.
kAfterOpen  Called after a File > Open operation.
kBeforeExport  Called before a File > Export operation.
kAfterExport  Called after a File > Export operation.
kBeforeSave  Called before a File > Save (or SaveAs) operation.
kAfterSave  Called after a File > Save (or SaveAs) operation.
kBeforeReference  Called before a File > Reference operation. Deprecated. Use kBeforeCreateReference/kBeforeLoadReference.
kAfterReference  Called after a File > Reference operation. Deprecated. Use kAfterCreateReference/kAfterLoadReference.
kBeforeRemoveReference  Called before a File > RemoveReference operation.
kAfterRemoveReference  Called after a File > RemoveReference operation.
kBeforeImportReference  Called before a File > ImportReference operation.
kAfterImportReference  Called after a File > ImportReference operation.
kBeforeExportReference  Called before a File > ExportReference operation.
kAfterExportReference  Called after a File > ExportReference operation.
kBeforeUnloadReference  Called before a File > UnloadReference operation.
kAfterUnloadReference  Called after a File > UnloadReference operation.
kBeforeSoftwareRender  Called before a Software Render begins.
kAfterSoftwareRender  Called after a Software Render ends.
kBeforeSoftwareFrameRender  Called before each frame of a Software Render.
kAfterSoftwareFrameRender  Called after each frame of a Software Render.
kSoftwareRenderInterrupted  Called when an interactive render is interrupted by the user.
kMayaInitialized  Called on interactive or batch startup after initialization.
kMayaExiting  Called just before Maya exits.
kBeforeNewCheck  Called prior to File > New operation, allows user to cancel action.
kBeforeOpenCheck  Called prior to File > Open operation, allows user to cancel action.
kBeforeSaveCheck  Called prior to File > Save operation, allows user to cancel action.
kBeforeImportCheck  Called prior to File > Import operation, allows user to cancel action.
kBeforeExportCheck  Called prior to File > Export operation, allows user to cancel action.
kBeforeLoadReference  Called before a File > LoadReference operation.
kAfterLoadReference  Called after a File > LoadReference operation.
kBeforeLoadReferenceCheck  Called before a File > LoadReference operation, allows user to cancel action.
kBeforeReferenceCheck  Called prior to a File > CreateReference operation, allows user to cancel action. Deprecated. Use kBeforeCreateReferenceCheck.
kBeforeCreateReferenceCheck  Called prior to a File > CreateReference operation, allows user to cancel action.
kBeforePluginLoad  Called prior to a plugin being loaded.
kAfterPluginLoad  Called after a plugin is loaded.
kBeforePluginUnload  Called prior to a plugin being unloaded.
kAfterPluginUnload  Called after a plugin is unloaded.
kBeforeCreateReference  Called before a File > CreateReference operation.
kAfterCreateReference  Called after a File > CreateReference operation.
kLast  Last value of the enum.

Member Function Documentation

MCallbackId MSceneMessage::addCallback ( MSceneMessage::Message  msg,
MMessage::MBasicFunction  func,
void *  clientData = NULL,
MStatus ReturnStatus = NULL  
) [static]

Adds a new callback for the specified scene message.

If a 'before' message is sent, the corresponding 'after' message will be as well.

Callbacks can be added to the following messages with this function:

  • kSceneUpdate
  • kBeforeNew
  • kAfterNew
  • kBeforeImport
  • kAfterImport
  • kBeforeOpen
  • kAfterOpen
  • kBeforeExport
  • kAfterExport
  • kBeforeSave
  • kAfterSave
  • kBeforeCreateReference
  • kAfterCreateReference
  • kBeforeRemoveReference
  • kAfterRemoveReference
  • kBeforeImportReference
  • kAfterImportReference
  • kBeforeExportReference
  • kAfterExportReference
  • kBeforeUnloadReference
  • kAfterUnloadReference
  • kBeforeLoadReference
  • kAfterLoadReference
  • kBeforeSoftwareRender
  • kAfterSoftwareRender
  • kBeforeSoftwareFrameRender
  • kAfterSoftwareFrameRender
  • kSoftwareRenderInterrupted
  • kMayaInitialized
  • kMayaExiting
Note that for referencing, the creation of the reference (i.e. creation of the reference node and associated structures) is separate from the loading of the reference itself (i.e. read the nodes from file).

The kBeforeCreateReference message will be sent when a reference is created. So it will happen for both loaded and unloaded references. But the kBeforeLoadReference message will only be sent when the file is read from disk.

When opening a file with a loaded reference, the callback order is as follows,

kBeforeCreateReference kAfterCreateReference

kBeforeLoadReference kAfterLoadReference

Parameters:
[in]  msg  the scene message that will trigger the callback
[in]  func  the callback function
  • clientData User defined data passed to the callback function
[in]  clientData  user data that will be passed to the callback function
[out]  ReturnStatus  Status code
Returns:
Identifier used for removing the callback.
Status Codes:
Examples:

MCallbackId MSceneMessage::addCheckCallback ( MSceneMessage::Message  msg,
MMessage::MCheckFunction  func,
void *  clientData = NULL,
MStatus ReturnStatus = NULL  
) [static]

This function adds a new callback for the specified scene message and also has the option to abort the current operation by return false through the return code parameter.

NOTE: The check message is sent out before the equivalent non-check type. As a result, if the check message aborts the operation, the equivalent non-check message type will not be sent.

Callbacks can be added to the following messages with this function:

  • kBeforeNewCheck
  • kBeforeImportCheck
  • kBeforeOpenCheck
  • kBeforeExportCheck
  • kBeforeSaveCheck
  • kBeforeCreateReferenceCheck
  • kBeforeLoadReferenceCheck
Parameters:
[in]  msg  the scene message that will trigger the callback
[in]  func  the callback function
  • retCode boolean passed in to the callback function. Incase of any error, this will be set to false in the callback function.
  • clientData User defined data passed to the callback function
Parameters:
[in]  clientData  user data that will be passed to the callback function
[out]  ReturnStatus  Status code
Returns:
Identifier used for removing the callback.
Status Codes:

MCallbackId MSceneMessage::addCheckFileCallback ( MSceneMessage::Message  msg,
MMessage::MCheckFileFunction  func,
void *  clientData = NULL,
MStatus ReturnStatus = NULL  
) [static]

This function adds a new callback for the specified scene message. This callback has the option to abort the current operation by setting the retCode parameter to false. The file parameter stores the target file for the current file IO operation, by modifying this file parameter the target file will be changed as well.

NOTE: The check message is sent out before the equivalent non-check type. As a result, if the check message aborts the operation, the equivalent non-check message type will not be sent.

Callbacks can be added to the following messages with this function:

  • kBeforeImportCheck
  • kBeforeOpenCheck
  • kBeforeExportCheck
  • kBeforeCreateReferenceCheck
  • kBeforeLoadReferenceCheck
Parameters:
[in]  msg  the scene message that will trigger the callback
[in]  func  the callback function
  • retCode boolean passed in to the callback function. Incase of any error, this will be set to false in the callback function.
  • file MFileObject passed in to the callback function. This is the MFileObject that will be acted on by the current file IO operation, any modifications to it will be passed back to Maya and change the file being acted on.
  • clientData User defined data passed to the callback function
Parameters:
[in]  clientData  user data that will be passed to the callback function
[out]  ReturnStatus  Status code
Returns:
Identifier used for removing the callback.
Status Codes:

MCallbackId MSceneMessage::addStringArrayCallback ( MSceneMessage::Message  msg,
MMessage::MStringArrayFunction  func,
void *  clientData = NULL,
MStatus ReturnStatus = NULL  
) [static]

Adds a new callback which takes a string array argument, in addition to the usual clientData.

The messages which can be used with this method and the contents of the string array passed to their callbacks are as follows:

  • kBeforePluginLoad - path to plug-in file
  • kAfterPluginLoad - path to plug-in file, name of plug-in
  • kBeforePluginUnload - name of plug-in
  • kAfterPluginUnload - name of plug-in, path to plug-in file
To allow for future expansion callbacks should not rely on the number of array elements being exactly as given above. While there will not be fewer elements than given above, there may in future be more.
Parameters:
[in]  msg  the scene message that will trigger the callback
[in]  func  the callback function
  • strs immutable array of strings
  • clientData User defined data passed to the callback function
Parameters:
[in]  clientData  user data that will be passed to the callback function
[out]  ReturnStatus  Status code
Returns:
Identifier used for removing the callback.
Status Codes:

MCallbackId MSceneMessage::addCallback ( MSceneMessage::Message  msg,
void(*)(bool *retCode, void *clientData)  func,
void *  clientData = NULL,
MStatus ReturnStatus = NULL  
) [static]

This method is obsolete. This method is not available in Python.

Deprecated:
Use the MSceneMessage::addCheckCallback() method instead.

MCallbackId MSceneMessage::addCallback ( MSceneMessage::Message  msg,
void(*)(bool *retCode, MFileObject &file, void *clientData)  func,
void *  clientData = NULL,
MStatus ReturnStatus = NULL  
) [static]

This method is obsolete. This method is not available in Python.

Deprecated:
Use the MSceneMessage::addCheckFileCallback() method instead.

MCallbackId MSceneMessage::addCallback ( MSceneMessage::Message  msg,
void(*)(const MStringArray &, void *)  func,
void *  clientData,
MStatus ReturnStatus  
) [static]

This method is obsolete. This method is not available in Python.

Deprecated:
Use the MSceneMessage::addStringArrayCallback() method instead.

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