Go to: Synopsis. Return value. Keywords.
Related. Flags.
Python examples.
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.
None
reference, attribute, node
file, referenceQuery
applyFailedEdits, changeEditTarget, editCommand, failedEdits, onReferenceNode, removeEdits, successfulEdits
| Long name (short name) |
Argument types |
Properties |
removeEdits(r) |
boolean |
 |
|
Remove edits which affect the specified unloaded
commandTarget. |
|
changeEditTarget(cet) |
[string, string] |
|
|
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 |
|
|
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 |
|
|
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 |
|
|
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 |
  |
|
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", and
"setAttr". In some contexts, this flag may be specified more than
once to specify multiple edit types to consider. |
|
onReferenceNode(orn) |
string |
|
|
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. |
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.
#