Customizing Forms

This tutorial series represents the old way to add a .gumx project to your MonoGame project. This tutorial was retired in April 2025, replaced by the new Gum Project Forms Tutorial.

This tutorial is still syntactically valid but it is not recommended as of the April 2025 release:

https://github.com/vchelaru/Gum/releases/tag/Release_April_27_2025

Introduction

Gum Forms controls provide standardized functionality which can be fully customized. Forms controls place very few restrictions on their appearance and behavior. Even though a typical Button has a Text and NineSlice, it could be made of anything (really).

This tutorial shows how to customize Forms controls

This tutorial continues from previous tutorials, but initially it deletes all instances from the TitleScreen except a single ButtonStandard instance.

A single ButtonStandardInstance in TitleScreen

This tutorial modifies the default Gum Forms components. You may want to make a copy of your current project or use version control such as Git to undo your changes in case in case you want to start over.

Customizing ButtonStandardInstance in Gum

The simplest form of customization is to modify the instance directly in Gum. Since the ButtonStandardInstance is a regular Gum object, any of its properties can be modified as expected. For example we can modify its X, Y, Width, Height, and Button Display Text properties in Gum and these changes show up in game.

Button with its instance properties changed

While we technically have modified variables on the ButtonStandardInstance, this is usually not what we mean by customizing.

Customizing Properties on ButtonStandard

We can make modifications to ButtonStandard directly in Gum. We can select the ButtonStandard in Gum to see its individual components.

ButtonStandard with its contained instances

Notice that by default the Default state is selected.

Default state is selected

If we make modifications to the ButtonStandard, every instance reflects these changes. For example, we can select TextInstance and set the following values:

• Font = Impact
• Font Size = 18
• Is Bold = false (unchecked)

Customized ButtonStandard

Now our instance in TitleScreen also reflects these changes, both in Gum and also in our game

ButtonStandardInstance with modified values

Changing ButtonStandard States

If we try to change the background color on our Button, it doesn't apply in our game. For example, we can change the Background's color value in Gum. the ButtonStandard background changes in Gum:

Background color updates in Gum

However, if we run the game, the color reverts back to the default teal color. This happens because the button has multiple colors, not just one. Which color is displayed depends on whether the button is enabled, disabled, hovered, or pressed. We can see some of these states by running the game, moving the mouse over the button, and clicking on it.

Button showing its enabled, highlighted, and pressed states

These colors are all controlled by the ButtonStandard's states inside of its ButtonCategory. We can expand the category and click on each of the states to preview them in the Editor tab.

ButtonStandard states

Since one of the states is always active, the maroon color we set in the default state is overridden immediately by the Enabled state when the app runs.

Note that only the color value was overridden by the ButtonCategory states - the changes we made to Font and Font Size showed up in game. We can see which variables are modified by the ButtonCategory states by selecting ButtonCategory.

Variables set by ButtonCategory

Any change we make to the ButtonStandard component can be either done in the Default state if it is not associated with a particular state, or it can be made in the specific ButtonCategory state.

We can modify the variables that are already set in the states, or we can remove the variables completely. For simplicity we will clear the states and start from scratch. To do this, select the ButtonCategory, then press the X button next to each variable to clear it from all states in that category.

Remove all variables from the ButtonCategory to create new states

Now we can select each of the states and modify the background color as desired. Feel free to experiment as you create states. Keep in mind you can modify anything on the ButtonStandard including TextInstance and Background. If you want to revert variable changes, select the ButtonCategory and press the X button to remove the variable assignments on all states.

As before, Gum lets us preview the states by selecting them.

Changed states

Once these states have been changed, we can run the game and see the states in game.

Customized ButtonStandard

For more information on states and categories, see the States and State Categories tutorials.

Modifying Other Forms Components

All Forms components can be customized in Gum. As with the ButtonStandard component, the first thing to check is whether a component has states. For example, to modify TextBox, first check which variables are modified in TextBoxCategory.

Variables in TextBoxCategory

After determining which variables are controlled by the TextBoxCategory, make the changes to the TextBox either in the default state (if the variable is not set in TextBoxCategory), or select the desired state in TextBoxCategory (if the variable is in TextBoxCategory).