Storyboard Engine Public API

Table of Contents

gr_application_create_args
gr_application_create
gr_application_free
gr_application_run
gr_application_quit
gr_application_debug
gr_app_log
gr_application_set_data
gr_application_set_data_variable
gr_application_get_data
gr_application_get_data_variable
gr_application_add_event_listener
gr_application_rem_event_listener
gr_application_send_event
gr_context_get_application
gr_context_max_fqn
gr_context_get_row
gr_context_get_column
gr_context_get_control
gr_context_get_group
gr_context_get_layer
gr_context_get_screen
gr_context_get_fqn
gr_context_get_event_name
gr_context_get_event_data

Users that are writing their own plugin or users who are working with a Storyboard RTExec or Storyboard Lite plaform should familiarize themseleves with this section as it talks about how the Storyboard engine is initialized. If you are running on a system such as Linux or QNX, then the information in this section is not needed.

The Storyboard Engine is initialized in two steps:

  1. The first step is to create the engine's application handle via the gr_application_create_args function. This function initializes the core framework and plugins and loads the UI model and verifies its integrity.

  2. Once the UI model is loaded then the main UI event loop can be started using the gr_application_run function along with the application handle returned from gr_application_create_args. The gr_application_run function will not return until the application terminates.

The Integration API is thread safe so it is possible to terminate the application, by calling gr_application_quit, in another thread. In general the gr_application_create and gr_application_run functions should be called from the same thread context since the initialization of some of the engine’s sub-systems may create thread local data required for execution.

When the application terminates, and returns from gr_application_run, then the application handle should be released by calling gr_application_free. Once an application handle has been released it is no longer valid to be used.

The Engine provides execution tracing functionality through the gr_application_debug interface. This function takes an optional application handle and an integer command value. Additional arguments may be required based on the type of command and are documented within the <gre/gre.h> header. This function is most often used to provide additional diagnostics. For example invoking:

gr_application_debug(NULL, GR_DEBUG_CMD_VERBOSITY, GR_LOG_TRACE2);                  

will enable logging of all significant operations within the engine.