Go to: Synopsis. Return value. Keywords. Related. Flags. Python examples.

Synopsis

referenceEdit([applyFailedEdits=boolean], [changeEditTarget=[string, string]], [editCommand=string], [failedEdits=boolean], [onReferenceNode=string], [removeEdits=boolean], [successfulEdits=boolean])

Note: Strings representing object names and arguments must be separated by commas. This is not depicted in the synopsis.

referenceEdit is NOT undoable, NOT queryable, and NOT editable.

Use this command to remove and change the modifications which have been applied to references. A valid commandTarget is either a reference node, a reference file, a node in a reference, or a plug from a reference. Only modifications that have been made from the currently open scene can be changed or removed. The 'referenceQuery -topReference' command can be used to determine what modifications have been made to a given commandTarget. Additionally only unapplied edits will be affected. Edits are unapplied when the node(s) which they affect are unloaded, or when they could not be successfully applied. By default this command only works on failed edits (this can be adjusted using the "-failedEdits" and "-successfulEdits" flags). Specifying a reference node as the command target is equivalent to specifying every node in the target reference file as a target. In this situation the results may differ depending on whether the target reference is loaded or unloaded. When it is unloaded edits which affect both a node in the target reference and a node in one of its decendant references may be missed (e.g. they may not be removed). Edits which only affect nodes in the target reference or one of its ancestral references, however, should be removed as expected. This is because when a reference is unloaded Maya no longer retains detailed information about which nodes belong to it. NOTE: When specifying a plug it is important to use the appropriate long attribute name.

Return value

None

Keywords

reference, attribute, node

Related

file, referenceQuery

Flags

applyFailedEdits, changeEditTarget, editCommand, failedEdits, onReferenceNode, removeEdits, successfulEdits
Long name (short name) Argument types Properties
removeEdits(r) boolean create
Remove edits which affect the specified unloaded commandTarget.
changeEditTarget(cet) [string, string] create
Used to change a target of the specified edits. This flag takes two parameters: the old target of the edits, and the new target to change it to. The target can either be a node name ("node"), a node and attribute name ("node.attr"), or just an attribute name (".attr"). If an edit currently affects the old target, it will be changed to affect the new target. You should use 'referenceQuery' to determine the format of the edit targets. As an example most edits store the long name of the attribute (e.g. "translateX"), so when specifying the old target, a long name must also be used. If the short name is specified (e.g. "tx"), chances are the edit won't be retargeted.
applyFailedEdits(afe) boolean create
Attempts to apply any unapplied edits. This flag is useful if previously failing edits have been fixed using the -changeEditTarget flag. This flag can only be used on loaded references. If the command target is a referenced node, the associated reference is used instead.
failedEdits(fld) boolean create
This is a secondary flag used to indicate whether or not failed edits should be acted on (e.g. queried, removed, etc...). A failed edit is an edit which could not be successfully applied the last time its reference was loaded. An edit can fail for a variety of reasons (e.g. the referenced node to which it applies was removed from the referenced file). By default failed edits will be acted on.
successfulEdits(scs) boolean create
This is a secondary flag used to indicate whether or not successful edits should be acted on (e.g. queried, removed, etc...). A successful edit is any edit which was successfully applied the last time its reference was loaded. This flag will have no affect if the commandTarget is loaded. By default successful edits will not be acted on.
editCommand(ec) string createquerymultiuse
This is a secondary flag used to indicate which type of reference edits should be considered by the command. If this flag is not specified all edit types will be included. This flag requires a string parameter. Valid values are: "addAttr", "connectAttr", "deleteAttr", "disconnectAttr", "parent", "setAttr", "lock" and "unlock". In some contexts, this flag may be specified more than once to specify multiple edit types to consider.
onReferenceNode(orn) string createquerymultiuse
This is a secondary flag used to indicate that only those edits which are stored on the indicated reference node should be considered. This flag only supports multiple uses when specified with the "exportEdits" command.
Flag can appear in Create mode of command Flag can appear in Edit mode of command
Flag can appear in Query mode of command Flag can have multiple arguments, passed either as a tuple or a list.

Python examples

import maya.cmds as cmds

#
# EXAMPLE FOR -removeEdits
#
# Assume:
# main.ma contains a reference to mid.ma.
# mid.ma contains a reference to bot.ma.
# NOTE: The target reference must be unloaded for the
# following commands to work.
# Remove all the edits which apply to mid.ma.
# This can be done by specifying either the reference
# node or the reference file.
cmds.referenceEdit( 'midRN', removeEdits=True )
cmds.referenceEdit( 'mid.ma', removeEdits=True )
# Remove all "setAttr" edits which apply to mid.ma.
# This can be done by specifying either the reference
# node or the reference file.
cmds.referenceEdit( 'midRN', editCommand='setAttr', removeEdits=True )
cmds.referenceEdit( 'mid.ma', editCommand='setAttr', removeEdits=True )
# Remove all the "parent" edits which apply to mid:pSphere1.
cmds.referenceEdit( 'mid:pSphere1', editCommand='parent', removeEdits=True )
# Remove all the "connectAttr" edits which apply to mid:pSphere1.translateX.
cmds.referenceEdit( 'mid:pSphere1.translateX', editCommand='connectAttr', removeEdits=True )
# Remove all the edits which apply to bot.ma and are stored on midRN.
# The referenceEdit command is only capable of removing edits which
# are stored on a top level reference node. The only edits which
# are stored on a top level reference node are those which were made
# from the main scene. If you had previously opened mid.ma and made
# modifications to bot.ma, those edits can only be removed by opening
# mid.ma and issuing a referenceEdit command.
#
cmds.referenceEdit( 'mid:botRN', removeEdits=True )
cmds.referenceEdit( 'bot.ma', removeEdits=True )
#
# EXAMPLE FOR -changeEditTarget
#
tempDir = cmds.internalVar(utd=True)
# Create a reference containing pSphere1.
#
cmds.file( f=True, new=True )
cmds.polySphere( ch=1, r=1, sx=20, sy=20, ax=(0, 1, 0) )
newFileName = '%sref.ma' % tempDir
cmds.file( rename=newFileName )
cmds.file( f=True, s=True, type='mayaAscii')
# Reference the file in and position pSphere1
#
cmds.file( f=True, new=True )
cmds.file( newFileName, r=True, ns='ref' )
cmds.select( 'ref:pSphere1', r=True )
cmds.move( 5, 5, 5 )
topFileName = '%stop.ma' % tempDir
cmds.file( rename=topFileName )
cmds.file( f=True, s=True, type='mayaAscii')
# Later on its determined that pSphere1 is actually
# BobMrozowski.
#
cmds.file( newFileName, f=True, o=True )
cmds.rename( 'pSphere1', 'BobMrozowski' )
cmds.file( f=True, s=True, type='mayaAscii')
# Now go to open your main scene again...
#
cmds.file( topFileName, f=True, o=True )
# ... and notice that BobMrozowski is back at
# the origin.
#
# So remap all edits so that anything that used to
# affect ref:pSphere1 now affects ref:BobMrozowski...
#
cmds.referenceEdit( 'refRN', changeEditTarget=('ref:pSphere1','ref:BobMrozowski') )
# ... and then force all previously failing edits affecting
# refRN to be re-applied.
#
cmds.referenceEdit( 'refRN', applyFailedEdits=True )
# BobMrozowski should now be back at 5 5 5.
#