MSceneMessage Class Reference

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:

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, 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 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
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
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
• kBeforeExport
• kExportStarted
• 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

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:

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]

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

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

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

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

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