/ HALion Developer Resource / HALion Script / Class Reference /

Element

The Element class is the base class for the classes Bus, Instance, Layer, Effect, MidiModule, ModulationMatrixRow, Slot and Zone.

On this page:

Element Class, findChildren, getChild, getParameter, getParameterDefinition, getParameterNormalized, hasParameter, removeFromParent, setName, setParameter, setParameterNormalized

Classes

Element Class

The different types of elements are Instance, Slot, Program, Layer, Zone, ModulationMatrixRow, MidiModule, Bus and Effect. The properties of an Element object are described by the following fields.

Available in: Controller, Processor.

Fields

Example

-- Print information about the script module.

print(this.name)
print(this.id)
print(this.type)
print(this.name)
print(this.numParams)
print(this.parent.name)
print(this.program.name)
print(this.level)
 
-- Print the names of all parameters of the parent element.

defs = this.parent.parameterDefinitions
 
for i, def in ipairs(defs) do
    print(def.name)
end

Jump to Top

Methods

findChildren

findChildren(recursive, nameOrFilterFunction)

Description

Function to find children in the specified Element object. For example, this.parent specifies the parent layer of the script module as the Element object to be searched in. If recursive is set to true, subelements will also be searched. The function returns an array with the Element objects of the found children. Particular children can be searched by name or via a filter function. If searching by name, findChildren accepts only the Element objects that match the specified name. The filter function uses the Element object of each child as argument. Only those Element objects that return true for the search criteria defined in the filter function will be accepted by findChildren. Without a name or filter function, the Element objects of all children in the searched Element object will be returned.

Available in: Controller, Processor.

Arguments

Return Values

Returns an array with the Element objects of the found children. Returns an empty table if no children are found.

Example

-- Find the MIDI module with the name "Lua Script" and print its type.

scriptModules = this.parent:findChildren(false, "Lua Script")
 
if scriptModules[1] then
    print(scriptModules[1].type)
end
 
-- Find all children and print their names.
children = this.program:findChildren(true)
 
if children[1] then
    for i, child in ipairs(children) do
        print(child.name)
    end
else
    print("Could not find any children!")
end

Jump to Top

getChild

getChild(nameOrPosition)

Description

Function to retrieve the Element object of a child in the specified Element object. For example, this.parent specifies the parent layer of the script module as the Element object to be searched in. This function does not search in subelements. A particular child can be searched by name or position. The position is the number indexing the children in the specified Element object. If several children share the same name, only the first match will be returned. If no argument is set, the function returns the first child it finds.

Available in: Controller, Processor.

Arguments

Return Values

Returns the Element object of the found child. Returns nil if no child is found.

Example

-- Locate the first child in the program and print its name.

child = this.program:getChild()
 
if child then
    print(child.name)
else
    print("Could not find a child!")
end

Jump to Top

getParameter

getParameter(nameOrID)

Description

Function to read the current value of a parameter. The parameter can be determined by name or ID.

Available in: Controller, Processor.

Arguments

Return Values

Returns the current value of the parameter or nil if the parameter doesn't exist.

Example

-- Print the value of the parent layer's level parameter.

function onLoadIntoSlot()
    print("Level = "..this.parent:getParameter("Level")) -- via name
    print("Level = "..this.parent:getParameter(38))      -- via ID
end

Jump to Top

getParameterDefinition

getParameterDefinition(nameOrID)

Description

Function to retrieve the ParameterDefinition object for a parameter. The parameter can be determined by name or ID. The ParameterDefinition object describes the properties of a parameter.

Available in: Controller, Processor.

Arguments

Return Values

Returns the ParameterDefinition object for the specified parameter.

Example

-- Print the parameter definition with corresponding
-- data type of the parent layer's level parameter.

function onLoadIntoSlot()
  
    local def = this.parent:getParameterDefinition("Level")
  
    print("Name = "..def.name..", "..type(def.name))
    print("ID = "..def.id..", "..type(def.id))
    print("Type = "..def.type..", "..type(def.type))
    print("Default = "..def.default..", "..type(def.default))
    print("Read Only = "..tostring(def.readOnly)..", "..type(def.readOnly))
    print("Min = "..def.min..", "..type(def.min))
    print("Max = "..def.max..", "..type(def.max))
    print("Unit = "..def.unit..", "..type(def.unit).."\n")
  
end

Jump to Top

getParameterNormalized

getParameterNormalized(nameOrID)

Description

Function to read the current value of a parameter in the normalized range from 0 to 1.0. The parameter can be determined by name or ID.

Available in: Controller, Processor.

Arguments

Return Values

Returns the current value of the parameter in the normalized range from 0 to 1.0 or nil if the parameter doesn't exist. If the parameter is not numeric, the function returns the same as getParameter

Example

-- Print the normalized value of the parent layer's level parameter.

function onLoadIntoSlot()
    print("Level = "..this.parent:getParameterNormalized("Level")) -- via name
    print("Level = "..this.parent:getParameterNormalized(38))      -- via ID
end

Jump to Top

hasParameter

hasParameter(nameOrID)

Description

Function to check if a parameter exists. The parameter can be determined by name or ID.

Available in: Controller, Processor.

Arguments

Return Values

Returns true if the parameter exists or false if not.

Example

-- Check if the elements in the Program Tree have filter cutoff.

function onLoadIntoSlot()
    childs = this.program:findChildren(true)
    for i, child in ipairs(childs) do
        if child:hasParameter("Filter.Cutoff") then
            print(child.name.." has filter cutoff.")
        else
            print(child.name.." has no filter cutoff.")
        end
    end
end

Jump to Top

removeFromParent

removeFromParent()

Description

Function to remove an element in the Program Tree from the parent element. The function can remove elements of the type Layer, Zone, MidiModule, Bus and Effect. It can even remove the script module that calls the function.

Available in: Controller.

Example

-- Remove the second child element.

childs = this.program:findChildren(true)
if childs[2] then
    childs[2]:removeFromParent()
end

-- Remove the program bus.

bus = this.program:getBus("Program-Bus")
if bus then
    bus:removeFromParent()
end

Jump to Top

setName

setName(name)

Description

Function to change the name of an element in the Program Tree.

Available in: Controller.

Arguments

Example

-- Print current name of the script module.

print(this.name)

-- Set the name of the script module to "My Element".

this:setName("My Element")

-- Print the new name of the script module.

print(this.name)

Jump to Top

setParameter

setParameter(nameOrID, value, undo)

Description

Function to set the value of a parameter. The parameter can be determined by name or ID. The function will have no effect if the parameter does not exist.

Available in: Controller, Processor.

Arguments

Example

-- Set the value of the Level parameter of the parent layer.

function onLoadIntoSlot()
    this.parent:setParameter("Level", 0) -- Set via name.
    this.parent:setParameter(38, 0)      -- Set via ID.
end

Jump to Top

setParameterNormalized

setParameterNormalized(nameOrID, value, undo)

Description

Function to set the value of a parameter in the normalized range from 0 to 1.0. The parameter can be determined by name or ID. This function has no effect if the parameter does not exist or if the value is of the type string.

Available in: Controller, Processor.

Arguments

Example

-- Set the normalized value of the parent layer's level parameter.

function onLoadIntoSlot()
    this.parent:setParameterNormalized("Level", 0.5) -- Set via name.
    this.parent:setParameterNormalized(38, 0.5)      -- Set via ID.
end

Jump to Top