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

#include <MSceneMessage.h>

Inheritance diagram for MSceneMessage:

[legend]

Collaboration diagram for MSceneMessage:

[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

enum MSceneMessage::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.
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:

• MS::kSuccess Operation succeeded
• MS::kInsufficientMemory No memory available
• MS::kFailure Error adding callback

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

• MS::kSuccess Operation succeeded
• MS::kInsufficientMemory No memory available
• MS::kFailure Error adding callback

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:

• MS::kSuccess Operation succeeded
• MS::kInsufficientMemory No memory available
• MS::kFailure Error adding callback

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:

• MS::kSuccess Operation succeeded
• MS::kInsufficientMemory No memory available
• MS::kFailure Error adding callback

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.