Storyboard Architecture

An application is organized as a hierarchy of screens, layers, groups, and controls that are collectively called model elements.

Screens are used to represent contextual visual states of your application. When working within Designer your primary viewport into how the application is organized will be through the screens of the application that are defined. Structurally a screen is an ordered list of layers that are composited together to form the final screen display. In a Storyboard application only one screen can be active at a time.

Layers are used to organize related visual elements together in a reusable manner. In this case, reuse means reusable in different screen contexts so that the same layer can be associated with several different screens. When layers are shared among multiple screens, for example, as a common menu or background, then the content of the layer is exactly the same in those different screen contexts. If content changes on the layer in one screen context, then the content will change across all screens that use that layer. While the content for layers may be shared, there are several properties that are tied specifically to how the layer is used within a screen. These properties are called layer instance properties since they relate directly to a particular instance of a layer and include the x/y position of the layer, the visibility/hidden state, and the transparency or alpha blending value of the layer.

Since the layers have a configured size, content can be positioned within the layer and will clip to the bounds of the layer and not draw outside of it. By adjusting the position of a layer, you can move a significant amount of visual content with minimal effort. Layers however, are still containers for other structural objects, groups, and controls.

Controls are the primary user interaction points for most applications. Controls contain an ordered list of render extensions which are the base Storyboard rendering and drawing primitives. Example render extensions include image, text, fills, arcs, and polygons. A control has a size and all of the drawing performed by the render extension happens within the area of the control, which means a control is a clipping region. Similar to layers, controls also have properties such as position and visibility.

Controls are the basic building blocks for assembling a user interface. The same visual effect may be achieved by using a single control with multiple render extensions stacked on top of each other and positioned within the area of the control, or by using multiple controls that together make up the same visual presentation, or a hybrid combination of multiple controls and multiple render extensions. In cases where multiple controls are used to achieve a visual effect, we want to maintain cohesion. For this, it can be useful to put the controls into a group. 

Groups are a collection of controls. Unlike a layer however, a group does not clip its content and the size of the group is determined by the bounds of the controls it contains. A group does have a position and all of the controls within the group will have a position that is relative to the group's position. In this way, groups are similar to layers in that changing the position of a group will translate all of the controls at once or changing the visible/hidden state will cause all of the controls contained to either be shown or hidden.

Groups and controls are both child objects of a layer, but groups can only contain controls. There is currently no grouping of groups, though that may be a future consideration.

Tables are a special form of templated control that is repeated over and over in a grid or list like pattern. Tables and their table cell control templates are treated the same as controls, but use a different representation for dynamic data. This topic is covered in more detail in the chapter Creating Lists and Tables.

The application is the root of this hierarchy. The application maintains the list of all screens, layers, groups, and controls and determines at the start of execution which screen is the first displayed. The start screen setting is a property of the screen model object and can be set within Designer. Every application must have at least one screen and every screen must have at least one layer to be valid. Designer will generally raise an error on export if these conditions aren't met within the application design.

Storyboard is an event-driven user interface state machine. Events are the basic communication mechanism for triggering activity and passing data in a Storyboard application.

Events are named entities and optionally carry an extra binary data payload. Events come in three main flavors:

Events may be received from multiple different input sources, but are always processed serially by the Storyboard Engine.

Events trigger actions. Actions perform tasks, such as manipulate data, interact with the system, log messages, and generate more events. There are many different actions that perform different things. Screen transition actions perform visual screen transitions. Data change and animation actions modify data within the UI that can cause a visual change. Timer actions trigger new events in either a repetitive or one-shot manner. Lua script actions invoke a callback function scripted in Lua (Lua is a script programming language used for glue logic in Storyboard). In addition to all of the fixed actions, the Storyboard SDK provides users with the ability to write and contribute their own actions to the engine.

The event/action association can be made on any of the model elements. For example, a control with an image render extension that is acting like a push button might have an event/action association that would match a press event and cause a data change action that hides or shows a control or changes the value of a variable.

Where the event/action association is made is important. Associations that are made on controls must be triggered by position-related events, such as press and release, otherwise the control must use focus settings to ensure that non-position based events (such as external events) are delivered to their context. Associations that are made on layer or group model objects are more generic, but in order to be triggered the event must first be potentially triggered against a control in that context. Screen actions will always be matched as long as the screen is the current visible screen. Application event/action bindings are the most general and will match in all contexts and are generally the most suitable when matching external events and processing model data.

The event-driven model that Storyboard uses for user interaction has significant benefits that may not be immediately apparent. The first is that the events form a discrete and defined interface point between the UI and the rest of the product. By isolating the external events:

The event model also ensures a complete decoupling of the UI from the implementation and is what makes desktop simulation a practical reality. Simulated data can be easily injected in environments where the real target hardware may not be ready, prohibitively expensive, or just plain awkward to work with. Building the UI in a comfortable environment and knowing that it will move readily to the embedded target at the time of deployment with small adjustments is an invaluable boost to overall productivity.

Events to external applications

Communication with external processes in the embedded system can be accomplished in several ways. One approach that provides a strong API while maintaining a loose coupling for the implementation is to use Storyboard IO.

Storyboard IO is provided as a plugin for the Storyboard Engine and includes a C API and library for external applications to link against.

When the Storyboard IO plug-in is loaded a channel is created in order for processes to inject events into the system. A single event queue is used to serialize the events and therefore any events sent via Storyboard IO will be placed in the queue with standard Storyboard system events. If the external application wishes to receive events, it can create its own Storyboard IO channel which can have events sent through. Applications can have multiple receive channels and the Engine has a single input channel. The following diagram illustrates an application which can send events to the Engine and review events on a named channel.

Sending and Receiving Data with Storyboard IO discusses how to work with Storyboard IO to send and receive events.

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.

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.

Application
 + MainScreen
   + ALayer
     + AGroup
       + AControl

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 contro

Animations can have an enormous impact on the application's user experience and are an important part of any modern user interface. Used well, they can make a relatively dull user interface appear modern and intriguing. Used poorly, they can waste a user's time and ruin what might have been a highly useful application.

An animation in Storyboard manipulates variables exposed by the application model. These variables may be the user-defined variables or they may be the internal variables associated with model element properties. When the variables are numeric there are a variety of easing functions that can be applied to transition from one value to another. Many variable changes can be orchestrated to occur at points relative to one another and edited on a timeline within the design environment and ultimately saved into a named animation block that accompanies the exported model.

A specific animation can be created that relies on the fully qualified paths to specific variables or a generic animation can be created that relies on variables that use the context relative naming convention. In both situations, the definition of an animation is independent from its use.

In order to use or trigger an animation, the definition has to be referenced by an action, which in turn is associated with an event. The Animation Action is specifically intended for the purpose of launching user-defined animations designed in Storyboard Designer.

When the visual content of an application is dynamically created, it may not be practical to create animations within Designer in advance. In these situations it is possible to create rich animations programmatically using the Lua Script Action.