Public Types | Static Public Member Functions

MSceneMessage Class Reference

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:
Inheritance graph
[legend]

List of all members.

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,
  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

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.

kExportStarted 

Called at the start of a File > Export operation, after the export file has become the active file.

kBeforeLoadReferenceAndRecordEdits 

Same as kBeforeLoadReference except reference edits are recorded during the execution of the callback.

kAfterLoadReferenceAndRecordEdits 

Same as kAfterLoadReference except reference edits are recorded during the execution of the callback.

kBeforeCreateReferenceAndRecordEdits 

Same as kBeforeCreateReference except reference edits are recorded during the execution of the callback.

kAfterCreateReferenceAndRecordEdits 

Same as kAfterCreateReference except reference edits are recorded during the execution of the callback.

kLast 

Last value of the enum.


Member Function Documentation

MCallbackId 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
  • 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]msgthe scene message that will trigger the callback
[in]functhe callback function
  • clientData User defined data passed to the callback function
[in]clientDatauser data that will be passed to the callback function
[out]ReturnStatusStatus code
Returns:
Identifier used for removing the callback.
Status Codes:
Examples:
AshliPluginMain.cpp, 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]

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]msgthe scene message that will trigger the callback
[in]functhe 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]clientDatauser data that will be passed to the callback function
[out]ReturnStatusStatus code
Returns:
Identifier used for removing the callback.
Status Codes:
MCallbackId 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]msgthe scene message that will trigger the callback
[in]functhe 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]clientDatauser data that will be passed to the callback function
[out]ReturnStatusStatus code
Returns:
Identifier used for removing the callback.
Status Codes:
MCallbackId 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]msgthe scene message that will trigger the callback
[in]functhe callback function
  • strs immutable array of strings
  • clientData User defined data passed to the callback function
[in]clientDatauser data that will be passed to the callback function
[out]ReturnStatusStatus code
Returns:
Identifier used for removing the callback.
Status Codes:
MCallbackId addConnectionFailedCallback ( MMessage::MConnFailFunction  func,
void *  clientData = NULL,
MStatus ReturnStatus = NULL 
) [static]

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 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]functhe 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]clientDataUser defined data passed to the callback function
[out]ReturnStatusstatus code
Returns:
Identifier used for removing the callback.
Status Codes:
const char * className ( ) [static]

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]

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]

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]

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