KUIMLElement ReferencePARAM

December 13, 2022

PARAM

This element can be used to create custom parameters.

Attributes brief detailed show all inherited

	Name	Description	Default
	min	Parameter minimum value	0
	max	Parameter maximum value	0
	default	Parameter default value	0
	type	Type of the declared parameter: 'real', 'boolean', 'integer' or 'enumeration'	real
	enum_values	List of text values for an enumeration. When set, this automatically sets the range from 0 to the number of values in the list minus 1Starting with v1.6.2, the start value for the enumeration is not necessarily 0, but the min value specified with the parameter if any	empty
	value_format	Custom formatting used by default to display the parameter as textSee the {text_value} field in parameter text widgets	' .2'
	unit	Unit of the parameter	empty
	name	Displayed named of the parameter	empty
	comment	Comment about the parameter	empty
	exposed	Make parameter available for scriptsWhen this property is set to 'true', the parameter will be exposed to the scripting engine. It can be also achieved via "requires" attribute in SCRIPT, ACTION or ACTION_TRIGGER, as well as via EXPOSED_OBJECTS element.	false
	persistent	Sets the persistency of the parameterWhen this property is set to 'true', the parameter will be saved when closing the user interface and the value will be restored next time the user interface is opened	false
	persistence_context	Sets when the persistency is saved or not ("-Preset", "-Init")If you don't want your parameter to be saved persistently with the preset, set this to "-Preset", not with the default preset: "-Init", if not with both: "-Init;Preset"	empty
	locked	If set to true, the associated param is ignored when loading presets.This is a meta attribute that controls the persistency of a persistent model element. When set to 'always', the generated locked attribute is read-only. When set to 'never', no lock attribute is generated. Otherwise, the value of the locked meta attribute can be changed at runtime via `my_param.meta.locked`	empty
Read Only Attributes
	capturing	true if user is changing the value	false
Events
	value_changed	the event is triggered anytime the value of the object has changed
	text_value	The value of the parameter as text.
Actions
	BeginCapture	Begin value edition (call when starting to modify the value from scripts, especially for parameters that are exposed to automation)Changes the value of the capturing attribute
	EndCapture	End value edition (call when done with modifying the value from scripts, especially for parameters that are exposed to automation)Changes the value of the capturing attribute
Common attributes
	id	Identifier of the elementThe id of an element has to be globally unique. Two elements cannot have the same identifier	empty

	Name	Value type	Default	Description	Comment
	min	real number	0	Parameter minimum value
	max	real number	0	Parameter maximum value
	default	real number	0	Parameter default value
	type	param type	real	Type of the declared parameter: 'real', 'boolean', 'integer' or 'enumeration'
	enum_values	list of strings separated by ';'	empty	List of text values for an enumeration. When set, this automatically sets the range from 0 to the number of values in the list minus 1	Starting with v1.6.2, the start value for the enumeration is not necessarily 0, but the min value specified with the parameter if any
	value_format	param value formatting	' .2'	Custom formatting used by default to display the parameter as text	See the {text_value} field in parameter text widgets
	unit	string	empty	Unit of the parameter
	name	string	empty	Displayed named of the parameter
	comment	string	empty	Comment about the parameter
	exposed	boolean	false	Make parameter available for scripts	When this property is set to 'true', the parameter will be exposed to the scripting engine. It can be also achieved via "requires" attribute in SCRIPT, ACTION or ACTION_TRIGGER, as well as via EXPOSED_OBJECTS element.
	persistent	boolean	false	Sets the persistency of the parameter	When this property is set to 'true', the parameter will be saved when closing the user interface and the value will be restored next time the user interface is opened
	persistence_context	see desc	empty	Sets when the persistency is saved or not ("-Preset", "-Init")	If you don't want your parameter to be saved persistently with the preset, set this to "-Preset", not with the default preset: "-Init", if not with both: "-Init;Preset"
	locked	true, false, always, never	empty	If set to true, the associated param is ignored when loading presets.	This is a meta attribute that controls the persistency of a persistent model element. When set to 'always', the generated locked attribute is read-only. When set to 'never', no lock attribute is generated. Otherwise, the value of the locked meta attribute can be changed at runtime via `my_param.meta.locked`
Read Only Attributes
	capturing	boolean	false	true if user is changing the value
Events
	value_changed	event		the event is triggered anytime the value of the object has changed
	text_value	string		The value of the parameter as text.
Actions
	BeginCapture	action		Begin value edition (call when starting to modify the value from scripts, especially for parameters that are exposed to automation)	Changes the value of the capturing attribute
	EndCapture	action		End value edition (call when done with modifying the value from scripts, especially for parameters that are exposed to automation)	Changes the value of the capturing attribute
Common attributes
	id	identifier	empty	Identifier of the element	The id of an element has to be globally unique. Two elements cannot have the same identifier

Examples

The following example creates a single parameter and adds a control to change that parameter:

Other param types

The default 'real' param type is the most useful: it can keep floating point values (like 0.234, 6124.234 etc). 
However other params types can sometimes be very handy:

Persistent, exposed, capturing, value_changed

Use "persistent" attribute to make this parameter remember its value even when the skin reloads.
Use "exposed" to expose it for scripting engine — when you need to read or write this parameter in the script.
Here are some examples of using "capturing" and "value_changed" to trigger events.

Note that in line 35 we expose required params to scripting engine via requires="hint;gain". We could achieve the same using exposed="true" for the gain param and for the hint string.

Persistence_context and locked

These attributes are related to persistent="true" attribute. When you make a param persistent (meaning its value is kept even when you reload the script) this parameter value is also saved within the preset (and within the default preset, called "Init" internally). If you don't want the preset loading to change your persistent param value, you can either use locked="true" meta-attribute to prevent it (and you can lock or unlock on the fly using param_id.meta.locked), or you can use persistence_context="-Preset;Init" to permanently prevent this param from saving and loading with presets and default preset.

BeginCapture and EndCapture

These actions are needed when you want to change the input parameter value from the GUI via script, If you don't call these actions you may see that param was changed in the GUI, but not in the DSP (as well as in DAW automation).

Let's say you have a GUI script that is automating DSP gain parameter (custom_param0 in our case)

On the DSP side there's a simple script adding a parameter using "params.as" extension (you can add it in traditional way as well), and printing it's value: