Creating New Behaviors (Advanced)

Introduction

Standard Forms behaviors (ButtonBehavior, TextBoxBehavior, and so on) already ship with every project that uses Forms controls - see Behaviors. Creating or editing a behavior yourself is a rare, advanced scenario, needed only when you're standardizing categories/states/instances for your own components that are not part of Gum Forms.

This document walks through creating a behavior from scratch, using a ButtonBehavior-style definition as a familiar illustration. You would not actually recreate ButtonBehavior in a real project — it already exists - but the same steps apply to any custom behavior you define for your own components.

Creating a Behavior

To add a behavior:

1. Right-click on the Behaviors folder
2. Select Add Behavior:

   

   Add Behavior menu item
3. Enter the new behavior name. Often time the word Behavior is added at the end of the name, such as ButtonBehavior

New behaviors appear in the Project tab.

ButtonBehavior in the Behaviors folder

Once a behavior is created, it can be given categories, states, and instances. Components which use this behavior are required to have matching categories and states.

The process of adding and removing states to behaviors is the same as adding and removing states in other elements. For more information, see the States page.

For example, the ButtonBehavior may have the following:

• ButtonCategory (Category)

  • Enabled (State)
  • Disabled (State)
  • Focused (State)
  • Pushed (State)

ButtonCategory defined on ButtonBehavior

A behavior can have as many categories and states as needed.

Once a behavior is added, it can be used in a component. To add a behavior to a component, drag+drop the behavior onto the component in the tree view.

Add a behavior to a component by drag+dropping the behavior on the component in the Project tab

Behaviors can also be added and removed on the component's Behaviors tab:

1. Select a component which should use the behavior
2. Click the Behaviors tab
3. Click the Edit button
4. Check the desired behaviors - a component may use multiple behaviors
5. Click OK

Button component adding the ButtonBehavior

Notice that once a behavior is added to a component, the component automatically creates the matching categories and states.

If the behavior is selected in the Behaviors tab, the required states and categories are highlighted in the States tab.

States and Categories required by the selected behavior are highlighted

These categories cannot be removed as long as the component uses the behavior.

Category and State Requirements

As mentioned above, if a component uses a behavior, then the component is required to include all of the states and categories defined by the behavior. If a behavior is added to a component, then all states and categories in the behavior are automatically added to the component. Keep in mind that newly-added states do not automatically assign any values. The behavior only requires that the states exist but it does not decide which variables are assigned by the states. These required states can even be left to their default so they have no affect on the component.

Required states and categories cannot be removed or renamed. Required states cannot be moved to different categories.

Renaming and deleting states and categories required by behaviors is not allowed

If a new category or state is added to a behavior, all components which use the behavior also have the new category or state added.

Adding states and categories in a component adds the states and categories to all components using the behavior

If a state or category is removed from a behavior, Gum does not remove the state or category from components which implement the behavior. Behaviors only define what is required, but they do not prevent components from defining additional states and categories. Also, the states on components may still be needed even if the behavior is removed. Therefore, if you remove any states or categories from a behavior, you may need to manually remove the same states and categories from components which use the behavior if these are no longer needed.

Instance Requirements

Behaviors can include instances, resulting in required instances existing in components which use the behavior. Instances in behaviors only include two properties:

• Name
• Base Type

Instances in behaviors only require that instances in components have these two matching properties. All other properties can be set to any value.

To add an instance to a behavior, drag+drop a standard element or component onto the behavior in the Project tab.

Drag+drop standard elements or components onto behaviors to create instances in the behavior

An instance can have its Name changed, Base Type changed, or removed.

The Variables tab lets you change Name and Base Type. Right-click to delete an instance.

If a component is missing a behavior then the Error window provides information about the missing requirement.

Button component is missing a SpriteInstance which is required by the ButtonBehavior

At this time Gum does not automatically add required instances to components which need them. This may change in future versions of Gum. For now, instances must be manually added to resolve errors.

Behavior Properties on Custom Behaviors

The standard Forms behaviors ship with Behavior Properties (see Behavior Properties) that surface a Behavior category in the Variables tab and drive design-time preview. A custom behavior can declare these too, but there is currently no tool UI for it - they are added by hand-editing the behavior's .behx file. This is an advanced, rarely-needed scenario; the standard Forms behaviors already cover the common cases.