Lua Scripting

Lua is a powerful, fast, lightweight, embeddable scripting language. Lua scripts can be used anywhere in Helm, in place of ‘classic’ Helm scripting. Lua scripts bring significant power and flexibility to Helm including the following features.

See also an update on this article here //

  • Conditionals: if… then … else …
  • Loops: ‘for’ and ‘while’ loops
  • Subroutines : Write re-useable code sections.
  • Stored variables
  • I/O : Read and write files
  • XML processing : Use XML files for additional system configuration

You can learn about Lua from and from these books below

Lua modules provided with Helm include LuaXML and LuaFileSystem.

You can mix Lua and Helm ‘classic’ scripts in the same panel. Note that you can’t mix languages within a single event script – the entire script is treated as either Lua or ‘classic’ script. The script editor allows you to select the language for each script.

Three Lua extension functions allow scripts to interact with Helm components: helm.get, helm.set and helm.exec.

  • helm.get(object, property) – return value of a property.
  • helm.set(object, property, value) – set an object’s property to a value
  • helm.exec(object, action , params...) – execute a helm objects’ action. Any number of parameters can be passed.

However, since Helm 4.2.0 you can use the global object “H” which is a table of all objects on the panel, and access their properties and actions directly. The extension functions are still supported

Example 1a: Before Helm 4.2.0

--make the label font size 4 points larger.

local oldsize = helm.get("LABEL_1","Font:PointSize")
helm.set("LABEL_1","Font:PointSize", oldsize + 4)

Example 1B: Since Helm 4.2.0 

--make the label font size 4 points larger.
H.LABEL_1.Font.PointSize = H.LABEL_1.Font.PointSize+4

Example 2a: Before Helm 4.2.0:


--Use the root panel's RunScript action to run a script from a file
--This is equivalent to the Helm script line RootPanel:RunScript(myfile.txt)

helm.exec("RootPanel","RunScript", "myfile.txt")

Example 2b: Since Helm 4.2.0:

--Use the root panel's RunScript action to run a script from a file


Helm automatically to convert strings to integers and vice-versa as required, but where  a  command requires “Enumeration” parameters they must be passed as a string. An example of this is the Label’s SetAlignment command:

H.LABEL_1:SetAlignment(Left) -- FAILS
H.LABEL_1:SetAlignment("Left") -- OK

Converting scripts using Helm ‘Variables’ to Lua

Standard Helm scripting allows you to use the current value of any object property as a parameter. You can do the same with Lua.

Performing actions on multiple objects

The first parameter to helm.exec and helm.set can be a wildcard pattern like “LABEL_*” which will match every object whose name begins with “LABEL_”. Alternatively you can pass a table of object names, and the operation will be performed on all those objects

helm.set("DEBUGLABEL_*", "Visible", false) -- hide debug labels

helm.set({"LABEL_1","LABEL_2"}, "Visible", false)

Printing to the log

The Lua print() function writes messages directly to Helm’s log and can be used for debugging

print("Something unexpected happened: ", H.BUTTON_1.Down)