MPxAssembly Class Reference

This reference page is linked to from the following overview topics: Extension for Autodesk Maya 2013.

---

Search for all occurrences

---

Detailed Description

Parent class of all user defined assembly nodes.

MPxAssembly is the parent class of all user defined assembly nodes. User defined assemblies are DAG nodes. An assembly allows activation of one of its representations. The implementation of representations is not specified by the MPxAssembly API: for example, a representation can be a data structure internal to the assembly implementation, identified by string name, or it can be a DAG node.

An assembly object is also a DAG container. As such, operations on containers can be done on assemblies.

This class can be used to implement new kinds of assembly nodes within Maya that integrate with Maya's scene assembly workflows.

For use of assemblies, see function set MFnAssembly. For use of container functionality on assemblies, see function set MFnContainerNode.

Deriving from MPxAssembly to Extend Scene Assembly

To extend Maya's scene assembly, you can write a dependency graph plug-in with an assembly node that is derived from MPxAssembly. The plug-in can be written either in C++ or in Python. A minimal scene assembly node must maintain a list of representations, and be able to activate one of them, inactivating the previous representation in the process.

An MPxAssembly derived node must be created with no representation active. In other words, after the MPxAssembly derived class constructor executes, the getActive() method must return the empty string. This is to ensure support for workflows where nested assembly hierarchies are expanded a single level at a time.

Fundamental Properties of Representations

The fundamental properties of a representation are the following:

Name

The MPxAssembly API refers to representations by string names, so the plug-in must have a correspondence between these names and its own representation data structures. The representation name is to be used in programming, should not be localized, and is not shown in the Maya UI.

Label

This is the representation property that is shown in the Maya UI to identify a representation to a user, and is the property that should be localized if desired.

Type

This representation property expresses commonality with other representations of the same type, and is used to control creation through createRepresentation(). It should not be localized.

Virtual Method Overrides

Here is a summary description of how to override MPxAssembly methods to implement a scene assembly node. The following MPxAssembly pure virtual methods must be overriden by even the most basic scene assembly node.

createRepresentation()

Use the type-dependent input, the representation type, and the given representation name to create a representation, and add it to the list of representations.

getActive()

Return the currently-active representation.

getRepresentations()

Return the list of representation names.

getRepType()

Return the type a representation.

getRepLabel()

Return the label of a representation.

repTypes()

Return the list of representation types that can be created.

deleteRepresentation()

Delete a representation from the list of representations.

deleteAllRepresentations()

Delete all representations.

setRepName()

Set a representation's name.

setRepLabel()

Set a representation's label.

activateRep()

Choose a representation to be active in the Maya scene, and inactivate the previously-active representation.

All other virtual methods have default implementations in MPxAssembly. Please refer to the documentation of these methods to determine if this default behavior is appropriate for your plug-in.

Non-Destructive Edit Tracking

Assembly nodes can track certain edits done on their members. These edits are non-destructive and recorded separately from the representation data onto which they are applied. Please see the Maya documentation for more details. Edits are a property of the assembly node, not of individual representations, and when switching active representations will be applied to a newly-activated representation if the representation can apply edits (see canRepApplyEdits()).

A plug-in node can opt in to the Maya edit tracking system simply by overriding supportsEdits() to return true.

To interact with edits once they have been created, see MItEdits.

Namespace Support

To avoid node name clashes on member nodes, each assembly node can optionally have a representation namespace, a namespace into which all nodes resulting from activating a representation will be placed. This representation namespace is always a child namespace of the namespace in which the assembly node itself has been placed. In the case of nested assemblies, this will produce a hierarchy of namespaces that matches the hierarchy of assemblies.

Without the use of namespaces, member node name clashes will be resolved by Maya adding a numerical suffix to clashing nodes. If an assembly node is tracking edits on its members, this name clash resolution will cause edits to fail, as edits are applied by name. Therefore, the use of representation namespaces is very strongly recommended when tracking assembly member edits.

Activate Support

An MPxAssembly derived class can completely override the activation of a representation (and therefore inactivation of the previously-active representation) provided by activate(). However, MPxAssembly provides the performActivate() and performInactivate() non-virtual methods as building blocks from which a derived class activate() method can be implemented. See the performActivate() and performInactivate() methods for a description of services that can be useful to derived class implementations of activate().

Assembly Integration into Maya

Once a derived assembly node type has been implemented, and registered into Maya's type system through MFnPlugin::registerNode(), it should be registered to the assembly command as an available assembly node type. See the assembly command documentation for more details.

Top-Level Assemblies versus Nested Assemblies

Assembly nodes can be created inside a hierarchy of assemblies. An assembly can be nested inside another assembly; the nested assembly is a DAG child of its parent assembly. MFnAssembly::getParentAssembly() and MFnAssembly::getSubAssemblies() can be used to efficiently navigate the hierarchy of assembly nodes. Nested assemblies are created through the activation of a representation on their parent assembly.

An assembly node that does not have an assembly parent is called a top-level assembly. It is created through file I/O (either opening a file, or importing a file at the top level), or through scripting. Top-level assemblies have special properties:

• Top-level assemblies are saved as part of the Maya file being edited (the top-level Maya file). Nested assemblies are not saved in the top-level Maya file. They are created by their parent assembly, and are saved elsewhere, or created procedurally by their parent's activation code.
• Top-level assemblies collect and store all non-destructive edits made to nodes under their DAG hierarchy while editing the top-level Maya file. Nested assemblies can contain edits which will be applied to nodes under their DAG hierarchy, but these edits are read-only and cannot be changed or deleted, only overridden. In contrast, edits on top-level assemblies can be added and deleted. In a hierarchy of assembly nodes, the application of edits is also hierarchical: edits from leaf assemblies are applied first, followed by parent edits, and so on, ending at the top-level assemblies. When edits are made to the same Maya data structure from multiple levels in the hierarchy, parent edits override child edits.
• Top-level assemblies created through scripting are not initialized by Maya through postLoad(). Nested assemblies are always initialized by Maya through postLoad(), and top-level assemblies created by file I/O are initialized by Maya, but top-level assemblies created through scripting are not, and the script should call postLoad() on the assembly, if required.

#include <MPxAssembly.h>

Inheritance diagram for MPxAssembly:

List of all members.

Public Member Functions
	MPxAssembly ()
	Class constructor.
virtual	~MPxAssembly ()
	Class destructor.
virtual MPxNode::Type	type () const
	Returns the type of node that this is.
virtual MString	createRepresentation (const MString &input, const MString &type, const MString &representation, MDagModifier *undoRedo=NULL, MStatus *ReturnStatus=NULL)=0
	Create a representation and add it to the list of representations.
virtual bool	activate (const MString &representation)
	Activate a representation in the list of representations.
virtual MString	getActive () const =0
	Get the active representation in the list of representations.
virtual bool	isActive (const MString &representation) const
	Determines whether the argument representation is the active representation.
virtual MStringArray	getRepresentations (MStatus *ReturnStatus=NULL) const =0
	Returns an array of the representations managed by the node attached to this function set.
virtual MString	getRepType (const MString &representation) const =0
	Get the type of the argument representation.
virtual MString	getRepLabel (const MString &representation) const =0
	Get the label of the argument representation.
virtual MStringArray	repTypes () const =0
	Return the list of representation types that can be created for this assembly node.
virtual MStatus	deleteRepresentation (const MString &representation)=0
	Delete a representation managed by the node.
virtual MStatus	deleteAllRepresentations ()=0
	Delete all representations managed by this node.
virtual MString	getRepNamespace () const
	Get the representations namespace of this assembly node.
virtual void	updateRepNamespace (const MString &repNamespace)
	This method is called by Maya to tell the assembly that the base representation namespace specified by getRepNamespace() has been changed.
virtual MString	setRepName (const MString &representation, const MString &newName, MStatus *ReturnStatus=NULL)=0
	Rename a representation.
virtual MStatus	setRepLabel (const MString &representation, const MString &label)=0
	Change the representation label.
virtual bool	supportsEdits () const
	Opt in/out of Maya's edit tracking system.
virtual bool	supportsMemberChanges () const
	Can members of the assembly be changed?
virtual bool	canRepApplyEdits (const MString &representation) const
	Determines whether the given representation can apply edits to its data.
virtual bool	handlesApplyEdits () const
	Determines whether the assembly handles the application of edits to its data, for the node attached to this function set.
virtual MStatus	applyEdits (MObject &target, MItEdits &edits)
	Apply edits to assembly data.
virtual bool	handlesAddEdits () const
	Determines whether the assembly is responsible for supplying edits to its data.
virtual MStatus	addEdits ()
	Add edits so they can be applied by Maya when switching representations.
virtual void	beforeSave ()
	Method called by Maya to allow assemblies to do any required preparation before file save.
virtual void	postLoad ()
	Method called by Maya to initialize assemblies after their creation.
virtual void	memberAdded (MObject &member)
	Called immediately after the argument node has been added to this assembly.
virtual void	memberRemoved (MObject &member)
	Called immediately after the argument node has been removed from this assembly.
bool	performActivate (const MString &representation)
	Provide access to the Maya core representation activation functionality.
bool	performInactivate ()
	Provide access to the Maya core representation inactivation functionality.
virtual bool	activateRep (const MString &representation)=0
	Called during activation to activate the new active representation.
virtual bool	inactivateRep ()
	Called during activation to inactivate the currently active representation.
virtual void	preApplyEdits ()
	Method called by performActivate() just before edits are applied.
virtual void	preUnapplyEdits ()
	Method called by performInactivate() just before edits are unapplied.
virtual MString	getInitialRep (const MObject &assembly, MStatus *ReturnStatus=NULL) const
virtual MString	getInitialRep (const MObject &assembly, bool &hasInitialRep, MStatus *ReturnStatus=NULL) const
	Get the initial representation to use when the specified assembly is first loaded.
bool	activating () const
	Return true when this assembly is activating a representation, within a call to activate() or activateNonRecursive().
MTypeId	typeId () const
	Returns the TYPEID of this node.
MString	typeName () const
	Returns the type name of this node.
MString	name () const
	Returns the name of this particular instance of this class.
MObject	thisMObject () const
	Returns the MObject associated with this user defined node.
MStatus	setExistWithoutInConnections (bool flag)
	This method specifies whether or not the node can exist without input connections.
bool	existWithoutInConnections (MStatus *ReturnStatus=NULL) const
	Determines whether or not this node can exist without input connections.
MStatus	setExistWithoutOutConnections (bool flag)
	This method specifies whether or not the node can exist without output connections.
bool	existWithoutOutConnections (MStatus *ReturnStatus=NULL) const
	Determines whether or not this node can exist without output connections.
MStatus	addSetAttrEdit (const MString &targetAssembly, const MString &plugName, const MString &parameters, MPxEditData *editData=NULL)
	Add a set attribute edit to be applied by Maya when switching representations.
MStatus	addConnectAttrEdit (const MString &targetAssembly, const MString &srcPlugName, const MString &dstPlugName, MPxEditData *editData=NULL)
	Add a connect attribute edit to be applied by Maya when switching representations.
MStatus	addDisconnectAttrEdit (const MString &targetAssembly, const MString &srcPlugName, const MString &dstPlugName, MPxEditData *editData=NULL)
	Add a disconnect attribute edit to be applied by Maya when switching representations.
MStatus	addDeleteAttrEdit (const MString &targetAssembly, const MString &nodeName, const MString &attributeName, MPxEditData *editData=NULL)
	Add a delete attribute edit to be applied by Maya when switching representations.
MStatus	addAddAttrEdit (const MString &targetAssembly, const MString &nodeName, const MString &longAttributeName, const MString &shortAttributeName, const MString &parameters, MPxEditData *editData=NULL)
	Add an add attribute edit to be applied by Maya when switching representations.
MStatus	addParentEdit (const MString &targetAssembly, const MString &childNodeName, const MString &parentNodeName, const MString &parameters, MPxEditData *editData=NULL)
	Add a parent edit to be applied by Maya when switching representations.
Static Public Member Functions
static const char *	className ()
	Returns the name of this class.
Protected Member Functions
virtual MDataBlock	forceCache (MDGContext &ctx=MDGContext::fsNormal)
	USE _forceCache() IN SCRIPT.
virtual void	setMPSafe (bool flag)
	USE _setMPSafe() IN SCRIPT.
virtual MStatus	setDoNotWrite (bool flag)
	USE _setDoNotWrite() IN SCRIPT.
virtual bool	doNotWrite (MStatus *ReturnStatus=NULL) const
	USE _doNotWrite() IN SCRIPT.

---

Constructor & Destructor Documentation

MPxAssembly

(

)

Class constructor.

Any calls to the MPxAssembly methods must be done in the postConstructor method and not here.

---

Member Function Documentation

MPxNode::Type type

(

)

const [virtual]

Search for all occurrences

Returns the type of node that this is.

This is used to differentiate user defined nodes that are derived off different MPx base classes.

It is not necessary to override this method.

Returns:

Type of the node (MPxNode::kAssembly)

Reimplemented from MPxNode.

MString createRepresentation	(	const MString &	input,
		const MString &	type,
		const MString &	representation,
		MDagModifier *	undoRedo = NULL,
		MStatus *	ReturnStatus = NULL
	)		[pure virtual]

Search for all occurrences

Create a representation and add it to the list of representations.

The input argument string is used as input data to the representation creation process. The semantics of this input are defined by the assembly derived class.

If passed in non-empty, the representation argument is used as a starting point for the representation name. This string value can be modified by the derived implementation to meet representation name uniqueness, or other constraints. If empty, the implementation is responsible for creating the representation name. The final representation name is returned by this method, after it has been added to the assembly.

If non-null, the pointer to an MDagModifier object can be used to help implement undo / redo for createRepresentation(): its redoIt() and undoIt() methods can be called in an MPxCommand. Note that MDagModifier can execute an arbitrary command through MDGModifier::commandToExecute().

Parameters:

[in]	input	Input data for representation creation.
[in]	type	Type of representation to create.
[in]	representation	Representation name starting point.
[out]	undoRedo	Pointer to MDagModifier object, for undo / redo purposes.
[out]	ReturnStatus	Return status.

Returns:

Added representation name.

Status Codes:

• MS::kSuccess Representation addition succeeded. All other status codes indicate failure.

bool activate

(

const MString &

representation

)

[virtual]

Search for all occurrences

Activate a representation in the list of representations.

Derived implementations should inactivate the currently-active representation, if any, activate the newly-active representation, and return true for success. If the argument representation is not in the list of this node's representations, this method should return false. Passing in an empty string argument means inactivate the previously-active representation (if any), activate no representation, and return true.

The default implementation does the following:

  // If the argument representation is not an empty string, check that
  // it is one of the assembly's representations.  If not, return false.

  // Perform the activation by inactivating the previously-active
  // representation, and activating the new one.
  if (performInactivate()) {
     return performActivate(representation);
  }
  return false;

See performInactivate() and performActivate() documentation for more details.

If you have opted into Maya's edit tracking system by overriding MPxAssembly::supportsEdits() to return true, you must call performActivate() and performInactivate() from within your implementation of activate() to get proper edit handling behaviour. This will ensure that edits are properly saved and restored when you switch representations.

Parameters:

[in]

representation

Representation to activate.

Returns:

Whether activation of the argument representation was successful or not.

MString getActive

(

)

const [pure virtual]

Search for all occurrences

Get the active representation in the list of representations.

Derived implementations should return the active representation, if any, else an empty string. If the list of representations is empty, the return object should be an empty string.

Returns:

The active representation, if any, else an empty string.

bool isActive

(

const MString &

representation

)

const [virtual]

Search for all occurrences

Determines whether the argument representation is the active representation.

The default implementation compares the argument representation to the result of getActive().

Parameters:

[in]

representation

Representation to query.

Returns:

true if the argument is active, false otherwise.

MStringArray getRepresentations

(

MStatus *

ReturnStatus = NULL

)

const [pure virtual]

Search for all occurrences

Returns an array of the representations managed by the node attached to this function set.

Parameters:

[out]

ReturnStatus

Return status

Returns:

representations array.

Status Codes:

• MS::kSuccess The method was successful to get the representations.
• MS::kFailure The method failed to get the representations.

MString getRepType

(

const MString &

representation

)

const [pure virtual]

Search for all occurrences

Get the type of the argument representation.

The type of a representation is a string that expresses its commonality with other representations of this assembly type. The type string does not have to be user-readable, and does not have to be localized; the type label should be used for UI purposes. If the argument representation is not found in this assembly, an empty string is returned.

Parameters:

[in]

representation

Representation whose type must be returned.

Returns:

Representation type.

MString getRepLabel

(

const MString &

representation

)

const [pure virtual]

Search for all occurrences

Get the label of the argument representation.

The label of a representation is a string that is meant to be shown in the UI and identify the representation meaningfully to a user. The representation label should support localization requirements. If the argument representation is not found in this assembly, an empty string is returned.

Parameters:

[in]

representation

Representation whose label must be returned.

Returns:

Representation label.

MStringArray repTypes

(

)

const [pure virtual]

Search for all occurrences

Return the list of representation types that can be created for this assembly node.

This can be a fixed list of representation types, or it can vary according to the state of the assembly node. For example, an assembly node might only want to allow one representation of a given type, so repTypes() could be used to enforce that constraint.

Returns:

Array of representation types.

MStatus deleteRepresentation

(

const MString &

representation

)

[pure virtual]

Search for all occurrences

Delete a representation managed by the node.

Parameters:

[in]

representation

Representation to delete.

Returns:

Return status.

Status Codes:

• MS::kSuccess The method successfully deleted the representation.
• MS::kFailure The method failed to delete the representation.

MStatus deleteAllRepresentations

(

)

[pure virtual]

Search for all occurrences

Delete all representations managed by this node.

Returns:

Return status.

Status Codes:

• MS::kSuccess The method successfully deleted all representations.
• MS::kFailure The method failed to delete all representations.

MString getRepNamespace

(

)

const [virtual]

Search for all occurrences

Get the representations namespace of this assembly node.

This is the namespace where nodes created by the activation of a representation will be added. This namespace is shared by all representations. The name can be updated by Maya if a name clash occurs when the namespace is added to its parent namespace (see MPxAssembly::updateRepNamespace() for details).

The default implementation returns a namespace formatted as follows: assembly base name appended with the '_NS' prefix. The plugin could decide to not support namespaces by returning an empty string.

Returns:

Namespace for representations.

void updateRepNamespace

(

const MString &

repNamespace

)

[virtual]

Search for all occurrences

This method is called by Maya to tell the assembly that the base representation namespace specified by getRepNamespace() has been changed.

Parameters:

[in]

repNamespace

New namespace for representations.

MString setRepName	(	const MString &	representation,
		const MString &	newName,
		MStatus *	ReturnStatus = NULL
	)		[pure virtual]

Search for all occurrences

Rename a representation.

The newName argument is used as a starting point for the new representation name. This string value can be modified by the derived implementation to meet representation name uniqueness, or other constraints. This method returns the final representation name.

Parameters:

[in]	representation	Current representation name.
[in]	newName	New representation name starting point.
[out]	ReturnStatus	Return status.

Returns:

New representation name.

Status Codes:

• MS::kSuccess The method successfully renamed the representation.
• MS::kFailure The method failed to rename the representation.

MStatus setRepLabel	(	const MString &	representation,
		const MString &	label
	)		[pure virtual]

Search for all occurrences

Change the representation label.

Parameters:

[in]	representation	Representation name.
[in]	label	New representation label.

Returns:

Return status.

Status Codes:

• MS::kSuccess The method successfully changed the representation label.
• MS::kFailure The method failed to change the representation label.

bool supportsEdits

(

)

const [virtual]

Search for all occurrences

Opt in/out of Maya's edit tracking system.

Override this method to return true if you want your assembly to support tracking of edits to its member nodes.

The edits system is node-based and only representations that have Maya nodes can handle tracking. Only certain types of edits can be tracked (see MItEdits for more details).

Use the MItEdits interface to manage/query edits generated by the edits system.

The default implementation returns false, so edits are not tracked.

Returns:

Whether to track edits on member nodes or not.

bool supportsMemberChanges

(

)

const [virtual]

Search for all occurrences

Can members of the assembly be changed?

If the assembly does not use Maya's edit tracking system (see supportsEdits()), does it support changes to its member nodes, outside of activation? If so, this means that any mutating operation on Maya nodes (parenting, connecting, disconnecting, renaming, deleting, setting attributes, adding attributes, removing attributes, locking) can be performed on member nodes of the assembly.

This method is only used if supportsEdits() returns false. If supportsEdits() returns true, Maya will track edits to assembly members, and the return value of supportsMemberChanges() will have no meaning.

The default implementation returns false, so that any mutating operation to member nodes of the assembly is prevented, and the assembly behaves as a read-only container of nodes. Override this method to return true if the assembly supports changes to its member nodes, e.g. if it implements its own edit tracking system without using Maya's.

This predicate is only used outside of representation activation. During activation, all types of changes to the assembly's members are allowed, including of course deleting the previous representation's nodes, and creating nodes for the new representation.

bool canRepApplyEdits

(

const MString &

representation

)

const [virtual]

Search for all occurrences

Determines whether the given representation can apply edits to its data.

The default implementation returns false.

Parameters:

[in]

representation

Representation to query.

Returns:

true if the representation can apply tracked edits, false otherwise.

bool handlesApplyEdits

(

)

const [virtual]

Search for all occurrences

Determines whether the assembly handles the application of edits to its data, for the node attached to this function set.

If this method returns true, Maya will call applyEdits() to apply edits, when a representation for which canRepApplyEdits() returns true is made active. If this method returns false, Maya will apply the edits itself.

The implementation in this class returns false, so Maya applies edits, and applyEdits() is not called.

Returns:

true if the assembly will apply edits, false if Maya applies the edits.

MStatus applyEdits	(	MObject &	target,
		MItEdits &	edits
	)		[virtual]

Search for all occurrences

Apply edits to assembly data.

If handlesApplyEdits() returns true, this method is called by Maya to apply edits to an assembly's data, which can include nested sub-assemblies.

See MFnAssembly::handlesApplyEdits() for examples of where this functionality can be useful.

Edits are attribute and connection changes that are to be applied to the assembly's data. An assembly that returns true from the supportsEdits() method will cause Maya to track such changes on any node inside the assembly, including inside nested assemblies. On representation activation, Maya will apply any edits that affect nodes in the representation. In scenes with nested assemblies, Maya will apply edits from most nested assembly to least nested assembly, so that the edits in the outer assemblies have precedence over more nested assembly edits.

To apply edits in the assembly, rather than having Maya apply edits, handlesApplyEdits() must return true, and this method must be implemented to loop over the list of edits in the edits argument, interpret each edit, and apply it to the assembly data. The assembly can choose not to apply an edit; each edit's applied status should be set using MEdit::setApplied(). If the edit was applied, but failed, its failed status should be set using MEdits::setFailed().

A successful return status from this method does not mean that all edits were applied successfully, or even that all edits were applied: it simply means that the assembly performed the application of edits as it intended. An implementation of this method must set the applied and failed state on each argument edit, which Maya will then query after application is done.

This method will be called by Maya on the top-level assembly at the time the edit was made. This is the assembly that "owns" the edit, and that stored the edit in the top-level file when it was made. An edit changes data in an assembly's representation, which might include a nested assembly's data. The target argument indicates the assembly which directly encloses the edit's data, which will be either the owner assembly node itself, if the edit is done to a node directly contained by the owner assembly, or to a sub-assembly of the owner assembly.

The implementation in this class returns failure, but should never be called, as the implementation of handlesApplyEdits() in this class returns false.

Parameters:

[in]	target	The innermost assembly holding the edited nodes.
[in,out]	edits	Edits to be applied.

Returns:

Return status.

Status Codes:

• MS::kSuccess Process of applying edits was performed as intended. All other status codes indicate failure.

bool handlesAddEdits

(

)

const [virtual]

Search for all occurrences

Determines whether the assembly is responsible for supplying edits to its data.

If this method returns true, Maya will call MPxAssembly::addEdits(). These edits will later be applied, either by Maya, or by the assembly through MPxAssembly::applyEdits(), if MPxAssembly::handlesApplyEdits() returns true.

Edits can be added for any node in the assembly's representations, which includes edits to any nested assembly of this assembly. In a scene with multiple levels of nested assemblies, if more than one nested assembly has edits to a given lower-level nested assembly, edits are applied by Maya starting at the most nested assembly level, moving up the chain of nesting assemblies. In this way, the most nested assembly's edit are overridden by less nested assembly edits, if they edit the same attribute or connection.

Returns:

true if the assembly adds edits, false if no edits are added.

MStatus addEdits

(

)

[virtual]

Search for all occurrences

Add edits so they can be applied by Maya when switching representations.

This method is called by Maya to allow an assembly node to provide edits to be applied at each representation switch. These edits will later be applied, either by Maya, or by the assembly through MPxAssembly::applyEdits(), if MPxAssembly::handlesApplyEdits() returns true.

Edits can be added for any node in the assembly's representations, which includes edits to any nested assembly of this assembly. In a scene with multiple levels of nested assemblies, if more than one nested assembly has edits to a given lower-level nested assembly, edits are applied by Maya starting at the most nested assembly level, moving up the chain of nesting assemblies. In this way, the most nested assembly's edit are overridden by less nested assembly edits, if they edit the same attribute or connection.

In the event that edits have already been added to this assembly (e.g. from a Maya scene representation), the new edits will simply be added to the list.

To add edits for a node, the plugin must call the methods addSetAttrEdit(), addConnectAttrEdit(), addDisconnectAttrEdit(), addDeleteAttrEdit(), and addAddAttrEdit(), as appropriate, for each edit to be added. An assembly should only add edits that it owns, and not those of nested assemblies: those will be queried by Maya separately. The assembly on which an edit is added is referred to as the edit owner.

The methods for adding edits require a targetAssembly name to be specified. The targetAssembly name is the most enclosing assembly holding the edited node. The targetAssembly is always specified as a node name relative to the namespace of this parent assembly (i.e. the edit owner) on which the method is being called.

To specify a relative node name that is in a namespace at or above the parent assembly namespace, a special syntax of "..:" is incorporated to indicate the parent namespace without explicitly naming it.

Use of this convention is necessary when the targetAssembly is the same as the parent assembly. The targetAssembly name in this case would be the same as the parent assembly name and would be specified as "..:parentAssemblyName".

A similar convention is used for specifying node names that reside in the parent assembly namespace, for example to specify the destination attribute for an edit, the format "..:parentAssemblyNamespace:nodeName.attr"

The implementation in this class returns MS::kFailure.

Returns:

Return status.

Status Codes:

• MS::kSuccess The method succeeded.
• MS::kFailure No valid node attached to function set.

void beforeSave

(

)

[virtual]

Search for all occurrences

Method called by Maya to allow assemblies to do any required preparation before file save.

It is called by Maya on top-level assemblies that are about to be saved, before the file I/O operation is actually performed.

Note that if this assembly supports edit tracking, any changes made within beforeSave() will not be recorded as edits.

Default implementation is to do nothing.

void postLoad

(

)

[virtual]

Search for all occurrences

Method called by Maya to initialize assemblies after their creation.

It is called on top-level assemblies after file I/O has completed, and on nested assemblies after the representation that contains them has finished activating. Maya does not call the postLoad() method when creating a node directly through the assembly command; it will only do so in two cases, (1) after file I/O (top-level assemblies only), or (2) after activation (nested assemblies only).

Note how this is later than MPxNode::postConstructor(), which is called immediately after the node has been created. For example, if the assembly is created through file I/O, the file I/O operation that created the node in the scene is not complete at the point of the postConstructor() call.

In contrast, in our example, postLoad() is called after the file I/O operation (open, import) is done, so a postLoad() implementation can itself issue file I/O operations with the knowledge that previous I/O operations have completed.

Note that if this assembly supports edit tracking, any changes made within postLoad() will be considered part of the setup process for the assembly and will not be recorded as edits.

MPxAssembly::postLoad() should never be called directly. Always use MFnAssembly::postLoad(), to ensure that Maya's internal postLoad() initialization is invoked before MPxAssembly::postLoad() is called.

An implementation of postLoad() should check MFnAssembly::canActivate() to determine whether it can activate a representation. See MFnAssembly::activateNonRecursive() for more details.

Default implementation is to do nothing.

void memberAdded

(

MObject &

member

)

[virtual]

Search for all occurrences

Called immediately after the argument node has been added to this assembly.

Default implementation does nothing.

Parameters:

[in]

member

Newly-added member node.

void memberRemoved

(

MObject &

member

)

[virtual]

Search for all occurrences

Called immediately after the argument node has been removed from this assembly.

Default implementation does nothing.

Parameters:

[in]

member

Newly-removed member node.

bool performActivate

(

const MString &

representation

)

Search for all occurrences

Provide access to the Maya core representation activation functionality.

This is useful to plugins overriding the default activate() method; see the activate() documentation for more details. A plugin implementing its own activate() method should call performActivate() when activating the newly-active representation to ensure it obtains the Maya services it needs.

The core representation activation functionality will call activateRep(). It will then initialize any nested assembly created by the activation using postLoad(), and will finally apply edits to the activated representation. If the postLoad() implementation of the newly-created nested assemblies calls activate(), this will recurse into performActivate() for the nested assembly.

Any changes made during performActivate() will not be tracked as edits, so that activating a representation will not generate spurious edits. Furthermore, performActivate() is not constrained to only those operations supported by edit tracking, so that node adds, deletes and renames are allowed, as expected.

Parameters:

[in]

representation

Representation to activate.

Returns:

true for success, false for failure.

bool performInactivate

(

)

Search for all occurrences

Provide access to the Maya core representation inactivation functionality.

This is useful to plugins overriding the default activate() method; see the activate() documentation for more details. A plugin implementing its own activate() method should call performInactivate() when inactivating the currently-active representation to ensure it obtains the Maya services it needs.

The core representation inactivation functionality performs the exact reverse of performActivate(). It first unapplies edits to the currently-active representation. It then loops over all nested assemblies (if any) and recursively calls performInactivate() on each. Finally, it calls inactivateRep().

Any changes made during performInactivate() will not be tracked as edits, so that inactivating a representation will not generate spurious edits. Furthermore, performInactivate() is not constrained to only those operations supported by edit tracking, so that node adds, deletes and renames are allowed, as expected.

Returns:

true for success, false for failure.

MStatus activateRep

(

const MString &

representation

)

[pure virtual]

Search for all occurrences

Called during activation to activate the new active representation.

See activate() documentation for more details.

Parameters:

[in]

representation

Representation name.

Returns:

true for success, false for failure.

bool inactivateRep

(

)

[virtual]

Search for all occurrences

Called during activation to inactivate the currently active representation.

See activate() documentation for more details.

The default implementation clears out all nodes in the assembly. Derived assembly node types that wish to change this behavior (e.g. hide nodes rather than removing them) should override this method.

Returns:

true for success, false for failure.

void preApplyEdits

(

)

[virtual]

Search for all occurrences

Method called by performActivate() just before edits are applied.

This method is called by performActivate() after the new representation has been activated with activateRep(), after any newly-created nested assemblies have been initialized with postLoad(), but just before edits are applied to this assembly (and any nested assemblies).

A use of this method might be to manage the assembly's list of edits before they are applied, perhaps adding edits.

The default implementation does nothing.

void preUnapplyEdits

(

)

[virtual]

Search for all occurrences

Method called by performInactivate() just before edits are unapplied.

This method is called by performInactivate() before unapplying edits, before any nested assemblies are inactivated, and before the current representation is inactivated with inactivateRep(). Therefore, when this call is made, no change has been made to the currently-active representation.

A use of this method might be to manage the assembly's list of edits before they are unapplied, perhaps removing edits. Any removed edit will be unapplied first, which can be done safely because the current representation has not been inactivated yet.

The default implementation does nothing.

MString getInitialRep	(	const MObject &	assembly,
		MStatus *	ReturnStatus = NULL
	)		const [virtual]

Search for all occurrences

Deprecated:

Use the method MPxAssembly::getInitialRep(const MObject&, bool& , MStatus* ) instead

Get the initial representation to use when the specified assembly is first loaded.

This method can be customized by the assembly implementation to determine which representation should be activated when an assembly is first initialized. An empty string should be returned if no initial representation has been determined.

This method should not be called directly - individual assemblies should always call MFnAssembly::getInitialRep(). When an assembly requests its initial representation, Maya will internally locate the associated top level assembly node and invoke this method on it to return the actual representation to use.

This base class defines no implementation and will unconditionally return an empty string. Derived implementations can override this method to customize this behaviour. Maya ensures that this method will only be called on top level assemblies.

Parameters:

[in]	assembly	The assembly for which the initial representation is being requested
[out]	ReturnStatus	Return status

Returns:

The initial representation to use, if any, else an empty string.

Status Codes:

• MS::kSuccess The method successfully completed
• MS::kFailure The method encountered a failure condition

MString getInitialRep	(	const MObject &	assembly,
		bool &	hasInitialRep,
		MStatus *	ReturnStatus = NULL
	)		const [virtual]

Search for all occurrences

Get the initial representation to use when the specified assembly is first loaded.

This method can be customized by the assembly implementation to determine which representation should be activated when an assembly is first initialized. The hasInitialRep return argument must be set to false if no initial representation has been determined. Returning an empty string with hasInitialRep true means the initial active representation for the assembly should be no representation.

This method should not be called directly - individual assemblies should always call MFnAssembly::getInitialRep(). When an assembly requests its initial representation, Maya will internally locate the associated top level assembly node and invoke this method on it to return the actual representation to use.

This base class defines no implementation, sets the hasInitialRep return argument to false, and returns an empty string. Derived implementations can override this method to customize this behaviour. Maya ensures that this method will only be called on top level assemblies.

Parameters:

[in]	assembly	The assembly for which the initial representation is being requested
[out]	hasInitialRep	Return whether or not we have an initial representation
[out]	ReturnStatus	Return status

Returns:

The initial representation to use, if any, else an empty string.

Status Codes:

• MS::kSuccess The method successfully completed
• MS::kFailure The method encountered a failure condition

const char * className

(

)

[static]

Search for all occurrences

Returns the name of this class.

Returns:

The name of this class.

Reimplemented from MPxNode.

bool activating

(

)

const

Search for all occurrences

Return true when this assembly is activating a representation, within a call to activate() or activateNonRecursive().

Reset to false just before initializing nested assemblies (through postLoad()) and applying edits. This can be used to implement activation-specific behavior for the assembly.

Returns:

true if the assembly is activating a representation, false otherwise.

MTypeId typeId

(

)

const [virtual]

Search for all occurrences

Returns the TYPEID of this node.

The TYPEID is a four byte identifier that uniquely identifies this type of node to the binary file format.

It is not necessary to override this method.

Returns:

Type id of the node

Reimplemented from MPxNode.

MString typeName

(

)

const [virtual]

Search for all occurrences

Returns the type name of this node.

The type name identifies the node type to the ASCII file format. It may also be used with the MEL command "createNode" to create a new node of this type.

It is not necessary to override this method.

Returns:

Type name of the node

Reimplemented from MPxNode.

MString name

(

)

const [virtual]

Search for all occurrences

Returns the name of this particular instance of this class.

Each object in the dependency graph has a name. This name will be used by the UI and by MEL.

It is not necessary to override this method.

Returns:

Type id of the node

Reimplemented from MPxNode.

MObject thisMObject

(

)

const [virtual]

Search for all occurrences

Returns the MObject associated with this user defined node.

This makes it possible to use MFnDependencyNode or to construct plugs to this node's attributes.

It is not necessary to override this method.

Returns:

MObject handle for this node

Reimplemented from MPxNode.

MStatus setExistWithoutInConnections

(

bool

flag

)

[virtual]

Search for all occurrences

This method specifies whether or not the node can exist without input connections.

If a node connected to this node is deleted resulting in no more input connections and if this flag is false, then this node will be deleted.

Parameters:

[in]

flag

true if this node can exist without input connections, false otherwise

Status Codes:

• MS::kSuccess operation successful
• MS::kFailure this MPxNode has not been initialized properly. Make sure this method is not being called from the constructor.

Reimplemented from MPxNode.

bool existWithoutInConnections

(

MStatus *

ReturnStatus = NULL

)

const [virtual]

Search for all occurrences

Determines whether or not this node can exist without input connections.

If a node connected to this node is deleted resulting in no more input connections and if this flag is false, then this node will be deleted.

Parameters:

[out]

ReturnStatus

Status code.

Returns:

true is this node can exist without input connections, false otherwise

Status Codes:

• MS::kSuccess operation successful
• MS::kFailure this MPxNode has not been initialized properly. Make sure this method is not being called from the constructor.

Reimplemented from MPxNode.

MStatus setExistWithoutOutConnections

(

bool

flag

)

[virtual]

Search for all occurrences

This method specifies whether or not the node can exist without output connections.

If a node connected to this node is deleted resulting in no more output connections and if this flag is false, then this node will be deleted.

Parameters:

[in]

flag

true if this node can exist without output connections, false otherwise

Status Codes:

• MS::kSuccess operation successful
• MS::kFailure this MPxNode has not been initialized properly. Make sure this method is not being called from the constructor.

Reimplemented from MPxNode.

bool existWithoutOutConnections

(

MStatus *

ReturnStatus = NULL

)

const [virtual]

Search for all occurrences

Determines whether or not this node can exist without output connections.

If a node connected to this node is deleted resulting in no more output connections and if this flag is false, then this node will be deleted.

Parameters:

[out]

ReturnStatus

Status code.

Returns:

true is this node can exist without output connections, false otherwise

Status Codes:

• MS::kSuccess operation successful
• MS::kFailure this MPxNode has not been initialized properly. Make sure this method is not being called from the constructor.

Reimplemented from MPxNode.

MStatus addSetAttrEdit	(	const MString &	targetAssembly,
		const MString &	plugName,
		const MString &	parameters,
		MPxEditData *	editData = NULL
	)

Search for all occurrences

Add a set attribute edit to be applied by Maya when switching representations.

This method is intended to be called by the plugin's addEdits() method, to add a set attribute edit. The set attribute edit is implemented with the setAttr command, so the full generality of setAttr command options is possible.

The targetAssembly name is specified relative to this assembly. Refer to the addEdits() method documentation for more information about specifying the targetAssembly for edits.

The plugName is in "nodeName.attr" format, and is specified relative to this assembly. Refer to the addEdits() method documentation for more information about specifying relative node names for edits.

The editData is an optional user data element that can be associated with this edit. The object must be dynamically allocated. Ownership of the editData will be assumed by Maya and subsequent management of the data object, including its eventual deletion will be handled along with the edit it is associated with. For this reason, an editData object should only be associated with a single edit, the same object should not be shared or associated with other edits. If multiple edits have editData of the same value, each edit must have its own unique copy.

Parameters:

[in]	targetAssembly	The most enclosing assembly holding the edited node.
[in]	plugName	The name of the node and attr, in "nodeName.attr" syntax.
[in]	parameters	Parameters to be added to the setAttr command, in MEL syntax.
[in]	editData	Optional user-defined data to be associated with the edit

Returns:

Return status.

Status Codes:

• MS::kSuccess The edit was successfully added
• MS::kFailure The edit was not successfully added

MStatus addConnectAttrEdit	(	const MString &	targetAssembly,
		const MString &	srcPlugName,
		const MString &	dstPlugName,
		MPxEditData *	editData = NULL
	)

Search for all occurrences

Add a connect attribute edit to be applied by Maya when switching representations.

This method is intended to be called by the plugin's addEdits() method, to add a connect attribute edit.

The targetAssembly name is specified relative to this assembly. Refer to the addEdits() method documentation for more information about specifying the targetAssembly for edits.

The srcPlugName and dstPlugName are in "nodeName.attr" format, and are specified relative to this assembly. Refer to the addEdits() method documentation for more information about specifying relative node names for edits.

Note that the targetAssembly for connections is determined by the destination plug of the connection.

The editData is an optional user data element that can be associated with this edit. The object must be dynamically allocated. Ownership of the editData will be assumed by Maya and subsequent management of the data object, including its eventual deletion will be handled along with the edit it is associated with. For this reason, an editData object should only be associated with a single edit, the same object should not be shared or associated with other edits. If multiple edits have editData of the same value, each edit must have its own unique copy.

Parameters:

[in]	targetAssembly	The most enclosing assembly holding the destination plug node.
[in]	srcPlugName	The name of the node and attribute that are the source of the connection, in "nodeName.attr" syntax.
[in]	dstPlugName	The name of the node and attribute that are the destination of the connection, in "nodeName.attr" syntax.
[in]	editData	Optional user-defined data to be associated with the edit

MStatus addDisconnectAttrEdit	(	const MString &	targetAssembly,
		const MString &	srcPlugName,
		const MString &	dstPlugName,
		MPxEditData *	editData = NULL
	)

Search for all occurrences

Add a disconnect attribute edit to be applied by Maya when switching representations.

This method is intended to be called by the plugin's addEdits() method, to add a disconnect attribute edit.

The targetAssembly name is specified relative to this assembly. Refer to the addEdits() method documentation for more information about specifying the targetAssembly for edits.

The srcPlugName and dstPlugName are in "nodeName.attr" format, and are specified relative to this assembly. Refer to the addEdits() method documentation for more information about specifying relative node names for edits.

Note that the targetAssembly for disconnections is determined by the destination plug of the connection.

The editData is an optional user data element that can be associated with this edit. The object must be dynamically allocated. Ownership of the editData will be assumed by Maya and subsequent management of the data object, including its eventual deletion will be handled along with the edit it is associated with. For this reason, an editData object should only be associated with a single edit, the same object should not be shared or associated with other edits. If multiple edits have editData of the same value, each edit must have its own unique copy.

Note: it is recommended that a disconnectAttrEdit be followed by a setAttrEdit on the destination plug to ensure it is set to a predictable value after disconnection.

Parameters:

[in]	targetAssembly	The most enclosing assembly holding the destination plug node.
[in]	srcPlugName	The name of the node and attribute that are the source of the connection, in "nodeName.attr" syntax.
[in]	dstPlugName	The name of the node and attribute that are the destination of the connection, in "nodeName.attr" syntax.
[in]	editData	Optional user-defined data to be associated with the edit

MStatus addDeleteAttrEdit	(	const MString &	targetAssembly,
		const MString &	nodeName,
		const MString &	attributeName,
		MPxEditData *	editData = NULL
	)

Search for all occurrences

Add a delete attribute edit to be applied by Maya when switching representations.

This method is intended to be called by the plugin's addEdits() method, to insert an edit that will remove a dynamic attribute from a node.

The targetAssembly name and nodeName are specified relative to this assembly. Refer to the addEdits() method documentation for more information about specifying the targetAssembly and relative node names for edits.

The editData is an optional user data element that can be associated with this edit. The object must be dynamically allocated. Ownership of the editData will be assumed by Maya and subsequent management of the data object, including its eventual deletion will be handled along with the edit it is associated with. For this reason, an editData object should only be associated with a single edit, the same object should not be shared or associated with other edits. If multiple edits have editData of the same value, each edit must have its own unique copy.

Parameters:

[in]	targetAssembly	The most enclosing assembly holding the affected node.
[in]	nodeName	The name of the node that the attribute will be removed from.
[in]	attributeName	The long name or short name of the attribute to be removed.
[in]	editData	Optional user-defined data to be associated with the edit

MStatus addAddAttrEdit	(	const MString &	targetAssembly,
		const MString &	nodeName,
		const MString &	longAttributeName,
		const MString &	shortAttributeName,
		const MString &	parameters,
		MPxEditData *	editData = NULL
	)

Search for all occurrences

Add an add attribute edit to be applied by Maya when switching representations.

This method is intended to be called by the plugin's addEdits() method, to insert an edit that will add a dynamic attribute to a node.

The targetAssembly name and nodeName are specified relative to this assembly. Refer to the addEdits() method documentation for more information about specifying the targetAssembly and relative node names for edits.

The parameters value is used to specify additional arguments to the addAttr command, such as the attribute type or data type information. Refer to the addAttr command for additional information.

The editData is an optional user data element that can be associated with this edit. The object must be dynamically allocated. Ownership of the editData will be assumed by Maya and subsequent management of the data object, including its eventual deletion will be handled along with the edit it is associated with. For this reason, an editData object should only be associated with a single edit, the same object should not be shared or associated with other edits. If multiple edits have editData of the same value, each edit must have its own unique copy.

Note: it is recommended that an addAttrEdit be followed by a setAttrEdit on the new attribute to ensure it is initialized to a predictable and valid value.

Parameters:

[in]	targetAssembly	The most enclosing assembly holding the affected node.
[in]	nodeName	The name of the node that the attribute will be added to.
[in]	longAttributeName	The long name of the attribute to be added.
[in]	shortAttributeName	The short name of the attribute to be added.
[in]	parameters	Parameters to be added to the addAttr command, in MEL syntax.
[in]	editData	Optional user-defined data to be associated with the edit

MStatus addParentEdit	(	const MString &	targetAssembly,
		const MString &	childNodeName,
		const MString &	parentNodeName,
		const MString &	parameters,
		MPxEditData *	editData = NULL
	)

Search for all occurrences

Add a parent edit to be applied by Maya when switching representations.

This method is intended to be called by the plugin's addEdits() method, to insert an edit that will create a parenting relationship between two nodes.

The targetAssembly name, parentNodeName and childNodeName are specified relative to this assembly. Refer to the addEdits() method documentation for more information about specifying the targetAssembly and relative node names for edits.

The parameters value is used to specify additional arguments to the parent command such as relative or shape. Refer to the parent command for additional information.

Parent edits are only allowed between main-scene nodes and nodes in an assembly. The targetAssembly for parenting is determined depending on which of the nodes (parent or child) is inside an assembly. There are two kinds of parent edits, parent-in and parent-out:

  A parent-in is when we have:

  A:nodeInAssembly
  |_ nodeInMain

  And the targetAssembly would be "A"

  Parent-out is when we have:

  nodeInMain
  |_ A:nodeInAssembly

  And the targetAssembly would be "A"

  We could have also created a parent edit between a deeply-nested node 
  and a main-scene node. In this case, we have something like

  A:B:nodeInAssembly
  |_ mainSceneNode

  And targetAssembly would be "B" in this case.

The editData is an optional user data element that can be associated with this edit. The object must be dynamically allocated. Ownership of the editData will be assumed by Maya and subsequent management of the data object, including its eventual deletion will be handled along with the edit it is associated with. For this reason, an editData object should only be associated with a single edit, the same object should not be shared or associated with other edits. If multiple edits have editData of the same value, each edit must have its own unique copy.

Parameters:

[in]	targetAssembly	The most enclosing assembly holding the affected node.
[in]	childNodeName	The name of the child node being parented
[in]	parentNodeName	The name of the parent node
[in]	parameters	Parameters to be added to the parent command, in MEL syntax.
[in]	editData	Optional user-defined data to be associated with the edit

MDataBlock forceCache

(

MDGContext &

context = MDGContext::fsNormal

)

[protected, virtual]

Search for all occurrences

USE _forceCache() IN SCRIPT.

Get the datablock for this node.

If there is no datablock then one will be created. NOTE: This should be used only in places where fast access to the datablock outside of a compute is critical such as the transformUsing method of MPxSurfaceShape.

Parameters:

[in]

context

The context in which the node will evaluate.

Returns:

The datablock

Reimplemented from MPxNode.

void setMPSafe

(

bool

flag

)

[protected, virtual]

Search for all occurrences

USE _setMPSafe() IN SCRIPT.

Set a flag to specify if a user defined shading node is safe for multi-processor rendering.

For a shading node to be MP safe, it cannot access any shared global data and should only use attributes in the datablock to get input data and store output data.

This flag does NOT mark a node thread safe for parallel DG evaluation in Viewport 2.0. To mark a node thread safe for parallel DG evaluation see the setNodeTypeFlag mel command.

NOTE: This should be called from the postConstructor() method for shading node plug-ins only. If a shading node is non-safe, then it will only be useful during single processor rendering.

Parameters:

[in]

flag

True if user node is safe, false if non-safe.

Reimplemented from MPxNode.

MStatus setDoNotWrite

(

bool

flag

)

[protected, virtual]

Search for all occurrences

USE _setDoNotWrite() IN SCRIPT.

Use this method to mark the "do not write" state of this proxy node.

If set, this node will not be saved when the Maya model is written out.

NOTES: 1. Plug-in "requires" information will be written out with the model when saved. But a subsequent reload and resave of the file will cause these to go away. 2. If this node is a DAG and has a parent or children, the "do not write" flag of the parent or children will not be set. It is the developer�s responsibility to ensure that the resulting scene file is capable of being read in without errors due to unwritten nodes.

Parameters:

[in]

flag

True if the user node should not be saved.

Reimplemented from MPxNode.

bool doNotWrite

(

MStatus *

ReturnStatus = NULL

)

const [protected, virtual]

Search for all occurrences

USE _doNotWrite() IN SCRIPT.

Use this method to query the "do not write" state of this proxy node.

True is returned if this node will not be saved when the Maya model is written out.

Parameters:

[out]

ReturnStatus

Reimplemented from MPxNode.