Styling Forms
Introduction
FlatRedBall.Forms is a logical wrapper over standard Gum objects. As such, the Gum objects can be modified in almost any way to fit the styling needs of your game. This document covers the default FlatRedBall.Forms controls and how to make modifications.
Forms Requirements
FlatRedBall.Forms provides flexibility in regards to Forms component structure, but some objects and states are required so that a Forms object can behave properly.
To identify the requirements you can look at the Forms behaviors in the Behaviors folder in your Gum project.
These behaviors are automatically added to your Gum project by the FlatRedBall Editor when you add a Gum project. If you used the FlatRedBall Wizard to create your project, these are also added automatically.
These behaviors indicate the requirements that a Forms control has. For example, ButtonBehavior requires that a ButtonBehavior-implementing Component must have a category called ButtonCategory, and that it must contain states with specific names.
If you create a Component which satisfies these behaviors, then your component can be used as a FlatRedBall.Forms button.
Some behaviors have additional requirements such as required objects. For example, the ComboBoxBehavior requires a category called ComboBoxCategory which contains a number of states, but it also requires two objects - a ListBoxInstance and a TextInstance.
If you modify any existing component which implements these behaviors, make sure you do not remove or change the name of any required categories, states, or instances.
Besides requirements from categories, some FlatRedBall.Forms can use optional instances if they exist. These are not required. For example, the Button component can optionally include an instance called TextInstance. Since this is an optional requirement, the Behavior does not include it as a requirement. However, you can find out more about optional requirements by looking at the API documentation for FlatRedBall.Forms.
In general, you will almost always be safe making the following modifications:
Changing variables such as position, size, or color
Modifying values assigned in states
Adding additional instances to a control, such as adding an icon Sprite to a ListBoxItem
Renaming components
The following modifications may introduce problems depending on if they are made on requirements:
Changing the name of states
Changing the name of instances
Changing the type of instances to incompatible types, such as changing an instance from Text to Sprite
Removing behaviors - you can do this if you would like the component to no longer be associated with FlatRedBall.Forms
Default Forms Components
Projects created through the FlatRedBall Wizard, or which have added Forms when creating a Gum project, should contain a default implementation of FlatRedBall.Forms controls in the Gum project. These can be found in the Components/Controls and Components/Elements folders. Note that as FlatRedBall.Forms is developed, new controls are created, so this list will change over time.
Changing Styles
These forms controls are built to support a common, centralized style. You can make changes at the base level so that your styling changes apply to the entire project, or you can choose to modify individual components one-by-one without changing the global style.
To see how the styling is implemented, we'll look at one of the most common controls: ButtonStandard.
As mentioned earlier, a Gum component must implement a Forms behavior to be considered a Forms object. We can confirm that this is the case by checking the behaviors on ButtonStandard in the Behaviors tab.
This means that the ButtonStandard is required to have a ButtonCategory which contains states for displaying the button depending on whether it is enabled/disabled, highlighted, and pressed.
As mentioned above, we should not delete or rename these states, but we are free to make changes to the states to modify the styling so it matches our game.
Selecting a category in Gum shows the variables that are modified by all states in the category. In this case, the ButtonCategory modifies
Background.ColorCategoryState
FocusedIndicator.Visible
TextInstance.ColorCategoryState
If we want to change the state, we can make additional changes to the state by selecting it and modifying variables. For example, we may want to make the Text larger when the cursor is highlighting the button. To do this:
Select the TextInstance
Select the Highlighted state
Change FontScale from 1 to 1.5
The FontScale variable shoudl display with a white background instead of green to indicate that it is explicitly set on this state.
Note that the FontScale variable is now modified by all states in the category, not just the one that you set. All of the other states explicitly set the variable to the default of 1. You can verify this by clicking on the ButtonCategory.
Since these states are used at runtime automatically, we can run the game and see the font size change when the button is highlighted. Notice that the button text shrinks back to its normal size when the cursor moves off of the button. The text also shrinks when the button is pushed since we didn't modify the Pushed state.
In this case our modification to the button added a new variable that was previously unmodified by ButtonCategory. We can also change existing values. For example, when highlighted our Button's background uses the PrimaryLight ColorCategoryState.
In this case, the ColorCategoryState is defined on NineSlice, which is the base type for Background. Therefore, we should not modify the Red, Green, or Blue values on the Background object because they will be in conflict with the values assigned by this state.
If we would like to modify the Background color in the Highlight (or any other) state, we have a few options:
We can go to the NineSlice standard object and modify the PrimaryLight state. Be careful, making modifications here is concpetually similar to making modifications to a style sheet which is used across an entire project. If you would like to change this value globally, feel free to do so, but realize that making changes to the NineSlice styles can modify many components in your project.
Change the state value that is being used on the background. Although this is not recommended, you can change the background to use a different ColorCategoryState, such as changing the value to Success. This is not recommended because the ColorCategoryState states are named to indicate where they should be used throughout your project, and switching to different ColorCategoryStates may result in confusing the user by using the same color for different behaviors and states.
Add a new state to NineSlice for your specific case. This is useful if you have a case that isn't handled by the existing NineSlice category states.
Removing the usage of ColorCategoryStates from your ButtonCategory. The states in the NineSlice exist to make global styling easier, but they are not a requirement. If you would prefer to implement your own styling method, such as direct RGB values on the background, that's okay. Keep in mind that the Background NineSlice isn't even a requirement! You can remove it and replace it with something else like a Sprite if that works better for your game.
As mentioned above, using Gum to style your FlatRedBall.Forms controls provides a lot of flexibility. The existing structure exists to make changes easier to implement, but you are free to experiment and find your own preferred styling.
Last updated
