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( 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 ) 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.
Parameters:
key The key whose value should be extracted from the data manager.
Returns:
A table containing the passed in arguments as keys and the resulting data manager values as
the values associated with those keys.
Example - Accessing Control Variables:
function get_data_fuc( 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
Example - Accessing Control Width (Internal Variable):
function get_control_width( mapargs ) --This will extract the width (grd_width) of the contro --'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.
Parameters:
key A string value containing the key to be set with the next following value
value The value to be assigned to the preceding argument (key)
Example:
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.
Parameters:
key The key whose value should be extracted from the data manager.
Returns:
The value associated with the data manager entry for the key, or nil if no entry exists. If multiple
keys are specified, then multiple return values will be generated matching the argument order.
Example - Accessing Control Width:
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.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( 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 ( 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 (ie 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.
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:
-- Send a 'int32_update' event with a 32bit signed integer (int32_t) -- payload to the 'controller' channel function send_integer(value) loca format = "4s1 value" local data = {} data["value"] = value gre.send_event_data("int32_update", format, data, "controller") end -- Send a 'int16_update' event with two 16bit signed integers (int16_t) -- payload to the 'controller' channel function send_two_integers(value1, value2) loca format = "2s1 first 2s1 second" local data = {} data["first"] = value1 data["second"] = value2 gre.send_event_data("int16_update", format, data, "controller") 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 gre.send_event_data("array_update", format, data, "controller") end send_integer(12) send_two_integers(10, 20) send_integer_array({10, 20, 30, 40})
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.
Parameters:
channel A Storyboard IO channel to receive the event on.
Returns:
event A table containing the name, target, format and a data table from a received event.
Example:
-- 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.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.
Parameters:
channel The channel that is to be disconnected.
is_receiving An optional boolean parameter.
-True if closing a receiving channel.
-False or no argument if closing a sending channel.
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( 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( 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( 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( 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( 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.
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( [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.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.
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( 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.
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( 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 required and the data parameter is optional. The data parameter is a table containing control data as listed below. All data variables belonging to this control will also be cloned, and assume the same value as their source control counterpart.
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( 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( 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, zindex, findex
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( 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, 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
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
Examples:
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_layer_attrs( layer_name tags... )
Get attributes 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 attributes associated with the layer instance and can include one or more of the following values:
x, y, 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.
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() -- 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 attributes 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
Any change to the width and height values affect all layers.
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 data = {} data.hidden = 1 gre.set_layer_attrs("my_layer", data) end
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. Table contains the tags and values for the attributes to set.
alpha, hidden, active, x, y, width, height
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
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:
The number of rows in the table
The number of columns in the table
The number of visible rows in the table
The number of visible columns in the table
The active cell row
The active cell column
The row index of the upper left row
The column index of the upper left column
The current scroll offset in the x direction
The current scroll offset in the y direction
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.set_table_attrs( table_name, tag_table )
Set attributes 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 attributes to set.
x, y, width, height, hidden, active, rows, cols, xoffset, yoffset
Parameters:
table_name The model full path of the table 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 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 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( 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 in
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:
"num_bytes" number of bytes that will fit in the 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.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 ...
Parameters:
x_values,
y_values An table containing numeric data for the x and y points respectively.
{{x=, y=}} A table containing tables with x and y members specifying the x and y points.
Example:
-- 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.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( 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.
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, background The width and height to cache the image at, and whether or not to load the
image asynchronously the 'background'
font pool:
size, antialias The point size of the font and if anti aliasing is to be used
These options can be passed in as a table in the 3d parameter instead, which allows any or all of them to be specified.
On completion of a 'background' loaded resource, the following event is sent:
gre.resource_loaded 1s0 resource
Example:
-- Call this on app init to pre-load the image and font into the cache function on_app_init(mapargs) gre.load_resource("image", "images/tree.jpg") gre.load_resource("font", "fonts/DejaVu.ttf") -- Call this on app init to pre-load the image and scale it to 100x100 gre.load_resource("image", "images/scaledtree.jpg", 100, 100) local tbl = {} tbl["w"]=100 tbl["h"]=100 tbl["background"]=1 -- Call this on app init to pre-load the image and scale it to 100x100 -- asynchronously gre.load_resource("image", "images/scaledtreebg.jpg", tbl) 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.
Parameters:
resource_name The name of the resource that is to be loaded
The optional parameters are as follows:
w The width to cache the image at
h The height to cache the image at
background Whether or not to load the image asynchronously the 'background'
On completion of a 'background' loaded resource, the following event is sent:
gre.resource_loaded 1s0 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( 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.timer_set_timeout( function, timeout )
This function creates a one-shot timer which fires after "timeout" milliseconds and then executes "function"
Parameters:
function The function to be called when the timer fires
timeout The time in milliseconds before the timer should fire
Returns:
A piece of lightuserdata which serves as an identifier for the timer
Example:
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"
Parameters:
function The function to be called when the timer fires
interval The time in milliseconds of how often the timer should fire
Returns:
A piece of lightuserdata which serves as an identifier for the timer
Example:
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
Parameters:
id The lightuserdata representing the timer
Returns:
Nothing
Example:
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
Parameters:
id The lightuserdata representing the timer
Returns:
Nothing
Example:
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.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.
Parameters:
func The Lua function to run in a separate thread of execution from the main UI thread.
Returns:
Nothing
Example:
-- 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.vfs_open(filename)
This function provides read-only file access to resources packaged in the Storyboard virtual filesystem for embedded targets with no filesystem support.
The function works similarly to the Lua io.open()
and returns a FILE type object based on a project relative path. The returned object
provides the file:read()
, file:lines()
, file:seek()
and file:close()
operations as described in the
standard Lua documentation.
The use of this function can incur significant memory overhead if large files are read entirely into memory.
This function is not available on all systems and is not available if gre.vfs_open
is set as nil.
Parameters:
filename The name of the resource to open as a project relative path (ie translations/french.csv)
Returns:
A file handle that contains read
, seek
, lines
, close
operations.
Example:
-- Use a simple CSV parser that assumes a single delimiter between -- variable and value function load_translation() local fp = gre.vfs_open("translations/french.csv") if(fp ~= nil) then local comma, var, value for l in fp:lines() do comma = string.find(l, ',', 0, true) if(comma ~= nil) then var = string.sub(l, 1, comma - 1) value = string.sub(l, comma + 1) gre.set_data({ [var] = value }) end end fp:close() end end
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.
Returns:
The current time in milliseconds in a system specific manner (gre.mstime()) or the time in milliseconds
since the start of the application (gre.mstime(true))
Example:
-- 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.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:
The target operating system
The target processor
The dimensions of the screen width
The dimensions of the screen height
The name of the currently active screen
The rendering capabilities. Currently the only defined capability is "3d" if 3d rendering is supported
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))
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.
Parameters:
fps The animation frame rate
auto_destroy Pass 1 in to release the animation once completed
end_callback Provide a Lua function to be called in the animation
Returns
An animation id to be used on future animation calls, nil on failure.
Example:
function animation_create(mapargs, fps) local id id = gre.animation_create(fps) 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.
Parameters:
id The animation id
data A table of animation step values which can include:
key: The data key for the animation step to act upon
rate: The animation rate string: [linear|easein|easeout|easeinout|bounce]
duration: The length of the step (msec)
offset: The offset from animation start where this step begins (msec)
from: The value to start the animation at, if not specified the value is the current value of "key"
to: The end point for the animation
delta: The delta for the end of the animation from the start point. If both "to" and "delta" are given
then the "to" value is used.
Example:
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)
Destroy the animation associated with id.
Parameters:
id The animation to destroy
Example:
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.
Parameters:
animation_id The animation to trigger
data A table containing the tags and values for the extra arguments to set
id The animation id used in the case of multiple animations with the same name
context The fully qualified name of an object in the model which will be used as the context for the animation
Example:
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