Introduction

FrameworkElement is the base class for all Gum Forms controls. It provides much of the common functionality across all controls.

Introduction

The static ModalRoot and PopupRoot properties provide an InteractiveGue which serve as the root for any element which should appear on top of other elements. These properties have the following characteristics:

• Automatically created by FormsUtilities.InitializeDefaults

• Automatically resized to fit the entire screen, including if the GraphicalUiElement.CanvasHeight and GraphicalUiElement.CanvasWidth change.

• Both Remains on top of all other elements for its given layer. ModalRoot appears on top of PopupRoot.

These properties can be used in custom code to place elements (such as custom popup and toast elements) above all other elements.

Modal Popups

Popups which are placed on the ModalRoot element are considered modal - they block the input of all other controls. This is useful if you would like to create a popup which must be clicked before any other elements receive input. If multiple elements are added to ModalRoot, only the last item (and its children) receive input events. This allows one popup to show another popup.

By contrast, elements added to the PopupRoot are not modal - other elements can receive input.

Example - Adding a Popup

The following code can be used to display a popup to either ModalRoot or PopupRoot depending on the isModal value.

Introduction

The IsFocused property gets or sets whether a component has focus. For example a TextBox will have its IsFocused set to true if the caret is visible and if it is taking input from the keyboard.

Code Example - Setting IsFocused

IsFocused can be directly assigned to give focus to an object. For example the following code gives a TextBoxInstance focus:

TextBoxInstance.IsFocused = true;

If you are setting focus on a TextBox in response to a click event, you may need to also clear the Cursor's input. For example, the following would set focus on TextBoxInstance when ButtonInstance is clicked:

ButtonInstance.Click += (_,_) =>
{
    TextBoxInstance.IsFocused = true;
    // Remove the clear so that the TextBoxInstance doesn't immediately lose focus
    // on the same frame it got focus due to the cursor having been clicked
    FormsUtilities.Cursor.ClearInputValues();
};

Introduction

IsEnabled controls whether the framework element responds to input from the user. Many controls reflect whether they are enabled visually, so a disabled element (such as a Button) appears differently than an enabled button.

Introduction

The ListBox control provides a scrollable list of ListBoxItems for displaying and selecting from a list.

Code Example: Adding a ListBox

The following code adds items to a ListBox when a button is clicked. When an item is added, ScrollIntoView is called so the item is shown.

var listBox = new ListBox();
this.Root.Children.Add(listBox.Visual);
listBox.X = 50;
listBox.Y = 50;
listBox.Width = 400;
listBox.Height = 200;

var button = new Button();
this.Root.Children.Add(button.Visual);
button.X = 50;
button.Y = 270;
button.Width = 200;
button.Height = 40;
button.Text = "Add to ListBox";
button.Click += (s, e) =>
{
    var newItem = $"Item @ {DateTime.Now}";
    listBox.Items.Add(newItem);
    listBox.ScrollIntoView(newItem);
};

Selection

ListBox items can be selected. The ListBox class provides a number of ways to work with the selection.

Selection can be set by index:

listBox.SelectedIndex = 0;

Item can also be selected by the reference itself, assuming the referenced item is part of the list box:

listBox.SelectedObject = "English";

Whenever the selection changes, the SelectionChanged event is raised:

listBox.SelectionChanged += (sender, args) =>
{
    System.Diagnostics.Debug.WriteLine($"Selected item: {listBox.SelectedObject}");
};

Customizing with VisualTemplate

The VisualTemplate lets you customize the type of ListBoxItem created for the ListBox. The following code shows how to assign a VisualTemplate to a runtime object named CustomListBoxItemRuntime:

// assign the template before adding new list items
listBox.VisualTemplate = 
    new MonoGameGum.Forms.VisualTemplate(() => 
        // do not create a forms object because this template will be
        // automatically added to a ListBoxItem by the ListBox:
        new CustomListBoxItemRuntime(tryCreateFormsObject:false));

The VisualTemplate class can optionally pass a parameter representing the item in the list box. This can be used to create different types of items based on the object added. For example the following code would compare the passed object as an integer to whether it is greater than 100 and returns a different item depending on this result:

// assign the template before adding new list items
listBox.VisualTemplate = 
    new MonoGameGum.Forms.VisualTemplate((item) => 
    {
        // Be sure you know the type before casting:
        var itemAsInt = (int)item;
        if(itemAsInt > 100)
        {
            return new CustomListBoxItemHighValue(tryCreateFormsObject:false);
        }
        else
        {
            return new CustomListBoxItemLowValue(tryCreateFormsObject:false);
        }
        
    }

Customizing Displayed Property with ListBoxItemFormsType

By default the ListBox calls ToString on each item. This is usually okay if you are dealing with primitive types. For example, the following code adds sequential integers to a ListBox:

for (int i = 0; i < 20; i++)
{
    listBox.Items.Add(i);
}

Often you may want to add a list of items which should not use their ToString method. For example you may have a list of IDs which represent weapons in a dictionary. The display can be customized by inheriting from ListBoxItem as shown in the following code:

listBox.ListBoxItemFormsType = typeof(WeaponDisplayingListBoxItem);

foreach(var weapon in weapons)
{
    listBox.Items.Add(weapon.Id);
}

// define WeaponDisplayingListBoxItem
class WeaponDisplayingListBoxItem : ListBoxItem
{
    public WeaponDisplayingListBoxItem(InteractiveGue gue) : base(gue) { }
    public override void UpdateToObject(object o)
    {
        var idAsInt = (int)o;
        // assuming this has access to Weapons:
        var weapon = Weapons[idAsInt];
        coreText.RawText = weapon.Name;
    }
}

Introduction

Gum Forms is a set of classes which provide fully-functional forms controls which you can use in your game. Examples of forms controls include:

• Button

• Checkbox

• ListBox

• TextBox

• Slider

Gum Forms can be used purely in code (no .gumx project required), or you can fully style your forms objects in a Gum project.

Quick Setup - Forms in code

The easiest way to add Forms to your project is to use the FormsUtilities class. Keep in mind that Forms is not a replacement for Gum; rather, it adds objects on top of Gum which provide common UI interaction. In other words, if you are using Forms, you are still using Gum as well. Therefore, when using Forms you must also initialize Gum.

The following code snippet shows how to initialize Forms and Gum, and how to add a single Button to your project:

public class Game1 : Game
{
    private GraphicsDeviceManager _graphics;

    // Gum renders and updates using a hierarchy. At least
    // one object must have its AddToManagers method called.
    // If not loading from-file, then the easiest way to do this
    // is to create a ContainerRuntime and add it to the managers.
    ContainerRuntime Root;

    public Game1()
    {
        _graphics = new GraphicsDeviceManager(this);
        Content.RootDirectory = "Content";
        IsMouseVisible = true;
    }

    protected override void Initialize()
    {
        SystemManagers.Default = new SystemManagers(); 
        SystemManagers.Default.Initialize(_graphics.GraphicsDevice, fullInstantiation: true);
        FormsUtilities.InitializeDefaults();
        // If you plan on loading Forms controls from Gum:
        FormsUtilities.RegisterFromFileFormRuntimeDefaults();

        Root = new ContainerRuntime();
        Root.Width = 0;
        Root.Height = 0;
        Root.WidthUnits = Gum.DataTypes.DimensionUnitType.RelativeToContainer;
        Root.HeightUnits = Gum.DataTypes.DimensionUnitType.RelativeToContainer;
        Root.AddToManagers();


        var button = new Button();
        Root.Children.Add(button.Visual);
        button.X = 50;
        button.Y = 50;
        button.Width = 100;
        button.Height = 50;
        button.Text = "Hello MonoGame!";
        int clickCount = 0;
        button.Click += (_, _) =>
        {
            clickCount++;
            button.Text = $"Clicked {clickCount} times";
        };
        base.Initialize();
    }

    protected override void Update(GameTime gameTime)
    {
        if(IsActive)
        {
            FormsUtilities.Update(this, gameTime, Root);
        }
        
        SystemManagers.Default.Activity(gameTime.TotalGameTime.TotalSeconds);
        base.Update(gameTime);
    }

    protected override void Draw(GameTime gameTime)
    {
        GraphicsDevice.Clear(Color.CornflowerBlue);
        SystemManagers.Default.Draw();
        base.Draw(gameTime);
    }
}

The code above produces a single button which can be clicked to increment the click count.

Quick Setup - Forms in the Gum Tool

Forms can be used with the Gum tool, allowing you to create fully functional UI layouts visually.

To use Forms in a project that loads a Gum project (.gumx) the following steps are needed:

1. Components must be added to the Gum project which have the necessary behaviors to be used as Forms visuals

2. The Gum project must be loaded in code, just like any other Gum project

Adding Forms Components to the Gum Project

To add components which are used for Forms visuals:

1. Open your project in Gum, or create a new project

   1. If creating a new project, save the project in a subfolder of your game's Content folder

2. Select Content -> Add Forms Components
3. Check the option to include DemoScreenGum, or alternatively add a new screen to your project and drag+drop the desired components into your screen

Once you have saved your project, modify your Gum file to include the project:

1. Open your .csproj in a text editor (or click on it in Visual Studio)

2. Add the wildcard addition code to copy all of your Gum projects

  <ItemGroup>
    <None Update="Content\GumProject\**\*.*">
      <CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
    </None>
  </ItemGroup>

Your project is now referenced in your game. Modify the Game file to initialize the Gum systems and to load the .gumx project. Your code might look like this:

public class Game1 : Game
{
    private GraphicsDeviceManager _graphics;

    // Gum renders and updates using a hierarchy. At least
    // one object must have its AddToManagers method called.
    // If not loading from-file, then the easiest way to do this
    // is to create a ContainerRuntime and add it to the managers.
    GraphicalUiElement Root;

    public Game1()
    {
        _graphics = new GraphicsDeviceManager(this);
        Content.RootDirectory = "Content";
        IsMouseVisible = true;
    }

    protected override void Initialize()
    {
        SystemManagers.Default = new SystemManagers();
        SystemManagers.Default.Initialize(_graphics.GraphicsDevice, fullInstantiation: true);
        FormsUtilities.InitializeDefaults();

        var gumProject = GumProjectSave.Load("GumProject/GumProject.gumx");
        ObjectFinder.Self.GumProjectSave = gumProject;
        gumProject.Initialize();
        FormsUtilities.RegisterFromFileFormRuntimeDefaults();

        FileManager.RelativeDirectory = "Content/GumProject/";

        // This assumes that your project has at least 1 screen
        Root = gumProject.Screens.First().ToGraphicalUiElement(
            SystemManagers.Default, addToManagers: true);

        base.Initialize();
    }

    protected override void Update(GameTime gameTime)
    {
        if (IsActive)
        {
            FormsUtilities.Update(this, gameTime, Root);
        }

        SystemManagers.Default.Activity(gameTime.TotalGameTime.TotalSeconds);
        FormsUtilities.Update(this, gameTime, Root);
        base.Update(gameTime);
    }

    protected override void Draw(GameTime gameTime)
    {
        GraphicsDevice.Clear(Color.CornflowerBlue);
        SystemManagers.Default.Draw();
        base.Draw(gameTime);
    }
}

Introduction

The Button control providing an event for handling clicks.

Code Example: Adding a Button

The following code adds a button which increments every time it is clicked:

var button = new Button();
Root.Children.Add(button.Visual);
button.X = 0;
button.Y = 0;
button.Width = 100;
button.Height = 50;
button.Text = "Hello MonoGame!";
int clickCount = 0;
button.Click += (_, _) =>
{
    clickCount++;
    button.Text = $"Clicked {clickCount} times";
};

Introduction

The CheckBox control provides the ability to display a true/false state and allows the user to toggle the state through clicking.

Code Example: Adding a CheckBox

var checkBox = new CheckBox();
Root.Children.Add(checkBox.Visual);
checkBox.X = 50;
checkBox.Y = 50;
checkBox.Text = "Checkbox";
checkBox.Checked += (_,_) => Debug.WriteLine($"IsChecked:{checkBox.IsChecked}");
checkBox.Unchecked += (_, _) => Debug.WriteLine($"IsChecked:{checkBox.IsChecked}");

Introduction

The ScrollViewer control provides a container which can hold Gum objects (including other Gum Forms objects). The user can scroll the ScrollViewer with the mouse or ScrollBar.

By default the ScrollViewer's InnerPanel expands automatically in response to its children and stacks its children top-to-bottom. Of course, this behavior can be changed since the InnterPanel is a standard GraphicalUiElement.

Code Example: Creating a ScrollViewer

The following code creates a ScrollViewer and adds ColoredRectangleRuntimes to the ScrollViewer.

VerticalScrollBarVisibility

VerticalScrollBarVisibility controls the visibility of the vertical scroll bar, specifically in regards to the number of items in the ScrollViewer. The available values are:

• Auto - the ScrollBar displays only if needed based on the size of the inner panel

• Hidden - the ScrollBar remains invisible even if the contents of the inner panel exceed the size of its container

• Visible - the ScrollBar always displays

The default is Auto which means that the scroll bar only displays if necessary.

The TextBox control allows users to enter a string. It supports highlighting, copy/paste, selection with mouse and keyboard, and CTRL key for performing operations on entire words.

Code Example: Creating a TextBox

The following code creates a TextBox.

Selection

Selection can be performed programmatically or by the user using the cursor.

The SelectionLength property can be used to determine if any text is selected. The following code shows how to output the selected characters:

The SelectionStart and SelectionLength proerties can be modified to change the visual selection. For example, the following selects the first 5 letters:

The entire text can be selected as shown in the following code:

Selection can also be performed by the user. Double-clicking the text box selects all text.

A push+drag with the mouse selects the text between the start and the current location of the drag.

Holding down the shift key and pressing the arrow keys adjusts the selection.

TextWrapping

The TextWrapping property can be used to set whether the TextBox wraps text. By default this value is set to TextWrapping.NoWrap which means the text does not wrap, but instead extends horizontally.

If TextWrapping is set to `TextWrapping.Wrap, then text wraps to multiple lines. Note that usually this is combined with a taller text box so that multiple lines display properly.

Introduction

The PasswordBox control is a TextBox-like control which can be used for entering passwords. It uses a SecureString rather than regular string and hides the entered characters by using the * key for each character typed. For more information see the SecureString documentation:

Code Example: Adding a PasswordBox

The following code adds a password box.

Introduction

The Slider control provides a way for the user to change a value by dragging the slider thumb.

Code Example: Creating a Slider

The following code creates a Slider which allows the user to select a value between 0 and 30, inclusive. The IsSnapToTickEnabled property results in the value being snapped to the TickFrequency value. In this case, the value is used to force whole numbers.

Introduction

Gum Forms provide fully functional controls with minimal setup. These controls can be restyled in code, either per-instance, or globally per control type. Customization can be performed in-code or in the Gum tool.

Customizing an Instance

Individual instances can be customized by modifying the built-in states which are added automatically by the default implementations.

The following code shows how to modify a Button instance. A default button can be constructed using the following code:

Notice that this button has subtle color changes when the cursor hovers over or pushes on it.

These cursor actions result in different states being applied to the button. These states are initialized by default when calling the following code:

We can customize the state by modifying the values. For example, we can change the color of the background by adding the following code:

Now the button highlights yellow instead of a lighter blue.

Any property on the button or its children can be modified through states. For example, we can also change the text color and size as shown in the following code. You may need to make the button bigger so it can contain the larger text.

The button text now becomes black and is twice as big when highlighted but notice that the text changes are not undone when the cursor moves off of the button (when the Highlighted state is unset).

The reason that the hover state is not unset is because all variables which are set through states persist until they are undone. Typically if you create states in the Gum tool, the Gum tool forces any state which is set in a category to also be propagated through all other states in the same category. However, when we're setting states in code, we must make sure to apply any states that we care to all other categories.

In this case we can fix the larger text by setting the TextInstance's color and FontScale back to its default:

Available Instances

Each default control type is made up of individual instances, most of which are standard types such as ColoredRectangle and TextInstance. The example above assigns properties on two instances:

• ButtonBackground

• TextInstance

Since each control (such as Button, CheckBox, or TextBox) has its own individual instances, we need to know the names and types of these instances to add VariableSaves to our states.

We can find the names of these instances by looking at the source code for the default forms implementations.

These can be found in the Gum repository here:

For example, we can look at the DefaultButtonRuntime.cs file and notice that it has a ButtonBackground and TextInstance:

By inspecting the code of other controls we can see which instances are available for styling. We can also look at the existing states which are provided by the default implementations. For example the DefaultButtonRuntime adds states for Enabled, Highlighted, Pushed, and Disabled. Note that this list may change in the future as Gum Forms continues to be developed.

Keep in mind that the Name property of the internal instances is important. For example using the code above, the background object is accessed through "ButtonBackground" rather than "background" when creating new states.

Replacing Styling Globally with Derived Classes

The example above shows how to replace styling on a single Button instance. Instead of changing each instance manually, we can create a derived class which defines its own custom styling.

The first step is to create a new class which inherits from the default Forms control. These can all be found in the DefaultVisuals page linked above.

For example, we can create a derived class which inherits from the base DefaultButtonRuntime as shown in the following code:

Notice that we must implement a constructor with the same parameters as the base class - this is important because Gum calls this constructor for us when we create a Button instance and the parameter list must match.

Now we can implement our own styling inside the if(fullInstantiation) block. The code to implement styling here is the same as above except this object is the visual, so the category exists on this. For example, we can make the background pink when highlighted and enabled as shown in the following code:

Next we need to tell Gum Forms to use our new button as the default Button type. We can do this by replacing the default type associated with Button as shown in the following code. This code should go in Game1 right after FormsUtilities.InitializeDefaults();, before instantiating any Buttons as shown in the following code:

You may want to also remove or comment out any code for customizing the button explicitly below otherwise your pink styling may get overwritten on the particular instance by the styling written earlier in this tutorial.

By instantiating a Button, Forms automatically uses your new StyledButtonRuntime resulting in the button appearing pink.

Defining a ButtonRuntime Without Inheritance

The section above shows how to customize a button using inheritance. This approach is beneificial if you would like to modify the styling colors on the existing children of the button. Since Gum visuals are regular Gum objects, you can achieve even more customization by creating a new Button class which inherits from InteractiveGue and adding your own controls. In other words, you can add your own instances to the button (such as additional Text instances) or replace existing instances with your own (such as replacing the background ColoredRectangleRuntime with a NineSlice or Sprite).

For example, we can create a NineSlice that uses the following image:

Now we can create a new Button which inherits from InteractiveGue rather than DefaultButtonRuntime to fully customize the appearance of our button. Note that the only requirement that Buttons have is that they contain a Text object named TextIntance, so we should copy this instance from the DefaultButtonRutime code into our own. Our new Button also has a NineSlice which references the button_square_gradient.png from above, and states for Enabled and Pressed.

In general when creating your own Forms control, it can be helpful to reference the existing Default implementation for the control you are creating.

Of course we also need to tell Forms to use our new class as the default button type:

Now we can run our game and see the button in action:

As mentioned above, you are free to add any controls to your custom button including icons, additional Text instances, and additional Sprites for other effects. You can customize your Forms objects to look however you want.

Available States

Most controls in Forms share the same common states. The exception is components which can be toggled on/off such as CheckBox. For all other controls the following states exist:

• Enabled

• Disabled

• Highlighted

• Pushed

• Focused

• HighlightedFocused

• DisabledFocused

CheckBoxes append the words On, Off, and Indeterminate to the states. For example, a CheckBox can support states including:

• EnabledOn

• EnabledOff

• EnabledIndeterminate

• DisabledOn

• DisabledOff

• DisabledIndetermate

• ... and so on.

Defining a Custom Runtime from Gum

Buttons can be defined fully in the Gum tool. This approach allows you to preview your visuals in the editor, and allows editing of the styles without writing any code.

Conceptually the steps are as follows:

1. Define a component for your forms type in the Gum tool

2. Add the states needed for the forms type that you are working with in the proper category

3. Define a custom runtime for the Forms control in your Visual Studio project

4. Associate the custom runtime to the forms type using the DefaultFormsComponents dictionary

This section walks you through how to create a custom Button component, and how to use this in your project. Once you understand how to create a Button component, other Forms controls can be created similarly.

Defining a Button Component in Gum

The first step is to define a Button component in Gum. This component can be named anything you want. For example, you may name it Button or StandardButton. You can also create components for specific purposes such as CloseButton which would be a button that closes menus.

Components defined in Gum can contain almost anything you want; however, Buttons should usually contain a TextInstance so that the Text property can assign the string on an internal Text object.

The following image shows the a component named StandardButton which contains a ColoredRectangle, a Rectangle, and a Text instance. For other controls, see the DefaultVisuals page linked above.

Adding Button States to the Component

All Gum Forms components react to various properties by assigning states. For a full list of states needed, see the DefaultVisuals page linked above.

Defining a Custom Runtime for the Forms Control

Once you have created a Component in your project, you need to create a custom runtime class. This custom runtime class associates the Component in your .gumx file to a strongly-typed class. This runtime type also enables the creation of Forms controls by instantiating the runtime object, including when an element from the Gum project is converted to a GraphicalUiElement.

The runtime class does not need much code since most of the work is done in the Gum project. The following shows an example custom runtime for the StandardButton component:

This runtime can be associated with the StandardButton component in Gum using the following code in your Game class:

Associate the Custom Runtime to the Forms Type

Finally, we can associate the Forms control with the runtime. For example, the following code can be used to create a StandardButtonRuntime whenever the code calls new Button. Note that this is not a requirement for working with Forms, but it can make testing more convenient.

Note that in this case, we can only associate one type of component runtime with each type of Forms control. In other words, if you write code that instantiates a new Button using the Button constructor, a StandardButtonRuntime will be created internally.

Of course, you are not required to create buttons this way - you can also create buttons by adding instances of your component in your Gum screen in the tool, or by instantiating the desired runtime.

Modifying ListBoxItems

ListBoxItems are typically created automatically when items are added to a ListBox instance. We can modify ListBoxItems by creating a runtime object for our ListBoxItem then assigning the ListBox's VisualTemplate.

You may want to rename the class when creating your own version. For example, you may want to name yours CustomListBoxItemRuntime.

Once you have created your custom ListBoxItem runtime implementation, you can use it on a list box by assigning the VisualTemplate. Be sure to assign it before adding items to your ListBox, as shown in the following code:

Introduction

This page discusses common troubleshooting techniques when your Gum Forms objects are not behaving as expected.

Cursor.WindowOver

You can check the WindowOver property to see what the Cursor believes it is over. This can tell you if the Cursor is over the object that you expect it to be over. The following code can be used to output the CursorOver to Visual Studio's output window:

Clicks are Offset

Clicks could be offset if the GraphicalUiElement's CanvasWidth and CanvasHeight are set incorrectly. For more information, see the .

You can also output the Cursor's X and Y values to the screen to compare them to the desired object's bounds, as shown in the following code: