uvi-script
Musical event scripting with Lua
ParamKnob Class Reference

A knob bound to an existing Element parameter. More...

Inheritance diagram for ParamKnob:
Widget

Public Member Functions

 ParamKnob (Element elementOrPath, string paramName)
 creates a knob bound to an existing Element parameter.
 
 ParamKnob (string name)
 creates an unbound knob, 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.
 
void setRange (number min, number max)
 override the range inherited from the parameter.
 
void setStripImage (string imagePath, int numImages)
 
void setLottieAnimation (string path)
 dress the widget with a Lottie animation, whose frame follows the value.
 

Public Attributes

number value
 the widget's value (read-only; reflects the bound parameter)
 
Unit::Type unit
 unit override, default is taken from the parameter
 
number default
 value restored by a reset (alt-click), in parameter units. Reads the parameter's default until overridden; nil while unbound. Useful for modulation depths, whose Ratio default is always 1
 
string stripImage
 path to knob strip image
 
bool showValue
 show/hide value display
 
bool showPopupDisplay
 show/hide the value popup display (if any)
 
string fillColour
 fill colour (named colour or RGB/ARGB hex string)
 
string outlineColour
 outline colour (named colour or RGB/ARGB hex string)
 
string lottieAnimation
 path to a Lottie animation or package, see Lottie Animations
 
- 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 knob bound to an existing Element parameter.

It drives a parameter that already lives on an engine Element instead of carrying its own value. The parameter provides the range, default, unit and response curve, so no min/max/default is passed at construction: the unit gives display formatting and text parsing for free, and the knob follows the parameter's own mapper. Moving the knob writes the parameter, and external changes (host automation, modulation, preset load) move the knob.

It is a Widget (not a Knob); it exposes the appearance properties below plus setRange, unit and default to override the inherited range, unit and reset value. Like every Param* widget it never calls a changed callback: use a ParameterValue on the same parameter to react to it from the script.

local fx = Program.inserts[1]
local drive = ParamKnob(fx, "DriveAmount")
ParamKnob(Element elementOrPath, string paramName)
creates a knob bound to an existing Element parameter.
A Patch that represents a monotimbral instrument.
Definition Engine.cpp:350
table inserts
all InsertEffect for this node
Definition Engine.cpp:355

Constructor & Destructor Documentation

◆ ParamKnob() [1/2]

ParamKnob::ParamKnob ( Element elementOrPath,
string paramName )

creates a knob bound to an existing Element parameter.

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

◆ ParamKnob() [2/2]

ParamKnob::ParamKnob ( string name)

creates an unbound knob, 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 ParamKnob::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)

◆ setLottieAnimation()

void ParamKnob::setLottieAnimation ( string path)

dress the widget with a Lottie animation, whose frame follows the value.

See Lottie Animations.

Parameters
pathpath to a .json animation or a .lottie package

◆ setRange()

void ParamKnob::setRange ( number min,
number max )

override the range inherited from the parameter.

Parameters
minminimum value
maxmaximum value

◆ setStripImage()

void ParamKnob::setStripImage ( string imagePath,
int numImages )
Parameters
imagePathpath to knob strip image. Supports Retina @2x variants.
numImagesnumber of images in strip