Chapter 8. Scripting with Lua

Table of Contents

Lua Function Parameters
Passing Extra Parameters to Functions
Storyboard Lua Integration
Lua Execution Environment
Asynchronous Lua Support
Lua Debugger
Introduction
Configuration
Debugging
Storyboard Lua API
gre.SCRIPT_ROOT
gre.set_data
gre.get_data
gre.send_event
gre.send_event_target
gre.send_event_data
gre.receive_event
gre.greio_disconnect
gre.touch
gre.key_up
gre.key_down
gre.key_repeat
gre.redraw
gre.quit
gre.move_layer
gre.move_control
gre.clone_control
gre.delete_control
gre.get_control_attrs
gre.set_control_attrs
gre.get_layer_attrs
gre.set_layer_attrs
gre.set_layer_attrs_global
gre.get_table_attrs
gre.set_table_attrs
gre.get_table_cell_attrs
gre.get_string_size
gre.poly_string
gre.resolve_data_key
gre.load_resource
gre.load_image
gre.dump_resource
gre.timer_set_timeout
gre.timer_set_interval
gre.timer_clear_timeout
gre.timer_clear_interval
gre.walk_pool
gre.mstime
gre.env
gre.animation_create
gre.animation_add_step
gre.animation_destroy
gre.animation_trigger
Storyboard Lua Android Integration
Storyboard Lua Android Integration

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:

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.

.

Lua Function Parameters

Each Lua function invoked from the Storyboard is passed two arguments:

script_function_name( table mapargs, string allargs)

The first 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:

context_app

The application context of the current action

context_screen

The screen context of the current action (the current screen)

context_layer

The layer context of the current action (the current layer)

context_control

The control context of the current action (the current control)

context_group

The control context of the current action (the current group)

context_row

If the context_control is a Table then this is the row index of the current cell

context_col

If the context_control is a Table then this is the column index of the current cell

context_target

The current context (app, screen, layer, or control) that the event was targeted at

context_event

The name of the event the triggered the action

context_event_data

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.

The second argument, allargs, provides a string containing the exact same string that was provided to the data arguments of the action.  

Example of using context data:

function get_context( mapargs )
  print("triggered by event : "..mapargs.context_event)
  print("event was targeting : "..mapargs[mapargs.context_target])
end