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

- Class List
- Class Hierarchy
- Class Members

Public Types | Static Public Member Functions

# MSceneMessage Class Reference
OpenMaya - API module for common classes

This reference page is linked to from the following overview topics: Differences between the Maya .NET API and the Maya C++ API.

Search for all occurrences

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

`#include <MSceneMessage.h>`

Inheritance diagram for MSceneMessage:
[legend]

List of all members.

## Public Types
enum | Message { kSceneUpdate, kBeforeNew, kAfterNew, kBeforeImport, kAfterImport, kBeforeOpen, kAfterOpen, kBeforeFileRead, kAfterFileRead, 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, kExportStarted, kBeforeLoadReferenceAndRecordEdits, kAfterLoadReferenceAndRecordEdits, kBeforeCreateReferenceAndRecordEdits, kAfterCreateReferenceAndRecordEdits, 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)
| Adds a new callback for the specified scene message.
static MCallbackId | addCheckCallback (Message msg, MMessage::MCheckFunction func, void *clientData=NULL, MStatus *ReturnStatus=NULL)
| 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.
static MCallbackId | addCheckFileCallback (Message msg, MMessage::MCheckFileFunction func, void *clientData=NULL, MStatus *ReturnStatus=NULL)
| This function adds a new callback for the specified scene message.
static MCallbackId | addStringArrayCallback (Message msg, MMessage::MStringArrayFunction func, void *clientData=NULL, MStatus *ReturnStatus=NULL)
| Adds a new callback which takes a string array argument, in addition to the usual clientData.
static MCallbackId | addConnectionFailedCallback (MMessage::MConnFailFunction func, void *clientData=NULL, MStatus *ReturnStatus=NULL)
| This method registers a callback that is called when a connection was unable to be made.
static const char * | className ()
| Returns the name of this class.
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

enum Message

Search for all occurrences

Events to which messages can be attached.

Enumerator:

  kSceneUpdate | Called after any operation that changes which files are loaded. Search for all occurrences
  kBeforeNew | Called before a File > New operation. Search for all occurrences
  kAfterNew | Called after a File > New operation. Search for all occurrences
  kBeforeImport | Called before a File > Import operation. Search for all occurrences
  kAfterImport | Called after a File > Import operation. Search for all occurrences
  kBeforeOpen | Called before a File > Open operation. Search for all occurrences
  kAfterOpen | Called after a File > Open operation. Search for all occurrences
  kBeforeFileRead | Called immediately before any file read operation (open, import or reference) and while reading state (MFileIO::isReadingFile) is true. Search for all occurrences
  kAfterFileRead | Called immediately after any file read operation (open, import or reference) and while reading state (MFileIO::isReadingFile) is true. Search for all occurrences
  kBeforeExport | Called before a File > Export operation. Search for all occurrences
  kAfterExport | Called after a File > Export operation. Search for all occurrences
  kBeforeSave | Called before a File > Save (or SaveAs) operation. Search for all occurrences
  kAfterSave | Called after a File > Save (or SaveAs) operation. Search for all occurrences
  kBeforeReference | Called before a File > Reference operation. Deprecated. Use kBeforeCreateReference/kBeforeLoadReference. Search for all occurrences
  kAfterReference | Called after a File > Reference operation. Deprecated. Use kAfterCreateReference/kAfterLoadReference. Search for all occurrences
  kBeforeRemoveReference | Called before a File > RemoveReference operation. Search for all occurrences
  kAfterRemoveReference | Called after a File > RemoveReference operation. Search for all occurrences
  kBeforeImportReference | Called before a File > ImportReference operation. Search for all occurrences
  kAfterImportReference | Called after a File > ImportReference operation. Search for all occurrences
  kBeforeExportReference | Called before a File > ExportReference operation. Search for all occurrences
  kAfterExportReference | Called after a File > ExportReference operation. Search for all occurrences
  kBeforeUnloadReference | Called before a File > UnloadReference operation. Search for all occurrences
  kAfterUnloadReference | Called after a File > UnloadReference operation. Search for all occurrences
  kBeforeSoftwareRender | Called before a Software Render begins. Search for all occurrences
  kAfterSoftwareRender | Called after a Software Render ends. Search for all occurrences
  kBeforeSoftwareFrameRender | Called before each frame of a Software Render. Search for all occurrences
  kAfterSoftwareFrameRender | Called after each frame of a Software Render. Search for all occurrences
  kSoftwareRenderInterrupted | Called when an interactive render is interrupted by the user. Search for all occurrences
  kMayaInitialized | Called on interactive or batch startup after initialization. Search for all occurrences
  kMayaExiting | Called just before Maya exits. Search for all occurrences
  kBeforeNewCheck | Called prior to File > New operation, allows user to cancel action. Search for all occurrences
  kBeforeOpenCheck | Called prior to File > Open operation, allows user to cancel action. Search for all occurrences
  kBeforeSaveCheck | Called prior to File > Save operation, allows user to cancel action. Search for all occurrences
  kBeforeImportCheck | Called prior to File > Import operation, allows user to cancel action. Search for all occurrences
  kBeforeExportCheck | Called prior to File > Export operation, allows user to cancel action. Search for all occurrences
  kBeforeLoadReference | Called before a File > LoadReference operation. Search for all occurrences
  kAfterLoadReference | Called after a File > LoadReference operation. Search for all occurrences
  kBeforeLoadReferenceCheck | Called before a File > LoadReference operation, allows user to cancel action. Search for all occurrences
  kBeforeReferenceCheck | Called prior to a File > CreateReference operation, allows user to cancel action. Deprecated. Use kBeforeCreateReferenceCheck. Search for all occurrences
  kBeforeCreateReferenceCheck | Called prior to a File > CreateReference operation, allows user to cancel action. Search for all occurrences
  kBeforePluginLoad | Called prior to a plugin being loaded. Search for all occurrences
  kAfterPluginLoad | Called after a plugin is loaded. Search for all occurrences
  kBeforePluginUnload | Called prior to a plugin being unloaded. Search for all occurrences
  kAfterPluginUnload | Called after a plugin is unloaded. Search for all occurrences
  kBeforeCreateReference | Called before a File > CreateReference operation. Search for all occurrences
  kAfterCreateReference | Called after a File > CreateReference operation. Search for all occurrences
  kExportStarted | Called at the start of a File > Export operation, after the export file has become the active file. Search for all occurrences
  kBeforeLoadReferenceAndRecordEdits | Same as kBeforeLoadReference except reference edits are recorded during the execution of the callback. Search for all occurrences
  kAfterLoadReferenceAndRecordEdits | Same as kAfterLoadReference except reference edits are recorded during the execution of the callback. Search for all occurrences
  kBeforeCreateReferenceAndRecordEdits | Same as kBeforeCreateReference except reference edits are recorded during the execution of the callback. Search for all occurrences
  kAfterCreateReferenceAndRecordEdits | Same as kAfterCreateReference except reference edits are recorded during the execution of the callback. Search for all occurrences
  kLast | Last value of the enum. Search for all occurrences

## Member Function Documentation

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

Search for all occurrences

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
- kBeforeFileRead
- kAfterFileRead
- kBeforeExport
- kExportStarted
- kAfterExport
- kBeforeSave
- kAfterSave
- kBeforeCreateReference
- kBeforeCreateReferenceAndRecordEdits
- kAfterCreateReference
- kAfterCreateReferenceAndRecordEdits
- kBeforeRemoveReference
- kAfterRemoveReference
- kBeforeImportReference
- kAfterImportReference
- kBeforeExportReference
- kAfterExportReference
- kBeforeUnloadReference
- kAfterUnloadReference
- kBeforeLoadReference
- kBeforeLoadReferenceAndRecordEdits
- kAfterLoadReference
- kAfterLoadReferenceAndRecordEdits
- 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
- kBeforeCreateReferenceAndRecordEdits
- kAfterCreateReference
- kAfterCreateReferenceAndRecordEdits

- kBeforeLoadReference
- kBeforeLoadReferenceAndRecordEdits
- kAfterLoadReference
- kAfterLoadReferenceAndRecordEdits

By default, edits to referenced objects will not be recorded during the execution of file I/O callbacks. A specific set of callbacks are provided that will enable the recording of reference edits during their execution as follows,

- kBeforeCreateReferenceAndRecordEdits
- kAfterCreateReferenceAndRecordEdits
- kBeforeLoadReferenceAndRecordEdits
- kAfterLoadReferenceAndRecordEdits

The kExportStarted callback is sent after the kBeforeExport callback, once Maya has actually started to process the exported data. One important difference between the two callbacks is that the fileInfo command affects the exported scene when used in the kExportStarted callback, but affects the current scene in memory when used in the kBeforeExport callback.

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:
  - MS::kSuccess Operation succeeded
  - MS::kInsufficientMemory No memory available
  - MS::kFailure Error adding callback

Examples:
  D3DViewportRendererPlugin.cpp, fileIOMsgCmd.cpp, hlslShader.cpp, hwAnisotropicShader_NV20.cpp, hwDecalBumpShader_NV20.cpp, hwPhongShader.cpp, hwReflectBumpShader_NV20.cpp, hwRefractReflectShader_NV20.cpp, hwToonShader_NV20.cpp, hwUnlitShader.cpp, pluginCallbacks.cpp, and pluginMain.cpp.

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

Search for all occurrences

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
  [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:
  - MS::kSuccess Operation succeeded
  - MS::kInsufficientMemory No memory available
  - MS::kFailure Error adding callback

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

Search for all occurrences

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
  [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:
  - MS::kSuccess Operation succeeded
  - MS::kInsufficientMemory No memory available
  - MS::kFailure Error adding callback

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

Search for all occurrences

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
  [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:
  - MS::kSuccess Operation succeeded
  - MS::kInsufficientMemory No memory available
  - MS::kFailure Error adding callback

MCallbackId addConnectionFailedCallback | ( | MMessage::MConnFailFunction | func,
|  | void * | clientData = `NULL`,
|  | MStatus * | ReturnStatus = `NULL`
| ) |  | `[static]`

Search for all occurrences

This method registers a callback that is called when a connection was unable to be made.

Currently, the callback is only triggered during the reading of files (.ma or .mb) or of edits files (.editMA or .editMB files created by Maya's offline file support). The most common reasons why a connection would fail are:

- inability to find the specified node or attribute names, or
- a conflicting existing connection

Parameters:

  [in] | func | the callback function srcPlug Source plug of the connection (or a NULL plug if it could not be found) destPlug Destination plug of the connection (or a NULL plug if it could not be found) srcPlugName Name used to look up the source plug. dstPlugName Name used to look up the destination plug. clientData User defined data passed to the callback function
  [in] | clientData | User defined data passed to the callback function
  [out] | ReturnStatus | status code

Returns:
  Identifier used for removing the callback.

Status Codes:
  - MS::kSuccess Operation succeeded
  - MS::kInsufficientMemory No memory available
  - MS::kFailure Error adding callback

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

Search for all occurrences

Returns the name of this class.

Returns:
  The name of this class.

Reimplemented from MMessage.

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

Search for all occurrences

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

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

Parameters:

  [in] | msg |
  [in] | func |
  [in] | clientData |
  [out] | ReturnStatus |

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

Search for all occurrences

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

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

Parameters:

  [in] | msg |
  [in] | func |
  [in] | clientData |
  [out] | ReturnStatus |

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

Search for all occurrences

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

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

Parameters:

  [in] | msg |
  [in] | func |
  [in] | clientData |
  [out] | ReturnStatus |

MSceneMessage MSceneMessage MSceneMessage MSceneMessage MSceneMessage MSceneMessage MSceneMessage MSceneMessage MSceneMessage MSceneMessage
MSceneMessage MSceneMessage MSceneMessage MSceneMessage MSceneMessage MSceneMessage MSceneMessage MSceneMessage MSceneMessage MSceneMessage