lockEvent.cpp

//-
// ==========================================================================
// Copyright 1995,2006,2008 Autodesk, Inc. All rights reserved.
//
// Use of this software is subject to the terms of the Autodesk
// license agreement provided at the time of installation or download,
// or which otherwise accompanies this software in either electronic
// or hard copy form.
// ==========================================================================
//+

// lockEvent.cpp 
// 
// This plug-in demonstrates the API callbacks for node and plug locking. 
// These callbacks allow you to receive notification when the locked 
// status of a plug or node is queried internally. The API programmer has 
// option, upon receipt of the callback, to 'override' the lock state of 
// node or plug.  This is 'override' is controlled via a 'decision' variable 
// passed into the callback function.  The variable can hold two values 
//
//  1) decision = true  --> You want to accept the lock state and do  
//     whatever the internal default behavior is. 
//  2) decision = false --> You want to deny the lock state and do the
//     opposite of what Maya would usually do. 
//
// The flow of execution would be as follows ... 
//
// 1) Received a callback from Maya.  
// 2) What kind of event is this?
// 3) Do I want to allow this event?
// |-- 4) Yes, I do not want to OVERRIDE this event. decision = true.
// |-- 4) No, I want to OVERRIDE this event. decision = false.
// 5) Return from callback.  
//
//
// Example usage: 
//   sphere ; 
//
//   // Watch the translateX plug on the sphere we just created ...
//   lockEvent -a 3 nurbsSphere1.translateX; 
//   // Do not allow any changes to the plug. 
//   lockEvent -o true 
//
//   // Now you can try changes nurbsSphere1.translateX 's value 
//   // but you will not be allowed to do so.  
//   // 
//   setAttr "nurbsSphere1.translateX" 22
//


#include <maya/MIOStream.h>
#include <maya/MString.h> 
#include <maya/MArgList.h> 
#include <maya/MFnPlugin.h> 
#include <maya/MPxCommand.h> 
#include <maya/MSyntax.h> 
#include <maya/MArgDatabase.h> 
#include <maya/MMessage.h> 
#include <maya/MLockMessage.h> 
#include <maya/MObject.h> 
#include <maya/MSelectionList.h> 
#include <maya/MFn.h> 
#include <maya/MItSelectionList.h> 
#include <maya/MFnDependencyNode.h> 
#include <maya/MStringArray.h> 
#include <maya/MString.h>
#include <maya/MGlobal.h> 
#include <maya/MDagPath.h> 
#include <maya/MCallbackIdArray.h>

// Macro Definitions 
//
#define MEL_COMMAND_NAME  "lockEvent"
#define VENDOR_TAG                "Autodesk"
#define PLUGIN_VERSION    "1.0"

#define checkStdError(stat,msg)         \
    if ( MS::kSuccess != stat ) {       \
                cerr << msg;                    \
                return MS::kFailure;    \
    }

// Flags 
//

// Clear the registered callbacks ... 
//
#define kClearCBLong      "-clearCB" 
#define kClearCB          "-ccb" 
#define kClearCBDV                false

// Toggle the override flag. Dictates if we should 
// obey the lock or override the lock 
// 
#define kOverrideLong     "-override"
#define kOverride         "-o"
#define kOverrideDV       false  

// Attach a new callback to a node. 
// 
#define kAttachLong       "-attach"
#define kAttach           "-a"
#define kAttachDV         0

// Macro used to save a little typing 
//
#define MLM               MLockMessage

// Class Definition 
//
class lockEvent : public MPxCommand 
{
public: 
    lockEvent( ); 
    virtual ~lockEvent( ); 
    
    MStatus        doIt( const MArgList & ); 
    MStatus        parseArgs( const MArgList &args ); 
        MCallbackId    installCallback( MItSelectionList & ); 
        static MSyntax newSyntax( );    
    static void*   creator( ); 

        // Clear callback ids 
        static bool    clearCallbackIds();

private: 
        MSelectionList theList; 
        unsigned int fAttach;
        bool fOverrideFlag, fOverrideVal, fClearCB; 
}; 

static MCallbackIdArray callbackIds; 
static bool overrideMode = false; 

// Callback for DAG locking events. 
// 
void lockDagDecision( MDagPath &path, MDagPath &other, 
                                          void *clientData, MLM::LockDAGEvent,
                                          bool &decision ); 

// Other, node related events ..  
// 
void lockDecision( MObject &node, MObject &aux, 
                                   void *clientData, MLM::LockEvent, 
                                   bool &decision ); 

// Events relating to plugs. 
// 
void plugDecision( MPlug &p1, MPlug &p2, 
                                   void *clientData, MLM::LockPlugEvent, 
                                   bool &decision ); 

// Callback for global watchers (i.e. watch all plugs on a node).
//
void nodePlugDecision( MPlug &p1, MPlug &p2, 
                                                void *clientData, MLM::LockPlugEvent, 
                                                bool &decision ); 

// Standard API entry and exit points. 
//
MStatus initializePlugin( MObject obj );
MStatus uninitializePlugin( MObject obj );

// -------- 
// METHODS 
// 

lockEvent::lockEvent( ) : 
        fOverrideFlag(kOverrideDV), 
        fOverrideVal(false),
        fAttach(kAttachDV)
{
}

lockEvent::~lockEvent( ) 
{
}

MCallbackId lockEvent::installCallback( MItSelectionList &iter )
// 
// Description: 
//  Uses given iterator and callback type to attach a new callback on
//  a node, dag path, or plug. The selection iterator must contain a
//  valid selection item for the target callback type (fAttach). That is, 
//  if the callback type is three, then the iterator must contain 
//  a dependency node on it the next list item. 
//
{
        MStatus status; 

        MCallbackId id = 0; 
        MObject node, component; 
        MDagPath path; 

        switch (fAttach) { 
        case 1: { 
                status = iter.getDependNode( node ); 
                if ( status ) { 
                        // Try to set the callback. Note: we check the status
                        // flag at the end of the switch statement. 
                        // 
                        id = MLM::setNodeLockQueryCallback( node, lockDecision, 
                                                                                                NULL, &status );
                }
        }       break;
        case 2: { 
                status = iter.getDagPath( path, component );
                if ( status ) { 
                        // Try to set the callback. Note: we check the status
                        // flag at the end of the switch statement. 
                        // 
                        id = MLM::setNodeLockDAGQueryCallback( path, lockDagDecision, 
                                                                                                   NULL, &status ); 
                }
        }       break;
        case 3: { 
                status = iter.getDependNode( node ); 
                MStringArray plugName; 
                iter.getStrings( plugName ); 
                // Now we have to parse the plug string. 
                // 
                if ( status && plugName.length() > 0 ) { 
                        MFnDependencyNode depNode( node ); 
                        MStringArray attrName; 
                        plugName[0].split( '.', attrName ); 
                        
                        MPlug plug = depNode.findPlug( attrName[1], &status ); 
                        if ( status ) { 
                                // Try to set the callback. Note: we check the status
                                // flag at the end of the switch statement. 
                                // 
                                id = MLM::setPlugLockQueryCallback( plug, plugDecision, 
                                                                                                        NULL,&status );
                        }
                } else { 
                        status = MS::kFailure; 
                }
        } break;        
        case 4: {
                status = iter.getDependNode( node ); 
                if ( status ) { 
                        // Try to set the callback. Note: we check the status
                        // flag at the end of the switch statement. 
                        // 
                        id = MLM::setPlugLockQueryCallback( node, nodePlugDecision, 
                                                                                                NULL, &status ); 
                }
        } break; 
        default: 
                MGlobal::displayError( "Invalid callback attach type" ); 
                status = MS::kFailure; 
        };      

        MFnDependencyNode fnNode( node ); 
        
        // Check the status flag here and report any particular problems 
        // encountered.  It is possible for the callback attach routines 
        // to fail.
        //
        // This typically occurs when a callback has already been attached
        // to the node or plug. 
        //
        if ( !status || !id ) { 
                MString msg; 
                msg = "Unable to add callback for node "; 
                msg += fnNode.name(); 
                MGlobal::displayError( msg );
                status.perror( msg ); 
        } else { 
                // Store the result -- so we can clean up later -- and 
                // echo some useful information. 
                // 
                cerr << "Callback attached to " << fnNode.name();       
                cerr << "; attachment type = " << fAttach << endl;  
                callbackIds.append( (int)id ); 
        }
        return id; 
}

MStatus lockEvent::doIt( const MArgList &args ) 
//
// Description: 
//  Entry point 
//
{
        MStatus status; 
        int result = 0;
        
        // First check our arguments 
        //
        if ( !parseArgs( args ) ) { 
                return MS::kFailure; 
        }

        if ( fAttach ) { 
                MItSelectionList iter( theList, MFn::kDependencyNode, &status ); 
                for ( ; status && !iter.isDone(); iter.next() ) { 
                        MCallbackId id = installCallback( iter ); 
                        if ( id ) { 
                                result ++; 
                        } else { 
                                status = MS::kFailure; 
                        }
                }
        } else if ( fOverrideFlag ) { 
                // What to do when callback occurs. 
                overrideMode = fOverrideVal; 
        } else if ( fClearCB ) { 
                clearCallbackIds(); 
                result++; 
        }        

        clearResult(); 
        // Let the caller know if the operation was successful. 
        // We just use an integer value here.  Anything > 0 is 
        // a success. 
        //
        setResult( result ); 

        return status; 
}

void *lockEvent::creator( )
// 
// Description: 
//  Create a new instance of this command. 
// 
{
        return new lockEvent; 
}

MStatus lockEvent::parseArgs( const MArgList &args )
{
        MStatus status; 
        MArgDatabase argData( syntax(), args ); 
        
        fAttach = kAttachDV; 
        fOverrideFlag = kOverrideDV; 
        fClearCB = kClearCBDV; 

        // begin-parse-args 

        if ( argData.isFlagSet( kClearCB ) ) { 
                fClearCB = !kClearCBDV; 
        }       

        if ( argData.isFlagSet( kOverride ) ) { 
                bool tmp;
                status = argData.getFlagArgument( kOverride, 0, tmp ); 
                if ( !status ) { 
                        MGlobal::displayError( "override flag parsing failed" ); 
                        return status;
                }
                fOverrideFlag = !kOverrideDV; 
                fOverrideVal = tmp; 
        }

        if ( argData.isFlagSet( kAttach ) ) { 
                unsigned int tmp;
                status = argData.getFlagArgument( kAttach, 0, tmp ); 
                if ( !status ) { 
                        MGlobal::displayError( "attach flag parsing failed" ); 
                        return status;
                }
                fAttach = tmp; 
        } 

        if ( fAttach ) { 
                status = argData.getObjects( theList ); 
                if ( theList.length() == 0 ) { 
                        MString msg = "You must specify a node/plug to attach to!"; 
                        MGlobal::displayError(msg); 
                        status = MS::kFailure; 
                }
        }

        // Ensure that the caller did not specify too many arguments! 
        //
        if ( status && fAttach && fOverrideFlag ) { 
                MString msg = "You specified too many flags!" ;
                MGlobal::displayError(msg);  
                status = MS::kFailure; 
        } 
        
        // end-parse-args 
        
        return status; 
}

MSyntax lockEvent::newSyntax( )
{
        MSyntax syntax; 
        
        // begin-syntax
        syntax.addFlag( kClearCB, kClearCBLong ); 
        syntax.addFlag( kOverride, kOverrideLong, MSyntax::kBoolean ); 
        syntax.addFlag( kAttach, kAttachLong, MSyntax::kUnsigned ); 

        syntax.useSelectionAsDefault( true ); 
        syntax.setObjectType( MSyntax::kSelectionList, 0 ); 
        // end-syntax 

        return syntax; 
}

void nodePlugDecision( MPlug &p1, MPlug &p2, 
                                           void *clientData, MLM::LockPlugEvent event, 
                                           bool &decision )
//
// Description:  
//  The watcher for plug callbacks on entire nodes. This callback
//  is invoked whenever lock query occurs on any plug in a node. 
//
{ 
        MString msg, eventString;
        msg = "nodePlugDecision called"; 

        // Echo the received event type. 
        //
        
        switch (event) { 
        case MLM::kPlugLockAttr: 
                eventString = "kPlugLockAttr"; 
                break; 
        case MLM::kPlugUnlockAttr: 
                eventString = "kPlugUnlockAttr";
                break; 
        case MLM::kPlugAttrValChange:
                eventString = "kPlugAttrValChange"; 
                break;
        case MLM::kPlugRemoveAttr: 
                eventString = "kPlugRemoveAttr"; 
                break; 
        case MLM::kPlugRenameAttr:
                eventString = "kPlugRenameAttr";
                break;
        case MLM::kPlugConnect: 
                eventString = "kPlugConnect"; 
                break;
        case MLM::kPlugDisconnect: 
                eventString = "kPlugDisconnect"; 
                break; 
        default:
                eventString = "kLastPlug"; 
                break;
        }; 
                        
        cerr << msg << "; event = " << eventString;     
        cerr << "; override = " << overrideMode << endl; 

        decision = !overrideMode; 
}       

void plugDecision( MPlug &p1, MPlug &p2, 
                                   void *clientData, MLM::LockPlugEvent event, 
                                   bool &decision )
// 
// Description: 
//   Callback function for plug locking events.  This callback 
//   is only invoked when the plug, p1, has its lock status 
//   queried. This callback shares the same event types 
//   as the nodePlugDecision callback. 
//
{ 
        MString msg, eventString;
        msg = "plugDecision called";

        switch (event) { 
        case MLM::kPlugLockAttr: 
                eventString = "kPlugLockAttr"; 
                break; 
        case MLM::kPlugUnlockAttr: 
                eventString = "kPlugUnlockAttr";
                break; 
        case MLM::kPlugAttrValChange:
                eventString = "kPlugAttrValChange"; 
                break;
        case MLM::kPlugRemoveAttr: 
                eventString = "kPlugRemoveAttr"; 
                break; 
        case MLM::kPlugRenameAttr:
                eventString = "kPlugRenameAttr";
                break;
        case MLM::kPlugConnect: 
                eventString = "kPlugConnect"; 
                break;
        case MLM::kPlugDisconnect: 
                eventString = "kPlugDisconnect"; 
                break; 
        default:
                eventString = "kInvalidPlug"; 
                break;
        }; 
                        
        cerr << msg << "; event = " << eventString;     
        cerr << "; override = " << overrideMode << endl; 
        
        decision = !overrideMode;  
}       
        
void lockDagDecision( MDagPath &path, MDagPath &other, 
                                          void *clientData, MLM::LockDAGEvent event, 
                                          bool &decision )
// 
// Description: 
//  Callback that is invoked whenever a DAG element is involved
//  in a locking event. 
//  
{
        MString eventString; 
        cerr << "lockDagDecision called ";

        switch (event) { 
        case MLM::kGroup: 
                eventString = "kGroup"; 
                break; 
        case MLM::kUnGroup:
                eventString = "kUnGroup";
                break;
        case MLM::kReparent: 
                eventString = "kReparent"; 
                break;
        case MLM::kChildReorder: 
                eventString = "kChildReorder"; 
                break;
        case MLM::kCreateNodeInstance: 
                eventString = "kCreateNodeInstance"; 
                break;
        case MLM::kCreateChildInstance:
                eventString = "kCreateChildInstance"; 
                break;
        case MLM::kCreateParentInstance:
                eventString = "kCreateParentInstance"; 
                break;
        case MLM::kInvalidDAG: 
        default: 
                eventString = "kInvalid";       
        }; 
                
        cerr << "on " << eventString << " event"; 
        cerr << "; overrideMode = " << overrideMode << endl; 

        decision = !overrideMode; 
}

void lockDecision( MObject &node, MObject &attr, 
                                   void *clientData, MLM::LockEvent event,
                                   bool &decision )
// 
// Description: 
//  All other lock callback events are convered in this routine. 
//  This includes everything that is not DAG related.  
//
{
        MString eventString; 
        cerr << "lockDecision called "; 
        
        switch ( event ) { 
        case MLM::kDelete: 
                eventString = "kDelete"; 
                break;
        case MLM::kRename: 
                eventString = "kRename"; 
                break;
        case MLM::kLockNode: 
                eventString = "kLockNode"; 
                break; 
        case MLM::kUnlockNode: 
                eventString = "kUnlockNode"; 
                break; 
        case MLM::kAddAttr: 
                eventString = "kAddAttr"; 
                break;
        case MLM::kRemoveAttr: 
                eventString = "kRemoveAttr"; 
                break;
        case MLM::kRenameAttr: 
                eventString = "kRemoveAttr"; 
                break; 
        case MLM::kUnlockAttr: 
                eventString = "kUnlockAttr"; 
                break;
        case MLM::kLockAttr: 
                eventString = "kLockAttr"; 
                break;
        case MLM::kInvalid: 
        default: 
                eventString = "kInvalid"; 
        }; 

        cerr << "on " << eventString << " event";
        cerr << "; overrideMode = " << overrideMode << endl; 

        decision = !overrideMode; 
}

bool lockEvent::clearCallbackIds( ) 
// 
// Description: 
//  Removes all currently attached callbacks.
//
{
        unsigned int idCount = callbackIds.length(); 
        for ( unsigned int i = 0; i < idCount; i ++ ) { 
                cerr << "callback #" << i << "; id = " << (unsigned)callbackIds[i] << endl; 
                MMessage::removeCallback( (MCallbackId) callbackIds[i] );
        } 
        callbackIds.clear(); 
        return true; 
}

MStatus initializePlugin( MObject obj )
// 
// Load the plugin ...
//
{
        MStatus status;
        
        MFnPlugin plugin( obj, VENDOR_TAG, PLUGIN_VERSION, "Any" ); 

        status = plugin.registerCommand( MEL_COMMAND_NAME, 
                                                                         lockEvent::creator, 
                                                                         lockEvent::newSyntax ); 

        callbackIds.clear(); 
        return status; 
}

MStatus uninitializePlugin( MObject obj )
// 
// Unload the plugin ...
//
{
        MFnPlugin plugin( obj ); 
        
        MStatus status; 

        status = plugin.deregisterCommand( MEL_COMMAND_NAME ); 
        if ( status ) { 
                lockEvent::clearCallbackIds(); 
        }

        return status; 
}