Data Binding for Dynamic Behavior

Render extensions associated with controls render the content, from text and images to arcs and polygons. Each render extension's behavior is controlled through a set of properties that the user can configure, such as fill color, text size and font, and image filename. By default, the settings for these properties are fixed at design time and can't be changed dynamically at runtime. However, these settings can be dynamically adjusted at runtime by using Storyboard variables.

Attributes, for both render extensions and actions, that may require dynamic adjustment at runtime can be associated to named Storyboard variables.

Similar to the event/action association, variables can be bound to any of the model elements in the application. This ownership dictates how that variable will be referenced when it is associated with a property in a render extension or action. Storyboard variables are managed as loosely typed key/value pairs in the Storyboard Engine's data manager component. The key is the fully qualified name of the variable as it is declared within the model and the value is the value of the variable set initially within Designer and changeable at runtime through various actionsactions, animations, or using the Lua API.

The Storyboard model is hierarchical, so the construction of a fully qualified model path is a straightforward process of joining model element name segments with a . (dot) in between them. The following list demonstrates how the fully qualified model name is formed for a variable, varname, associated with different contexts in the model.

varnameThis identifies a variable, varname, as an application level variable
screen_name.varnameThis identifies a variable, varname, as associated with the screen screen_name
layer_name.varnameThis identifies a variable, varname, as associated with the layer layer_name
screen_name.layer_name.varnameThis identifies a variable, varname, as associated with the layer instance layer_name associated with the screen screen_name. Most variables are not defined as layer instance variables, but rather as layer variables.
layer_name.control_name.varnameThis identifies a variable, varname, as associated with the control control_name that is located on the layer layer_name. Groups variables can also be addressed in this same manner as groups are also children of layers. The variable, layer_name.group_name.varname identifies a variable varname within the group group_name.
layer_name.group_name.control_name.varnameThis identifies a variable, varname, as associated with the control control_name that is located in the group group_name on the layer layer_name.

Note

There is some overlap in the Storyboard namespace that could lead to ambiguous resolution. To maintain a clear name resolution, layers and screens may not have the same names. Within a container, such as a layer or a group, all of the model element names must be unique. Storyboard Designer enforces this restriction.

Which model element owns a variable is usually a good indication of its scope. Variables that are owned by control model elements will typically have an association with render extensions or actions local to that control. A variable with a broader ownership, such as at the screen or application level, will likely have several different associations within the model.

For example, to represent a button with a changing image, one might create a variable on a control that is used by an image render extension on that control. To easily configure the fonts and text sizes used within the application, you might create several variables at the application level and have all of text render extensions refer to those variables.

Variables represent data that is used within the user interface but are not tied to any single context. The same variable may be referenced by different render extension clients or even associated with action properties.

When you want to make a change to the visual presentation of the user interface, you don't perform drawing calls directly, instead you make changes to one of the variables that you have created. The Storyboard Engine monitors the values of all variables. As variable content changes, Storyboard determines if the variable is used by the current on-screen content. If there are changes, the Engine automatically schedules a refresh operation and groups the refresh operations together for efficiency.

To associate a property with a variable or to change the value of a variable, it's important to understand how a variable is addressed within the application. The addressing scheme generally follows the model hierarchy. When a variable is sourced from the application root using this full path, it is called a fully qualified name.

Note that variables associated with layers and variables associated with screens have the same addressing path. This is because a layer and it's content can exist on multiple screens, and removing the screen component allows a consistent address path to groups and controls on that layer.

Context and Variables

It can be cumbersome to always use a variable's fully qualified name. In some cases it is more convenient to address a variable by its context of use. For example, render extensions are always associated with a control and in many instances the properties that they associate to variables will also be local to that control. In this situation it would be more convenient to refer to a variable as being 'local to the control'. Storyboard supports this through the use of a data context shorthand that can replace a variable's fully qualified name.

The data context is the context of execution of a particular activity. For render extensions, this means the parent control of the render extension. For actions, this means the model element associated with the triggering event. The shorthand notation is a string formatted as ${@@CONTEXT:NAME} where CONTEXT is going to be one of app, screen, group, layer, or control indicating the model element in context to resolve, while the NAME is the name of the variable being addressed.

To reduce complexity of using the fully qualified model paths and to minimize the maintenance effort as a project evolves or changes, Storyboard defines several variable shortcuts that will expand their value based on the current model context in which they are being resolved.

${app:varname}Refers to the application variable varname.
${screen:varname}Refers to the screen variable varname.
${layer:varname}Refers to the layer variable varname.
${group:varname}Refers to the group variable varname.
${control:varname}Refers to the control variable varname.

For example, in the following Storyboard model:

Application
 + MainScreen
   + ALayer
     + AGroup
       + AControl

where the current focus is associated with the control AControl, reference to a variable varname would resolve to a fully qualified path as follows:

${app:varname}varname
${screen:varname}MainScreen.varname
${layer:varname}ALayer.varname
${group:varname}ALayer.AGroup.varname
${control:varname}ALayer.AGroup.AControl.varname

For tables, where the context also includes the row and column index of the table cell being adjusted, a special ${cell:CONTEXT:NAME} notation can be used that converts the variable shorthand into a variable that contains the row and column as a postfix to the standard variable name. For example, if the current focus or selection was directed a table control named ATable on the cell that was occupying row five and column one then the following would be variable expansions:

${cell:app:varname}varname.5.1
${cell:group:varname}ALayer.AGroup.varname.5.1
${cell:control:varname}ALayer.AGroup.ATable.varname.5.1

Storyboard Model Internal Variables

Not all variables have to be defined by the user and associated with render extension and action properties. Storyboard defines a set of variables for the model element properties such as position, size, and visibility. Each class of model elements contains a slightly different set of values, but all of the variables are prefixed with the grd_ (Graphical Runtime Data) variable namespace to avoid any confusion with user created variables.

These variables are generally accessed using ${model_object:varname}, for example ${control:grd_x} indicates the x position of the current control

Layer variables

The following values can be queried and changed through normal data management channels. The position variables are relative to the screen.

grd_x4s1The layer instance's x position relative to the screen
grd_y4s1The layer instance's y position relative to the screen
grd_xoffset4s1The x pixel offset that will be used to determine the origin of the layer instance
grd_yoffset4s1The y pixel offset that will be used to determine the origin of the layer instance

Note

Any change to the following values affects all layers.

grd_width4s1The layer's width
grd_height4s1The layer's height
grd_alpha1u1The layer's transparency value. The values range from 255 (opaque) to 0 (transparent)
grd_hidden1u1The layer's visibility. A value of 0 states that the layer and all of its controls are visible and a value of 1 hides the layer and all of its controls

Group variables

The following values can be queried and changed through normal data management channels.

grd_x4s1The group's x position relative to its layer
grd_y4s1The group's y position relative to its layer
grd_zindex4s1The group's z-index position. This sets the stacking order of groups within its layer where 0 is at the back (furthest from the eye).
grd_hiddenlu1The group's visibility. A value of 0 indicates that the control is visible and 1 that it is hidden

Control variables

The following values can be queried and changed through normal data management channels.

grd_x4s1The control's x position relative to its layer
grd_y4s1The control's y position relative to its layer
grd_width4s1The control's width
grd_height4s1The control's height
grd_zindex4s1The control's z-index position. This sets the stacking order of controls within its layer where 0 is at the back (furthest from the eye).
grd_hidden 1u1The control's visibility. A value of 0 indicates that the control is visible and 1 that it is hidden
grd_active1u1A value of 1 states that the control is active (can receive and react to events) and 0 for an inactive control (cannot receive or react to events)
grd_opaque1u1Indicates if the control is opaque to events. If opaque (1), the control will block events from being handled by other controls.  If the value is 0, the events flow through the control to ones behind it.
grd_findex4s1The control's focus index. This sets the focus on a control in a navigation sequence, where 1 sets the focus on the first control, 2 sets the second, etc. A value of 0 indicates that the control is not focusable. In order for a control's focus index to be changed dynamically at runtime, the focus value must be initially set to a non-zero value in Storyboard Designer.

Table variables

A table contains all of the control variables and also a set of table specific variables. These table specific variables can be queried but not dynamically changed. In order to change these values in a table, actions are provided: gra.table.resize, gra.table.scroll.  The variables are as follows.

grd_rows4s1The number of rows in the table
grd_cols4s1The number of columns in the table
grd_visible_rows4s1The number of visible rows in the table
grd_visible_cols4s1The number of visible columns in the table
grd_active_row4s1The row index of the currently active cell
grd_active_col4s1The column index of the currently active cell
grd_row4s1The table’s current top left row
grd_col4s1The table’s current top left column
grd_xoffset4s1The x pixel offset that will be used to determine the origin of the 1,1 table cell
grd_yoffset4s1The y pixel offset that will be used to determine the origin of the 1,1 table cell