/ HALion Developer Resource / HALion Script / Reference /

defineParameter

On this page:

• Description
  • Numeric
  • Indexed String Array
  • Boolean
  • String
  • Table
  • By Parameter Definition
  • By Named Arguments
• Arguments
  • Example 1
• Additional Named Arguments
  • Example 2

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 default, min, max 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:

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, processorCallback 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.

Jump to Top

Arguments

Example 1

-- Showcase different parameters.
 
-- Initialize variables.

maxVelocity = 127
 
-- Change callback of the parameter "Label".

function nameChanged()
    print("name changed to", Label) --Print the value of the parameter.
end
 
-- Initialize parameters.

defineParameter("Scale", nil, 100)                                          -- Parameter with default 100 and range 0 to 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 array.
defineParameter("Enable", "Enable Filter", true)                            -- Switch with long name.
defineParameter("Label", 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.

Jump to Top

Additional Named Arguments

(Since HALion 6.1)

If you create a parameter by named arguments, you get access to the following additional arguments. See Definging Parameters by Named Arguments for more details.

The arguments readOnly, writeAlways and automatable are helpful if you have a parameter that is used only for indication, but not for entering values.

Example 2

-- The following parameter is read only, not automatable and not persistent.

defineParameter {
    name = "deltaTime",
    longName = "Delta Time",
    default = 0,
    min = 0,
    max = 2^31,
    type = "float",
    format = "%.3f ms",
    readOnly = true,
    automatable = false,
    persistent = false,
}
   
-- Measure the time between subsequent notes.

function onNote(event)
    postEvent(event)
    t2 = getTime()
    if t1 then
        deltaTime = t2 - t1
    end
    t1 = t2
end
 
-- The following parameter change callback is executed in the processor context with high accuracy.

function onP1changed()
   this.parent:setParameterNormalized("Level", P1 / 100)
end
 
defineParameter{name = "P1", min=0, max=100, onChanged = onP1changed, processorCallback = true}

Jump to Top

See also: getParameter, setParameter