Appendix A. Storyboard Lua API

gre.APP_ROOT
                    

This is a variable that is filled in by the Storyboard Engine to point at the filesystem path for the application's project root directory. This can be used in order to access resources in a project relative manner. This variable is only applicable for filesystem based configurations.

Historical code may use gre.SCRIPT_ROOT .. "/.." as a way of referring to files in a project relative manner, but gre.APP_ROOT is preferred as not all filesystems support relative path operations. Unix forward slash directory path separator conventions are preferred when working file filenames.

 -- Open the french translation file in the translations folder
 local translation_file = gre.APP_ROOT .. "/translations/french.csv"
 local fp = io.open(translation_file, "r")
 ...
                    

gre.SCRIPT_ROOT
                    

This is a variable that is filled in by the Storyboard Engine to contain the path to the application project's scripts directory.

The gre.SCRIPT_ROOT variable provides a convenient way to reference the Lua script related resources in a location independent, project relative, manner. This variable is only applicable for filesystem based configurations.

When used in conjunction with the gre.env() function, the gre.SCRIPT_ROOT can provide an effective way to configure the search path for extra Lua modules.

-- Add the scripts/<os>-<cpu> to the Lua file resolver for require statements
-- ie ..../scripts/linux-x86
local target = gre.env({"target_os", "target_cpu"})
local extra_path = string.format("%s/%s-%s/?.lua;", gre.SCRIPT_ROOT,
target.target_os, target.target_cpu)
package.path = extra_path .. package.path 
                    

gre.PLUGIN_ROOT
                    

This is a variable that is filled in by the Storyboard Engine to contain the path to the Storyboard Engine's plugins directory. This is the directory that is specified to the model_mgr using the -omodel_mgr,plugin_path option or via the SB_PLUGINSenvironment variable. This path can be used to load application specific binaries that may be packaged with a particular Storyboard Engine. This variable is only applicable for systems that dynamically load plugins from a filesystem.

gre.set_data(
    table
)
            

Sets one or more items in the Storyboard application's data manager.  Each index and value in the table passed in will be set in the data manager using the index name as the key.

function lua_func( mapargs )
    local data_table  = {}
    data_table["variable_name"] = "variable data"
    gre.set_data( data_table )
end
            

gre.get_data(
    key
    [, key2, ...]
)
            

Gets one or more values from the data manager. Each argument to the function is interpreted as a data manager key whose value should be extracted from the data manager. This function returns a table using all the values as indexes and the corresponding value is the data returned from the data manager. A nil is returned for any values that do not match a key in the data manager.

function get_data_func( mapargs )
    --When accessing control variables, use the following qualified
    --model path Layer.Control.Variable
    local data_table = gre.get_data("my_layer.my_control.variable_name")
    local value = data_table["my_layer.my_control.variable_name"]
    print("control_variable_name = " .. tostring(value))
end
            

function get_control_width( mapargs )
    --This will extract the width (grd_width) of the control
    --'my_control' on the layer 'my_layer'
    local data = gre.get_data("my_layer.my_control.grd_width")
    local value = data["my_layer.my_control.grd_width"]
    print("The width of the control is " .. tostring(value))
end
            

gre.set_value(
    key,
    value
    [, key2, value2, ...]
)
            

Set a variable in the data manager to a particular value. This function is a convenience function on top of gre.set_data that allows the key and value to be passed as a set of arguments to the function instead of having to create a table containing the key/value pairs.

function lua_func( mapargs )
    -- Assign the string 'variable_data' to the application variable
    -- 'variable_name'
    -- This example is the same as gre.set_data()
    gre.set_value("variable_name", "variable_data")
end
            

gre.get_value(
    key
    [, key2, ...]
)
            

Get the value of a variable from the data manager. This function is a convenience function on top of gre.get_data that allows the value to be returned directly to the caller instead of a single table return value. A nil is returned for any values that do not match a key in the data manager.

function get_control_width( mapargs )
    -- This will extract the width of the control 'my_control'
    -- on the layer 'my_layer'
    -- This is the same example as gre.get_data()
    local value = gre.get_value("my_layer.my_control.grd_width")
    print("The width of the control is " .. tostring(value))
end
            

gre.resolve_data_key(
    key1
    [, key2, ...]
)
		    

This function allows Lua scripts to resolve Storyboard context variables to a fully qualified name based on the current execution context.

-- Resolve the application my_var to a fully qualified name
local varname = "${app:my_var}"
local dv = gre.resolve_data_key(varname)
print("Full path for ${app:my_var} is " .. dv[varname])
		    

gre.get_control_attrs(
    control_name
    tags ...
)
            

Get properties for a control.  Key name is the name of the control or a variable.  Tags can be a list of the following values:

        x, y, width, height, hidden, active, zindex, findex

A table with the results is returned.

function check_if_hidden()
    local dk_data = {}
    -- check if my_control is currently hidden
    dk_data = gre.get_control_attrs("my_layer.my_control", "hidden")
    if dk_data["hidden"] == 1 then
        print("my_control is currently hidden")
    else
        print("my_control is currently visible")
    end
end
            

gre.set_control_attrs(
    control_name,
    tag_table
)
            

Set properties for a control.  The control_name is the name of the control or a variable. The tag_table contains the tags and values for the properties to set.

        x,  y, width, height, hidden, active, zindex, findex, effect

In the case of the focus index (findex), the initial value set in Storyboard Designer must be non-zero in order for it to be changed dynamically at runtime

The effect tag is a special attribute that can be used with OpenGL rendering platforms to apply a custom shader directly as an effect on the control object

function set_control_hidden()
    local dk_data = {}
    dk_data["hidden"] = 1
    gre.set_control_attrs("my_control", dk_data)       
end
            

function set_control_blur_effect()
    local dk_data = {}
    local effect = {}

    effect["name"] = "blur"
    effect["passes"] = 3
    effect["radius"] = 1
    effect["composite"] = true

    dk_data["effect"] = effect
    gre.set_control_attrs("my_control", dk_data)
end
                    

gre.get_table_attrs(
    table_name,
    tags
)
            

Get properties for a table.  Key name is the name of the control or a variable.  Tags can be any of the control tags mentioned in section 6.1.12 and any of the following values:

function check_if_hidden()
    local dk_data = {}
    -- Get the active row/column
    dk_data = gre.get_table_attrs("my_table", "active_row", "active_col")
    print("Active Cell: " .. tostring(dk_data["active_row"] .. ","
    .. tostring(dk_data["active_col"]))
end
            

gre.set_table_attrs(
    table_name,
    tag_table
)
            

Set properties for a table.  The table_name is the name of the control or a variable. The tag_table contains the tags and values for the properties to set.

        x,  y, width, height, hidden, active, rows, cols, xoffset, yoffset

function resize_table()
    local dk_data = {}
    dk_data["rows"] = 5
    dk_data["cols"] = 10
    gre.set_table_attrs("my_table", dk_data)       
end
            

gre.get_table_cell_attrs(
    table_name,
    row,
    col,
    tags ...
)
            

Get properties for a table cell.  table_name is the name of the table.  Tags can be a list of the following values:

        x, y, width, height, hidden

A table with the results is returned.

function check_if_hidden()
    local dk_data = {}
    -- check if my_control is currently hidden
    dk_data = gre.get_table_cell_attrs("my_table", 1, 1, "hidden")
    if dk_data["hidden"] == 1 then
        print("cell 1.1 of my_table is currently hidden")
    else
        print("cell 1.1 of my_table is currently visible")
    end
end
            

gre.get_group_attrs(
    group_name
    tags ...
)
            

Get properties for a group.  Key name is the name of the group or a variable.  Tags can be a list of the following values:

        x, y, hidden

A table with the results is returned.

function check_if_hidden()
    local dk_data = {}
    -- check if my_group is currently hidden
    dk_data = gre.get_group_attrs("my_layer.my_group", "hidden")
    if dk_data["hidden"] == 1 then
        print("my_control is currently hidden")
    else
        print("my_control is currently visible")
    end
end
            

gre.set_group_attrs(
    group_name,
    tag_table
)
            

Set properties for a group.  The group_name is the name of the group or a variable. The tag_table contains the tags and values for the properties to set.

        x,  y, hidden

function set_control_hidden()
    local dk_data = {}
    dk_data["hidden"] = 1
    gre.set_control_attrs("my_layer.my_group", dk_data)       
end
            

function set_control_blur_effect()
    local dk_data = {}
    local effect = {}

    effect["name"] = "blur"
    effect["passes"] = 3
    effect["radius"] = 1
    effect["composite"] = true

    dk_data["effect"] = effect
    gre.set_control_attrs("my_control", dk_data)
end

                    

gre.get_layer_attrs(
    layer_name
    tags...
)
            

Get properties for a layer instance associated with a particular screen.   The layer_name specifies either the fully qualified name of a layer instance using the ScreenName.LayerName naming convention or, if only the layer name is specified, the name will refer to a layer instance associated with the current screen

The tags are a list of string properties associated with the layer instance and can include one or more of the following values:

        x, y, width, height, alpha, hidden, active, zindex, xoffset, yoffset

A table containing the keys and their respective values is returned or nil if the layer can not be found.

function check_if_hidden()
    -- check if my_layer is currently hidden
    local data = gre.get_layer_attrs("my_layer", "hidden")
    if data.hidden == 1 then
        print("my_layer is currently hidden")
    else
        print("my_layer is currently visible")
    end
end
            

gre.set_layer_attrs(
    layer_name,
    tag_table
)
            

Set properties for a layer instance associated with a particular screen.   The layer_name specifies either the fully qualified name of a layer instance using the ScreenName.LayerName naming convention or, if only the layer name is specified, the name will refer to a layer instance associated with the current screen

alpha, hidden, active, x, y, zindex, width, height, xoffset, yoffset, effect

function set_layer_hidden()
    local data = {}
    data.hidden = 1
    gre.set_layer_attrs("my_layer", data)       
end
            

function cbBlurEffect(mapargs)
    local attrs = {}
    local effect = {}

    effect["name"] = "blur"
    effect["passes"] = 2
    effect["radius"] = 1
    effect["composite"] = false
    attrs["effect"] = effect
    gre.set_layer_attrs("background.control1",attrs)
end
                            

function cbSetGeometry(mapargs)
    local gdata = {}
    local dz = 0.0
    local offset = mapargs.offset
    local dz2 = -offset
    local w
    local h = 240

    dz2 = -offset
    w = 320 - offset
    gdata = {
      {x=w/2, y=h/2, z=dz2, u=0.5, v=0.5},

      {x=w, y=0, z=dz, u=1.0, v=0},
      {x=w/2, y=0, z=dz2, u=0.5, v=0},
      {x=0, y=0, z=dz, u=0, v=0},

      {x=0, y=h, z=dz, u=0, v=1.0},
      {x=w/2, y=h, z=dz2, u=0.5, v=1.0},
      {x=w, y=h, z=dz, u=1.0, v=1.0},

      {x=w, y=0, z=dz, u=1.0, v=0},
    }

    local attrs = {}
    attrs["geometry"] = {
        width = w,
        height = h,
        type = "fan",
        nvert = 3,
        nuv = 2,
        data = gdata
    }
    gre.set_layer_attrs("geometry.layer3",attrs)
end
                            

gre.set_layer_attrs_global(
    layer_name,
    table
)
            

Set properties for a layer globally on all instances of the layer on all screens.  The layer_name is the name of the layer.  Table contains the tags and values for the properties to set.

        alpha, hidden, active, x, y, width, height

gre.move_control(
    control_name,
    dx,
    dy,
    x,
    y
)
            

Move a controls to a new position.  The control_name is the name of the control or a variable.  Setting dx and or dy will move the layer by the specified delta from its current position.  The  dx and dy values can be 0 to set an absolute position using the x and y values only.

gre.move_layer(
    layer_name,
    dx,
    dy,
    x,
    y
)
            

Move a layer to a new position.  The layer_name is the name of the layer or a variable that is associated with the layer name. Setting dx or dy will move the layer by the specified delta from its current position. The  dx and dy values can be 0 to set an absolute position using the x and y values only.

gre.set_focus(
    fqn
)
            

Set the focus to a control as described by its fully qualified name. This function returns true if the control could be found and was focusable and focus could be set to it. If the control can be found but is not focusable then false will be returned. If the control can't be found then nil will be returned.

When the fully qualified name indicates the row and column of a table, then this function will set the active table cell rather than adjusting the control focus.

-- Set the focus to MyControl
local didApply = gre.set_focus("MyLayer.MyControl")
if(not didApply) then
    print("Failed to set focus")
end

-- Set to focus to the second row item in a table
local didApply = gre.set_focus("MyLayer.MyTable.2.1")
if(not didApply) then
    print("Failed to set table cell focus")
end
                    

gre.set_focus()
            

Get the fully qualified path to the control that is currently focused or nil if no control currently has focus

gre.send_event(
    event_name,
    [channel]
)
            

Send an event to the application or to a Storyboard IO channel.  channel is an optional parameter and if channel is not passed then the channel will be chosen as follows:

If the environment variable GREIONAME is set then it will be used otherwise the default channel is used.

-- Send to the event  to the application :
local success, error = gre.send_event("my_event")
if(success == false) then
    print(error)
    --handle error
end


--To send the event to a Storyboard IO channel via parameters:
local success, error = gre.send_event("my_event", “io_channel_name”)
if(success == false) then
    print(error)
    --handle error
end

            

gre.send_event_target(
    event_name,
    target,
    [channel]
)
            

Send an event to a targeted model element (control, layer instance or screen) using the model's fully qualified path. The channel is an optional parameter.

-- Send to the event directed at a particular control target:
gre.send_event("my_event", "my_layer.my_control")
            

gre.send_event_data(
    event_name,
    format_string,
    data,
    [channel]
)
            

Send an event with custom data to the application or to a Storyboard IO channel. The data parameter is a Lua table where the indexes match the values from the format string. channel is an optional parameter.

Special consideration is required for sending data that is to be formatted as an array (i.e., N[suf]M where M is greater than 0). In this case the data entry should be provided as a Lua table and not as a raw value parameter.

Data parameters must be sent in order of descending alignment requirements. Example: 4u1 4u1 2u1 1s0 is good, 2u1 4u1 4u1 1s0 is not

-- Send a 'int32_update' event with a 32bit signed integer (int32_t)
-- payload to the 'controller' channel
function send_integer(value)
    local  format = "4s1 value"
    local data = {}
    data["value"] = value
    local success, error = gre.send_event_data("int32_update", format,
    data, "controller")
    if(success == false) then
        print(error)
        --handle error
    end
end

-- Send a 'int16_update' event with two 16bit signed integers (int16_t)
-- payload to the 'controller' channel
function send_two_integers(value1, value2)
    local  format = "2s1 first 2s1 second"
    local data = {}
    data["first"] = value1
    data["second"] = value2
    local success, error = gre.send_event_data("int16_update", format, 
    data, "controller")
    if(success == false) then
        print(error)
        --handle error
    end
end

-- Send an 'array_update' event with an array of int32_t numbers (provided
-- as a table) to the client
function send_integer_array(values)
    -- Generate the format string dynamically based on the number of entries
    local count = #values
    local format = string.format("4s%d values", count)
    local data = {}
    data["values"] = values
    local success, error = gre.send_event_data("array_update", format, 
    data, "controller")
    if(success == false) then
        print(error)
        --handle error
    end
end

send_integer(12)
send_two_integers(10, 20)
send_integer_array({10, 20, 30, 40})

gre.greio_disconnect(
    channel,
    [is_receive_channel]
)
		    

This function forces any cached Storyboard IO channel connections to the specified channel to be closed. Subsequent calls using the same channel name will re-establish the connection to the channel if required.

-- Send an event to a custom channel
gre.send_event("StoryboardRocks", "my_channel")
-- Close the cached connection to that channel
gre.greio_disconnect("my_channel")
            

gre.clone_object(
    reference_object_name,
    new_object_name,
    parent_name,
    data
)
            

Create a new control, table or group (new_object_name) within an existing parent (layer_name) by copying all of the properties of an existing object (reference_object_name). This new object will have all of the same actions, variables and it's current state will match the state of the reference object that is being copied. In the case of cloning groups, all of the reference group's controls will be cloned into the new group.

Currently only controls and groups are supported as source reference objects.

The data argument is a table of properties that match the properties for that type of object as described in the gre.set_control_attrs, gre.set_table_attrs or gre.set_group_attrs functions as applicable. For example, most objects support x, y,hidden properties

function create_new_control()
    local data = {}
    data["x"] = 10
    data["y"] = 10
    gre.clone_object("my_control", "my_new_control", "my_layer", data)       
end
            

gre.delete_object(
    object_name,
)
            

Delete an object that has been cloned using gre.clone_object from the model. The object must be a control, table or a group.

function delete_object()
    gre.delete_object("my_layer.my_object")       
end
            

gre.clone_control(
    reference_control_name,
    new_control_name,
    layer_name,
    data
)
            

This is a function to clone a control. This function has been deprecated and has been replaced with the gre.clone_object Lua API function. See the gre.clone_object for usage and examples.

gre.delete_control(
    control_name
)
            

This is a function to delete a cloned control. This function has been deprecated and has been replaced with the gre.delete_object Lua API function. See the gre.delete_object for usage and examples.

gre.poly_string(
    x_values,
    y_values
)
  or
gre.poly_string(
    {{x=, y=}, ...}
)
            

This is a higher performance function for generating a polygon string based on a set of numeric data points maintained in Lua table arrays.

In the two argument form, the function receives as inputs two Lua tables whose content represents the numeric x and y data points to be converted to a string. The tables are 1 based arrays and must be of the same length.

In the single argument form, the function receives as input a single Lua table whose array content are tables with an "x" and "y" member value.

The string returned is designed to be compatible with the Storyboard polygon plugin and is in the form of X1:Y1 X1:Y2 ...

-- Create a triangle polygon in a 100x100 square
local x_points = { 0, 50, 100 }         -- Left, Middle, Right
local y_points = { 100, 0, 100 }        -- Bottom, Top, Bottom
local x_y_string = gre.poly_string(x_points, y_points)
print("X Y String: " .. x_y_string)

-- Create the same triangle, but with x,y member variables
local xy_points = { {x=0,y=100}, {x=50,y=0}, {x=100,y=100} }
local xy_string = gre.poly_string(xy_points)
print("XY String: " .. xy_string)
                

gre.get_string_size(
    font,
    font_size,
    string,
    length,
    width
)
            

Calculate the area in pixels which the given string will occupy on the screen. Optionally calculate how many characters can fit into a predefined screen area.

This call can only be made from the main Lua action execution thread.

gre.load_resource(
    pool_name,
    resource_name,
    [pool parameters]
)
		    

This function will force the loading of a resource, such as an image or font, into the Storyboard application. This can be used in order to avoid load time delays that may be incurred as resources are lazy loaded into the application.

This call can only be made from the main Lua action execution thread.

-- Call this to pre-load the image and font into the cache
function on_app_init(mapargs)
    -- Call this to pre-load a font at a 24pt size
    local opt = {}
    opt.size = 24
    gre.load_resource("font", "fonts/DejaVu.ttf", opt)

    -- Call this to pre-load the image unscaled
    gre.load_resource("image", "images/tree.jpg")

    -- Call this to pre-load the image and scale it to 100x100
    local opt = {}
    opt.w = 100
    opt.h = 100
    gre.load_resource("image", "images/scaledtree.jpg", opt)

    -- Call this to pre-load the image and scale it to 100x100 asynchronously
    local opt = {}
    opt.w = 100
    opt.h = 100
    opt.background = 1
    gre.load_resource("image", "images/scaledtreebg.jpg", opt)
end
            

gre.dump_resource(
    pool_name,
    resource_name
)
		    

This function performs the opposite of the gre.load_resource call and removes a resource from the specified resource pool cache.

This call can only be made from the main Lua action execution thread.

-- Force the tree.jpg image out of the cache, image will reload as required
function flush_tree_image()
    gre.dump_resource("image", "images/tree.jpg")
    gre.dump_resource("font", "fonts/DejaVu.ttf")
end
            

gre.walk_pool(
    pool_name
)
		    

This function reports on the memory used by all of the resources loaded into a particular resource pool.

-- Display the content of the current image cache
function show_image_cache(mapargs)
    print("Images")
    local data = gre.walk_pool("image")
    for k,v in pairs(data) do
        print("  ".. tostring(k) .. "=" .. tostring(v))
    end
end
            

gre.load_image(
    image_name,
    [optional table of parameters]
)
		    

This function will force the loading of an image into the Storyboard application. This can be used in order to avoid load time delays that may be incurred as resources are lazy loaded into the application.

This is a convenience function for calling the more generic gre.load_resource

This call can only be made from the main Lua action execution thread.

gre.timer_set_timeout(
    function,
    timeout
)
		    

This function creates a one-shot timer which fires after "timeout" milliseconds and then executes "function"

local idval = {}
function cb_func()
    print("CB FUNC HAS BEEN CALLED")
end

--Call cb_func after 1 second
function cb_set_timeout()
    idval = gre.timer_set_timeout(cb_func, 1000)
end
            

gre.timer_set_interval(
    function,
    interval
)
		    

This function creates a repeating timer which fires every "interval" milliseconds and then executes "function"

local idval = {}
function cb_func()
    print("CB FUNC HAS BEEN CALLED")
end

--Call cb_func every 2 seconds
function cb_set_interval()
    idval = gre.timer_set_interval(cb_func, 2000)
end
            

gre.timer_clear_timeout(
    id
)
		    

This function stops an existing timer from firing

local idval = {}
function cb_func()
    print("CB FUNC HAS BEEN CALLED")
end

--Call cb_func after 5 seconds
function cb_set_timeout()
    idval = gre.timer_set_timeout(cb_func, 2000)
end

function cb_clear_timeout()
    local data

    data = gre.timer_clear_timeout(idval)
end
            

gre.timer_clear_interval(
    id
)
		    

This function stops an existing timer from firing

local idval = {}
function cb_func()
    print("CB FUNC HAS BEEN CALLED")
end

--Call cb_func every 5 seconds
function cb_set_interval()
    idval = gre.timer_set_interval(cb_func, 2000)
end

function cb_clear_interval()
    local data

    data = gre.timer_clear_interval(idval)
end
            

gre.animation_create(fps, [auto_destroy], [end_callback])
                    

Create a new animation at the desired frame rate (fps). The second parameter (optional), auto_destroy, tells if the animation should be released once completed. If you specify a value of 1 the animation will be released and the returned id is not valid once the animation has completed. The third parameter (optional) indicates a callback function to be invoked when the animation is complete.

function animation_create(mapargs, fps)
    local id
    id = gre.animation_create(fps)
end

--Example of an creating an animation with an animation complete callback
local animation_state = "STOPPED"
function animation_create(mapargs, fps)
    local id
    id = gre.animation_create(fps, 0, animation_complete)

    gre.animation_trigger(id, {context="my_layer.my_control",
    id="my_control_animation"})
    animation_state = "RUNNING"
end

--The callback's first argument will be the completed animation's id.
--When triggered with an animation instance id (e.g., "my_control_animation"),
--otherwise it will be the id returned from calling animation_create.
function animation_complete(id)
    animation_state = "COMPLETED"
end

        

gre.animation_add_step(id, data)

Add a step to a created animation. The id must be from a call to gre.animation_create. The data parameter defines the animation step values.

function create_animation(mapargs)
    local data = {}

    -- slide the x position 400 pixels over 2000 msec and auto-destroy
    -- it on completion
    id  = gre.animation_create(60, 1)
    data["rate"] = "linear"
    data["duration"] = 2000
    data["offset"] = 0
    data["delta"] = 400
    data["key"] = "mylayer.mycontrol.grd_x"
    gre.animation_add_step(id, data)
end
                    

gre.animation_destroy(id)

function create_animation(mapargs)
    local data = {}

    -- slide the x position 400 pixels over 2000 msec
    id = gre.animation_create(60)
    data["rate"] = "linear"
    data["duration"] = 2000
    data["offset"] = 0
    data["delta"] = 400
    data["key"] = "mylayer.mycontrol.grd_x"
    gre.animation_add_step(id, data)

    -- destroy it
    gre.animation_destroy(id)
end
                    

gre.animation_trigger(animation_id, data)

gre.animation_trigger("animation_name")

Trigger an animation to run. If an animation_id is used to trigger the animation, then it must be the return value from gre.animation_create(). If a name is used to trigger an animation, then that name must be the name of the animation specified in Designer. This function can take an optional parameter, data_table. The data_table contains the tags and values for the extra arguments to set.

function create_animation(mapargs)
    local data = {}

    -- slide the x position 400 pixels over 2000 msec and auto-destroy
    -- it on completion
    id = gre.animation_create(60, 1)
    data["rate"] = "linear"
    data["duration"] = 2000
    data["offset"] = 0
    data["delta"] = 400
    data["key"] = "mylayer.mycontrol.grd_x"
    gre.animation_add_step(id, data)

    gre.animation_trigger(id)
end

--Example of using gre.animation_trigger passing animation names.
function cb_toggle_cur_5day()
    if cur_5day_toggle == false then
        gre.animation_trigger("show_5day")
    else
        gre.animation_trigger("hide_mon_to_fri")
    end
end

--Example of using gre.animation_trigger with context.
function cb_toggle_cur_5day()
    local data = {}

    data["context"] = "Layer1.mycontrol"
    gre.animation_trigger("show_5day", data)
end
                    

gre.animation_stop(animation_id, data)

gre.animation_stop("animation_name")

Stop an animation. If an animation_id is used to stop the animation, then it must be the return value from gre.animation_create(). If a name is used to stop an animation, then that name must be the name of the animation specified in Designer. This function can take an optional parameter, data_table. The data_table contains the tags and values for the extra arguments to set.

function create_animation(mapargs)
    local data = {}

    -- slide the x position 400 pixels over 2000 msec and auto-destroy
    -- it on completion
    id = gre.animation_create(60, 1)
    data["rate"] = "linear"
    data["duration"] = 2000
    data["offset"] = 0
    data["delta"] = 400
    data["key"] = "mylayer.mycontrol.grd_x"
    gre.animation_add_step(id, data)

    gre.animation_trigger(id)

    --do stuff

    --Stop the animation
    gre.animation_stop(id)
end

--Example of using gre.animation_stop passing animation names.
function cb_stop_cur_5day()
    if cur_5day_toggle == false then
        gre.animation_stop("show_5day")
    else
        gre.animation_stop("hide_mon_to_fri")
  end
end

--Example of using gre.animation_stop with context.
function cb_toggle_cur_5day()
    local data = {}

    data["context"] = "Layer1.mycontrol"
    gre.animation_stop("show_5day", data)
end
                    

gre.animation_pause(animation_id, data)

gre.animation_pause("animation_name")

Pause a running animation. If an animation_id is used to pause the animation, then it must be the return value from gre.animation_create(). If a name is used to pause an animation, then that name must be the name of the animation specified in Designer. This function can take an optional parameter, data_table. The data_table contains the tags and values for the extra arguments to set.

function pause_animation(id)
    --Pause the animation
    gre.animation_pause(id)
end

--Example of using gre.animation_pause passing animation names.
function cb_pause_cur_5day()
    if cur_5day_toggle == false then
        gre.animation_pause("show_5day")
    else
        gre.animation_pause("hide_mon_to_fri")
    end
end

--Example of using gre.animation_pause with context.
function cb_pause_cur_5day()
    local data = {}

    data["context"] = "Layer1.mycontrol"
    gre.animation_pause("show_5day", data)
end
                    

gre.animation_resume(animation_id, data)

gre.animation_resume("animation_name")

Pause a running animation. If an animation_id is used to pause the animation, then it must be the return value from gre.animation_create(). If a name is used to pause an animation, then that name must be the name of the animation specified in Designer. This function can take an optional parameter, data_table. The data_table contains the tags and values for the extra arguments to set.

function resume_animation(id)
    --Resume the animation
    gre.animation_resume(id)
end

--Example of using gre.animation_resume passing animation names.
function cb_resume_cur_5day()
    if cur_5day_toggle == false then
        gre.animation_resume("show_5day")
    else
        gre.animation_resume("hide_mon_to_fri")
    end
end

--Example of using gre.animation_resume with context.
function cb_resume_cur_5day()
    local data = {}

    data["context"] = "Layer1.mycontrol"
    gre.animation_resume("show_5day", data)
end
                    

gre.animation_create_tween(name, tween_callback)
                    

Create a new animation tweening (interpolation) function that can be used by both Lua and Animation Timeline animations. The name of the tweening function cannot collide with any existing animation tweening names. The callback function is a generic tween function that will be provided with specific parameters outlining the desired range of the values being tweend and the frame at which the values should be interpolated.

The tweening function is called with four parameters elapsed, base, change, duration. The elapsed value indicates the interpolation location and is in the range from [0,duration] so if one wanted to derive the percentage that the animation has completed, it would be elapsed/duration. The base value represents the numeric starting point of interpolation and the end point of the animation will be base+change. These four values can be applied to various transforms to return a single floating point value that represents the desired outcome of the interpolation function at that point in time. The output of the interpolation is clamped to the range [base,base+change] though this restriction may be lifted in future releases of Storyboard.

-- Re-implemented linear tween
local function CustomTweenCB(elapsed, base, change, duration)
    return base + ((change * elapsed) / duration)
end

-- This is called at application initialization to register the custom
-- tween function
function CBRegisterTween(mapargs)
    gre.animation_create_tween("MyTween", CustomTweenCB)
end

-- Create an animation that fades out a layer and uses the custom
-- tween function
function CBAnimation(mapargs)
    local id = gre.animation_create(60)

    local data = {}
    data["rate"] = "MyTween"
    data["duration"] = 2000
    data["offset"] = 0
    data["from"] = 255
    data["to"] = 0
    data["key"] = "MyScreen.MyLayer.grd_alpha"
    gre.animation_add_step(id, data)

    gre.animation_trigger(id)
end
        

gre.touch(
    x ,
    y,
    [channel]
)
            

Send a touch event to the application at the co-ordinates passed in through the parameters.  channel is an optional parameter

function CBTouch()
    gre.touch(25, 50)
end

function CBSendTouch()
    local success, error = gre.touch(25, 50, "my_channel")
    if(success == false) then
        print(error)
        --handle error
    end
end

gre.key_up(
    code,
    [channel]
)
            

Send a key_up event to the application with the scancode passed in the parameters. channel is an optional parameter

function CBSpaceUp()
    gre.key_up(0x20)
end

function CBSendSpaceUp()
    local success, error = gre.key_up(0x20, "my_channel")
    if(success == false) then
        print(error)
        --handle error
    end
end

gre.key_down(
    code,
    [channel]
)
            

Send a key_down event to the application with the scancode passed in the parameters. channel is an optional parameter

function CBSpaceDown()
    gre.key_down(0x20)
end

function CBSendSpaceDown()
    local success, error = gre.key_down(0x20, "my_channel")
    if(success == false) then
        print(error)
        --handle error
    end
end

gre.key_repeat(
    code,
    [channel]
)
            

Send a key_repeat event to the application with the scancode passed in the parameters. channel is an optional parameter

function CBKeyRepeat()
    gre.key_repeat(0x20)
end

function CBSendKeyRepeat()
    local success, error = gre.key_repeat(0x20, "my_channel")
    if(success == false) then
        --handle error
    end
end

gre.redraw(
    x,
    y,
    width,
    height,
    [channel]
)
            

Force a screen redraw.  channel is an optional parameter. Specifying a x,y,width,height of 0 will result in a full screen refresh occurring.

function CBRedraw()
    gre.redraw(25, 50, 100, 100)
end

function CBSendRedraw()
    local success, error = gre.redraw(25, 50, 100, 100, "my_channel")
    if(success == false) then
        print(error)
        --handle error
    end
end

gre.quit(
    [channel]
)
            

Send QUIT event to application to force shutdown.  channel is an optional parameter.

function CBQuit()
    gre.quit()
end

function CBSendQuit()
    local success, error = gre.quit("my_channel")
    if(success == false) then
        print(error)
        --handle error
    end
end

-- Send a quit message to the application
gre.quit()

gre.thread_create(func)
		    

This function starts a new operating system thread of execution that is independent from Storyboard's main thread. The function provided as an argument indicates the starting context for this new thread of execution.

The Storyboard data and event (get_data/set_data/send_event) API are thread safe. However the execution of data changes outside of the main thread of execution can have a significant impact on performance of the application and the preferred way of synchronizing data obtained in a thread with the Storyboard UI thread is by using a Storyboard IO event and sending the data via gre.send_event or gre.send_event_data. There are no thread specific synchronization primitives, such as mutexes, for synchronizing Lua data access, serialize to the main thread using an event if this is a requirement.

In scenarios where a controlled shutdown and restart of a Storyboard application is required, separate threads of execution pose a synchronization challenge. In these situations all created thread(s) must have their execution interrupted and terminate in order for a clean shutdown to be observed. This can be accomplished nominally by intercepting the gre.quit event and then taking appropriate action to flag a shutdown variable or send an unblocking event.

This function is not available on all systems and is not available if gre.thread_create is set to nil.

-- Flag to indicate that we want our threads to quit executing
local quit_threads = false

-- Run a poll loop waiting for a file (a_file) to appear and
-- then send an event
function async_function()
    while(not quit_threads) do
        local fp = io.open("a_file")
        if(fp ~= nil) then
            fp:close()
            gre.send_event("file_created")
            return
        end
    end
end

-- Create the monitoring thread of execution
gre.thread_create(async_function)
		    

gre.receive_event(
    channel
)
            

Receive an event from a Storyboard IO channel.  This is a blocking call and works best when used on a separate Lua thread.

-- Receive a Storyboard IO event with data payload x, y, z:
ev = gre.receive_event("my_channel")

if ev ~= nil then
    print(ev.name)

    for k,v in pairs(ev.data) do
        print(tostring(k).." "..tostring(v))
    end
end

--To disconnect from my_channel:
gre.greio_disconnect("my_channel", true)
            

gre.env(
    string_key
)
or
gre.env(
    table
)
		    

Return information about the Storyboard runtime environment. The input can be either a single string containing the key to look up or a table of keys for variables to match. The following table describes the available keys:

-- Get the target OS for dynamic module loading
local os = gre.env("target_os")
print("Running on target OS: " .. tostring(os))

-- Report on the Storyboard version and rendering technology
local info = gre.env({"version", "renderer"})
local msg = string.format("Storyboard version %s (%s renderer)",\
            info.version, info.renderer)
print(msg)
		    

gre.log(
	id,
    msg
)
		    

Generate a log message that will be carried through the Storyboard engine logging system. This can be more effective than using standard Lua print statement because the output can be redirected to different outputs.

-- Generate an error message
gre.log(1, "This is an error message")

-- Generate an diagnostic information message
gre.log(4, "This is an info  message")

-- Generate an unfiltered message
gre.log(-1, "This message will always be shown")
		    

gre.mstime()
gre.mstime(app_relative)
		    

Retrieve the current time in milliseconds in the default, no argument flavour. This call provides a higher resolution than the standard Lua os.clock()or os.date() functions.

When true is passed in as an argument, then the time returned will be relative to the application start time and aligned with the timestamps that are generated by the Storyboard logging API.

-- Time an operation
local s = gre.mstime()
my_function()
local e = gre.mstime()
print("my_function took " .. tostring(e - s) .. "ms")

-- Determine how long from app start to this point
local delta = gre.mstime(true)
print(string.format("Application start to now: %d ms", delta)
		    

gre.rgb(
	r,
    g,
    b,
    [a]
)
		    

Create a color number value from the individual red, green and blue color components. An optional fourth argument, alpha, may be provided.

-- Create a grey single color value
local grey = gre.rgb(100, 100, 100)

-- Extract the red, green and blue values from the grey
local r, g, b = gre.torgb(grey)		    

gre.torgb(
	color
)
		    

Extract the red, green, blue and alpha components from a single color value.

-- Create a grey single color value
local grey = gre.rgb(100, 100, 100)

-- Extract the red, green and blue values from the grey
local r, g, b = gre.torgb(grey)		    

gre.rtext_text_extent(text, target, table)

Gets the extent of a rich text field