Difference between revisions of "Par Class"

From TouchDesigner Documentation
Jump to: navigation, search
(Par Class Auto Create)
m
 
(31 intermediate revisions by 5 users not shown)
Line 1: Line 1:
{{TDClassSummary|summary=The Par class describes an instance of a single Parameter. See also Custom Parameters.}}
+
{{TDClassSummary|label=Par|summary=The Par class describes an instance of a single [[Parameter]]. See also [[Custom Parameters]].}}
 
<section begin=HELPBODY />
 
<section begin=HELPBODY />
{{ClassMemberSection|empty=}}
+
{{ClassMemberSection|empty=
 +
|Sectionsummary=
 +
|items=
 
{{ClassMember
 
{{ClassMember
 
     |class=Par
 
     |class=Par
     |name=clampMax
+
     |name=valid
     |returns=
+
     |type=bool
 
     |set=0
 
     |set=0
     |text=Get or set the parameter's numerical clamping behavior. If set to clampMax = True, the parameter will clamp on the upper end at the value specified in max Can only be set on Custom Parameters.
+
     |text=True if the referenced parameter currently exists, False if it has been deleted.
 
}}
 
}}
 
{{ClassMember
 
{{ClassMember
 
     |class=Par
 
     |class=Par
     |name=clampMin
+
     |name=val
     |returns=
+
     |type=value
     |set=0
+
     |set=1
     |text=Get or set the parameter's numerical clamping behavior. If set to clampMin = True, the parameter will clamp on the lower end at the value specified in min Can only be set on Custom Parameters.
+
     |text=Get or set the constant value of the parameter only. To get the parameter's current value, regardless of the [[Parameter Mode]] (constant, expression, export or bound), use the <syntaxhighlight lang=python inline>eval()</syntaxhighlight> method described below.
 +
<syntaxhighlight lang=python>
 +
op('geo1').par.tx.val  # the constant value
 +
op('geo1').par.tx.eval()  # the evaluated parameter
 +
op('geo1').par.tx.val = 5
 +
op('geo1').par.tx = 5  #equivalent to above, more concise form
 +
</syntaxhighlight>
 +
When setting this member, the parameter will also be placed in constant mode.  See mode member below.
 +
To set a menu value by its index, use the <code>menuIndex</code> member as described below.
 
}}
 
}}
 
{{ClassMember
 
{{ClassMember
 
     |class=Par
 
     |class=Par
     |name=cloneImmune
+
     |name=expr
     |returns=
+
     |type=str
     |set=0
+
     |set=1
     |text=Get or set the parameter's clone immunity. When False, the parameter definition is matched to any matching master parameter its operator is cloned to. When True, it is left unchanged.
+
     |text=Get or set the non-evaluated expression only. To get the parameter's current value, regardless of the [[Parameter Mode]] (constant, expression, export or bound), use the <syntaxhighlight lang=python inline>eval()</syntaxhighlight> method described below.
 +
<syntaxhighlight lang=python>
 +
op('geo1').par.tx.expr = 'absTime.frame'  #set to match current frame
 +
</syntaxhighlight>
 +
When setting this member, the parameter will also be placed in expression mode. See mode member below.
 +
'''NOTE:''' For convenience, the expression is placed in double-quotes so you can safely put in expressions containing single quotes. 'a' and "a" have the same effect of enclosing strings in python.
 
}}
 
}}
 
{{ClassMember
 
{{ClassMember
 
     |class=Par
 
     |class=Par
     |name=default
+
     |name=exportOP
     |returns=
+
     |type=OP or None
 
     |set=0
 
     |set=0
     |text=Get or set the parameter's default value. Can only be set on Custom Parameters.  Only one of default, defaultExpr can be set.
+
     |text=The [[OP Class|operator]] exporting to this parameter.}}
}}
 
 
{{ClassMember
 
{{ClassMember
 
     |class=Par
 
     |class=Par
     |name=defaultExpr
+
     |name=exportSource
     |returns=
+
     |type=Cell Channel or None
 
     |set=0
 
     |set=0
     |text=Get or set the parameter's default expression. Can only be set on Custom Parameters.  Only one of default, defaultExpr can be set.
+
    |text=The object exporting to this parameter. Examples: [[Cell Class|Cell]], [[Channel Class|Channel]] or None.}}
 
+
{{ClassMember
op('base1').par.Size.defaultExpr = 'me.time.frame' #value defaults to this expression.
+
    |class=Par
}}
+
    |name=bindExpr
 +
    |type=expression
 +
    |set=1
 +
     |text=Get or set an expression that returns a Parameter object. This can be used to bind this parameter's constant value to the referenced parameter.
 +
<syntaxhighlight lang=python>p.bindExpr = "op('geo1').par.tx"</syntaxhighlight>  
 +
Note the outside quotes, as bindExpr is an expression, not an object.}}
 
{{ClassMember
 
{{ClassMember
 
     |class=Par
 
     |class=Par
     |name=displayOnly
+
     |name=bindMaster
     |returns=
+
     |type=OP or None
 
     |set=0
 
     |set=0
     |text=Get or set the parameter's displayOnly state. Can only be set on Custom Parameters.
+
     |text=The object to which this parameter is bound to, possibly None.}}
}}
 
 
{{ClassMember
 
{{ClassMember
 
     |class=Par
 
     |class=Par
     |name=enable
+
     |name=bindReferences
     |returns=
+
     |type=list
 
     |set=0
 
     |set=0
     |text=Get or set the parameter's enable state. Can only be set on Custom Parameters.
+
     |text=The (possibly empty) list of objects which bind to this parameter.}}
}}
 
 
{{ClassMember
 
{{ClassMember
 
     |class=Par
 
     |class=Par
     |name=exportOP
+
     |name=index
     |returns=
+
     |type=int
 
     |set=0
 
     |set=0
     |text=The operator exporting to this parameter.
+
     |text=The parameter's order in the list.
 
}}
 
}}
 
{{ClassMember
 
{{ClassMember
 
     |class=Par
 
     |class=Par
     |name=expr
+
     |name=vecIndex
     |returns=
+
     |type=int
 
     |set=0
 
     |set=0
     |text=Get or set the non-evaluated expression only.
+
     |text=The parameter's vector index. For example, <syntaxhighlight lang=python inline>op('geo1').par.tz</syntaxhighlight> would have a value of 2.
 
 
op('geo1').par.tx.expr = 'me.time.frame'  #set to match current frame
 
 
 
When setting this member, the parameter will also be placed in expression mode.  See mode member below.
 
 
 
 
 
To get the parameter's current value, regardless if it's from a constant, expression, or export, use the eval() method described below.
 
 
 
NOTE: For convenience, the expression is placed in double-quotes so you can safely put in expressions containing single quotes. 'a' and "a" have the same effect of enclosing strings in python.
 
 
}}
 
}}
 
{{ClassMember
 
{{ClassMember
 
     |class=Par
 
     |class=Par
     |name=isCustom
+
     |name=name
     |returns=
+
     |type=str
     |set=0
+
     |set=1
     |text=True for Custom Parameters.
+
     |text=Get or set the parameter's unique name.
}}
+
<syntaxhighlight lang=python>
 +
op('myOperator').par.Custompar.name = 'Translate'
 +
</syntaxhighlight>
 +
Can only be set on [[Custom Parameters]].}}
 +
{{ClassMember
 +
    |class=Par
 +
    |name=label
 +
    |type=str
 +
    |set=1
 +
    |text=Get or set the parameter's label.
 +
<syntaxhighlight lang=python>
 +
op('myOperator').par.Custompar.label = 'Translate'
 +
</syntaxhighlight>
 +
Can only be set on [[Custom Parameters]].}}
 
{{ClassMember
 
{{ClassMember
 
     |class=Par
 
     |class=Par
     |name=isDefault
+
     |name=startSection
     |returns=
+
     |type=bool
     |set=0
+
     |set=1
     |text=True when the parameter value, expression and mode are in their default settings.
+
     |text=Get or set the parameter's separator status. When <code>True</code> a visible separator is drawn between this parameter and the ones preceding it. Can only be set on [[Custom Parameters]].}}
}}
 
 
{{ClassMember
 
{{ClassMember
 
     |class=Par
 
     |class=Par
     |name=isFloat
+
     |name=displayOnly
     |returns=
+
     |type=bool
     |set=0
+
     |set=1
     |text=True for floating point numeric parameters.
+
     |text=Get or set the parameter's displayOnly state. Can only be set on Custom Parameters.
 
}}
 
}}
 
{{ClassMember
 
{{ClassMember
 
     |class=Par
 
     |class=Par
     |name=isInt
+
     |name=readOnly
     |returns=
+
     |type=bool
     |set=0
+
     |set=1
     |text=True for integer numeric parameters.
+
     |text=Get or set the parameter's read only status. When <code>True</code> the parameter cannot be modified through the UI, only scripting.
 
}}
 
}}
 
{{ClassMember
 
{{ClassMember
 
     |class=Par
 
     |class=Par
     |name=isMenu
+
     |name=tuplet
     |returns=
+
     |type=tuplet
 
     |set=0
 
     |set=0
     |text=True for menu parameters.
+
     |text=The tuplet of parameters this parameter belongs to. A tuplet is typically a set of parameters sharing one line on a parameter dialog, example: Translate (x, y, z).
 
}}
 
}}
 
{{ClassMember
 
{{ClassMember
 
     |class=Par
 
     |class=Par
     |name=isMomentary
+
     |name=tupletName
     |returns=
+
     |type=str
 
     |set=0
 
     |set=0
     |text=True for momentary parameters.
+
     |text=The tuplet name of a parameter.  Example: The tuplet name of a (tx,ty,tz) translate parameter is t.
 
}}
 
}}
 
{{ClassMember
 
{{ClassMember
 
     |class=Par
 
     |class=Par
     |name=isNumber
+
     |name=min
     |returns=
+
     |type=value
     |set=0
+
     |set=1
     |text=True for numeric parameters.
+
     |text=Get or set the parameter's numerical minimum value. The parameter's value will be clamped at that minimum if clampMin = True. Can only be set on [[Custom Parameters]].}}
}}
 
 
{{ClassMember
 
{{ClassMember
 
     |class=Par
 
     |class=Par
     |name=isOP
+
     |name=max
     |returns=
+
     |type=value
     |set=0
+
     |set=1
     |text=True for OP parameters.
+
     |text=Get or set the parameter's numerical maximum value. The parameter's value will be clamped at that maximum if clampMax = True. Can only be set on [[Custom Parameters]].}}
}}
 
 
{{ClassMember
 
{{ClassMember
 
     |class=Par
 
     |class=Par
     |name=isPulse
+
     |name=clampMin
     |returns=
+
     |type=bool
     |set=0
+
     |set=1
     |text=True for pulse parameters.
+
     |text=Get or set the parameter's numerical clamping behavior. If set to clampMin = True, the parameter will clamp on the lower end at the value specified in min Can only be set on [[Custom Parameters]].}}
}}
 
 
{{ClassMember
 
{{ClassMember
 
     |class=Par
 
     |class=Par
     |name=isPython
+
     |name=clampMax
     |returns=
+
     |type=bool
     |set=0
+
     |set=1
     |text=True for python parameters.
+
     |text=Get or set the parameter's numerical clamping behavior. If set to clampMax = True, the parameter will clamp on the upper end at the value specified in max Can only be set on [[Custom Parameters]].}}
}}
 
 
{{ClassMember
 
{{ClassMember
 
     |class=Par
 
     |class=Par
     |name=isString
+
     |name=default
     |returns=
+
     |type=value
     |set=0
+
     |set=1
     |text=True for string parameters.
+
     |text=Get or set the parameter's default value. Can only be set on [[Custom Parameters]].  Only one of default, defaultExpr can be set.}}
}}
 
 
{{ClassMember
 
{{ClassMember
 
     |class=Par
 
     |class=Par
     |name=isToggle
+
     |name=defaultExpr
     |returns=
+
     |type=str
     |set=0
+
     |set=1
     |text=True for toggle parameters.
+
     |text=Get or set the parameter's default expression. Can only be set on [[Custom Parameters]].  Only one of default, defaultExpr can be set.
}}
+
<syntaxhighlight lang=python>
 +
# value defaults to this expression.
 +
op('base1').par.Size.defaultExpr = 'me.time.frame'
 +
</syntaxhighlight>}}
 
{{ClassMember
 
{{ClassMember
 
     |class=Par
 
     |class=Par
     |name=label
+
     |name=normMin
     |returns=
+
     |type=float
     |set=0
+
     |set=1
     |text=Get or set the parameter's label. Example: Translate. Can only be set on Custom Parameters.
+
     |text=Get or set the parameter's minimum slider value if the parameter is a numerical slider. Can only be set on [[Custom Parameters]].}}
}}
 
 
{{ClassMember
 
{{ClassMember
 
     |class=Par
 
     |class=Par
     |name=max
+
     |name=normMax
     |returns=
+
     |type=float
     |set=0
+
     |set=1
     |text=Get or set the parameter's numerical maximum value. The parameter's value will be clamped at that maximum if clampMax = True. Can only be set on Custom Parameters.
+
     |text=Get or set the parameter's maximum slider value if the parameter is a numerical slider. Can only be set on [[Custom Parameters]].}}
}}
 
 
{{ClassMember
 
{{ClassMember
 
     |class=Par
 
     |class=Par
     |name=menuIndex
+
     |name=normVal
     |returns=
+
     |type=float
     |set=0
+
     |set=1
     |text=Get or set a menu constant value by its index.
+
     |text=Get or set the parameter's value as a normalized slider position. Can only be set on [[Custom Parameters]].}}
}}
 
 
{{ClassMember
 
{{ClassMember
 
     |class=Par
 
     |class=Par
     |name=menuLabels
+
     |name=enable
     |returns=
+
     |type=bool
     |set=0
+
     |set=1
     |text=Get or set a list of all possible menu choice labels. In the case of non menu parameters, None is returned. Can only be set on Custom Parameters.
+
     |text=Get or set the parameter's enable state. Can only be set on [[Custom Parameters]].}}
}}
 
 
{{ClassMember
 
{{ClassMember
 
     |class=Par
 
     |class=Par
     |name=menuNames
+
     |name=order
     |returns=
+
     |type=int
     |set=0
+
     |set=1
     |text=Get or set a list of all possible menu choice names. In the case of non menu parameters, None is returned. Can only be set on Custom Parameters.
+
     |text=Get or set the custom parameter's position on the parameter page. Can only be set on [[Custom Parameters]].}}
}}
 
 
{{ClassMember
 
{{ClassMember
 
     |class=Par
 
     |class=Par
     |name=menuSource
+
     |name=page
     |returns=
+
     |type=td.Page
     |set=0
+
     |set=1
     |text=Get or set an expression that returns an object with .menuItems .menuNames members.  This can be used to create a custom menu whose entries dynamically follow that of another menu for example.   Example:  p.menuSource = "op('audiodevin1').par.device".  Note the outside quotes, as menuSource is an expression, not an object.
+
     |text=Get or set the parameter page the custom parameter is part of. Can only be set on [[Custom Parameters]].}}
}}
 
 
{{ClassMember
 
{{ClassMember
 
     |class=Par
 
     |class=Par
     |name=min
+
     |name=password
     |returns=
+
     |type=bool
     |set=0
+
     |set=1
     |text=Get or set the parameter's numerical minimum value. The parameter's value will be clamped at that minimum if clampMin = True. Can only be set on Custom Parameters.
+
     |text=Get or set the parameter's password mode. When True all text is rendered as asterisks. Can only be set on Custom string, int or float parameters. [[Custom Parameters]].}}
}}
+
 
 +
 
 
{{ClassMember
 
{{ClassMember
 
     |class=Par
 
     |class=Par
 
     |name=mode
 
     |name=mode
     |returns=
+
     |type=ParMode
     |set=0
+
     |set=1
 
     |text=Get or set the parameter's evaluation mode.
 
     |text=Get or set the parameter's evaluation mode.
 
+
<syntaxhighlight lang=python>
 
op('geo1').par.tx.mode = ParMode.EXPRESSION
 
op('geo1').par.tx.mode = ParMode.EXPRESSION
 
+
</syntaxhighlight>
The mode is one of:  ParMode.CONSTANT, ParMode.EXPRESSION, or ParMode.EXPORT.
+
The mode is one of:  <code>ParMode.CONSTANT</code>, <code>ParMode.EXPRESSION</code>, or <code>ParMode.EXPORT</code>, or <code>ParMode.BIND</code>.
 
+
See [[Parameter_Dialog#Working_with_Parameter_Modes]] for more information.}}
See Parameter_Dialog#Working_with_Parameter_Modes for more information.
 
}}
 
 
{{ClassMember
 
{{ClassMember
 
     |class=Par
 
     |class=Par
     |name=name
+
     |name=prevMode
     |returns=
+
     |type=ParMode
 
     |set=0
 
     |set=0
     |text=Get or set the parameter's unique name. Example: Translate. Can only be set on Custom Parameters.
+
     |text=The parameter's previous evaluation mode.
 
}}
 
}}
 
{{ClassMember
 
{{ClassMember
 
     |class=Par
 
     |class=Par
     |name=normMax
+
     |name=menuNames
     |returns=
+
     |type=list
     |set=0
+
     |set=1
     |text=Get or set the parameter's maximum slider value if the parameter is a numerical slider. Can only be set on Custom Parameters.
+
     |text=Get or set a list of all possible menu choice names. In the case of non menu parameters, None is returned. Can only be set on [[Custom Parameters]].}}
 +
{{ClassMember
 +
    |class=Par
 +
    |name=menuLabels
 +
    |type=list
 +
    |set=1
 +
    |text=Get or set a list of all possible menu choice labels. In the case of non menu parameters, None is returned. Can only be set on [[Custom Parameters]].}}
 +
{{ClassMember
 +
    |class=Par
 +
    |name=menuIndex
 +
    |type=int
 +
    |set=1
 +
    |text=Get or set a menu constant value by its index.
 
}}
 
}}
 
{{ClassMember
 
{{ClassMember
 
     |class=Par
 
     |class=Par
     |name=normMin
+
     |name=menuSource
     |returns=
+
     |type=str
     |set=0
+
     |set=1
     |text=Get or set the parameter's minimum slider value if the parameter is a numerical slider. Can only be set on Custom Parameters.
+
     |text=Get or set an expression that returns an object with .menuItems .menuNames members.  This can be used to create a custom menu whose entries dynamically follow that of another menu for example.
 +
<syntaxhighlight lang=python>
 +
p.menuSource = "op('audiodevin1').par.device"
 +
</syntaxhighlight>
 +
Note the outside quotes, as menuSource is an expression, not an object.
 
}}
 
}}
 
{{ClassMember
 
{{ClassMember
 
     |class=Par
 
     |class=Par
     |name=normVal
+
     |name=owner
     |returns=
+
     |type=OP
 
     |set=0
 
     |set=0
     |text=Get or set the parameter's value as a normalized slider position. Can only be set on Custom Parameters.
+
     |text=The [[OP Class|OP]] to which this object belongs.}}
 +
{{SubSection|title=Type Members
 +
|text=
 
}}
 
}}
 
{{ClassMember
 
{{ClassMember
 
     |class=Par
 
     |class=Par
     |name=order
+
     |name=isDefault
     |returns=
+
     |type=bool
 
     |set=0
 
     |set=0
     |text=The custom parameter's position on the parameter page.  Can only be set on Custom Parameters.
+
     |text=True when the parameter value, expression and mode are in their default settings.
 
}}
 
}}
 
{{ClassMember
 
{{ClassMember
 
     |class=Par
 
     |class=Par
     |name=owner
+
     |name=isCustom
     |returns=
+
     |type=bool
 
     |set=0
 
     |set=0
     |text=The OP to which this object belongs.
+
     |text=True for [[Custom Parameters]].}}
}}
 
 
{{ClassMember
 
{{ClassMember
 
     |class=Par
 
     |class=Par
     |name=page
+
     |name=isPulse
     |returns=
+
     |type=bool
 
     |set=0
 
     |set=0
     |text=The custom parameter page the parameter is part of.  Can only be set on Custom Parameters.
+
     |text=True for pulse parameters.
 
}}
 
}}
 
{{ClassMember
 
{{ClassMember
 
     |class=Par
 
     |class=Par
     |name=prevMode
+
     |name=isMomentary
     |returns=
+
     |type=bool
 
     |set=0
 
     |set=0
     |text=The parameter's previous evaluation mode.
+
     |text=True for momentary parameters.
 
}}
 
}}
 
{{ClassMember
 
{{ClassMember
 
     |class=Par
 
     |class=Par
     |name=startSection
+
     |name=isMenu
     |returns=
+
     |type=bool
 
     |set=0
 
     |set=0
     |text=Get or set the parameter's separator status. When True a visible separator is drawn between this parameter and the ones preceding it. Can only be set on Custom Parameters.
+
     |text=True for menu parameters.
 
}}
 
}}
 
{{ClassMember
 
{{ClassMember
 
     |class=Par
 
     |class=Par
     |name=style
+
     |name=isNumber
     |returns=
+
     |type=bool
 
     |set=0
 
     |set=0
     |text=Describes the behaviour and contents of the custom parameter. Example 'Float', 'Int', 'Pulse', 'XYZ', etc.
+
     |text=True for numeric parameters.
 
}}
 
}}
 
{{ClassMember
 
{{ClassMember
 
     |class=Par
 
     |class=Par
     |name=tuplet
+
     |name=isFloat
     |returns=
+
     |type=bool
 
     |set=0
 
     |set=0
     |text=The tuplet of parameters this parameter belongs to. A tuplet is typically a set of parameters sharing one line on a parameter dialog, example:  Translate (x, y, z).
+
     |text=True for floating point numeric parameters.
 
}}
 
}}
 
{{ClassMember
 
{{ClassMember
 
     |class=Par
 
     |class=Par
     |name=tupletName
+
     |name=isInt
     |returns=
+
     |type=bool
 
     |set=0
 
     |set=0
     |text=The tuplet name of a parameter.  Example: The tuplet name of a (tx,ty,tz) translate parameter is t.
+
     |text=True for integer numeric parameters.
 
}}
 
}}
 
{{ClassMember
 
{{ClassMember
 
     |class=Par
 
     |class=Par
     |name=val
+
     |name=isOP
     |returns=
+
     |type=bool
 
     |set=0
 
     |set=0
     |text=Get or set the constant value of the parameter only.
+
     |text=True for OP parameters.
 
 
op('geo1').par.tx.val = 5
 
op('geo1').par.tx = 5  #equivalent to above, more concise form
 
 
 
When setting this member, the parameter will also be placed in constant mode.  See mode member below.
 
 
 
 
 
To get the parameter's current value, regardless if it's from a constant, expression, or export, use the eval() method described below.  To set a menu value by its index, use the menuIndex member as described below.
 
 
}}
 
}}
 
{{ClassMember
 
{{ClassMember
 
     |class=Par
 
     |class=Par
     |name=valid
+
     |name=isPython
     |returns=
+
     |type=bool
 
     |set=0
 
     |set=0
     |text=True if the referenced parameter currently exists, False if it has been deleted.
+
     |text=True for python parameters.
 
}}
 
}}
 
{{ClassMember
 
{{ClassMember
 
     |class=Par
 
     |class=Par
     |name=index
+
     |name=isString
     |returns=
+
     |type=bool
 
     |set=0
 
     |set=0
     |text=The parameter's order in the list.
+
     |text=True for string parameters.
 
}}
 
}}
 
{{ClassMember
 
{{ClassMember
 
     |class=Par
 
     |class=Par
     |name=vecIndex
+
     |name=isToggle
     |returns=
+
     |type=bool
 
     |set=0
 
     |set=0
     |text=The parameter's vector index. For example, op('geo1').par.tz would have a value of 2.
+
     |text=True for toggle parameters.
 
}}
 
}}
{{ClassMethodSection|empty=}}
+
{{ClassMember
{{ClassMethod
 
 
     |class=Par
 
     |class=Par
     |name=evalExpression
+
     |name=style
     |call=evalExpression()
+
     |type=str
     |returns=
+
     |set=0
     |text=: -> value
+
     |text=Describes the behavior and contents of the custom parameter. Example <code>'Float'</code>, <code>'Int'</code>, <code>'Pulse'</code>, <code>'XYZ'</code>, etc.
Evaluate the expression portion of a parameter, if it contains one.  This will ignore any exports, etc.
 
a = op('geo1').par.tx.evalExpression()
 
To evaluate an arbitrary expression string, that is not inside a parameter, see OP.evalExpression.
 
 
}}
 
}}
 +
{{SubSection|title=Menu Parameters
 +
|text=Menu parameters can be get or set by specifying either the string value of the menu, or its numeric index. For example, the following are equivalent:
 +
<syntaxhighlight lang=python>
 +
op('geo1').par.xord = 'trs'
 +
op('geo1').par.xord = 5
 +
</syntaxhighlight>
 +
Alternatively, the menu can be accessed more directly:
 +
<syntaxhighlight lang=python>
 +
n = op('geo1')
 +
n.par.xord.menuIndex = 5  #trs
 +
a = n.menuNames[0]  #returns 'srt'
 +
b = n.menuLabels[0] #returns 'Scale Rotate Translate'
 +
</syntaxhighlight>
 +
}}}}
 +
{{ClassMethodSection|empty=
 +
|Sectionsummary=
 +
|items=
 
{{ClassMethod
 
{{ClassMethod
 
     |class=Par
 
     |class=Par
 
     |name=copy
 
     |name=copy
 
     |call=copy(Par)
 
     |call=copy(Par)
     |returns=
+
     |returns=None
     |text=:
+
     |text=Copy the specified [[Par Class|parameter]].
Copy the specified parameter.
+
*Par - The parameter to copy.
Par - The parameter to copy.
+
<syntaxhighlight lang=python>
 
op('geo1').par.tx.copy( op('geo2').par.tx )
 
op('geo1').par.tx.copy( op('geo2').par.tx )
}}
+
</syntaxhighlight>}}
 
{{ClassMethod
 
{{ClassMethod
 
     |class=Par
 
     |class=Par
     |name=destroy
+
     |name=eval
     |call=destroy()
+
     |call=eval()
     |returns=
+
     |returns=value
     |text=:
+
     |text=Evaluate a parameter. This value may be derived by the parameter's constant value, expression, or export, dependent on its mode.
Destroy the custom parameter referenced by this Par. An exception will be raised if the parameter has already been destroyed.
+
<syntaxhighlight lang=python>
 +
a = op('geo1').par.tx.eval()
 +
</syntaxhighlight>
 
}}
 
}}
 
{{ClassMethod
 
{{ClassMethod
Line 375: Line 410:
 
     |name=evalNorm
 
     |name=evalNorm
 
     |call=evalNorm()
 
     |call=evalNorm()
     |returns=
+
     |returns=value
     |text=: -> value
+
     |text=Similar to eval() but the returns the normalized slider value.
Similar to eval() but the returns the normalized slider value.
 
 
}}
 
}}
 
{{ClassMethod
 
{{ClassMethod
 
     |class=Par
 
     |class=Par
     |name=pulse
+
     |name=evalExpression
     |call=pulse(value, frames=nframes, seconds=nseconds)
+
     |call=evalExpression()
     |returns=
+
     |returns=value
     |text=:
+
     |text=Evaluate the expression portion of a parameter, if it contains one. This will ignore any exports, etc.
Pulsing sets a parameter to the specific value, cooks the operator, then restores the parameter to its previous value.
+
<syntaxhighlight lang=python>
No value is necessary when the parameter is an actual pulse type.
+
a = op('geo1').par.tx.evalExpression()
value - (Optional) The value to pulse this parameter with, default is 1.
+
</syntaxhighlight>
frames - (Optional) Number of frames before restoring the parameter to its original value.
+
To evaluate an arbitrary expression string, that is not inside a parameter, see [[OP Class|OP]].evalExpression.}}
seconds - (Optional) Number of seconds before restoring the parameter to its original value.
 
op('moviein1').par.reload.pulse(1)  #set the reload toggle, then cook
 
op('glsl1').par.loadvariablenames.pulse() #activate the pulse parameter
 
op('geo1').par.ty.pulse(2, frames=120) #pulse geometry ty for 120 frames
 
op('text1').par.text.pulse('GO!', seconds=3)#pulse text TOP string field, for 3 seconds
 
op('noise').par.type.pulse('random', seconds=0.5)#pulse noise meny type for half a second
 
}}
 
{{ClassMethod
 
    |class=Par
 
    |name=eval
 
    |call=eval()
 
    |returns=
 
    |text=: -> value
 
Evaluate a parameter.  This value may be derived by the parameter's constant value, expression, or export, dependent on its mode.
 
a = op('geo1').par.tx.eval()
 
}}
 
 
{{ClassMethod
 
{{ClassMethod
 
     |class=Par
 
     |class=Par
 
     |name=evalExport
 
     |name=evalExport
 
     |call=evalExport()
 
     |call=evalExport()
     |returns=
+
     |returns=value
     |text=: -> value
+
     |text=Evaluate the export portion of a parameter, if it contains one. This will ignore any expressions, etc.
Evaluate the export portion of a parameter, if it contains one. This will ignore any expressions, etc.
+
<syntaxhighlight lang=python>
 
a = op('geo1').par.tx.evalExport()
 
a = op('geo1').par.tx.evalExport()
 +
</syntaxhighlight>
 
}}
 
}}
 
{{ClassMethod
 
{{ClassMethod
Line 418: Line 437:
 
     |name=evalOPs
 
     |name=evalOPs
 
     |call=evalOPs()
 
     |call=evalOPs()
     |returns=
+
     |returns=list
     |text=: -> list
+
     |text=Evaluate the parameter as series of operators. This is useful for a custom  parameter that specifies a list of operator paths for example.
Evaluate the parameter as series of operators. This is useful for a custom  parameter that specifies a list of operator paths for example.
+
<syntaxhighlight lang=python>
 
a = op('base1').par.Paths.evalOPs()
 
a = op('base1').par.Paths.evalOPs()
 +
</syntaxhighlight>
 
}}
 
}}
 +
{{ClassMethod
 +
    |class=Par
 +
    |name=pulse
 +
    |call=pulse(value, frames=nframes, seconds=nseconds)
 +
    |returns=None
 +
    |text=Pulsing sets a parameter to the specific value, cooks the operator, then restores the parameter to its previous value.
 +
For pulse type parameters no value is specified or used.
 +
*value - (Optional) The value to pulse this parameter with, default is 1.
 +
*frames - (Optional) Number of frames before restoring the parameter to its original value.
 +
*seconds - (Optional) Number of seconds before restoring the parameter to its original value.
 +
<syntaxhighlight lang=python>
 +
op('moviein1').par.reload.pulse(1) #set the reload toggle, then cook
 +
op('glsl1').par.loadvariablenames.pulse() #activate the pulse parameter
 +
op('geo1').par.ty.pulse(2, frames=120) #pulse geometry ty for 120 frames
 +
op('text1').par.text.pulse('GO!', seconds=3) #pulse text TOP string field, for 3 seconds
 +
op('noise').par.type.pulse('random', seconds=0.5) #pulse noise meny type for half a second
 +
</syntaxhighlight>
 +
}}
 +
{{ClassMethod
 +
    |class=Par
 +
    |name=destroy
 +
    |call=destroy()
 +
    |returns=None
 +
    |text=Destroy the custom parameter referenced by this Par. An exception will be raised if the parameter has already been destroyed.
 +
}}
 +
{{SubSection|title=Casting to a Value
 +
|text=The Par Class implements all necessary methods to be treated as a number or string, which in this case gets or sets its value. Therefore, an explicit call to <syntaxhighlight lang=python inline>eval()</syntaxhighlight> or <syntaxhighlight lang=python inline>set()</syntaxhighlight> is unnecessary when used in a parameter, or in a numeric expression.
 +
 +
For example, the following are equivalent in a parameter:
 +
 +
*<syntaxhighlight lang=python inline>(float)me.par.tx</syntaxhighlight>
 +
*<syntaxhighlight lang=python inline>me.par.tx.eval()</syntaxhighlight>
 +
*<syntaxhighlight lang=python inline>me.par.tx</syntaxhighlight>
 +
 +
The following are also equivalent:
 +
 +
*<syntaxhighlight lang=python inline>me.par.tx.eval() + 1</syntaxhighlight>
 +
*<syntaxhighlight lang=python inline>me.par.tx + 1</syntaxhighlight>
 +
 +
As are the following:
 +
 +
*<syntaxhighlight lang=python inline>me.par.tx.val = 3</syntaxhighlight>
 +
*<syntaxhighlight lang=python inline>me.par.tx = 3</syntaxhighlight>
 +
}}}}
 
<section end=HELPBODY />
 
<section end=HELPBODY />
<taggedhistory/>
+
{{History}}
 
+
{{#invoke:Category|list|Python Reference}}
{{{{#invoke:Category|list|Python Reference}}}}
 

Latest revision as of 17:52, 30 July 2019

The Par class describes an instance of a single Parameter. See also Custom Parameters.


Members[edit]

validbool (Read Only):

True if the referenced parameter currently exists, False if it has been deleted.

valvalue :

Get or set the constant value of the parameter only. To get the parameter's current value, regardless of the Parameter Mode (constant, expression, export or bound), use the eval() method described below.

op('geo1').par.tx.val   # the constant value 
op('geo1').par.tx.eval()   # the evaluated parameter
op('geo1').par.tx.val = 5
op('geo1').par.tx = 5  #equivalent to above, more concise form

When setting this member, the parameter will also be placed in constant mode. See mode member below.

To set a menu value by its index, use the menuIndex member as described below.

exprstr :

Get or set the non-evaluated expression only. To get the parameter's current value, regardless of the Parameter Mode (constant, expression, export or bound), use the eval() method described below.

op('geo1').par.tx.expr = 'absTime.frame'  #set to match current frame

When setting this member, the parameter will also be placed in expression mode. See mode member below.

NOTE: For convenience, the expression is placed in double-quotes so you can safely put in expressions containing single quotes. 'a' and "a" have the same effect of enclosing strings in python.

exportOPOP or None (Read Only):

The operator exporting to this parameter.

exportSourceCell Channel or None (Read Only):

The object exporting to this parameter. Examples: Cell, Channel or None.

bindExprexpression :

Get or set an expression that returns a Parameter object. This can be used to bind this parameter's constant value to the referenced parameter.

p.bindExpr = "op('geo1').par.tx"

Note the outside quotes, as bindExpr is an expression, not an object.

bindMasterOP or None (Read Only):

The object to which this parameter is bound to, possibly None.

bindReferenceslist (Read Only):

The (possibly empty) list of objects which bind to this parameter.

indexint (Read Only):

The parameter's order in the list.

vecIndexint (Read Only):

The parameter's vector index. For example, op('geo1').par.tz would have a value of 2.

namestr :

Get or set the parameter's unique name.

op('myOperator').par.Custompar.name = 'Translate'

Can only be set on Custom Parameters.

labelstr :

Get or set the parameter's label.

op('myOperator').par.Custompar.label = 'Translate'

Can only be set on Custom Parameters.

startSectionbool :

Get or set the parameter's separator status. When True a visible separator is drawn between this parameter and the ones preceding it. Can only be set on Custom Parameters.

displayOnlybool :

Get or set the parameter's displayOnly state. Can only be set on Custom Parameters.

readOnlybool :

Get or set the parameter's read only status. When True the parameter cannot be modified through the UI, only scripting.

tuplettuplet (Read Only):

The tuplet of parameters this parameter belongs to. A tuplet is typically a set of parameters sharing one line on a parameter dialog, example: Translate (x, y, z).

tupletNamestr (Read Only):

The tuplet name of a parameter. Example: The tuplet name of a (tx,ty,tz) translate parameter is t.

minvalue :

Get or set the parameter's numerical minimum value. The parameter's value will be clamped at that minimum if clampMin = True. Can only be set on Custom Parameters.

maxvalue :

Get or set the parameter's numerical maximum value. The parameter's value will be clamped at that maximum if clampMax = True. Can only be set on Custom Parameters.

clampMinbool :

Get or set the parameter's numerical clamping behavior. If set to clampMin = True, the parameter will clamp on the lower end at the value specified in min Can only be set on Custom Parameters.

clampMaxbool :

Get or set the parameter's numerical clamping behavior. If set to clampMax = True, the parameter will clamp on the upper end at the value specified in max Can only be set on Custom Parameters.

defaultvalue :

Get or set the parameter's default value. Can only be set on Custom Parameters. Only one of default, defaultExpr can be set.

defaultExprstr :

Get or set the parameter's default expression. Can only be set on Custom Parameters. Only one of default, defaultExpr can be set.

# value defaults to this expression.
op('base1').par.Size.defaultExpr = 'me.time.frame'

normMinfloat :

Get or set the parameter's minimum slider value if the parameter is a numerical slider. Can only be set on Custom Parameters.

normMaxfloat :

Get or set the parameter's maximum slider value if the parameter is a numerical slider. Can only be set on Custom Parameters.

normValfloat :

Get or set the parameter's value as a normalized slider position. Can only be set on Custom Parameters.

enablebool :

Get or set the parameter's enable state. Can only be set on Custom Parameters.

orderint :

Get or set the custom parameter's position on the parameter page. Can only be set on Custom Parameters.

pagetd.Page :

Get or set the parameter page the custom parameter is part of. Can only be set on Custom Parameters.

passwordbool :

Get or set the parameter's password mode. When True all text is rendered as asterisks. Can only be set on Custom string, int or float parameters. Custom Parameters.


modeParMode :

Get or set the parameter's evaluation mode.

op('geo1').par.tx.mode = ParMode.EXPRESSION

The mode is one of: ParMode.CONSTANT, ParMode.EXPRESSION, or ParMode.EXPORT, or ParMode.BIND.

See Parameter_Dialog#Working_with_Parameter_Modes for more information.

prevModeParMode (Read Only):

The parameter's previous evaluation mode.

menuNameslist :

Get or set a list of all possible menu choice names. In the case of non menu parameters, None is returned. Can only be set on Custom Parameters.

menuLabelslist :

Get or set a list of all possible menu choice labels. In the case of non menu parameters, None is returned. Can only be set on Custom Parameters.

menuIndexint :

Get or set a menu constant value by its index.

menuSourcestr :

Get or set an expression that returns an object with .menuItems .menuNames members. This can be used to create a custom menu whose entries dynamically follow that of another menu for example.

p.menuSource = "op('audiodevin1').par.device"

Note the outside quotes, as menuSource is an expression, not an object.

ownerOP (Read Only):

The OP to which this object belongs.

Type Members[edit]

isDefaultbool (Read Only):

True when the parameter value, expression and mode are in their default settings.

isCustombool (Read Only):

True for Custom Parameters.

isPulsebool (Read Only):

True for pulse parameters.

isMomentarybool (Read Only):

True for momentary parameters.

isMenubool (Read Only):

True for menu parameters.

isNumberbool (Read Only):

True for numeric parameters.

isFloatbool (Read Only):

True for floating point numeric parameters.

isIntbool (Read Only):

True for integer numeric parameters.

isOPbool (Read Only):

True for OP parameters.

isPythonbool (Read Only):

True for python parameters.

isStringbool (Read Only):

True for string parameters.

isTogglebool (Read Only):

True for toggle parameters.

stylestr (Read Only):

Describes the behavior and contents of the custom parameter. Example 'Float', 'Int', 'Pulse', 'XYZ', etc.

Menu Parameters[edit]

Menu parameters can be get or set by specifying either the string value of the menu, or its numeric index. For example, the following are equivalent:

op('geo1').par.xord = 'trs'
op('geo1').par.xord = 5

Alternatively, the menu can be accessed more directly:

n = op('geo1')
n.par.xord.menuIndex = 5  #trs
a = n.menuNames[0]  #returns 'srt'
b = n.menuLabels[0] #returns 'Scale Rotate Translate'

Methods[edit]

copy(Par)None:

Copy the specified parameter.

  • Par - The parameter to copy.
op('geo1').par.tx.copy( op('geo2').par.tx )

eval()value:

Evaluate a parameter. This value may be derived by the parameter's constant value, expression, or export, dependent on its mode.

a = op('geo1').par.tx.eval()

evalNorm()value:

Similar to eval() but the returns the normalized slider value.

evalExpression()value:

Evaluate the expression portion of a parameter, if it contains one. This will ignore any exports, etc.

a = op('geo1').par.tx.evalExpression()

To evaluate an arbitrary expression string, that is not inside a parameter, see OP.evalExpression.

evalExport()value:

Evaluate the export portion of a parameter, if it contains one. This will ignore any expressions, etc.

a = op('geo1').par.tx.evalExport()

evalOPs()list:

Evaluate the parameter as series of operators. This is useful for a custom parameter that specifies a list of operator paths for example.

a = op('base1').par.Paths.evalOPs()

pulse(value, frames=nframes, seconds=nseconds)None:

Pulsing sets a parameter to the specific value, cooks the operator, then restores the parameter to its previous value.

For pulse type parameters no value is specified or used.

  • value - (Optional) The value to pulse this parameter with, default is 1.
  • frames - (Optional) Number of frames before restoring the parameter to its original value.
  • seconds - (Optional) Number of seconds before restoring the parameter to its original value.
op('moviein1').par.reload.pulse(1) #set the reload toggle, then cook
op('glsl1').par.loadvariablenames.pulse() #activate the pulse parameter
op('geo1').par.ty.pulse(2, frames=120) #pulse geometry ty for 120 frames
op('text1').par.text.pulse('GO!', seconds=3) #pulse text TOP string field, for 3 seconds
op('noise').par.type.pulse('random', seconds=0.5) #pulse noise meny type for half a second

destroy()None:

Destroy the custom parameter referenced by this Par. An exception will be raised if the parameter has already been destroyed.

Casting to a Value[edit]

The Par Class implements all necessary methods to be treated as a number or string, which in this case gets or sets its value. Therefore, an explicit call to eval() or set() is unnecessary when used in a parameter, or in a numeric expression.

For example, the following are equivalent in a parameter:

  • (float)me.par.tx
  • me.par.tx.eval()
  • me.par.tx

The following are also equivalent:

  • me.par.tx.eval() + 1
  • me.par.tx + 1

As are the following:

  • me.par.tx.val = 3
  • me.par.tx = 3

TouchDesigner Build:

Any of the procedural data operators. OPs do all the work in TouchDesigner. They "cook" and output data to other OPs, which ultimately result in new images, data and audio being generated. See Node.

To pulse a parameter is to send it a signal from a CHOP or python or a mouse click that causes a new action to occur immediately. A pulse via python is via the .pulse() function on a pulse-type parameter, such as Reset in a Speed CHOP. A pulse from a CHOP is typically a 0 to 1 to 0 signal in a channel.

An Operator Family that creates, composites and modifies images, and reads/writes images and movies to/from files and the network. TOPs run on the graphics card's GPU.