#include <MLockMessage.h>
Node and plug locking messages.
Plug locking was implemented with Maya 1.0. Individual plugs can be locked so that their values cannot be changed. The locking state is held within the plug. The plug's locked state can be changed via the API with the method MPlug::setLocked(bool), or, in MEL, using the command "setAttr -l {on,off}".
The ability to lock nodes was added with Maya 4.5. Node locking prevents renaming, reparenting, deletion, and other node-related changes. It also restricts the ability to change the state of any plug locks. The intent is that the user relies upon plug locking first, to lock the desired plugs they don't want to change, and then uses node locking to lock the node itself. Node locking can be set via MEL command, "lockNode", or via MFnDependencyNode::setLocked(bool)
MLockMessage class allows the API user to register callbacks that control how Maya handles locks. The registered callbacks are invoked whenever a query to the lock state is involved. Therefore, the callback would be called even if the node was not locked.
When a callback is invoked, the API user will be given a decision variable where they can place their decision. This decision variable is a boolean, and the boolean can take on the following values:
Caveats
You must use caution when using these routines. The flow of execution is interrupted when these callbacks are invoked. Therefore, you should make your decision in a timely maanner or a serious performance penalty will result. Also, you should NEVER try to alter the DG state while executing within callback. This includes quering/assigning a plug's value. You may, however, examine state information like the lock state of the plug/node.
Public Types | |
enum | LockPlugEvent { kInvalidPlug = 0, kPlugLockAttr, kPlugUnlockAttr, kPlugAttrValChange, kPlugRemoveAttr, kPlugRenameAttr, kPlugConnect, kPlugDisconnect, kLastPlug } |
Plug related locking events. More... | |
enum | LockDAGEvent { kInvalidDAG = 0, kGroup, kUnGroup, kReparent, kChildReorder, kCreateNodeInstance, kCreateChildInstance, kCreateParentInstance, kLastDAG } |
DAG related locking events. More... | |
enum | LockEvent { kInvalid = 0, kRename, kDelete, kLockNode, kUnlockNode, kAddAttr, kRemoveAttr, kRenameAttr, kUnlockAttr, kLockAttr, kLast } |
Miscellaneous lock event types. More... | |
typedef void(* | MLockEventFunction) (MObject &node, MObject &aux, void *clientData, MLockMessage::LockEvent eventType, bool &decision) |
Pointer to a dependency node lock event callback function. More... | |
typedef void(* | MLockDagEventFunction) (MDagPath &dagPath, MDagPath &otherPath, void *clientData, MLockMessage::LockDAGEvent eventType, bool &decision) |
Pointer to a DAG lock event callback function. More... | |
typedef void(* | MLockPlugEventFunction) (MPlug &plug, MPlug &otherPlug, void *clientData, MLockMessage::LockPlugEvent eventType, bool &decision) |
Pointer to a plug lock event callback function. More... | |
Callback result action codes. More... |
Static Public Member Functions | |
static MCallbackId | setNodeLockQueryCallback (MObject &node, MLockMessage::MLockEventFunction func, void *clientData=NULL, MStatus *status=NULL) |
This methods registers a callback that is invoked in any locking condition on node properties, e.g. More... | |
static MCallbackId | setNodeLockDAGQueryCallback (MDagPath &path, MLockMessage::MLockDagEventFunction func, void *clientData=NULL, MStatus *status=NULL) |
This methods registers a callback that is invoked in any situation involving a locking condition on DAG level changes. More... | |
static MCallbackId | setPlugLockQueryCallback (MPlug &plug, MLockMessage::MLockPlugEventFunction func, void *clientData=NULL, MStatus *status=NULL) |
This method registers a callback that is invoked in any locking condition on a plug, e.g. More... | |
static MCallbackId | setPlugLockQueryCallback (MObject &node, MLockMessage::MLockPlugEventFunction func, void *clientData=NULL, MStatus *status=NULL) |
This method registers a callback that is invoked in any locking condition on any plug of a given node, e.g. More... | |
static const char * | className () |
Returns the name of this class. More... | |
typedef void(* MLockEventFunction) (MObject &node, MObject &aux, void *clientData, MLockMessage::LockEvent eventType, bool &decision) |
Pointer to a dependency node lock event callback function.
[in,out] | node | Node for which the lock event occurred. |
[in,out] | aux | Auxiliary data used by some events. E.g. the attribute about to be added. |
[in] | clientData | Pointer to user-defined data supplied when the callback was registered. |
[in] | eventType | Type of node lock event which occurred. |
[out] | decision | Decision of the callback whether to allow (true) or disallow (false) the default action associated with the lock event. |
typedef void(* MLockDagEventFunction) (MDagPath &dagPath, MDagPath &otherPath, void *clientData, MLockMessage::LockDAGEvent eventType, bool &decision) |
Pointer to a DAG lock event callback function.
[in,out] | dagPath | Path to the DAG node for which the lock event occurred. |
[in,out] | otherPath | Second DAG node used in some events. E.g. the new parent. |
[in] | clientData | Pointer to user-defined data supplied when the callback was registered. |
[in] | eventType | Type of DAG node lock event which occurred. |
[out] | decision | Decision of the callback whether to allow (true) or disallow (false) the default action associated with the lock event. |
typedef void(* MLockPlugEventFunction) (MPlug &plug, MPlug &otherPlug, void *clientData, MLockMessage::LockPlugEvent eventType, bool &decision) |
Pointer to a plug lock event callback function.
[in,out] | plug | Plug for which the lock event occurred. |
[in,out] | otherPlug | Second plug used in some events. E.g. during connect and disconnect events. |
[in] | clientData | Pointer to user-defined data supplied when the callback was registered. |
[in] | eventType | Type of plug lock event which occurred. |
[out] | decision | Decision of the callback whether to allow (true) or disallow (false) the default action associated with the lock event. |
enum LockPlugEvent |
Plug related locking events.
enum LockDAGEvent |
DAG related locking events.
enum LockEvent |
Miscellaneous lock event types.
|
static |
This methods registers a callback that is invoked in any locking condition on node properties, e.g.
name, lock status, etc. When called, the API user can make a decision on how to handle the given locking situation. The programmer can either accept the default action, or they can deny the default action. The decision is returned through a decision variable which is passed to the callback function.
The callback function takes the following parameters:
The meanings of the node and aux parameters for each eventType, and default actions associated with those event types, are as follows:
kRename
kDelete
kLockNode
kUnlockNode
kAddAttr
kRemoveAttr
kRenameAttr
kUnlockAttr
kLockAttr
[in] | node | - The node to register the callback for. |
[in] | func | - Pointer to the callback function. |
[in] | clientData | - Client data that should be passed back to the callback. |
[out] | ReturnStatus | - status code |
|
static |
This methods registers a callback that is invoked in any situation involving a locking condition on DAG level changes.
When called, the API user can make a decision on how to handle the given locking situation. The programmer can either accept the default action, or they can deny the default action. The decision is returned through a decision variable which is passed to the callback function.
The callback function takes the following parameters:
The meanings of the dagPath and otherPath parameters for each eventType, and default actions associated with those event types, are as follows:
kGroup
kUnGroup
kReparent
kChildReorder
kCreateNodeInstance
kCreateChildInstance
[in] | dagPath | The path to attach the callback. |
[in] | func | - Pointer to the callback function. |
[in] | clientData | Client data that should be passed back to the callback. |
[out] | ReturnStatus | status code |
|
static |
This method registers a callback that is invoked in any locking condition on a plug, e.g.
plug unlock, plug lock, connections, etc. When the callback is invoked, the API programmer can make a decision on how to handle the given locking situation. The programmer can either accept the default action, or they can deny the default action. The decision is made through the decision variable described above.
The callback function takes the following parameters:
The meanings of the plug and otherPlug parameters for each eventType, and default actions associated with those event types, are as follows:
kPlugLockAttr
kPlugUnlockAttr
kPlugAttrValChange
kPlugRemoveAttr
kPlugRenameAttr
kPlugConnect
kPlugDisconnect
[in] | plug | - The plug to attach the callback. |
[in] | func | - Pointer to the callback function. |
[in] | clientData | - Client data that should be passed back to the callback. |
[out] | ReturnStatus | - status code |
|
static |
This method registers a callback that is invoked in any locking condition on any plug of a given node, e.g.
plug unlock, plug lock, connections, etc. When the callback is invoked, the API programmer can make a decision on how to handle the given locking situation. The programmer can either accept the default action, or they can deny the default action. The decision is returned through a decision variable which is passed to the callback function.
The callback function takes the following parameters:
If a lock event occurs on a plug which has callbacks registered both on the plug itself, using the previous method, and on the entire node, using this method, then only the plug-specific callback will be called. This allows you to have both plug-specific and node-wide callbacks on a node while ensuring that the most specific callback is the one called.
The meanings of the plug and otherPlug parameters for each eventType, and the default actions associated with those event types, are described in the plug-specific version of the method, above.
[in] | node | - The node to attach the callback. |
[in] | func | - Pointer to the callback function. |
[in] | clientData | - Client data that should be passed back to the callback. |
[out] | ReturnStatus | - status code |
|
static |
Returns the name of this class.