Introduction

This series of tutorials covers how to work with Gum Forms in code. This tutorial does not use the Gum tool and it does not load any Gum files (such as .gumx).

Code-only projects can be useful if you are adding diagnostic tools to your game, if you are evaluating Gum Forms, or if you prefer to develop without the use of GUI-based tools such as the Gum tool.

Introduction

Forms controls are a collection of classes which provide common UI behavior. You will probably be familiar with many controls. The most common controls include:

• Button

• CheckBox

• ComboBox

• Image

• Label

• ListBox

• RadioButton

• ScrollViewer

• Slider

• TextBox

All controls are in the MonoGameGum.Forms.Controls namespace.

Common Control Properties

All controls share a few common properties and characteristics. If you are familiar with these concepts then the following list may quickly get you familiar with forms controls. If the following list doesn't make sense don't worry, we'll cover each topic in this and following tutorials.

• All can controls can be added to a StackPanel. Technically, any control can be added to any other control, but for this tutorial we'll keep things simple by adding only to a StackPanel.

• All controls have a Visual property which can be used to position, size, and perform advance layout behavior. This Visual property is ultimately a GraphicalUiElement which provides access to all Gum layout properties.

• All controls can receive input from the mouse (usually through the Gum Cursor object). Most controls can also receive focus and input from gamepads.

• All controls support binding by assigning their BindingContext property. Children controls inherit BindingContext from their parents if the BindingContext is not explicitly assigned.

For the rest of this tutorial we'll add a few of the most common controls to our project and show how to work with them. Note that for this tutorial I've removed the Button control from the previous tutorial.

Code Organization

For the sake of brevity, we will add all of our controls to the Root object, and all code will be added to the game's Initialize method after the Root has been created. Of course a full game may require more advanced organization but we'll keep everything in the Game Initialize for simplicity.

Label

Labels are text objects which can display a string. Labels do not have any direct interaction such as responding to clicks. The following code adds a label to the project:

var label = new Label();
Root.AddChild(label);
label.Text = $"I was created at {System.DateTime.Now}";

The rest of this tutorial assumes that the Label is not removed. It is used to show when events have occurred.

Button

Button controls are usually added when a user needs to perform a command. Buttons can be clicked with the mouse and gamepad, and their click event can be manually invoked for custom support such as pressing Enter on the keyboard.

The following code creates two buttons. One is disabled so it does not respond to click events:

var button = new Button();
Root.AddChild(button);
button.Text = "Click Me";
button.Click += (_, _) => 
    label.Text = $"Button clicked @ {System.DateTime.Now}";

var disabledButton = new Button();
Root.AddChild(disabledButton);
disabledButton.Text = "Disabled Button";
disabledButton.IsEnabled = false;
disabledButton.Click += (_, _) =>
    label.Text = "This never happens";

CheckBox

CheckBox controls allow the user to toggle a bool value by clicking on it. Just like Button, the CheckBoxes support clicking with mouse and gamepad and changing the IsChecked property in code.

The following code creates two CheckBoxes:

var checkBox = new CheckBox();
Root.AddChild(checkBox);
checkBox.Text = "Click Me";
checkBox.Checked += (_, _) => label.Text = "CheckBox checked";
checkBox.Unchecked += (_, _) => label.Text = "CheckBox unchecked";

TextBox

TextBox controls allow the user to see and edit string values. TextBoxes support typing with the keyboard, copy/paste, selection, and multiple lines of text.

TextBoxes are automatically focused when clicked, but IsFocused can be explicitly set to give focus.

UNDER CONSTRUCTION.....

Introduction

This tutorial walks you through creating an empty Gum project which acts as a starting point for the rest of the tutorials.

This tutorial covers:

• Adding Gum NuGet packages

• Modifying your Game class to support Gum and Gum Forms

• Adding your first Gum control (Button)

Adding Gum NuGet Packages

Before writing any code, we must add the Gum nuget package. Add the Gum.MonoGame package to your game. For more information see the Setup page.

Once you are finished, your game project should reference the Gum.MonoGame project.

Adding Gum to Your Game

Gum requires a few lines of code to get started. A simplified Game class with the required calls would look like the following code:

using MonoGameGum.Forms.Controls;

public class Game1 : Game
{
    private GraphicsDeviceManager _graphics;
    
    StackPanel Root;
    
    public Game1()
    {
        _graphics = new GraphicsDeviceManager(this);
        Content.RootDirectory = "Content";
        IsMouseVisible = true;
    }

    protected override void Initialize()
    {
        var gumProject = MonoGameGum.GumService.Default.Initialize(this);
            
        Root = new StackPanel();
        Root.Visual.AddToManagers();
        
        base.Initialize();
    }

    protected override void Update(GameTime gameTime)
    {
        MonoGameGum.GumService.Default.Update(this, gameTime, Root);
        base.Update(gameTime);
    }

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

The code above includes the following sections:

• StackPanel Root - Games using Gum usually have a Root object which contains all other instances. In this case we create a StackPanel which will hold all of our controls.

StackPanel Root;

• Initialize - The contents of the Initialize method calls GumService.Default.Initialize which prepares Gum. It also creates a Root instance of type StackPanel. Finally, the StackPanel has its AddToManagers method called which tells Gum to draw the StackPanel and its children that we'll add later.

        var gumProject = MonoGameGum.GumService.Default.Initialize(this);
            
        Root = new StackPanel();
        Root.Visual.AddToManagers();

• Update - this updates the internal keyboard, mouse, and gamepad instances and applies default behavior to any components which implement Forms. For example, if a Button is added to the Screen, this code is responsible for checking if the cursor is overlapping the Button and adjusting the highlight/pressed state appropriately. We pass the Root instance so that it and all of its children can receive input events.

MonoGameGum.GumService.Default.Update(this, gameTime, Root);

• Draw - this method draws all Gum objects to the screen. This method does not yet perform any drawing since StackPanels are invisible, but we'll be adding controls later in this tutorial.

MonoGameGum.GumService.Default.Draw();

We can run our project to see a blank (cornflower blue) screen.

Adding Controls

Now that we have Gum running, we can add controls to our StackPanel (Root). The following code in Initialize adds a button which responds to being clicked by modifying its Text property:

protected override void Initialize()
{
    MonoGameGum.GumService.Default.Initialize(this);

    Root = new StackPanel();
    Root.Visual.AddToManagers();

    // Creates a button instance
    var button = new Button();
    // Adds the button as a child so that it is drawn and has its
    // events raised
    Root.AddChild(button);
    // Initial button text before being clicked
    button.Text = "Click Me";
    // Makes the button wider so the text fits
    button.Visual.Width = 350;
    // Click event can be handled with a lambda
    button.Click += (_, _) =>
        button.Text = $"Clicked at {System.DateTime.Now}";

    base.Initialize();
}