Table of Contents
The Storyboard Lua API (Lua API) gives developers access to the Engine though a Lua scripting interface. This API is a library of functions which allow interaction with the Engine by manipulating data and working with events and user interface components. Through the Storyboard Lua API developers can:
Get and set data values from the model
Inject application events
Manipulate model objects such as controls/layers
The Storyboard Lua plugin is built on top of the standard 5.1 release of Lua available from www.lua.org. While the core Lua interpreter is unchanged from the standard release, two additional modules have been incorporated to facilitate development with Storyboard:
| The bitwise manipulation module (bit32) from Lua 5.2 has been built-in to this Lua plugin. This module provides a native implementation of several standard bit operations, including those required for text conversion to/from UTF-8. The documentation for the bitwise functions available from this module can be found in the Lua 5.2 Reference Manual |
| The Storyboard module (gre) is included that provides function extensions to manipulate and work with the currently active Storyboard model. This module also incorporates the Storyboard IO communication API that can be used to send events to external programs. |
.
When a Lua callback function is invoked by the Lua action it will be invoked with a single parameter as in the following prototype:
script_function_name(table mapargs)
The argument mapargs, is a Lua table whose keys provide the context in which
the action is being invoked along with any action specific argument and parameters.
This context includes the application, screen and control the action was associated
with, the currently focused control, any arguments provided to the action as well as
all of the event data that cause the action to fire.
The following keys are always available inside the context’s table:
The application context of the current action
The screen context of the current action (the current screen)
The layer context of the current action (the current layer)
The group context of the current action (the current group)
The control context of the current action (the current control)
If the context_control is a table then this is the row index of the current cell
If the context_control is a table then this is the column index of the current cell
The current context (app, screen, layer, or control) that the event was targeted at
The name of the event the triggered the action
A pointer to a Lua table containing any event data. The event data is different for each event and is defined in the event definition.
A Lua type called 'context' has been defined inside Storyboard's custom Lua module 'gre' to represent the mapargs object for the purpose of auto completion inside the editor. However since Lua is untyped by default, a Doxygen comment describing the mapargs parameter must be added to a function in order to get auto completion on it, as follows:
--- @param gre#context mapargs
function CBMyFunc( mapargs )
-- I now have auto completion on mapargs
end
Functions created by Storyboard will automatically be prepended with this comment.
Example of using context data:
--- @param gre#context mapargs
function CBGetContext( mapargs )
print("Triggered by event : " .. mapargs.context_event)
print("Event was targeting : " .. mapargs[mapargs.context_target])
end