- Main Page
- Related Pages
- Modules
- Classes
- Examples

# 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;
    }