States are a powerful way to create expressive groups of variables. Some UI elements may require a combination of states to be applied simultaneously.
For example, consider creating a CheckBox element. This CheckBox may have one set of states for whether it is checked:
Checked
Unchecked
But it may also need a second set of states for being enabled and disabled (which may modify the color of the Text and graphics for the check box:
Enabled
Disabled
In this case multiple states need to coexist and may be combined. Categories allow you to organize states so that multiple states can be set simultaneously.
For this tutorial we'll create a new component. This component will have state categories for size and for color. To do this:
Open Gum
Create a new Component called "CategoryDemo"
Right-click anywhere in the State box and select "Add Category"
Enter the name "Size" for the new category and click OK
Repeat the above steps to create a "Color" category
Now we can add states to the categories. To do this:
Right-click on the "Size" category and select "Add State"
Enter the name "Small" for the new state
Right-click on the "Size" category again and select "Add State"
Add a second state to "Big"
Right-click on the "Color" category and select "Add State
Add a state called "Red"
Right-click on the "Color" category again and select "Add State
Add a state called "Blue"
Now that we have states set up we need to add a visual element to the component so that we can see our changes.
To do this, drag+drop a ColoredRectangle into your component
To modify a state, you can select it and edit in the preview window or change properties in the Variables tab to modify what the state sets. Notice that normally for a component like this the ColoredRectangleInstance would have its width and height be relative to its container, but we're not doing this for the sake of keeping the tutorial shorter.
First we'll set the Size states. To do this:
Select the "Big" state
Resize the colored rectangle so it is larger than the default
Select the "Small" state
Resize the colored rectangle so it is smaller than the default
Next we'll set the Color states. To do this:
Select the "Red" state
Set the Red, Green, Blue values to: 255, 0, 0
Select the "Blue" state
Set the Red, Green, Blue values to: 0, 0, 255
Now that we have our CategoryDemo component set up with multiple categories, we can view these states on any CategoryDemo instance. To do this:
Create a Screen called CategoryDemoScreen
Drop an instance of the CategoryDemo component into the CategoryDemoScreen
Select the newly-created CategoryDemoInstance
Scroll down in the Variables list and notice that the instance has drop-downs for each category.
You can set each state independently and the states will combine
If a variable is modified in one of the states in a category, then all of the states in that category are automatically assigned the default value, and this value is explicitly set. This concept makes working with states far more predictable.
For example, we can consider a component which has:
A single ColoredRectangle
A category called RectangleSizeCategory
States called Big, Medium, and Small
Initially, all states in a category do not explicitly assign any variables. We can see this by selecting the category and observing the Variables tab.
If a variable is changed in one of the states in the category, then that variable propagates to all other states, and the Category lists this as one of the variables that it modifies.
For example, we can select the Big category and change the ColoredRectangle.Width property to 150.
Once this value is changed, the RectangleSizeCategory lists this as a variable that it modifies in the Variables tab.
If we select any of the other states in the category, they show that they explicitly set the Width value as well (the value has a white background instead of light green). The value is inherited from the default state.
Once a variable is set in a category, all states are required to set this value. A variable cannot be removed from a single state in a category. Rather, to remove a variable, all states in the category must remove the variable. This can be done by selecting the category and pressing the X button next to the variable name.
