Close

Par Class

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


Members

valAny :

Get or set the constant mode value of the parameter only. Important: To get the parameter's current working value, regardless of the Parameter Mode (constant, expression, export or bound), always 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
op('parexec1').par.op = [parent(), parent(2)] # you can assign a list of ops to a parameter that allows multiple operators

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.

enableExprstr :

Get or set an expression that controls the enable state for this parameter.

p.enableExpr = "me.par.X.menuIndex == 5"
# Note the outside quotes, as this is an expression, not an object.

exportOPOP (Read Only):

The operator exporting to this parameter.

exportSourceChannel (Read Only):

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

bindExprstr :

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

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

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

bindMasterOP (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.

bindRangebool :

Get or set parameter's range binding state. If True, min, max, clampMin, clampMax, normMin, normMax, normVal values will be based on master bind parameter. Can only be set on Custom Parameters.

hiddenbool (Read Only):

Get the parameter's hidden status. When True the parameter is considered obsolete or irrelevant and should not be modified. They are not shown in the dialog but only maintained for backward compatibility.

indexint (Read Only):

A unique identifier for the parameter. May change in the case of custom parameters.

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.

subLabelstr (Read Only):

Returns the name of the sub-label.

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.

readOnlybool :

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

helpstr (Read Only):

Get or set a custom parameter's help text. To see any parameter's help, rollover the parameter while holding the Alt key. For built-in parameters this can be used to get the parameter's help text.

parGroupParGroup (Read Only):

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

minint :

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.

maxint :

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.

defaultAny :

Get or set the parameter's default value. Can only be set on Custom Parameters.

defaultBindExprstr :

Get or set the parameter's default bind expression. Can only be set on Custom Parameters.

op('base1').par.Size.defaultBindExpr = 'me.par.tx'

defaultExprstr :

Get or set the parameter's default expression. Can only be set on Custom Parameters.

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

defaultModeParMode :

Get or set the parameter's default evaluation mode.

op('geo1').par.tx.defaultMode = 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.

normMinint :

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

normMaxint :

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.

orderfloat :

Get or set the 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. Simple menu sources include another parameter with a menu c, an object created by tdu.TableMenu, or an object created by TDFunctions.parMenu.

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

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

validbool (Read Only):

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

sequenceSequence | None (Read Only):

The Sequence this parameter belongs to. None if not in a sequence.

sequenceBlockSequenceBlock | None (Read Only):

The SequenceBlock this parameter belongs to. None if not in a sequence.

ownerOP (Read Only):

The OP to which this object belongs.

styleCloneImmunebool :

Get or set the parameter's style 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.

lastScriptChangetuple (Read Only):

Return information about when this parameter was last modified by a script. Cleared when the parameter is updated via the UI.

python >>> op('/level1').par.invert.lastScriptChange
SetInfo(dat=type:textDAT path:/text1, function='<module>', line=1, frame=300061, timeStamp=1613150878)

Type Members

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.

isSequencebool (Read Only):

True for sequence header 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.

collapserbool (Read Only):

Returns True if the parameter is a parent of collapsable parameters (ie. a collapser).

collapsablebool (Read Only):

Returns True if the parameter is collapsable.

Menu Parameters

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

copy(Par)None:

Copy the specified parameter.

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

eval()Any:

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

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

Calling eval on an OP parameter that can hold multiple OPs will return a single OP if there is only 1 result, a list of OPs if there are more than 1, and None if there are no results.

evalNorm()float:

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

evalExpression()Any:

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

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

Note: the results of evalExpression is always the expression's Python return value, which can be slightly different than Par.eval(). For example, in parameters that hold an operator, .eval() will always return an operator if it exists, even if the expression actually returns a string path. The evalExpression function would return the string path.

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

evalExport()Any:

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[OP]:

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()

evalFile()tdu.FileInfo:

Evaluate the parameter as a file path. This returns a FileInfo object with the full path.

a = op('moviefilein1').par.file.evalFile()
print(a.ext)
print(a.baseName)
print(a.exists)

pulse(value=1, frames=0, seconds=0)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 or time 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 parameter referenced by this Par. An exception will be raised if the parameter has already been destroyed. Only custom and sequential parameters can be destroyed. Destroying a sequential parameter will destroy its entire block. Note: When any parameter is destroyed, any existing parameter objects will be invalid and should be re-fetched.

reset()bool:

Resets the parameter to its default state.

Returns true if anything was changed.

op('geo1').par.tx.reset()

isPar(par : Par)bool:

True if the provided Par is the same parameter on the same operator. Because op('container1').par.x == op('container2').par.x compares values and op('container1').par.x is op('container1').par.x is always False (because of TouchDesigner internals), you must use isPar to compare parameter objects.

  • par - The parameter to compare identity with.

Casting to a Value

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

Note: However, you can't use functions belonging to the cast object type without evaluating the parameter:

  • me.par.tx.hex() # doesn't work
  • me.par.tx.eval().hex() # works!

TouchDesigner Build: