Difference between revisions of "TDFunctions"

From TouchDesigner Documentation
Jump to: navigation, search
 
(13 intermediate revisions by 2 users not shown)
Line 1: Line 1:
=Summary=
+
{{TDClassSummary|label=TDF|summary=The '''TDFunctions''' module provides a variety of Python utility functions for TouchDesigner. To use TDFunctions put the following line at the top of your Python script:
  
The '''TDFunctions''' module provides a variety of Python utility functions for TouchDesigner. To use TDFunctions put the following line at the top of your Python script:
+
<syntaxhighlight lang=python>TDF = op.TDModules.mod.TDFunctions</syntaxhighlight>
 
 
<code>TDF = op.TDModules.mod.TDFunctions</code>
 
  
 
You can now use any of the following functions by calling:
 
You can now use any of the following functions by calling:
  
<code>TDF.<function name>(...)</code>
+
<syntaxhighlight lang=python>TDF.<function name>(...)</syntaxhighlight>}}
 
+
<section begin=HELPBODY />
=Functions=
+
{{ClassMethodSection|empty=
 
+
|Sectionsummary=
<!--PYHMVK clamp-->
+
|items=
'''<code>clamp(value, inMin, inMax)</code>''' &rarr; '''<code>clamped value</code>'''
+
{{ClassMethod
:returns the value clamped between <code>inMin</code> and <code>inMax</code>.
+
    |class=TDF
:* <code>value</code> - the value to be clamped.
+
    |name=clamp
:* <code>inMin</code> - the minimum value.
+
    |call=clamp(value, inMin, inMax)
:* <code>inMax</code> - the maximum value.
+
    |returns=float
<!--PYHEND-->
+
    |text=returns the value clamped between inMin and inMax.
 
+
*value - The value to be clamped.
<!--PYHMVK parentLevel-->
+
*inMin - The minimum value.
'''<code>parentLevel(parentOp, childOp)</code>''' &rarr; '''<code>depth of parenthood or None</code>'''
+
*inMax - The maximum value.}}
:determines if <code>parentOp</code> is a parent of <code>childOp</code> at any depth. Returns None or the depth of parenthood. i.e. <code>childOp.parent(<returnValue>)</code> will yield <code>parentOp</code>. This method returns <code>None</code> if <code>childOp</code> is not a child of <code>parentOp</code>. '''Note:''' <code>childOp.parent(<returnValue>)</code> will error in that case.
+
{{ClassMethod
:* <code>parentOp</code> - the parent to be evaluated.
+
    |class=TDF
:* <code>childOp</code> - the child to be evaluated.
+
    |name=parentLevel
<!--PYHEND-->
+
    |call=parentLevel(parentOp, childOp)
 
+
    |returns=OP or None
<!--PYHMVK sharedParent-->
+
    |text=determines if parentOp is a parent of childOp at any depth. Returns None or the depth of parenthood. i.e. childOp.parent(<returnValue>) will yield parentOp. This method returns None if childOp is not a child of parentOp.  
'''<code>sharedParent(op1, op2)</code>''' &rarr; '''<code>closest parent</code>'''
+
   
:Returns the nearest shared parent of <code>op1</code> and <code>op2</code>. Returns <code>None</code> if root is result.
+
'''Note:''' childOp.parent(<returnValue>) will error in that case.
:* <code>op1</code> - the first operator.
+
*parentOp - The parent to be evaluated.
:* <code>op2</code> - the second operator.
+
*childOp - The child to be evaluated.}}
<!--PYHEND-->
+
{{ClassMethod
 
+
    |class=TDF
<!--PYHMVK getShortcutPath-->
+
    |name=sharedParent
'''<code>getShortcutPath(fromOp, toOp)</code>''' &rarr; '''<code>path expression</code>'''
+
    |call=sharedParent(op1, op2)
:Return a shortcut path expression from <code>fromOp</code> to <code>toOp</code>. This expression is suitable for use in any OP parameter expression on <code>fromOp</code>.
+
    |returns=OP or None
:Return value will be the first of:
+
    |text=Returns the nearest shared parent of op1 and op2. Returns None if root is result.
:# <code>op.<opshortcut></code>
+
*op1 - The first operator.
:# <code>me</code>
+
*op2 - The second operator.}}
:# <code>parent.<parentshortcut></code>
+
{{ClassMethod
:# <code>parent(#)</code>
+
    |class=TDF
:# <code>op('./<path>')</code>
+
    |name=getShortcutPath
:# <code>op.opshortcut('<path>')</code>
+
    |call=getShortcutPath(fromOp, toOp, toParName=None)
:# <code>parent.parentshortcut('<path>')</code>
+
    |returns=path expression
:# <code>parent(#).op('<path>')</code>
+
    |text=Return a shortcut path expression from fromOp to toOp. This expression is suitable for use in any OP parameter expression on fromOp. The expression will incorporate [[Parent Shortcut|Parent Shortcuts]] and [[Global OP Shortcut|Global OP Shortcuts]].  
:# <code>op('<toOp.path>')</code>
+
   
:# <code>op('<toOp.path>')</code>
+
'''Note:''' because there are multiple ways to create a shortcut expression, the result of this function will always be a best guess.
 
+
*fromOp - the operator to generate expression from.
:* <code>fromOp</code> - the operator to generate expression from.
+
*toOp - the operator to generate expression to.
:* <code>toOp</code> - the operator to generate expression to.
+
*toParName - (string) if provided, the shortcut will be to that parameter on toOp.}}
<!--PYHEND-->
+
{{ClassMethod
 
+
    |class=TDF
<!--PYHMVK panelParentShortcut-->
+
    |name=panelParentShortcut
'''<code>panelParentShortcut(panel, parentShortcut)</code>''' &rarr; '''<code>Panel Comp</code>'''
+
    |call=panelParentShortcut(panel, parentShortcut)
:Return the first <code>panelParent</code> of panel that has the provided [[Parent Shortcut|parentShortcut]]. Returns <code>None</code> if no <code>panelParent</code> with shortcut is found.
+
    |returns=Panel COMP or None
 
+
    |text=Return the first panelParent of panel that has the provided [[Parent Shortcut|parentShortcut]]. Returns None if no panelParent with shortcut is found.
:* <code>panel</code> - the panel to start searching at.
+
*panel - the panel to start searching at.
:* <code>parentShortut</code> - the parent shortcut to look for.
+
*parentShortcut - the parent shortcut to look for.}}
<!--PYHEND-->
+
{{ClassMethod
 
+
    |class=TDF
<!--PYHMVK parMenu-->
+
    |name=parMenu
'''<code>parMenu(menuNames, menuLabels=None)</code>''' &rarr; '''<code>menuSource object</code>'''
+
    |call=parMenu(menuNames, menuLabels=None)
:Returns an object suitable for menuSource property of [[Par Class|parameters]].
+
    |returns=menuSource object
:* <code>menuNames</code> - a list of strings for menu values.
+
    |text=Returns an object suitable for menuSource property of [[Par Class|parameters]].
:* <code>menuLabels</code> - '''(Optional)''' a list of strings for menu labels. Defaults to menuNames.
+
*menuNames - A list of strings for menu values.
<!--PYHEND-->
+
*menuLabels - (Optional) A list of strings for menu labels. Defaults to menuNames.}}
 
+
{{ClassMethod
<!--PYHMVK incrementStringDigits-->
+
    |class=TDF
'''<code>incrementStringDigits(string, min=1)</code>''' &rarr; '''<code>new string</code>'''
+
    |name=incrementStringDigits
:Method for iterating a string with digits on the end, or adding digits if none are there. This simulates the automatic naming of duplicate operators.
+
    |call=incrementStringDigits(string, min=1)
:* <code>string</code> - the string to add digits to.
+
    |returns=string
:* <code>min</code> - '''(Optional)''' the number to add if string doesn't have a number already.
+
    |text=Method for iterating a string with digits on the end, or adding digits if none are there. This simulates the automatic naming of duplicate operators.
<!--PYHEND-->
+
*string - The string to add digits to.
 
+
*min - (Optional) The number to add if string doesn't have a number already.}}
<!--PYHMVK findNetworkEdges-->
+
{{ClassMethod
'''<code>findNetworkEdges(comp, ignoreNodes=None)</code>''' &rarr; '''<code>info dictionary</code>'''
+
    |class=TDF
:A utility for placing nodes in a network. Returns a dictionary of 'nodes' and 'positions' at extremes of network. Returns None if no nodes found. Dictionary keys are 'top', 'left', 'right', 'bottom'.
+
    |name=findNetworkEdges
:* <code>comp</code> - the network to analyze.
+
    |call=findNetworkEdges(comp, ignoreNodes=None)
:* <code>ignoreNodes</code> - '''(Optional)''' a list of nodes to ignore during analysis.
+
    |returns=dict or None
<!--PYHEND-->
+
    |text=A utility for placing nodes in a network. Returns a dictionary of 'nodes' and 'positions' at extremes of network. Returns None if no nodes found. Dictionary keys are 'top', 'left', 'right', 'bottom'.
 
+
*comp - The network to analyze.
<!--PYHMVK arrangeNode-->
+
*ignoreNodes - (Optional) A list of nodes to ignore during analysis.}}
'''<code>arrangeNode(node, position='bottom', spacing=20)</code>'''
+
{{ClassMethod
:Place a node according to the other nodes in the network.
+
    |class=TDF
:* <code>node</code> - the node to move.
+
    |name=arrangeNode
:* <code>position</code> - '''(Optional)''' can be 'bottom', 'top', 'left' or 'right'. left, right will be placed parallel with top nodes. top, bottom will be placed parallel with left nodes.
+
    |call=arrangeNode(node, position='bottom', spacing=20)
:* <code>spacing</code> - '''(Optional)''' distance from network edge.
+
    |returns=float
<!--PYHEND-->
+
    |text=Place a node according to the other nodes in the network.
 
+
*node - The node to move.
<!--PYHMVK createProperty-->
+
*position - (Optional) Can be 'bottom', 'top', 'left' or 'right'. left, right will be placed parallel with top nodes. top, bottom will be placed parallel with left nodes.
'''<code>createProperty(classInstance, name, value=None, attributeName=None, readOnly=False, dependable=False)</code>'''
+
*spacing - (Optional) Distance from network edge.}}
:Use this method to add a property to a class. '''WARNING''': the property is added to the '''class''' of instance, so all objects of instance's class will now have this property.
+
{{ClassMethod
:* <code>classInstance</code> - an instance of the class to add a property to. This is usually 'self' in the __init__ method of the class.
+
    |class=TDF
:* <code>name</code> - the name of the property. Must be a valid Python object name.
+
    |name=createProperty
:* <code>value</code> - '''(Optional)''' the starting value of the property.
+
    |call=createProperty(classInstance, name, value=None, attributeName=None, readOnly=False, dependable=True)
:* <code>attributeName</code> - '''(Optional)''' the attribute name used to store the value of the property. Defaults to <code>_<name></code>.
+
    |returns=None
:* <code>readOnly</code> - '''(Optional)''' if True, the property will be read only. A read only property can be changed via the attributeName. If the property is dependable, use attributeName.val.
+
    |text=Use this method to add a property to a class.  
:* <code>dependable</code> - '''(Optional)''' if True, the value will be dependable. If set to "deep", collections will be deeply dependable.
 
<!--PYHEND-->
 
 
 
<!--PYHMVK makeDeepDependable-->
 
'''<code>makeDeepDependable(value)</code>''' &rarr; '''<code>dependency object</code>'''
 
:returns a [[TDStoreTools#Deeply_Dependable_Collections|deeply dependable]] object out of the provided python object. Deeply dependable collections will cause cooks when their contents change.
 
:* <code>value</code> - the value of the deep dependable object.
 
<!--PYHEND-->
 
 
 
<!--PYHMVK forceCookNonDatOps-->
 
'''<code>forceCookNonDatOps(comp)</code>'''
 
:Recursively force cook op and all children of <code>comp</code>, unless they are DATs
 
<!--PYHEND-->
 
 
 
<!--PYHMVK showInPane-->
 
'''<code>showInPane(operator, pane='Floating', inside=False)</code>''' &rarr; '''<code>pane</code>'''
 
:Open an operator for viewing in a chosen editor pane. The pane will be focused on the chosen operator unless inside is True, in which case it will show the inside if possible.
 
:* <code>operator</code> - the operator to view.
 
:* <code>pane</code> - '''(Optional)''' a ui.pane or 'Floating' for a new floating pane.
 
:* <code>inside</code> - '''(Optional)''' if inside is True, try to show view inside comps.
 
<!--PYHEND-->
 
 
 
<!--PYHMVK tScript-->
 
'''<code>tScript(cmd)</code>'''
 
:Run a tscript command. This is slow because it creates and destroys an operator. If you need this to be faster, build an optimized network with its own tscript DAT.
 
:* <code>cmd</code> - tScript command to run.
 
<!--PYHEND-->
 
 
 
<!--PYHMVK parStringToIntList-->
 
'''<code>parStringToIntList(parString)</code>'''  &rarr; '''<code>int list</code>'''
 
:Convert a space delimited string to a list of ints.
 
:* <code>parString</code> - space delimited list of ints.
 
<!--PYHEND-->
 
 
 
<!--PYHMVK listToParString-->
 
'''<code>listToParString(l)</code>'''  &rarr; '''<code>space delimited string list</code>'''
 
:Convert a list to a space delimited string.
 
:* <code>l</code> - a python list.
 
<!--PYHEND-->
 
 
 
<!--PYHMVK replaceOp-->
 
'''<code>replaceOp(dest, source=None)</code>'''
 
:Replace <code>dest</code> with an exact copy of <code>source</code>. If <code>source</code> is <code>None</code> and <code>dest</code> is a comp, try to use <code>dest</code>'s clone parameter.
 
:* <code>dest</code> - the OP to be replaced.
 
:* <code>source</code> - '''(Optional)''' the OP to replace with. If <code>None</code>, use dest's clone source.
 
<!--PYHEND-->
 
 
 
<!--PYHMVK getParInfo-->
 
'''<code>getParInfo(sourceOp, pattern='*', names=None, includeCustom=True, includeNonCustom=True)</code>''' &rarr; '''<code>parInfo dict</code>'''
 
:Returns a parInfo dict for <code>sourceOp</code>. The format of a parInfo dict is <code>{<parName>:(parVal, parExpr, parMode)...}</code>
 
:* <code>sourceOp</code> - the operator to look for pars on.
 
:* <code>pattern</code> - '''(Optional)''' a pattern match string for par names.
 
:* <code>names</code> - '''(Optional)''' a list of specific names to include. None means include all.
 
:* <code>includeCustom</code> - '''(Optional)''' include custom parameters.
 
:* <code>includeNonCustom</code> - '''(Optional)''' include non-custom parameters.
 
<!--PYHEND-->
 
 
 
<!--PYHMVK applyParInfo-->
 
'''<code>applyParInfo(targetOp, parInfo)</code>'''
 
:Apply par values, expressions, and modes from <code>parInfo</code> dict to <code>targetOp</code>. The format of a parInfo dict is <code>{<parName>:(parVal, parExpr, parMode)...}</code>
 
:* <code>targetOp</code> - the operator to apply values to.
 
:* <code>parInfo</code> - the parInfo dict.
 
<!--PYHEND-->
 
  
<noinclude>[[Category:TD Python Modules]]</noinclude>
+
'''WARNING:''' the property is added to the class of instance, so all objects of instance's class will now have this property.
[[Category:TDPages]]
+
*classInstance - An instance of the class to add a property to. This is usually 'self' in the __init__ method of the class.
[[Category: Python‏‎]]
+
*name - The name of the property. Must be a valid Python object name.
 +
*value - (Optional) The starting value of the property.
 +
*attributeName - (Optional) The attribute name used to store the value of the property. Defaults to _<name>.
 +
*readOnly - (Optional) If True, the property will be read only. A read only property can be changed via the attributeName. If the property is dependable, use attributeName.val.
 +
*dependable - (Optional) If True, the value will be dependable. If set to "deep", collections will be deeply dependable.}}
 +
{{ClassMethod
 +
    |class=TDF
 +
    |name=makeDeepDependable
 +
    |call=makeDeepDependable(value)
 +
    |returns=dependency object
 +
    |text=Returns a [[TDStoreTools#Deeply_Dependable_Collections|deeply dependable]] object out of the provided python object. Deeply dependable collections will cause cooks when their contents change.
 +
*value - The value of the deep dependable object.}}
 +
{{ClassMethod
 +
    |class=TDF
 +
    |name=forceCookNonDatOps
 +
    |call=forceCookNonDatOps(comp)
 +
    |returns=None
 +
    |text=Recursively force cook op and all children of comp, unless they are DATs}}
 +
{{ClassMethod
 +
    |class=TDF
 +
    |name=showInPane
 +
    |call=showInPane(operator, pane='Floating', inside=False)
 +
    |returns=None
 +
    |text=Open an operator for viewing in a chosen editor pane. The pane will be focused on the chosen operator unless inside is True, in which case it will show the inside if possible.
 +
*operator - The operator to view.
 +
*pane - (Optional) A ui.pane or 'Floating' for a new floating pane.
 +
*inside - (Optional) If inside is True, try to show view inside comps.}}
 +
{{ClassMethod
 +
    |class=TDF
 +
    |name=tScript
 +
    |call=tScript(cmd)
 +
    |returns=float
 +
    |text=Run a tscript command. This is slow because it creates and destroys an operator. If you need this to be faster, build an optimized network with its own tscript DAT.
 +
*cmd - tScript command to run.}}
 +
{{ClassMethod
 +
    |class=TDF
 +
    |name=parStringToIntList
 +
    |call=parStringToIntList(parString)
 +
    |returns=list of ints
 +
    |text=Convert a space delimited string to a list of ints.
 +
*parString - Space delimited list of ints.}}
 +
{{ClassMethod
 +
    |class=TDF
 +
    |name=listToParString
 +
    |call=listToParString(l)
 +
    |returns=space delimited string list
 +
    |text=Convert a list to a space delimited string.
 +
*l - A python list.}}
 +
{{ClassMethod
 +
    |class=TDF
 +
    |name=replaceOp
 +
    |call=replaceOp(dest, source=None)
 +
    |returns=None
 +
    |text=Replace dest with an exact copy of source. If source is None and dest is a comp, try to use dest's clone parameter.
 +
*dest - The OP to be replaced.
 +
*source - (Optional) The OP to replace with. If None, use dest's clone source.}}
 +
{{ClassMethod
 +
    |class=TDF
 +
    |name=getParInfo
 +
    |call=getParInfo(sourceOp, pattern='*', names=None, includeCustom=True, includeNonCustom=True)
 +
    |returns=dict
 +
    |text=Returns a parInfo dict for sourceOp. The format of a parInfo dict is <syntaxhighlight lang=python inline>{<parName>:(par.val, par.expr, par.mode string, par.bindExpr, par.default)...}</syntaxhighlight>
 +
*sourceOp - The operator to look for pars on.
 +
*pattern - (Optional) A pattern match string for par names.
 +
*names - (Optional) A list of specific names to include. None means include all.
 +
*includeCustom - (Optional) Include custom parameters.
 +
*includeNonCustom - (Optional) Include non-custom parameters.}}
 +
{{ClassMethod
 +
    |class=TDF
 +
    |name=applyParDefaults
 +
    |call=applyParDefaults(targetOp, parInfo)
 +
    |returns=None
 +
    |text=Apply par defaults from parInfo dict to targetOp. The format of a parInfo dict is <syntaxhighlight lang=python inline>{<parName>:(par.val, par.expr, par.mode string, par.bindExpr, par.default)...}</syntaxhighlight>
 +
*targetOp - The operator to apply values to.
 +
*parInfo - The parInfo dict.
 +
}}
 +
{{ClassMethod
 +
    |class=TDF
 +
    |name=applyParInfo
 +
    |call=applyParInfo(targetOp, parInfo, setDefaults=False)
 +
    |returns=None
 +
    |text=Apply par values, expressions, and modes from parInfo dict to targetOp. The format of a parInfo dict is <syntaxhighlight lang=python inline>{<parName>:(par.val, par.expr, par.mode string, par.bindExpr, par.default)...}</syntaxhighlight>
 +
*targetOp - The operator to apply values to.
 +
*parInfo - The parInfo dict.
 +
*setDefaults - if True, set the par.default as well
 +
}}
 +
{{ClassMethod
 +
    |class=TDF
 +
    |name=panelParentShortcut
 +
    |call=panelParentShortcut(panel, parentShortcut)
 +
    |returns=COMP with provided shortcut or None
 +
    |text=return the first panelParent of panel that has the provided parentShortcut. Returns None if no panelParent with shortcut is found.
 +
*panel - The panel to search from.
 +
*parentShortuct - The shortcut to look for.
 +
}}
 +
{{ClassMethod
 +
    |class=TDF
 +
    |name=getMenuLabel
 +
    |call=getMenuLabel(menuPar)
 +
    |returns=label string
 +
    |text=Return menuPar's currently selected menu item's label
 +
*menuPar - a menu style parameter
 +
}}
 +
{{ClassMethod
 +
    |class=TDF
 +
    |name=setMenuLabel
 +
    |call=setMenuLabel(menuPar, label)
 +
    |returns=None
 +
    |text=Sets menuPar's selected menu item to the item with menuLabel == label
 +
*menuPar - a menu style parameter
 +
*label - label to set menu entry to
 +
}}
 +
{{ClassMethod
 +
    |class=TDF
 +
    |name=messageDialog
 +
    |call=messageDialog(text, title)
 +
    |returns=None
 +
    |text=Open a popup dialog (after one frame delay), with just an OK button
 +
*text - text of dialog
 +
*title - title of dialog
 +
}}
 +
{{ClassMethod
 +
    |class=TDF
 +
    |name=bindChain
 +
    |call=bindChain(par, parsOnly=False)
 +
    |returns=list of [par, par's bind master, ...]
 +
    |text=Return a list of parameters, starting with par, followed by its bind master, if available, followed by it's master's master if available etc.
 +
*par - the parameter to start the chain search
 +
*parsOnly - if True, only return parameters in the chain
 +
}}
 +
{{ClassMethod
 +
    |class=TDF
 +
    |name=unbindReferences
 +
    |call=unbindReferences(par, modeOnly=False)
 +
    |returns=list of references that were changed
 +
    |text=Erase bind strings or change modes for all bindReferences of a parameter
 +
*par - the bindMaster parameter
 +
*modeOnly - if True, just change the references modes to prevMode
 +
}}
 +
{{ClassMethod
 +
    |class=TDF
 +
    |name=getCustomPage
 +
    |call=getCustomPage(comp, name)
 +
    |returns=Page object or None if name not found
 +
    |text=Get a custom page object by name
 +
*comp - comp with custom page
 +
*name - page name
 +
}}
 +
{{ClassMethod
 +
    |class=TDF
 +
    |name=changeParStyle
 +
    |call=changeParStyle(p, style, size=1, includeValueData=True)
 +
    |returns=A list of newly created parameters
 +
    |text=Change a parameter's style
 +
*p - The parameter to change
 +
*style - The style string for the parameter (e.g. 'Int', 'Float', 'Menu' etc.)
 +
*size - For multivalue pars (e.g. 'Int', 'Float') the number of values 1-4
 +
*includeValueData - If True, include all val, expr, bind settings
 +
}}
 +
}}

Latest revision as of 19:03, 11 April 2020

The TDFunctions module provides a variety of Python utility functions for TouchDesigner. To use TDFunctions put the following line at the top of your Python script:

TDF = op.TDModules.mod.TDFunctions

You can now use any of the following functions by calling:

TDF.<function name>(...)


Methods[edit]

clamp(value, inMin, inMax)float:

returns the value clamped between inMin and inMax.

  • value - The value to be clamped.
  • inMin - The minimum value.
  • inMax - The maximum value.

parentLevel(parentOp, childOp)OP or None:

determines if parentOp is a parent of childOp at any depth. Returns None or the depth of parenthood. i.e. childOp.parent(<returnValue>) will yield parentOp. This method returns None if childOp is not a child of parentOp.

Note: childOp.parent(<returnValue>) will error in that case.

  • parentOp - The parent to be evaluated.
  • childOp - The child to be evaluated.

sharedParent(op1, op2)OP or None:

Returns the nearest shared parent of op1 and op2. Returns None if root is result.

  • op1 - The first operator.
  • op2 - The second operator.

getShortcutPath(fromOp, toOp, toParName=None)path expression:

Return a shortcut path expression from fromOp to toOp. This expression is suitable for use in any OP parameter expression on fromOp. The expression will incorporate Parent Shortcuts and Global OP Shortcuts.

Note: because there are multiple ways to create a shortcut expression, the result of this function will always be a best guess.

  • fromOp - the operator to generate expression from.
  • toOp - the operator to generate expression to.
  • toParName - (string) if provided, the shortcut will be to that parameter on toOp.

panelParentShortcut(panel, parentShortcut)Panel COMP or None:

Return the first panelParent of panel that has the provided parentShortcut. Returns None if no panelParent with shortcut is found.

  • panel - the panel to start searching at.
  • parentShortcut - the parent shortcut to look for.

parMenu(menuNames, menuLabels=None)menuSource object:

Returns an object suitable for menuSource property of parameters.

  • menuNames - A list of strings for menu values.
  • menuLabels - (Optional) A list of strings for menu labels. Defaults to menuNames.

incrementStringDigits(string, min=1)string:

Method for iterating a string with digits on the end, or adding digits if none are there. This simulates the automatic naming of duplicate operators.

  • string - The string to add digits to.
  • min - (Optional) The number to add if string doesn't have a number already.

findNetworkEdges(comp, ignoreNodes=None)dict or None:

A utility for placing nodes in a network. Returns a dictionary of 'nodes' and 'positions' at extremes of network. Returns None if no nodes found. Dictionary keys are 'top', 'left', 'right', 'bottom'.

  • comp - The network to analyze.
  • ignoreNodes - (Optional) A list of nodes to ignore during analysis.

arrangeNode(node, position='bottom', spacing=20)float:

Place a node according to the other nodes in the network.

  • node - The node to move.
  • position - (Optional) Can be 'bottom', 'top', 'left' or 'right'. left, right will be placed parallel with top nodes. top, bottom will be placed parallel with left nodes.
  • spacing - (Optional) Distance from network edge.

createProperty(classInstance, name, value=None, attributeName=None, readOnly=False, dependable=True)None:

Use this method to add a property to a class.

WARNING: the property is added to the class of instance, so all objects of instance's class will now have this property.

  • classInstance - An instance of the class to add a property to. This is usually 'self' in the __init__ method of the class.
  • name - The name of the property. Must be a valid Python object name.
  • value - (Optional) The starting value of the property.
  • attributeName - (Optional) The attribute name used to store the value of the property. Defaults to _<name>.
  • readOnly - (Optional) If True, the property will be read only. A read only property can be changed via the attributeName. If the property is dependable, use attributeName.val.
  • dependable - (Optional) If True, the value will be dependable. If set to "deep", collections will be deeply dependable.

makeDeepDependable(value)dependency object:

Returns a deeply dependable object out of the provided python object. Deeply dependable collections will cause cooks when their contents change.

  • value - The value of the deep dependable object.

forceCookNonDatOps(comp)None:

Recursively force cook op and all children of comp, unless they are DATs

showInPane(operator, pane='Floating', inside=False)None:

Open an operator for viewing in a chosen editor pane. The pane will be focused on the chosen operator unless inside is True, in which case it will show the inside if possible.

  • operator - The operator to view.
  • pane - (Optional) A ui.pane or 'Floating' for a new floating pane.
  • inside - (Optional) If inside is True, try to show view inside comps.

tScript(cmd)float:

Run a tscript command. This is slow because it creates and destroys an operator. If you need this to be faster, build an optimized network with its own tscript DAT.

  • cmd - tScript command to run.

parStringToIntList(parString)list of ints:

Convert a space delimited string to a list of ints.

  • parString - Space delimited list of ints.

listToParString(l)space delimited string list:

Convert a list to a space delimited string.

  • l - A python list.

replaceOp(dest, source=None)None:

Replace dest with an exact copy of source. If source is None and dest is a comp, try to use dest's clone parameter.

  • dest - The OP to be replaced.
  • source - (Optional) The OP to replace with. If None, use dest's clone source.

getParInfo(sourceOp, pattern='*', names=None, includeCustom=True, includeNonCustom=True)dict:

Returns a parInfo dict for sourceOp. The format of a parInfo dict is {<parName>:(par.val, par.expr, par.mode string, par.bindExpr, par.default)...}

  • sourceOp - The operator to look for pars on.
  • pattern - (Optional) A pattern match string for par names.
  • names - (Optional) A list of specific names to include. None means include all.
  • includeCustom - (Optional) Include custom parameters.
  • includeNonCustom - (Optional) Include non-custom parameters.

applyParDefaults(targetOp, parInfo)None:

Apply par defaults from parInfo dict to targetOp. The format of a parInfo dict is {<parName>:(par.val, par.expr, par.mode string, par.bindExpr, par.default)...}

  • targetOp - The operator to apply values to.
  • parInfo - The parInfo dict.

applyParInfo(targetOp, parInfo, setDefaults=False)None:

Apply par values, expressions, and modes from parInfo dict to targetOp. The format of a parInfo dict is {<parName>:(par.val, par.expr, par.mode string, par.bindExpr, par.default)...}

  • targetOp - The operator to apply values to.
  • parInfo - The parInfo dict.
  • setDefaults - if True, set the par.default as well

panelParentShortcut(panel, parentShortcut)COMP with provided shortcut or None:

return the first panelParent of panel that has the provided parentShortcut. Returns None if no panelParent with shortcut is found.

  • panel - The panel to search from.
  • parentShortuct - The shortcut to look for.

getMenuLabel(menuPar)label string:

Return menuPar's currently selected menu item's label

  • menuPar - a menu style parameter

setMenuLabel(menuPar, label)None:

Sets menuPar's selected menu item to the item with menuLabel == label

  • menuPar - a menu style parameter
  • label - label to set menu entry to

messageDialog(text, title)None:

Open a popup dialog (after one frame delay), with just an OK button

  • text - text of dialog
  • title - title of dialog

bindChain(par, parsOnly=False)list of [par, par's bind master, ...]:

Return a list of parameters, starting with par, followed by its bind master, if available, followed by it's master's master if available etc.

  • par - the parameter to start the chain search
  • parsOnly - if True, only return parameters in the chain

unbindReferences(par, modeOnly=False)list of references that were changed:

Erase bind strings or change modes for all bindReferences of a parameter

  • par - the bindMaster parameter
  • modeOnly - if True, just change the references modes to prevMode

getCustomPage(comp, name)Page object or None if name not found:

Get a custom page object by name

  • comp - comp with custom page
  • name - page name

changeParStyle(p, style, size=1, includeValueData=True)A list of newly created parameters:

Change a parameter's style

  • p - The parameter to change
  • style - The style string for the parameter (e.g. 'Int', 'Float', 'Menu' etc.)
  • size - For multivalue pars (e.g. 'Int', 'Float') the number of values 1-4
  • includeValueData - If True, include all val, expr, bind settings

An Operator Family that contains its own Network inside. There are twelve 3D Object Component and eight 2D Panel Component types. See also Network Path.

An Operator Family that manipulates text strings: multi-line text or tables. Multi-line text is often a command Script, but can be any multi-line text. Tables are rows and columns of cells, each containing a text string.