Reusable Graphical Components

February 22, 2021 16:36

Storyboard Designer allows developers to create re-usable design components that can be shared among multiple projects. Components combine model elements, such as groups and controls, together with graphical assets such as fonts and images plus interaction rules such as events and animations. The ease with which these re-usable elements can be created based on custom graphical design elements makes them significantly different than traditional widgets that offer a fixed behavior and are difficult to create.

A component is created by selecting a Storyboard Designer group or control model element in the Storyboard editor or the Application View and right clicking and selecting Create New Component. A dialog will prompt for a component name, description, and additional animations and resources to include in the component. Components are saved by default in the project's templates and use the file extension sbc which stands for Storyboard Component.

Components located in the templates directory are automatically loaded into the Components View. To use a component simply drag the component into the Storyboard Editor into a visual design context. The first time that a component is used, all of the resources associated with the component (images, fonts, scripts and animations) will be extracted into the local project. Subsequent uses of the component will not overwrite the initial resources. If there is a name conflict with resources that are already in the project, then the default behavior is to use the existing project resources and not to overwrite the project resource with the template resource.

When a component is used within an application, a link is established between the component definition and each instance where that component is used within the application. This association allows components to be changed and for those changes to be applied as updates to any existing instance of the component.

Creation Guidelines and Conventions

Components provide a lot of freedom to users with regards to packaging re-usable content. However, there are some guidelines that if followed will reduce the potential for confusion when your component is applied to a number of projects.

Favor Groups over Controls

While it is possible to create components from a single control, this is generally only useful for the simplest of components. In order to manage interactive state, provide feedback and handle input it is better to use a group to provide a consistent namespace for controls and variables.

Use a Consistent Name Prefix

Components are intended to be created in the context of one project and then shared and used in other projects. However, since a component packages all of its images, fonts, scripts and animations with it, there is always the potential for name conflicts to occur. To minimize the change of conflict it is suggested that you name all of resources with a prefix that links them to component. For example Crank provided components use following naming convention:

A prefix name is established using a prefix of SBC followed by the name of the component. For example SBCPushButton
All image resources use the prefix name (e.g., SBCPushButtonBevel.png)
All animation definitions use the prefix name (e.g., SBCPushButtonFadeOut)
All Lua script files use the prefix name (e.g., SBCPushButton.lua)

Keep Lua Scripts Isolated

In order to avoid any conflict within the Lua namespace it is important to not only identify the Lua script file(s) used by the component but also to ensure that all of the Lua functions and variables used by the component do not conflict with anything else in the application. This means ensuring only a minimal set of callback functions are exposed and that the local keyword is rigorously applied.

Provide Change Notification via callback Variable

In many component situations is it desirable to remove the user from the mechanics of what a component is doing within the UI and to simply provide status information as a final result. For example a check-box button might have a selected/unselected state or a slider might have a percentage result that they indicate. In these cases it is a convention to use a variable associated with the group named callback that is typed as a Lua function variable. This allows the user to set different callback functions for different instances of the component but use the same controlling logic.

Editing Components and Propagating Changes

There are two ways to change and update a component after it has been created.

The first way is to simply use the component in an application, make the modifications that you want and then save the component back as a new component, potentially overwriting the previous file. This is the same process used to create the initial component, the only difference being that you started the process by using a component to seed the initial functionality and behavior. This technique is most applicable when you want to introduce significant structural change to a component, for example adding or removing controls, render extensions or actions. In these situations, the component you are creating is not really related any longer to any instances that the user may have created and would be difficult to synchronize while guaranteeing compatible behavior.

The second approach for updating a component is most suitable when you want to make cosmetic changes to the component and have those changes be applicable to any of the current instances of the component in the application. In this case you can edit the component file directly from the templates directory launching a Component Editor. When you do this, the component will automatically be opened and applied to a sandboxed Storyboard project containing a single screen and single layer. From within this sandboxed project, you can change anything you like about the component. This includes existing properties such as color, images or variable values. It also includes changing the structure of the component entirely, by adding or removing controls, render extensions or actions. When the component is edited in this fashion, it will save a history of what properties have been changed along with a new internal revision number.

When components are changed using the Component Editor technique the changes that are recorded within the template can be applied to components that have been used in the current application. From the Component View select the component to update and right-click and select the Update Instances option. This selection will scan the application for any uses of the component that are not already synchronized with the latest changes in the template and offer to synchronize the changes for you.

Component instances can also be resized very easily using the component resize tool. This can do a comprehensive resize on all the controls, render extensions, actions, variables and animations associated with a component (similar to the application resize tool). Statically referenced animations associated with the component will be duplicated and automatically bound to the new instance so that existing clients of those animations are unaffected.

There are two ways to trigger a component resize. You can right-click on a component instance in the Application Model and select 'Resize' -> 'Resize Component Instance' to take you to a dialog that will simply ask for a new width and height. You can also interact with a component instance in the editor and drag on it using the control points in order to resize it. Component instances are outlined in red when selected in the editor, to indicate that this is the action being taken. However, you can hold down the 'Shift' key while dragging to use the original group/control resize operation instead. Keep in mind that the resize operation is done on a component instance, not on the component definition. As such it is not easily transferable to other component instances that share the same source.