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.

varname This identifies a variable, varname, as an application level variable
screen_name.varname This identifies a variable, varname, as associated with the screen screen_name
layer_name.varname This identifies a variable, varname, as associated with the layer layer_name
screen_name.layer_name.varname This 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.varname This 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.varname This 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] 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

 

Was this article helpful?
0 out of 0 found this helpful
Have more questions? Submit a request

Comments

0 comments

Please sign in to leave a comment.