Chapter 20. Reusable Graphical Components

Table of Contents

Creation Guidelines and Conventions
Editing Components and Propagating Changes

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.