Custom Storyboard Hooks

Custom Storyboard Hooks allow you to use your own button types in storyboards. They will show up in the canvas preview area as hookable elements, just as native UI Buttons do.

See also: Creating a Custom Storyboard Hook For UI.Toggle

Overview

A storyboard hook is a component that is attached to game objects in your canvas controller's scene. Any game object in the canvas controller's scene with a StoryboardHook component will become hookable in a storyboard.

You do not use the StoryboardHook component directly, however. Instead, a subclass is created that adds support for a single target component type - the component that you wish to make hookable. It is this StoryboardHook subclass that is then added to any game objects with the target component type. Additionally, the process of adding StoryboardHook subclasses to their relevant game objects can be performed automatically for you by Canvas Flow, each time a canvas controller's scene is saved.

For example, Canvas Flow includes one such StoryboardHook subclass - StoryboardHookUnityEngineUIButton - which is a storyboard hook for native UI Button components. It can be (and is automatically) added to any game object with a UI.Button component in order to make it hookable in a storyboard.

In order to make your own buttons hookable in a storyboard, you must create a similar StoryboardHook subclass for your custom button type, as documented below.

Canvas Flow's default storyboard hook for native UI Button components is included as a .cs file. This means you can easily inspect the source code, which is recommended when creating your first custom storyboard hook. It can be found in the Project inspector at Canvas Flow/Storyboard Hooks/StoryboardHookUnityEngineUIButton.cs.

1. Create A New Storyboard Hook Subclass

To begin creating a new storyboard hook, open Unity's Create menu - by either right-clicking in the Project window or selecting Assets in the menu bar - and selecting Create/Canvas Flow/Storyboard Hook. Enter a name and a directory for your new hook. This will generate a new StoryboardHook subclass at the specified location.

The generated script contains three methods for you to implement.

2. Implement The Connect Method

When a canvas controller is loaded from a storyboard at runtime, its connected hooks will be provided with a callback via the Connect() method. Your hook's responsibility is to simply invoke this callback when it deems itself to have been triggered. Invoking the provided callback is all that is required to trigger a storyboard transition.

So, in the case of the StoryboardHookUnityEngineUIButton, the callback passed to the Connect() method is attached to the button's onClick handler. This means that when the button is clicked, the callback will be invoked, triggering the storyboard transition.

The source code for the StoryboardHookUnityEngineUIButton's Connect() method is therefore:

public override void Connect(System.Action<StoryboardHook> invokeTransition)
{
    // For a Unity UI Button we invoke our storyboard transition when
    // our Button is clicked.
    button.onClick.AddListener(() => {
        invokeTransition(this);
    });
}

You may wish to do some additional logic here. For example, if we were making a hook to be used with a UI Toggle switch, we might only wish to trigger the transition when the toggle is switched on, like so:

public override void Connect(System.Action<StoryboardHook> invokeTransition)
{
    toggle.onValueChanged.AddListener(() =>
    {
        // Only invoke the transition if the toggle is switched on.
        if (toggle.isOn)
        {
            invokeTransition(this);
        }
    });
}

Note: You can pass your hook to the callback with this, as above. This causes it to be included in the subsequent StoryboardTransition object that is created and passed to methods such as PrepareForStoryboardTransition.

3. Implement The Reset Method

The Reset() method is called on your hook in the Unity Editor when the component is added to a game object or the user resets it in the inspector. A hook can be automatically added to a game object when the scene is saved or manually added in the inspector. In either case, the Reset() method is where you must do any configuration you require.

In the case of the StoryboardHookUnityEngineUIButton, the Reset() method obtains the required reference to the Button component that is used in the Connect() method above, like so:

protected override void Reset()
{
    // Always call base.Reset() when overriding Reset() in a custom hook.
    base.Reset();

    // Store a reference to the Button component.
    button = GetComponent<UnityEngine.UI.Button>();
}

You might wish to follow a similar pattern, storing a reference to your custom button type that can later be used in the Connect() method.

4. Implement The Auto-Add Component Type Property (Optional)

When a canvas controller scene is saved in the Editor, Canvas Flow will ensure that storyboard hooks are present on any game objects with the hook's 'auto-add' component type. Here you can return the target type of your hook, such as your custom button type, to have your hook automatically added to any game objects with the target component type.

For example, Canvas Flow's default storyboard hook for native UI Button components returns the UI.Button component here, causing it to automatically be added to any game objects with a UI.Button component.

public override System.Type AutoAddComponentType
{
    get
    {
        // Automatically add this hook to game objects with a Unity UI
        // Button component when the scene is saved.
        return typeof(UnityEngine.UI.Button);
    }
}

Note: This is an optional step. You may return null here if you do not want your custom storyboard hook to automatically be added to the target component type when the scene is saved. Additionally, you can turn off auto-add for all storyboard hooks in Canvas Flow's preferences, found in the menu bar at Unity/Preferences/Canvas Flow.