uvi-script
Musical event scripting with Lua
ParameterValue Class Reference

A non-visual (logical) binding to an existing Element parameter. More...

Inheritance diagram for ParameterValue:
Widget

Public Member Functions

 ParameterValue (Element elementOrPath, string paramName)
 creates a logical binding to an existing Element parameter.
 
 ParameterValue (string name)
 creates an unbound binding, to be targeted later with bind.
 
void bind (Element elementOrPath, string paramName)
 bind the widget to another parameter, or bind an unbound widget for the first time.
 
string toString ()
 

Public Attributes

Value value
 the bound parameter's value (read and write)
 
bool bound
 true if the target element/parameter was resolved (read-only)
 
- Public Attributes inherited from Widget
string name
 widget name, given at construction (read-only)
 
string displayName
 widget display name
 
string displayText
 custom text to display in place of the standard value display, on widgets that show one.
 
string tooltip
 widget tooltip, default is name
 
int x
 x position in pixels
 
int y
 y position in pixels
 
int width
 widget width in pixels
 
int height
 widget height in pixels
 
int w
 alias of width
 
int h
 alias of height
 
table size
 widget size {width, height}
 
table position
 widget position {x,y}
 
table pos
 alias of position
 
table bounds
 widget bounding rect {x,y,width,height}
 
number alpha
 transparency value between 0.0 and 1.0
 
bool enabled
 boolean flag to enable / disable the widget
 
bool visible
 boolean flag to toggle widget visibility
 
bool interceptsMouseClicks
 boolean flag to toggle mouse handling on widget.
 
bool showLabel
 show widgets label if any
 
bool persistent
 flag to tell if the widget values should be serialized when saving.
 
function changed
 callback function used by child widgets to be notified of changes.
 

Detailed Description

A non-visual (logical) binding to an existing Element parameter.

Unlike the Param* widgets, this draws nothing: it exposes the parameter through a read/write value, staying in sync with host automation, modulation and preset changes. Useful to observe or drive a parameter without placing a control on the UI. It is a global function only (not a Panel method) and does not accept widget layout options.

Its changed callback is called each time the parameter changes, and once when the script's interface is built.

Note
A path-string target binds only when the script's interface is built: until then value is nil, writes are dropped and bound is false. An Element reference binds at once. A write whose Lua type does not match the parameter's type is dropped without an error.
-- inserts[4] is a Gain effect: its Volume is a linear gain, 1.0 is unity
local vol = ParameterValue(Program.auxs[1].inserts[4], "Volume")
vol.value = 0.5 -- write the parameter (about -6 dB)
print(vol.value) -- read it back
ParameterValue(Element elementOrPath, string paramName)
creates a logical binding to an existing Element parameter.
Value value
the bound parameter's value (read and write)
Definition ui.cpp:2193
A Patch that represents a monotimbral instrument.
Definition Engine.cpp:350
table auxs
all AuxEffect for this node, in position order. Falcon can add and delete them; a delete shifts the i...
Definition Engine.cpp:356

Constructor & Destructor Documentation

◆ ParameterValue() [1/2]

ParameterValue::ParameterValue ( Element elementOrPath,
string paramName )

creates a logical binding to an existing Element parameter.

Parameters
elementOrPathan Element reference, or a path string identifying one
paramNamethe parameter name (as used by setParameter)

◆ ParameterValue() [2/2]

ParameterValue::ParameterValue ( string name)

creates an unbound binding, to be targeted later with bind.

Until then it shows a placeholder and its value is nil.

Parameters
namethe widget name

Member Function Documentation

◆ bind()

void ParameterValue::bind ( Element elementOrPath,
string paramName )

bind the widget to another parameter, or bind an unbound widget for the first time.

The control is rebuilt with the new parameter's range, unit, mapper and value; rebinding to the same element and parameter does nothing. Typically called when the element the UI edits changes, e.g. the insert effect selected in an effect rack. Raises an error when the element no longer exists or has no such parameter.

Parameters
elementOrPathan Element reference, or a path string identifying one
paramNamethe parameter name (as used by setParameter)

◆ toString()

string ParameterValue::toString ( )
Returns
the parameter value formatted as a display string