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 actions, 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.


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.