Version: 9.0.3

Storyboard Lua API

Stroyboard Lua 'gre' documentation.

📄️gre.action_trigger

Trigger a Storyboard action by name with the provided arguments.

📄️gre.add_data_listener

Add a data change listener. When the specified variable changes in the data manager, the provided callback function will be executed.

Add an event listener that will invoke a callback with the standard mapargs table as its first argument. The target option can be used to specify a model object to listen on, if it is not present the listener will be created at the application level.

📄️gre.animation_add_step

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.

📄️gre.animation_create

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.

📄️gre.animation_create_tween

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

📄️gre.animation_destroy

Destroy the animation associated with id.

📄️gre.animation_get_state

Get the current state of an animation. Possible states are:

📄️gre.animation_pause

Pause a running animation. If an animationid is used to pause the animation, then it must be the return value from gre.animationcreate(). 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, datatable. The datatable contains the tags and values for the extra arguments to set.

📄️gre.animation_resume

📄️gre.animation_stop

Stop an animation. If an animationid is used to stop the animation, then it must be the return value from gre.animationcreate(). 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, datatable. The datatable contains the tags and values for the extra arguments to set.

📄️gre.animation_trigger

Trigger an animation to run. If an animationid is used to trigger the animation, then it must be the return value from gre.animationcreate(). 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, datatable. The datatable contains the tags and values for the extra arguments to set.

📄️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.

📄️gre.clone_control

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

📄️gre.clone_object

Create a new control, table or group (newobjectname) within an existing parent (parentname) by copying all of the properties of an existing object (referenceobject_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.

📄️gre.delete_control

This is a function to delete a cloned control. This function has been deprecated and has been replaced with the gre.deleteobject() Lua API function.

📄️gre.delete_object

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

📄️gre.dump_resource

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

📄️gre.env

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:

📄️gre.get_control_attrs

Get properties for a control. Key name is the name of the control or a

📄️gre.get_data

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.

📄️gre.get_focus

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

📄️gre.get_group_attrs

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:

📄️gre.get_layer_attrs

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

📄️gre.get_string_size

Calculate the area in pixels which the given string will occupy on the screen.

📄️gre.get_table_attrs

Get properties for a table. Key name is the name of the control or a variable.

📄️gre.get_table_cell_attrs

Get properties for a table cell. table_name is the name of the table.

📄️gre.get_value

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.

📄️gre.greio_disconnect

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.

📄️gre.key_down

Send a gre.keydown event to the application with the scancode passed in the parameters.

📄️gre.key_repeat

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

📄️gre.key_up

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

📄️gre.LEFT, gre.RIGHT, gre.CENTER, gre.TOP, gre.BOTTOM

These are definitions for horizontal and vertical values and are a shorthand for the following numeric values representing alignment:

📄️gre.load_image

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.

📄️gre.load_resource

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.

📄️gre.log

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. In order to have gre.log() messages logged properly, the -olua,log option or the -omodelmgr,pluginlog option needs to be set.

📄️gre.LOG_ constants

| Name | Value | Description |

📄️gre.move_control

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

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

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.

📄️gre.OPAQUE, gre.TRANSPARENT

These are definitions for the transparency (alpha) values and are a shorthand for the following numeric values representing extreme transparency:

📄️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 modelmgr using the -omodelmgr,pluginpath option or via the SBPLUGINSenvironment 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.poly_string

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

📄️gre.quit

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

📄️gre.receive_event

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

📄️gre.redraw

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.

📄️gre.remove_data_listener

Remove a previously added data listener created with gre.adddatalistener()

📄️gre.remove_event_listener

Remove an event listener created with gre.addeventlistener().

📄️gre.resize_control

Resize a control. The control_name is the name of the control or a variable. Setting dw and or dh will resize the control by the specified delta from its current size. The dw and dh values can be 0 to set an absolute position using the w and h values only.

📄️gre.resolve_data_key

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

📄️gre.rgb

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

📄️gre.rtext_text_extent

Gets the extent of a rich text field

📄️gre.screen_attach_layer

Attaches a layer to a screen dynamically creating a new layer instance. When used without a screen list this will attach the specified layer to all screens in the application. When used with a list of screens it will bind the specified layer to all of the screens named in the screen list.

📄️gre.SCRIPT

The argument passed to Storyboard if an entry script was specified with -olua,script=[file].

📄️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.

📄️gre.send_event

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:

📄️gre.send_event_data

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.

📄️gre.send_event_target

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.

📄️gre.set_control_attrs

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

📄️gre.set_data

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.

📄️gre.set_focus

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.

📄️gre.set_group_attrs

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

📄️gre.set_layer_attrs

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

📄️gre.set_layer_attrs_global

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.

📄️gre.set_table_attrs

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

📄️gre.set_table_cell_attrs

Set attributes for a table cell. This can only be applied for single column or single row tables and the parameters that can be modified are restricted in each case:

📄️gre.set_table_template_attrs

Set attributes for a table column template. This will result in the template being changed and the entire table being re-laid out and re-configured. If any changes were made to specific cells then those changes will be lost and need to be re-applied.

📄️gre.set_value

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.