Storyboard Lua API

gre.SCRIPT_ROOT

gre.SCRIPT_ROOT
                    

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

The gre.SCRIPT_ROOT variable provides a convenient way to reference the file resources in a location independent, project relative, fashion. 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.


Example:
                    

 local data_file = gre.SCRIPT_ROOT .. "/input_data.csv"
                    

gre.set_data

 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’s name as the key.


Parameters:
    
        table A table containing the variable to change as the key and the value to change it to as that key's value.

Example:
            

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

gre.get_data

gre.get_data( 
    val1 
    [ ,val2 , ...] 
) 
            

Gets one or more data entries from the data manager. Each value passed in as a parameter has a lookup in the data manager using the value as the key. 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.


Parameters:
    
        val1    One or more strings containing data manger variable keys to look up.
        
Returns:

        A table containing the passed in arguments as keys and the resulting data manager values as
        the values associated with those keys.

Example:
            

function get_data_fuc( mapargs, stringargs )
  local data_table  = {}
  data_table = gre.get_data("variable_name")
  print("variable_name = "..data_table["variable_name"])
end
            

gre.send_event

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.


Parameters:
    
        event_name    A string containing the event to send
        channel       An optional Storyboard IO channel to send the event on, if not specified the
                      event is added directly into the current Storyboard application event queue
                      if neither the environment variable or global GREIONAME variable are set.
        
Example:
            

-- Send to the event  to the application : 
gre.send_event("my_event")

--To send the event to a Storyboard IO channel via parameters:
gre.send_event("my_event", “io_channel_name”)
            

gre.send_event_target

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.


Parameters:
        
        event_name    A string containing the event to send
        target        A string containing the object to target the event to (see Storyboard IO)
        channel       An optional Storyboard IO channel to send the event on, if not specified the
                      event is added directly into the current Storyboard application event queue
                      if neither the environment variable or global GREIONAME variable are set.
        
Example:
            

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

gre.send_event_data

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.   data is a Lua table where the indexes match the values from the format string. channel is an optional parameter.


Parameters:
        
        event_name    A string containing the event to send
        format_string A string format of the event data payload 
        data          A table whose keys match up with the keys specified in the format_string 
        channel       An optional Storyboard IO channel to send the event on, if not specified the
                      event is added directly into the current Storyboard application event queue
                      if neither the environment variable or global GREIONAME variable are set.
Example:
            

gre.greio_disconnect

gre.greio_disconnect(
    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.


Parameters:

            channel    The channel that is to be disconnected. 
            
Example:
    

-- 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.touch

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


Parameters:
        
        x           The x position to simulate the touch event at
        y           The y position to simulate the touch event at
        channel     An optional Storyboard IO channel to send the event on, if not specified the
                    event is added directly into the current Storyboard application event queue
                    if neither the environment variable or global GREIONAME variable are set.
Example:
            

gre.key_up

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


Parameters:
        
        code        The utf-8 character code to inject
        channel     An optional Storyboard IO channel to send the event on, if not specified the
                    event is added directly into the current Storyboard application event queue
                    if neither the environment variable or global GREIONAME variable are set.
Example:
            

gre.key_down

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


Parameters:
        
        code        The utf-8 character code to inject
        channel     An optional Storyboard IO channel to send the event on, if not specified the
                    event is added directly into the current Storyboard application event queue
                    if neither the environment variable or global GREIONAME variable are set.
Example:
            

gre.key_repeat

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


Parameters:
        
        code        The utf-8 character code to inject
        channel     An optional Storyboard IO channel to send the event on, if not specified the
                    event is added directly into the current Storyboard application event queue
                    if neither the environment variable or global GREIONAME variable are set.
Example:
            

gre.redraw

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 occuring.


Parameters:
        
        x           The x position of the redraw bounding box event
        y           The y position of the redraw bounding box event
        width       The width position of the redraw bounding box event
        height      The height position of the redraw bounding box event
        channel     An optional Storyboard IO channel to send the event on, if not specified the
                    event is added directly into the current Storyboard application event queue
                    if neither the environment variable or global GREIONAME variable are set.
Example:
            

gre.quit

gre.quit(
    [channel]
)
            

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


Parameters:
                
        channel     An optional Storyboard IO channel to send the event on, if not specified the
                    event is added directly into the current Storyboard application event queue
                    if neither the environment variable or global GREIONAME variable are set.

Example:
            

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

gre.layer_move

gre.layer_move(
    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 and or dy will move the layer by the specified delta from its current position.   Dx and dy can be 0 to set an absolute position using x and y.


Parameters:
        
        layer_name  The model full path of the layer to move
        dx          A delta from the current x position or 0 to move using x
        dy          A delta from the current y position or 0 to move using y
        x           The x position to move to in absolute co-ordinates
        y           The y position to move to in absolute co-ordinates

Example:
            

gre.move_control

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.  Dx and dy can be 0 to set an absolute position using x and y.


Parameters:
        
        control_name    The model full path of the control to move
        dx              A delta from the current x position or 0 to move using x
        dy              A delta from the current y position or 0 to move using y
        x               The x position to move to in absolute co-ordinates
        y               The y position to move to in absolute co-ordinates

Example:
            

gre.clone_control

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

Create a new control by cloning an existing control. The template_name, new_control_name and layer_name are manditory and the data parameter is optional. The data parameter is a table containing control data as listed below.

        x,  y, width, height, hidden, active


Parameters:
        
        template_name     The name of the control to clone
        new_control_name The name for the new control, must be unique
        layer_name The name of the layer to place this control on, must already exist
        data Optional: A table with tags as the keys and the new values stored as the table's key values 
       
Example:
            

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

gre.delete_control

gre.delete_control(
    control_name, 
)                
            

Delete a control from the model. The control must be a control which was dynamically created with the clone_control function.


Parameters:
        
        control_name     The name of the control to delete
       
Example:
            

function delete_control()
  gre.delete_control("my_control")        
end
            

gre.get_control_attrs

gre.get_control_attrs(
    control_name
    tags ...
)
            

Get attributes 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

A table with the results is returned.


Parameters:
        
        control_name    The model full path of the control to get information about
        tags            One or more tags as strings 
       
Returns:

        A table containing the tags as keys with the associated table value being the Storyboard
        value associated with that tag.

Example:
            

function check_if_hidden()
  local dk_data = {}
  -- check if my_control is currently hidden
  dk_data = gre.get_control_attrs("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

gre.set_control_attrs(
    control_name, 
    tag_table
)                
            

Set attributes 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 attributes to set.

        x,  y, width, height, hidden, active


Parameters:
        
        control_name    The model full path of the control to change attributes on
        tag_table       A table with tags as the keys and the new values stored as the table's key values 
       
Example:
            

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

gre.get_layer_attrs

 gre.get_layer_attrs(
    layer_name
    tags...
 )
            

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

        x, y, alpha, hidden, active

A table with the results is returned.


Parameters:
        
        layer_name      The model full path of the layer to get information about
        tags            One or more tags as strings 
       
Returns:

        A table containing the tags as keys with the associated table value being the Storyboard
        value associated with that tag.

Example:
            

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

gre.set_layer_attrs

gre.set_layer_attrs(
    layer_name, 
    tag_table
)                
            

Set attributes for a layer.  Key name is the name of the layer or a variable.  Table contains the tags and values for the attributes to set.

        alpha, hidden, active, x, y


Parameters:
        
        layer_name    The model full path of the layer to change attributes on
        tag_table     A table with tags as the keys and the new values stored as the table's key values 
       
Example:
            

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

gre.set_layer_attrs_global

gre.set_layer_attrs_global(
    layer_name, 
    table
)                
            

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

        alpha, hidden, active, x, y


Parameters:
        
        layer_name    The model full path of the layer to change attributes on
        tag_table     A table with tags as the keys and the new values stored as the table's key values 
       
Example:
            

gre.get_table_attrs

gre.get_table_attrs(
    table_name,
    tags
)
            

Get attributes 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:

rows

The number of rows in the table

cols

The number of columns in the table

visible_rows

The number of visible rows in the table

visible_cols

The number of visible columns in the table

active_row

The active cell row

active_col

The active cell column

row

The row index of the upper left column

col

The column index of the upper left column


Parameters:
        
        table_name      The model full path of the table to get information about
        tags            One or more tags as strings 
       
Returns:

        A table containing the tags as keys with the associated table value being the Storyboard
        value associated with that tag.

Example:
            

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.get_table_cell_attrs

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

Get attributes 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.


Parameters:
        
        table_name    The model full path of the table to get information about
        row   The row of the table to get information on
        col   The column of the table to get information on        
        tags          One or more tags as strings 
       
Returns:

        A table containing the tags as keys with the associated table value being the Storyboard
        value associated with that tag.

Example:
            

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_string_size

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.


Parameters:
                
        string          The string to render
        font            The name of the font to render int
        font_size       The size of the font to render in  
        string_length   The length of the string to render or 0 for all (optional)
        width           A clipping width (in pixels) for the string, used to calculate how many characters fit
        (optional, by default there is no clip)
                
Returns:
                
        A table containing the following entries:
        "nbytes" number of bytes that will fit in the clip
        "nchars" number of characters that will fit in clip
  "width" string width in pixels as clipped by clip width
  "height" string height in pixels
        "line_height" height in pixels of the specified font
        

gre.resolve_data_key

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.


Parameters:

            key1 ...    One or more string arguments containing the variable to resolve. 
            
Returns:

            A table containing the arguments provided on input as keys with the values being the 
            resolved data value.
                
Example:
    

-- 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.load_resource

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 resoruces are lazy loaded into the application.


Parameters:

            pool_name       The name of the resource pool: image or font
            resource_name   The name of the resource that is to be loaded
            
The optional parameters vary depending on the pool being specified and are not required:
            image pool:
                w, h        The width and height to cache the image at
            font pool:
                size, antialias The point size of the font and if antialiasing is to be used
Example:
    

-- Call this on app init to pre-load the tree.jpg image and DejaVu.ttf font into the cache
function on_app_init(mapargs) 
    gre.load_resource("image", "images/tree.jpg")
    gre.load_resource("font", "fonts/DejaVu.ttf")
end
            

gre.dump_resource

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.


Parameters:

            pool_name       The name of the resource pool: image or font
            resource_name   The name of the resource that is to be removed
            
Example:
    

-- 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

gre.walk_pool(
    pool_name,
)		      
		    

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


Parameters:

            pool_name       The resource pool whose content should be reported

Returns:

            A table is returned with keys as the resources that are contained in the pool and values 
            indicating the number of bytes that a particular resource is using within the system.
            
Example:
    

-- 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.mstime

gre.mstime()		        
		    

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


Returns:
        
        The current time in milliseconds.
                
Example:
    

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

gre.env

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:

target_os

The target operating system

target_cpu

The target processor

screen_width

The dimensions of the screen width

screen_height

The dimensions of the screen height

active_screen

The name of the currently active screen


Parameters:

Returns:
        
        If a single string is provided as an input argument, just a single data value for that argument is returned
        
        If a table is provided as an input argument, then a table with key/value pairs corresponding to the keys
        of the input argument and the results they provide.
                
Example:
    

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