Page tree
Skip to end of metadata
Go to start of metadata

Description

Function to specify a parameter with the specified name and characteristics. The parameters you define can be used to configure the script module and save its state with the program. They are shown in the Parameter List from where you can connect them to controls on the macro page. For more details see Creating Parameters.

Available in: Controller.

Numeric

defineParameter(name, longName, default, min, max, increment, changeCallback)

Creates a numeric parameter. The default argument defines the value that the parameter will default to. The min and max arguments define the value range of the parameter. The increment argument defines the step size of the parameter. The arguments defaultminmax  and increment can be any integer or floating point value. How many digits are shown behind the decimal point for a value string of a parameter is determined by the value of the increment argument. For example:

ValueDescription
increment = 1The parameter will be an integer value and its value string will display no digits behind the decimal point.
increment = 0.001The parameter will be a floating point value and its value string will display three digits behind the decimal point.
increment = 0The parameter will be a floating point value and its value string will display two digits behind the decimal point.

The automatic formatting of a value can be overridden with the format argument. See Additional Named Arguments for more details.

Indexed String Array

defineParameter(name, longName, default, strings, changeCallback)

Creates a parameter with integer indices that have a text representation given by the string values of an array. The default argument defines the index that the parameter will default to. The strings argument must be an array with string values starting with index 0 or 1.

Boolean

defineParameter(name, longName, bool, changeCallback)

Creates a boolean parameter. The bool argument also defines the default value of the parameter.

String

defineParameter(name, longName, string, changeCallback)

Creates a parameter with a string value. You can change the string by assigning a new string value to the parameter.

Table

defineParameter(name, longName, table, changeCallback)

Creates a parameter with a table as value. The name argument of the parameter also defines the name of the table. You can access the values of the table using the regular methods, e.g., dot notation.

By Parameter Definition

defineParameter(name, longName, parameterDefinition, changeCallback)

Creates a parameter with the behavior of the specified parameterDefinition. You can use this to clone the behavior of existing parameters.

By Named Arguments

defineParameter { name = "p", longName = "param", default = 0, min = 0, max = 100, increment = 0.01, onChanged = callback, type = "float", format = "%.2f", readOnly = false, writeAlways = false, automatable = true, persistent = true }

Creates a parameter by named arguments. The only argument to the function is a table with the key/value pairs that define the parameter. The additional keys type, format, readOnly, writeAlways, automatable and persistent give you control over more advanced features. They can only be set with named arguments. See Defining Parameters by Named Arguments for more details.

Arguments

nameThe name of the parameter.string
longNameThe long name of the parameter, e.g., the name of the tool tip. If the argument is nil or not set, the name will be used.string, optional
defaultThe default value of the parameter. The argument defaults to 0 if not set.number, optional
minThe minimum value of the parameter. The argument defaults to 0 if not set.number, optional
maxThe maximum value of the parameter. The argument defaults to 100 if not set.number, optional
incrementThe step size of the parameter as floating point value. Set this to 1 for integer steps. The argument defaults to 0 (floating point value, no steps) if not set.number, optional
stringsCreates a parameter with an indexed string array. The index starts with 0 or 1, depending on how you initialize the table. The string values of the array define the text representation of the parameter in the Parameter List.array, optional
boolCreates a boolean parameter. This argument also defines the default value of the parameter.bool, optional
stringCreates a parameter with a string value. You can change the string by assigning a new string value to the parameter.string, optional
tableCreates a parameter with a table as value.table, optional
parameterDefinitionCreates a parameter with the behavior of the set parameterDefinition. You can use this to clone the behavior of existing parameters.ParameterDefinition, optional
onChangedCallback function that is called if the value of the parameter has changed. See Parameter Change Callback for more details.function, optional
typeThe value type of the parameter (integer, float, boolean, string, variant, or envelope). The type must match the default and increment arguments. See Additional Named Arguments for more details.string, optional
formatFormats the value string of a float value using the provided arguments. Only the format specifiers for float values are supported, i.e., e, E, f, g, or G. Other format specifiers are not supported. This overrides any automatic formatting from the increment argument. See Additional Named Arguments for more details.string, optional
readOnlyThe parameter can only be changed from the script if this is set to true. The argument defaults to false if not set. See Additional Named Arguments for more details.bool, optional
writeAlwaysA parameter does not call its change callback if its value is set without being changed. Set this to true if you want to guarantee that the change callback of the parameter is called. The argument defaults to false if not set. See Additional Named Arguments for more details.bool, optional
automatableSet this to false if you do not want the parameter to be automated. The argument defaults to true if not set. See Additional Named Arguments for more details.bool, optional
persistentThe parameter will not be restored from the VST preset if this is set to false. The argument defaults to true if not set. See Additional Named Arguments for more details.bool, optional

Example

-- showcase different parameters

-- change callback of parameter "Name"
function nameChanged()
    print("name changed to", Name) -- print the value of the parameter
end
 
-- initialize parameters
defineParameter("Scale") -- parameter with default 0 and range 0-100
defineParameter("Offset", nil, 0, -100, 100, 1) -- bipolar parameter with integer steps
defineParameter("Pan", nil, 0, -100, 100, 0.1) -- bipolar parameter with 0.1 steps
defineParameter("Mode", nil, 1, { "Off", "Normal", "Hyper" }) -- indexed string table
defineParameter("Enable", "Enable Filter", true) -- switch with long name
defineParameter("Name", nil, "untitled", nameChanged) -- string parameter
defineParameter("Intervals", nil, { 0, 4, 7 }) -- table parameter
defineParameter("Volume", nil, this.parent:getParameterDefinition("Level")) --[[ parameter with the same behavior
                                                                                as the "Level" parameter 
                                                                                of the parent layer ]]

3 Comments

    1. Documented additional features of defineParameter. Please re-read. Thanks!