Go to: Synopsis. Return value. Related. Flags. Python examples.
listHistory(
objects
, [allConnections=boolean], [allFuture=boolean], [allGraphs=boolean], [breadthFirst=boolean], [fastIteration=boolean], [fullNodeName=boolean], [future=boolean], [futureLocalAttr=boolean], [futureWorldAttr=boolean], [groupLevels=boolean], [historyAttr=boolean], [interestLevel=int], [leaf=boolean], [levels=uint], [pruneDagObjects=boolean])
Note: Strings representing object names and arguments must be separated by commas. This is not depicted in the synopsis.
listHistory is undoable, queryable, and NOT editable.
This command traverses backwards or forwards in the graph from
the specified node and returns all of the nodes whose construction
history it passes through. The construction history consists of
connections to specific attributes of a node defined as the
creators and results of the node's main data, eg. the curve for
a Nurbs Curve node.
For information on history connections through specific plugs use
the "listConnections" command first to find where the history begins
then use this command on the resulting node.
| string[] | List of history nodes |
In query mode, return type is based on queried flag.
listConnections, listRelatives
allConnections, allFuture, allGraphs, breadthFirst, fastIteration, fullNodeName, future, futureLocalAttr, futureWorldAttr, groupLevels, historyAttr, interestLevel, leaf, levels, pruneDagObjects
| Long name (short name) |
Argument types |
Properties |
|
allConnections(ac)
|
boolean
|
|
|
If specified, the traversal that searches for the history or future will
not restrict its traversal across nodes to only dependent plugs.
Thus it will reach all upstream nodes (or all downstream nodes for f/future).
|
|
allFuture(af)
|
boolean
|
|
|
If listing the future, list all of it. Otherwise if a shape has
an attribute that represents its output geometry data, and that plug
is connected, only list the future history downstream from that
connection.
|
|
allGraphs(ag)
|
boolean
|
|
|
This flag is obsolete and has no effect.
|
|
breadthFirst(bf)
|
boolean
|
|
|
The breadth first traversal will return the closest nodes in the
traversal first. The depth first traversal will follow a complete
path away from the node, then return to any other paths from the
node. Default is depth first.
|
|
fastIteration(fi)
|
boolean
|
|
|
This flag enables a faster iteration mode that offers more scalable performance,
especially when traversing nodes with numerous connections. However, the results can
be slightly different, especially in cases with transitive dependencies between
attributes (attribute A is affected by B which is affected by C, but A is not
directly affected by C).
|
|
fullNodeName(fnn) 2023.1
|
boolean
|
|
|
Return full node name in result.
|
|
future(f)
|
boolean
|
|
|
List the future instead of the history.
|
|
futureLocalAttr(fl)
|
boolean
|
|
|
This flag allows querying of the local-space future-related attribute(s) on shape nodes.
|
|
futureWorldAttr(fw)
|
boolean
|
|
|
This flag allows querying of the world-space future-related attribute(s) on shape nodes.
|
|
groupLevels(gl)
|
boolean
|
|
|
The node names are grouped depending on the level. > 1 is
the lead, the rest are grouped with it.
|
|
historyAttr(ha)
|
boolean
|
|
|
This flag allows querying of the attribute where history connects on shape nodes.
|
|
interestLevel(il)
|
int
|
|
|
If this flag is set, only nodes whose historicallyInteresting
attribute value is not less than the value will be listed.
The historicallyInteresting attribute is 0 on nodes which are
not of interest to non-programmers. 1 for the TDs, 2 for the users.
|
|
leaf(lf)
|
boolean
|
|
|
If transform is selected, show history for its leaf
shape. Default is true.
|
|
levels(lv)
|
uint
|
|
|
Levels deep to traverse. Setting the number of levels to
0 means do all levels. All levels is the default.
|
|
pruneDagObjects(pdo)
|
boolean
|
|
|
If this flag is set, prune at dag objects.
|
|
|
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
cmds.curve( d=3, p=[(-3, 0, 0),(-1, 0, 6),(6, 0, 8),(8, 0, 2)], k=[0,0,0,1,1,1], n="snake" )
cmds.instance( n="rattler" )
cmds.revolve( 'rattler', ch=True, n="charmer" )
cmds.revolve( 'snake', ch=True, n="medusa" )
cmds.listHistory()
# Result:[u'medusaShape', u'revolve2', u'snake|curveShape1'] #
cmds.listHistory( 'charmer' )
# Result:[u'charmerShape', u'revolve1', u'rattler|curveShape1'] #
cmds.listHistory( 'medusa', lv=1 )
# Result:[u'medusaShape', u'revolve2'] #
cmds.listHistory( 'medusa', future=True )
# Result:[u'medusaShape', u'initialShadingGroup'] #
# If you just list the curve's future you get both directions
cmds.listHistory( 'curveShape1', future=True )
# Result:[u'snake|curveShape1', u'revolve2', u'medusaShape', u'revolve1', u'charmerShape'] #
# To follow only one history you'll need to follow the path you
# want first, then add the node you started at if so desired since
# it will not be included (here snake|curveShape1 won't list).
# List the future of the first curve
hist = cmds.listConnections('curveShape1.ws[0]',c=1)
cmds.listHistory( hist[1], future=True )
# Result:[u'revolve2', u'medusaShape'] #
# List the future of the second curve
hist = cmds.listConnections('curveShape1.ws[1]',c=1)
cmds.listHistory( hist[1], future=True )
# Result:[u'revolve1', u'charmerShape'] #
cmds.listHistory( leaf=0 )
# Result:[u'medusa'] #