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

#include <MNodeMessage.h>
Inheritance diagram for MNodeMessage:
Inheritance graph
[legend]
Collaboration diagram for MNodeMessage:
Collaboration graph
[legend]

List of all members.


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.


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)
static MCallbackId  addAttributeAddedOrRemovedCallback (MObject &node, MNodeMessage::MAttrPlugFunction func, void *clientData=NULL, MStatus *ReturnStatus=NULL)
static MCallbackId  addNodeDirtyCallback (MObject &node, MMessage::MNodeFunction func, void *clientData=NULL, MStatus *ReturnStatus=NULL)
  This method is obsolete. This method is not available in Python.
static MCallbackId  addNodeDirtyPlugCallback (MObject &node, MMessage::MNodePlugFunction func, void *clientData=NULL, MStatus *ReturnStatus=NULL)
static MCallbackId  addNameChangedCallback (MObject &node, MMessage::MNodeStringFunction func, void *clientData=NULL, MStatus *ReturnStatus=NULL)
  This method is obsolete. This method is not available in Python.
static MCallbackId  addNodeAboutToDeleteCallback (MObject &node, MMessage::MNodeModifierFunction func, void *clientData=NULL, MStatus *ReturnStatus=NULL)
  This method is obsolete. This method is not available in Python.
static MCallbackId  addNodePreRemovalCallback (MObject &node, MMessage::MNodeFunction func, void *clientData=NULL, MStatus *ReturnStatus=NULL)
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.

Member Typedef Documentation

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

Pointer to an AttributeMessage callback which takes two plugs.

Parameters:
[in]  msg  Type of message which caused the function to be called.
[in,out]  plug  First plug. Meaning depends upon the specific message which invoked the callback.
[in,out]  otherPlug  Second plug. Meaning depends upon the specific message which invoked the callback.
[in]  clientData  Pointer to user-defined data supplied when the callback was registered.

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

Pointer to an AttributeMessage callback which takes a single plug.

Parameters:
[in]  msg  Type of message which caused the function to be called.
[in,out]  plug  Meaning depends upon the specific message which invoked the callback.
[in]  clientData  Pointer to user-defined data supplied when the callback was registered.

typedef void(* MNodeMessage::MKeyableFunction)(MPlug &plug, void *clientData, MNodeMessage::KeyableChangeMsg msg, bool &decision)

Pointer to a change in keyability callback function.

Parameters:
[in,out]  plug  The plug whose keyability is changing.
[in]  clientData  Pointer to user-defined data supplied when the callback was registered.
[in]  msg  Specifies how the plug's keyability is changing.
[out]  decision  Callback 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 MNodeMessage::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]  node  the node to register the callback for
[in]  func  the callback function
  • 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
Parameters:
[in]  clientData  User defined data that will be passed to the callback function
[out]  ReturnStatus  status code
Returns:
Identifier used for removing the callback.
Status Codes:
Examples:

MCallbackId MNodeMessage::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]  node  the node to register the callback for
[in]  func  the callback function
  • 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
Parameters:
[in]  clientData  User defined data that will be passed to the callback function
[out]  ReturnStatus  status code
Returns:
Identifier used for removing the callback.
Status Codes:

MCallbackId MNodeMessage::addNodeDirtyCallback ( MObject node,
MMessage::MNodeFunction  func,
void *  clientData = NULL,
MStatus ReturnStatus = NULL  
) [static]

This method is obsolete. This method is not available in Python.

Deprecated:
Use the other MNodeMessage::addNodeDirtyCallback method instead.
This callback will not let you know which node is dirty.
Parameters:
[in]  node  the node to register the callback for
[in]  func  the callback function
[in]  clientData  User defined data passed to the callback
[out]  ReturnStatus  status code
Returns:
Identifier used for removing the callback.
Status Codes:
Registers a callback for node dirty messages.
Parameters:
[in]  node  the node to register the callback for
[in]  func  the callback function
  • node The node that has become dirty
  • clientData User defined data passed to the callback function
Parameters:
[in]  clientData  User defined data that will be passed to the callback function
[out]  ReturnStatus  status code
Returns:
Identifier used for removing the callback.
Status Codes:
Deprecated:
Use the other MNodeMessage::addNodeDirtyPlugCallback method instead.
Parameters:
[in]  node  The node to register the callback for.
[in]  func  The callback function.
[in]  clientData  User defined data passed to the callback.
[out]  ReturnStatus  Status code.
Examples:

MCallbackId MNodeMessage::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]  node  the node to register the callback for
[in]  func  the callback function
  • 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
Parameters:
[in]  clientData  User defined data that will be passed to the callback function
[out]  ReturnStatus  status code
Returns:
Identifier used for removing the callback.
Status Codes:

MCallbackId MNodeMessage::addNameChangedCallback ( MObject node,
MMessage::MNodeStringFunction  func,
void *  clientData = NULL,
MStatus ReturnStatus = NULL  
) [static]

This method is obsolete. This method is not available in Python.

Deprecated:
Use the version of MNodeMessage::addNameChangedCallback that has an MMessage::MNodeStringFunction as its callback type.
This callback will not let you know the previous name of the node.

Registers a callback for name changed messages.

Parameters:
[in]  node  the node. If this is a NULL MObject then the callback applies to all node name changes.
[in]  func  the callback function
  • node the node
  • clientData User defined data passed to the callback function
Parameters:
[in]  clientData  User defined data that will be passed to the callback function
[out]  ReturnStatus  status code
Returns:
Identifier used for removing the callback.
Status Codes:
Registers a callback for name changed messages.
Parameters:
[in]  node  the node. If this is a NULL MObject then the callback applies to all node name changes.
[in]  func  the callback function
  • node the node
  • prevName the previous name of the node
  • clientData User defined data passed to the callback function
Parameters:
[in]  clientData  User defined data that will be passed to the callback function
[out]  ReturnStatus  status code
Returns:
Identifier used for removing the callback.
Status Codes:
Examples:

MCallbackId MNodeMessage::addNodeAboutToDeleteCallback ( MObject node,
MMessage::MNodeModifierFunction  func,
void *  clientData = NULL,
MStatus ReturnStatus = NULL  
) [static]

This method is obsolete. This method is not available in Python.

Deprecated:
Use the version of MNodeMessage::addNodeAboutToDeleteCallback that has an MObject as the first argument.
This callback will not let you know which node is about to be deleted.
Parameters:
[in]  node  the node to register the callback for
[in]  func  the callback function
  • modifier DG modifier used to delete the node
  • clientData User defined data passed to the callback function
Parameters:
[in]  clientData  User defined data that will be passed to the callback function
[out]  ReturnStatus  status code
Returns:
Identifier used for removing the callback.
Status Codes:
Registers a callback which will get called when a node is about to be deleted.
The user 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. Note that MDGModifier::doIt() will get called automatically and does not need to be called in the callback.

The callback registered with this method will only get called when the deletion operation is first performed. If you also wish to receive notification of deletion events when they are redone, you should register an additional callback using addNodePreRemovalCallback().

Parameters:
[in]  node  the node to register the callback for
[in]  func  the callback function
  • node the node that will be deleted
  • modifier DG modifier used to delete the node
  • clientData User defined data passed to the callback function
Parameters:
[in]  clientData  User defined data that will be passed to the callback function
[out]  ReturnStatus  status code
Returns:
Identifier used for removing the callback.
Status Codes:
Examples:

MCallbackId MNodeMessage::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]  node  the node to register the callback for
[in]  func  the callback function
  • node the node that is being deleted
  • clientData User defined data passed to the callback function
Parameters:
[in]  clientData  User defined data that will be passed to the callback function
[out]  ReturnStatus  status code
Returns:
Identifier used for removing the callback.
Status Codes:
Examples:

MCallbackId MNodeMessage::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]  node  the node to register the callback for
[in]  func  the callback function
  • clientData User defined data passed to the callback function
Parameters:
[in]  clientData  User defined data that will be passed to the callback function
[out]  ReturnStatus  status code
Returns:
Identifier used for removing the callback.
Status Codes:

MCallbackId MNodeMessage::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]  plug  - The plug to attach the callback.
[in]  func  the callback function
  • plug - The plug that triggered the callback.
  • clientData - User defined data passed to the callback function.
  • eventType - Description of the event.
  • decision - Decision to accept the keyable state change, decision == 'true', or regect it, decision == 'false'.
Parameters:
[in]  clientData  User defined data passed back to the user.
[in]  ReturnStatus  status code
Status Codes:

Autodesk® Maya® 2011 © 1997-2010 Autodesk, Inc. All rights reserved. Generated with doxygen 1.5.6