Advanced Lua Callbacks

In Storyboard 6.1, we introduced the ability to have advanced Lua callbacks which give developers more powerful ways to organize and architect their code into modular and well-encapsulated behaviour. The Lua script action gra.lua has always been able to call global functions in your Lua scripts, developers have much more flexibility with their Lua function callbacks.

Advanced callbacks allow developers to invoke functions that are nested in other tables. This can be done with a . for tables or a: for Lua object methods where self is the first parameter. As long as the top-level variable is global, nested objects and functions can be found.

An advanced Lua function may look like parent.child.grandchild.func if the first parameter of the func function is mapargs, or like parent.child.grandchild:func if the first parameter of the function is self and the second is mapargs, where self is parent.child.grandchild in this example.

Selecting the ADVANCED entry will open the Advanced Lua Callback Function Wizard which allows developers to select an instance of a Lua Object and a method to invoke in the Lua Action.

Example Advanced Lua Callback Scripts

This section shows some snippets of code to define and create Lua objects and how to annotate them appropriately for Lua to be able to infer types of the variables in your scripts. To get more detailed information and examples of Lua code annotations, refer to.

scripts/callbacks.lua

This script has a global table that holds onto all the buttons of our application. The use of @field in this manner helps Storyboard to understand the contents of the buttons table and their types and provide more information back to the developer.

local ToggleButton = require("widgets.toggleButton")

---
--@type buttons
--@field widgets.toggleButton#toggleButton togglePower
--@field widgets.toggleButton#toggleButton toggleStar
buttons = {}

---@param gre#context mapargs
function CBInit(mapargs)
  buttons.togglePower = ToggleButton.new("Layer.power", false)
  buttons.toggleStart = ToggleButton.new("Layer.start", false
end

scripts/widgets/toggleButton.lua

This script is an example of a toggleButton class. An advantage of Object Oriented programming is that you can maintain state together with the functionality of the object. This module returns a table with a single method on it, new and it returns a toggleButton#toggleButton. This object created with new has a single method, press which takes two parameters, self and mapargs. Pressing an instance of a toggleButton will flip it' it's self.state and trigger "buttonUp" or "buttonDown" animation accordingly.

---@module toggleButton
local ToggleButton = {}

---
--@type toggleButton
--@field gredom#control control
--@field #table context
--@field #boolean state
local toggleButton = {}

--- Create a new toggle button
--@param #string controlName fully qualified name of control
--@param #boolean initialState the initial state of the button
--@return #toggleButton
function ToggleButton.new(controlName, initialState)
  local button = {}
  setmetatable(button, {__index=toggleButton})

  button.control = gredom.get_control(controlName)
  button.context = {context=controlName}
  button.state = initialState
  return button
end

---
--@param #toggleButton self
--@param gre#context mapargs
function toggleButton:press(mapargs)
  self.state = not self.state
  if(self.state) then
    gre.animation_trigger("buttonDown", self.context)  
  else
    gre.animation_trigger("buttonUp", self.context)
  end
end

return ToggleButton