class MLockMessage

Jump to documentation

Inheritance:

MLockMessage < MMessage

public members:

enum	LockPlugEvent Plug related locking events kInvalidPlug An invalid plug event received. kPlugLockAttr User is trying to lock the plug. kPlugUnlockAttr User is trying to unlock the plug. kPlugAttrValChange Plug lock query on plug value change. kPlugRemoveAttr Plug lock query on a remove attribute event. kPlugRenameAttr Plug lock query on a rename attribute event. kPlugConnect Plug lock query on a connect to a locked attribute. kPlugDisconnect Plug lock query on a disconnect from a locked source attribute. kLastPlug Used for internal bounds checking.
enum	LockDAGEvent DAG related locking events kInvalidDAG Invalid DAG event received. kGroup Lock query on group action. kUnGroup Lock query on ungroup action. kReparent Lock query on reparent action. kChildReorder Lock query on a child add action. kCreateNodeInstance Lock query on an instance event. kCreateChildInstance Lock query on node whose children will be instanced. kCreateParentInstance Lock query on node whose parent will be instanced. kLastDAG Used for internal bounds checking.
enum	LockEvent Miscellaneous lock event types kInvalid Invalid node lock event received. kRename Lock query on a rename event. kDelete Lock query on a delete event. kLockNode Lock query on a lock event. kUnlockNode Lock query on an unlock event. kAddAttr Lock query on an add attribute event. kRemoveAttr Lock query on an remove attribute event. kRenameAttr Lock query on an rename attribute event. kUnlockAttr Lock query on an unlock attribute event. kLockAttr Lock query on a lock attribute event. kLast Used for internal bounds checking.
static MCallbackId	setNodeLockQueryCallback ( MObject & node, MLockMessage::MLockEventFunction func, void *clientData = NULL, MStatus *status = NULL )
static MCallbackId	setNodeLockDAGQueryCallback ( MDagPath & path, MLockMessage::MLockDagEventFunction func, void *clientData = NULL, MStatus *status = NULL )
static MCallbackId	setPlugLockQueryCallback ( MPlug & plug, MLockMessage::MLockPlugEventFunction func, void *clientData = NULL, MStatus *status = NULL )
static MCallbackId	setPlugLockQueryCallback ( MObject & node, MLockMessage::MLockPlugEventFunction func, void *clientData = NULL, MStatus *status = NULL )

Inherited from MMessage:

public members:

static MStatus	removeCallback ( MCallbackId id )
static MStatus	removeCallbacks ( MCallbackIdArray &ids )
static MCallbackId	currentCallbackId ( MStatus * ReturnStatus = NULL )
static MStatus	nodeCallbacks ( MObject & node, MCallbackIdArray & ids )
static void	setRegisteringCallableScript ()
static bool	registeringCallableScript ()
static MStatus	removeCallbacks ( MIntArray &ids )
static MStatus	nodeCallbacks ( MObject & node, MIntArray & ids )

Documentation

Description

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:

• true - accept the default behavior. When the node/plug is locked the default behavior is to obey the lock. When the node/plug is unlocked the default behavior is to do the action/edit.
• false - deny the default behavior. When the node/plug is locked the default behavior is to deny/override the lock; thus allowing the edit/action to occur. When the node/plug is unlocked the default behavior is make the node/plug locked - without physically setting the lock bit.

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.

Functions

MCallbackId MLockMessage:: setNodeLockDAGQueryCallback ( MDagPath & dagPath, MLockMessage::MLockDagEventFunction func, void *clientData, MStatus *ReturnStatus )

Description

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 made through the decision variable described above.

Arguments

• dagPath - The path to attach the callback.
• func - The callback function pointer.
  • dagPath - The DAG path that the event occurred on.
  • otherPath - The other path involved, e.g. the new parent.
  • clientData - User defined data passed to the callback function.
  • eventType - Description of the event.
  • decision - The decision that is made by the registered callback. A value of true accepts the default behavior. A value of false denies the default action.
• clientData - Client data that should be passed back to the callback.
• status - status code
  • MS::kFailure - Error registering callback. This can occur when another DAG decision callback is already attached to the path.
  • MS::kInsufficientMemory - Not enough memory to register the callback.
  • MS::kInvalidParameter - The given path is not a valid path.
  • MS::kSuccess - Callback successfully added.

dagPath, otherPath, and default actions values by eventType

• kGroup
  • dagPath - Path of the node to be grouped.
  • otherPath - Path of the group node.
  • default actions - If dagPath is locked then the default action is to not allow the grouping. If dagPath is unlocked then dagPath can be grouped with otherPath.
• kUnGroup
  • dagPath - Path of the node attempted to ungroup.
  • otherPath - Path of the group node.
  • default actions - If dagPath is locked then the default action is to not allow the ungrouping. If dagPath is unlocked then dagPath can be ungrouped from otherPath.
• kReparent
  • dagPath - Path of the node which is being reparented.
  • otherPath - Path of the new parent, if any. When reparenting to the world, otherPath will be invalid.
  • default actions - If dagPath is locked then the default action is to not allow the reparenting. If dagPath is unlocked then dagPath can be parented to otherPath.
• kChildReorder
  • dagPath - Path of the child node to be reordered.
  • otherPath - Path of the parent node.
  • default actions - If dagPath is locked then the default action is to not allow the reordering. If dagPath is unlocked then dagPath can be reordered on otherPath.
• kCreateNodeInstance
  • dagPath - Path of the node which is being instanced.
  • otherPath - Invalid Path.
  • default actions - If dagPath is locked then the default action is to not allow the instance to be created. If dagPath is unlocked then dagPath can be instanced.
• kCreateChildInstance
  • dagPath - Path of the node whose child is being instanced.
  • otherPath - Path of the child node.
  • default actions - If dagPath is locked then the default action is to not allow the instance to be created. If dagPath is unlocked then dagPath can be instanced.

MCallbackId MLockMessage:: setNodeLockQueryCallback ( MObject & node, MLockMessage::MLockEventFunction func, void *clientData, MStatus *ReturnStatus )

Description

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 made through the decision variable described above.

Arguments

• node - The node to register the callback for.
• func - The callback function pointer.
  • node - The node that triggered the callback.
  • aux - Any auxiliary data that may be needed, e.g. the attribute about to be added.
  • clientData - User defined data passed to the callback function.
  • eventType - Description of the event.
  • decision - The decision that is made by the registered callback. A value of true accepts the default behavior. A value of false denies the default action.
• clientData - Client data that should be passed back to the callback.
• status - status code
  • MS::kFailure - Error registering callback. This can occur when another lock decision callback is already attached to the node.
  • MS::kInsufficientMemory - Not enough memory to register the callback.
  • MS::kInvalidParameter - The given node is not a valid node to register the callback on.
  • MS::kSuccess - Callback successfully added.

node, aux, and default action values by eventType

• kRename
  • node - The node that the user is attempting to rename.
  • aux - MObject::kNullObj
  • default actions - If node is locked then the default action is to not allow the rename. Otherwise, if node is unlocked then node can be renamed.
• kDelete
  • node - The node that the user is attempting to delete.
  • aux - MObject::kNullObj
  • default actions - If node is locked then the default action is to not allow the delete. If node is unlocked then the node can be deleted.
• kLockNode
  • {bf node} - The node that the user is attempting to lock.
  • {bf aux} - MObject::kNullObj
  • {bf default actions} - If node is unlocked then the default action is to ALLOW the node to be locked. The callback is not invoked when the user tries to unlock an already unlocked node.
• kUnlockNode
  • node - The node that the user is attempting to unlock.
  • aux - MObject::kNullObj
  • default actions - If node is locked then the default action is to ALLOW the unlock. The callback is not invoked when the user tries to unlock an already unlocked node.
• kAddAttr
  • node - The node that is having an attribute added.
  • aux - MObject of the attribute to be added. Note: the attribute does not belong to the node yet. You can only access the attribute information using MFnAttribute.
  • default actions - If node is locked then the default action is to not allow to the addition of aux. If node is unlocked then aux can be added to the node.
• kRemoveAttr
  • node - The node that is having an attribute removed.
  • aux - The attribute to be removed. In certain situations the user is allowed to do a global delete, e.g. "deleteAttr -at AttrName [nodes]". In these cases the plug is not created until checks have been performed; so aux == MObject::kNullObj.
  • default actions - If node is locked then the default action is to not allow the attribute removal. If node is unlocked then aux can be removed.
• kRenameAttr
  • node - The node that is having an attribute renamed.
  • aux - The attribute.
  • default actions - If node is locked then the default action is to not allow the rename. If node is unlocked then aux can be renamed.
• kUnlockAttr
  • node - The node that is having an attribute unlocked.
  • aux - The attribute to be unlocked.
  • default actions - If node is locked then the default action is to not allow the unlock. If node is unlocked then aux attribute can be unlocked.
• kLockAttr
  • node - The node that is having an attribute locked.
  • aux - The attribute to be locked.
  • default actions - If node is locked then the default action is to not allow the locking of aux. If node is unlocked then aux can be locked.

MCallbackId MLockMessage:: setPlugLockQueryCallback ( MPlug & plug, MLockMessage::MLockPlugEventFunction func, void *clientData, MStatus *ReturnStatus )

Description

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.

Arguments

• plug - The plug to attach the callback.
  • plug - The plug that triggered the callback.
  • otherPlug - The other plug involved in the callback. This is only valid during connect and disconnect events.
  • clientData - User defined data passed to the callback function.
  • eventType - Description of the event.
  • decision - The decision that is made by the registered callback. A value of true accepts the default behavior. A value of false denies the default action.
• clientData - Client data that should be passed back to the callback.
• status - status code
  • MS::kFailure - Error registering callback. This can occur when another callback is already attached to the plug. to the plug.
  • MS::kInsufficientMemory - Not enough memory to register the callback.
  • MS::kInvalidParameter - The given plug is not a valid plug to register the callback on.
  • MS::kSuccess - Callback successfully added.

plug, otherPlug, and default values by eventType

• kPlugLockAttr
  • plug - The plug that the user is attempting to lock.
  • otherPlug - NULL plug.
  • default actions - If plug is unlocked then the default action is to allow the plug to be locked.
• kPlugUnlockAttr
  • plug - The plug that the user is attempting to unlock.
  • otherPlug - NULL plug.
  • default actions - If plug is locked then the default action is to allow the plug to be unlocked.
• kPlugAttrValChange
  • plug - The plug that the user is attempting to change.
  • otherPlug - NULL plug.
  • default actions - If plug is locked then the default action is to not allow plug to change. If plug is unlocked then plug can change.
• kPlugRemoveAttr
  • plug - The plug that the user is attempting to remove.
  • otherPlug - NULL plug.
  • default actions - If plug is locked then the default action is to not allow removal. Otherwise, if plug is unlocked then plug can be removed.
• kPlugRenameAttr
  • plug - The plug that the user is attempting to rename.
  • otherPlug - NULL plug.
  • default actions - If plug is locked then the default action is to not allow the rename. Otherwise, if plug is unlocked then plug can be renamed.
• kPlugConnect
  • plug - The plug that is to be connected (incoming connection).
  • otherPlug - The source plug of the connection being made.
  • default actions - If plug is locked then the connection is DENIED. If plug is unlocked then otherPlug can be connected to plug.
• kPlugDisconnect
  • plug - The plug that it is having an incoming connection broken.
  • otherPlug - The source plug of the connection being made.
  • default actions - If plug is locked then the default action is to DENY the connection from being broken. If plug is unlocked then otherPlug can be disconnected from plug.

MCallbackId MLockMessage:: setPlugLockQueryCallback ( MObject & node, MLockMessage::MLockPlugEventFunction func, void *clientData, MStatus *ReturnStatus )

Description

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.

This overloaded class actually assigns a global plug watcher. So every plug on the node is watched. If a global watcher is assigned to a node that has plug specific watchers then the plug specific watcher will be executed over the global watcher. This allows you to have both plug specific watchers and global watchers on a node. Be aware that only one callback will be invoked. That is, you will not receive a callback on both plug specific and global watcher. The plug specific watcher has precedence.

Arguments

• node - The node to attach the callback.
  • plug - The plug that triggered the callback.
  • otherPlug - The other plug involved in the callback. This is only valid during connect and disconnect events.
  • clientData - User defined data passed to the callback function.
  • eventType - Description of the event.
  • decision - The decision that is made by the registered callback. A value of true accepts the default behavior. A value of false denies the default action.
• clientData - Client data that should be passed back to the callback.
• status - status code
  • MS::kFailure - Error registering callback. This can occur when a global watcher is already attached to the node.
  • MS::kInsufficientMemory - Not enough memory to register the callback.
  • MS::kInvalidParameter - The given node is not a valid node to register the callback on.
  • MS::kSuccess - Callback successfully added.

plug, otherPlug, and default action values by eventType

See the setPlugLockQueryCallback above.

This class has no child classes.