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 or the and right clicking and selecting . 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 . To use a component
simply drag the component into the 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.
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.
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.
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)
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.
callback VariableIn 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.