Public Types | Static Public Member Functions

MNodeMessage Class Reference

This reference page is linked to from the following overview topics: Differences between the Maya .NET API and the Maya C++ API, Example C++ plug-in descriptions.


Search for all occurrences

Detailed Description

Dependency node messages.

This class is used to register callbacks for dependency node messages of specific dependency nodes.

There are 4 add callback methods which will add callbacks for the following messages

The first parameter passed to each of the add callback methods is the depenency node that will trigger the callback.

Callbacks that are registered for attribute changed/addedOrRemoved messages will be passed an AttributeMessage value as a parameter. This value indicates the type of attribute message that has occurred. See the AttributeMessage enum for all available messages.

Each method returns an id which 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 <MNodeMessage.h>

Inheritance diagram for MNodeMessage:
Inheritance graph
[legend]

List of all members.

Public Types

enum  AttributeMessage {
  kConnectionMade = 0x01, kConnectionBroken = 0x02, kAttributeEval = 0x04, kAttributeSet = 0x08,
  kAttributeLocked = 0x10, kAttributeUnlocked = 0x20, kAttributeAdded = 0x40, kAttributeRemoved = 0x80,
  kAttributeRenamed = 0x100, kAttributeKeyable = 0x200, kAttributeUnkeyable = 0x400, kIncomingDirection = 0x800,
  kAttributeArrayAdded = 0x1000, kAttributeArrayRemoved = 0x2000, kOtherPlugSet = 0x4000, kLast = 0x8000
}
 

The type of attribute changed/addedOrRemoved messages that has occurred.

More...
enum  KeyableChangeMsg { kKeyChangeInvalid = 0, kMakeKeyable, kMakeUnkeyable, kKeyChangeLast }
 

Allows you to prevent attributes from becoming (un)keyable.

More...
typedef void(* MAttr2PlugFunction )(MNodeMessage::AttributeMessage msg, MPlug &plug, MPlug &otherPlug, void *clientData)
 Pointer to an AttributeMessage callback which takes two plugs.
typedef void(* MAttrPlugFunction )(MNodeMessage::AttributeMessage msg, MPlug &plug, void *clientData)
 Pointer to an AttributeMessage callback which takes a single plug.
typedef void(* MKeyableFunction )(MPlug &plug, void *clientData, MNodeMessage::KeyableChangeMsg msg, bool &decision)
 Pointer to a change in keyability callback function.

Static Public Member Functions

static MCallbackId addAttributeChangedCallback (MObject &node, MNodeMessage::MAttr2PlugFunction func, void *clientData=NULL, MStatus *ReturnStatus=NULL)
 This method registers a callback for attribute changed messages.
static MCallbackId addAttributeAddedOrRemovedCallback (MObject &node, MNodeMessage::MAttrPlugFunction func, void *clientData=NULL, MStatus *ReturnStatus=NULL)
 Registers callbacks for attribute add/removed messages.
static MCallbackId addNodeDirtyCallback (MObject &node, MMessage::MNodeFunction func, void *clientData=NULL, MStatus *ReturnStatus=NULL)
 Registers a callback for node dirty messages.
static MCallbackId addNodeDirtyPlugCallback (MObject &node, MMessage::MNodePlugFunction func, void *clientData=NULL, MStatus *ReturnStatus=NULL)
 Registers a callback for node dirty messages.
static MCallbackId addNameChangedCallback (MObject &node, MMessage::MNodeStringFunction func, void *clientData=NULL, MStatus *ReturnStatus=NULL)
 Registers a callback for name changed messages.
static MCallbackId addNodeAboutToDeleteCallback (MObject &node, MMessage::MNodeModifierFunction func, void *clientData=NULL, MStatus *ReturnStatus=NULL)
 Registers a callback which will get called when a node is about to be deleted.
static MCallbackId addNodePreRemovalCallback (MObject &node, MMessage::MNodeFunction func, void *clientData=NULL, MStatus *ReturnStatus=NULL)
 Registers a callback which will get called before a node is deleted.
static MCallbackId addNodeDestroyedCallback (MObject &node, MMessage::MBasicFunction func, void *clientData=NULL, MStatus *ReturnStatus=NULL)
 NodeDestroyed callback.
static MCallbackId addKeyableChangeOverride (MPlug &plug, MNodeMessage::MKeyableFunction func, void *clientData=NULL, MStatus *status=NULL)
 Attribute keyable state change override.
static const char * className ()
 Returns the name of this class.

Member Typedef Documentation

typedef void(* MAttr2PlugFunction)(MNodeMessage::AttributeMessage msg, MPlug &plug, MPlug &otherPlug, void *clientData)

Pointer to an AttributeMessage callback which takes two plugs.

Parameters:
[in]msgType of message which caused the function to be called.
[in,out]plugFirst plug. Meaning depends upon the specific message which invoked the callback.
[in,out]otherPlugSecond plug. Meaning depends upon the specific message which invoked the callback.
[in]clientDataPointer to user-defined data supplied when the callback was registered.
typedef void(* MAttrPlugFunction)(MNodeMessage::AttributeMessage msg, MPlug &plug, void *clientData)

Pointer to an AttributeMessage callback which takes a single plug.

Parameters:
[in]msgType of message which caused the function to be called.
[in,out]plugMeaning depends upon the specific message which invoked the callback.
[in]clientDataPointer to user-defined data supplied when the callback was registered.
typedef void(* MKeyableFunction)(MPlug &plug, void *clientData, MNodeMessage::KeyableChangeMsg msg, bool &decision)

Pointer to a change in keyability callback function.

Parameters:
[in,out]plugThe plug whose keyability is changing.
[in]clientDataPointer to user-defined data supplied when the callback was registered.
[in]msgSpecifies how the plug's keyability is changing.
[out]decisionCallback sets this true to accept the change, false to reject it.

Member Enumeration Documentation

The type of attribute changed/addedOrRemoved messages that has occurred.

Enumerator:
kConnectionMade 

a connection has been made to an attribute of this node

kConnectionBroken 

a connection has been broken for an attribute of this node

kAttributeEval 

an attribute of this node has been evaluated

kAttributeSet 

an attribute value of this node has been set

kAttributeLocked 

an attribute of this node has been locked

kAttributeUnlocked 

an attribute of this node has been unlocked

kAttributeAdded 

an attribute has been added to this node

kAttributeRemoved 

an attribute has been removed from this node

kAttributeRenamed 

an attribute of this node has been renamed

kAttributeKeyable 

an attribute of this node has been marked keyable

kAttributeUnkeyable 

an attribute of this node has been marked unkeyable

kIncomingDirection 

the connection was coming into the node

kAttributeArrayAdded 

an array attribute has been added to this node

kAttributeArrayRemoved 

an array attribute has been removed from this node

kOtherPlugSet 

the otherPlug data has been set

kLast 

last value of the enum

Allows you to prevent attributes from becoming (un)keyable.

Enumerator:
kKeyChangeInvalid 

 

kMakeKeyable 

 

kMakeUnkeyable 

 

kKeyChangeLast 

 


Member Function Documentation

MCallbackId addAttributeChangedCallback ( MObject node,
MNodeMessage::MAttr2PlugFunction  func,
void *  clientData = NULL,
MStatus ReturnStatus = NULL 
) [static]

This method registers a callback for attribute changed messages.

See the AttributeChanged enum for a list of all possible messages that will trigger the callback.

Note: Attribute Changed messages will not be generated while Maya is either in playback or scrubbing modes. If you need to do something during playback or scrubbing you will have to register a callback for the timeChanged message which is the only message message that is sent during those modes.

The callback function will be passed the type of attribute message that has occurred, the plug(s) for the attributes, and any client data that the user wishes to pass in.

Example callback ( prints out a message when a connection is made or broken ) :

    void userCB( MNodeMessage::AttributeMessage msg, MPlug & plug,
                 MPlug & otherPlug, void* )
    {
        if ( msg & MNodeMessage::kConnectionMade ) {
            cout << "Connection made ";
        } else if ( msg & MNodeMessage::kConnectionBroken ) {
            cout << "Connection broken ";
        } else {
            return;
        }
        cout << plug.info();
        if  ( msg & MNodeMessage::kOtherPlugSet ) {
            if ( msg & MNodeMessage::kIncomingDirection ) {
                cout << "  <--  " << otherPlug.info();
            } else {
                cout << "  -->  " << otherPlug.info();
            }
        }
        cout << endl;
    }
Parameters:
[in]nodethe node to register the callback for
[in]functhe callback function, which takes the following parameters:
  • msg the kind of attribute change triggering the callback
  • plug the node's plug where the connection changed
  • otherPlug the plug opposite the node's plug where the connection changed
  • clientData User defined data passed to the callback function
[in]clientDataUser defined data that will be passed to the callback function
[out]ReturnStatusstatus code
Returns:
Identifier used for removing the callback.
Status Codes:
Examples:
cgfxShaderNode.cpp, D3DResourceManager.cpp, and nodeMessageCmd.cpp.
MCallbackId addAttributeAddedOrRemovedCallback ( MObject node,
MNodeMessage::MAttrPlugFunction  func,
void *  clientData = NULL,
MStatus ReturnStatus = NULL 
) [static]

Registers callbacks for attribute add/removed messages.

This is a more specific version of addAttributeChanged as only attribute added and attribute removed messages will trigger the callback.

Parameters:
[in]nodethe node to register the callback for
[in]functhe callback function, which takes the following parameters:
  • msg the kind of attribute change triggering the callback
  • plug the node's plug where the connection changed
  • clientData User defined data passed to the callback function
[in]clientDataUser defined data that will be passed to the callback function
[out]ReturnStatusstatus code
Returns:
Identifier used for removing the callback.
Status Codes:
Examples:
cgfxShaderNode.cpp.
MCallbackId addNodeDirtyCallback ( MObject node,
MMessage::MNodeFunction  func,
void *  clientData = NULL,
MStatus ReturnStatus = NULL 
) [static]

Registers a callback for node dirty messages.

Parameters:
[in]nodethe node to register the callback for
[in]functhe callback function, which takes the following parameters:
  • node The node that has become dirty
  • clientData User defined data passed to the callback function
[in]clientDataUser defined data that will be passed to the callback function
[out]ReturnStatusstatus code
Returns:
Identifier used for removing the callback.
Status Codes:
Examples:
D3DResourceManager.cpp, NodeMonitor.cpp, and ShapeMonitor.cpp.
MCallbackId addNodeDirtyPlugCallback ( MObject node,
MMessage::MNodePlugFunction  func,
void *  clientData = NULL,
MStatus ReturnStatus = NULL 
) [static]

Registers a callback for node dirty messages.

This callback provides the plug on the node that was dirtied. Only provides dirty information on input plugs.

Parameters:
[in]nodethe node to register the callback for
[in]functhe callback function, which takes the following parameters:
  • node The node that has become dirty
  • plug The plug on the node that has become dirty
  • clientData User defined data passed to the callback function
[in]clientDataUser defined data that will be passed to the callback function
[out]ReturnStatusstatus code
Returns:
Identifier used for removing the callback.
Status Codes:
MCallbackId addNameChangedCallback ( MObject node,
MMessage::MNodeStringFunction  func,
void *  clientData = NULL,
MStatus ReturnStatus = NULL 
) [static]

Registers a callback for name changed messages.

Parameters:
[in]nodethe node. If this is a NULL MObject then the callback applies to all node name changes.
[in]functhe callback function, which takes the following parameters:
  • node the node
  • prevName the previous name of the node
  • clientData User defined data passed to the callback function
[in]clientDataUser defined data that will be passed to the callback function
[out]ReturnStatusstatus code
Returns:
Identifier used for removing the callback.
Status Codes:
Examples:
NodeMonitor.cpp, and ShapeMonitor.cpp.
MCallbackId addNodeAboutToDeleteCallback ( MObject node,
MMessage::MNodeModifierFunction  func,
void *  clientData = NULL,
MStatus ReturnStatus = NULL 
) [static]

Registers a callback which will get called when a node is about to be deleted.

The callback will be passed the MDGModifer that will be used to delete the node. This modifier can be used to do any DG modifications, such as disconnections, before the node is deleted. These operations are also stored and performed when the deletion operation is undone or redone.

The callback registered with this method will only get called when the deletion operation is first performed. Undos and redos will be handled solely through the MDGModifier which was passed to the callback on the original deletion. If you also wish to receive notification of deletion events when they are redone, you should register an additional callback using addNodePreRemovalCallback().

When a node is deleted Maya automatically breaks all connections to that node. This process takes place after the callback has been called. This means that if you use the passed-in MDGModifier to break any connections to the node you must be sure to call the modifier's doIt() method before returning from the callback. Otherwise Maya will see that the connections still exist and try to delete them again, which can lead to errors.

The example below shows a callback function which takes the connection coming into the node's input attribute and reconnects it to all of the plugs connected to the node's output attribute:

import maya.OpenMaya as om

def rewire(node, dgmod, data):
    nodefn = om.MFnDependencyNode(node)
    try:
        # Find the input plug.
        inPlug = nodefn.findPlug('input')

        # Get the incoming connections.
        srcs = om.MPlugArray()
        inPlug.connectedTo(srcs, True, False)

        if srcs.length() > 0:
            srcPlug = srcs[0]

            outPlug = nodefn.findPlug('output')
            dests = om.MPlugArray()
            outPlug.connectedTo(dests, False, True)

            if dests.length() > 0:
                # Now that we know we have a valid flow-through
                # connection, disconnect the source from this node.
                dgmod.disconnect(srcPlug, inPlug)

                # Disconnect all of destinations from this node.
                for i in range(dests.length()):
                    dgmod.disconnect(outPlug, dests[i])

                # Force our disconnections to be done now.
                dgmod.doIt()

                # Make a direct connection from the source to each of
                # the destinations.
                for i in range(dests.length()):
                    dgmod.connect(srcPlug, dests[i])
    except:
        # This node does not have an 'input' plug, or does not have
        # an 'output' plug, so let's ignore it.
        pass

Note that it uses the passed-in MDGModifier to perform all the disconnections and connections. This ensures that if the deletion is undone or redone then all of the connections will be restored correctly.

After it is done breaking connections, the callback calls the modifier's doIt() method to commit those disconnections. As noted above, this is necessary to ensure that Maya doesn't see the connections and try to break them again later on.

Parameters:
[in]nodethe node to register the callback for
[in]functhe callback function, which takes the following parameters:
  • node the node that will be deleted
  • modifier DG modifier used to delete the node
  • clientData User defined data passed to the callback function
[in]clientDataUser defined data that will be passed to the callback function
[out]ReturnStatusstatus code
Returns:
Identifier used for removing the callback.
Status Codes:
Examples:
D3DResourceManager.cpp, and deletedMsgCmd.cpp.
MCallbackId addNodePreRemovalCallback ( MObject node,
MMessage::MNodeFunction  func,
void *  clientData = NULL,
MStatus ReturnStatus = NULL 
) [static]

Registers a callback which will get called before a node is deleted.

This callback is called before connections on the node are removed. Unlike the aboutToDelete callback, this callback will be invoked whenever the node is deleted, even during a redo.

Pre-removal and aboutToDelete callbacks serve different purposes. If DG changes need to be made when a node is deleted, the aboutToDelete callback should be used to add undoable operations to an MDGModifier to perform these changes. When the desired actions cannot be accomplished using the MDGModifier passed to the aboutToDelete callback, this callback can be used to receive notification of the deletion event, even during redo.

Note that this callback method should not perform any DG operations.

Parameters:
[in]nodethe node to register the callback for
[in]functhe callback function, which takes the following parameters:
  • node the node that is being deleted
  • clientData User defined data passed to the callback function
[in]clientDataUser defined data that will be passed to the callback function
[out]ReturnStatusstatus code
Returns:
Identifier used for removing the callback.
Status Codes:
Examples:
deletedMsgCmd.cpp.
MCallbackId addNodeDestroyedCallback ( MObject node,
MMessage::MBasicFunction  func,
void *  clientData = NULL,
MStatus ReturnStatus = NULL 
) [static]

NodeDestroyed callback.

Registers a callback which will get called when a node's destructor is called.

Parameters:
[in]nodethe node to register the callback for
[in]functhe callback function, which takes the following parameters:
  • clientData User defined data passed to the callback function
[in]clientDataUser defined data that will be passed to the callback function
[out]ReturnStatusstatus code
Returns:
Identifier used for removing the callback.
Status Codes:
MCallbackId addKeyableChangeOverride ( MPlug plug,
MNodeMessage::MKeyableFunction  func,
void *  clientData = NULL,
MStatus ReturnStatus = NULL 
) [static]

Attribute keyable state change override.

This method registers a callback that is invoked by any class that changes the keyable state of an attribute.

When the callback is invoked, the API programmer can make a decision on how to handle the given keyable change event. The programmer can either accept the the keyable state change by returning a decision == 'true' or reject it by returning decision == 'false'.

Note: you can only attach one callback keyable change override callback per attribute. It is an error to attach more than one callback to the same attribute.

Parameters:
[in]plugThe plug to which to attach the callback.
[in]functhe callback function, which takes the following parameters:
  • plug - The plug that triggered the callback.
  • clientData - User defined data passed to the callback function.
  • eventType - Description of the event.
  • decision - Return true to accept the keyable state change or false to reject it.
[in]clientDataUser defined data passed back to the user.
[in]ReturnStatusstatus code
Status Codes:
const char * className ( ) [static]

Returns the name of this class.

Returns:
The name of this class.

Reimplemented from MMessage.


MNodeMessage MNodeMessage MNodeMessage MNodeMessage MNodeMessage MNodeMessage MNodeMessage MNodeMessage MNodeMessage MNodeMessage
MNodeMessage MNodeMessage MNodeMessage MNodeMessage MNodeMessage MNodeMessage MNodeMessage MNodeMessage MNodeMessage MNodeMessage