Gum Screens and Code Generation

Introduction

Gum screens are top level items which can contain instances of Gum objects. We'll be creating our first Gum screen in this tutorial. We'll also load this screen in code and work with gum objects.

Creating a Screen in the Gum Tool

To add a new Screen:

1. Open the project in the Gum tool
2. Right-click on the Screens folder and select Add Screen

   

   Add Screen right-click item
3. Name the screen TitleScreen and click OK

   

   Enter the new screen name and click OK

The newly created TitleScreen is now in the Screens folder.

TitleScreen in Gum

Adding Instances

We can add new instances to Gum Screen by drag+dropping the files onto the Game screen.

Add a ButtonStandard to TitleScreen.

Drag+drop ButtonStandard onto TitleScreen to create a Text instance

Instances can also be created by selecting the TitleScreen, then drag+dropping the item in the editor window.

Add a second ButtonStandard instance by dropping Components/Controls/ButtonStandard onto TitleScreen.

Drag+drop a component onto the Editor tab to add it to TitleScreen

Be sure to select the TitleScreen first, then drag+drop. If you click the component instead, then it will be selected, so you must re-select the TitleScreen.

The Gum tool includes lots of functionality for creating and customizing UI. For a more complete tutorial covering the Gum tool, see the Gum Tool Intro Tutorials. Feel free to spend some time creating your TitleScreen.

Setting Up Code Generation

Code generation reduces the amount of code you have to write to work with Gum. It results in strongly-typed screens and components, reducing the chances of typos and catching errors at runtime.

To set up code generation for your project:

1. Select a Screen such as TitleScreen - the Code tab does not appear unless a Screen or Component is selected
2. Click on the Code tab
3. Click the Auto Setup Code Generation button\

   
4. Gum locates your .csproj file and sets up default values.

Code tab in Gum

If you do not see the Auto Setup Code Generation button, that means you saved your Gum project in a location that is not relative to your game's .csproj. Be sure to save Gum projects in a subfolder of where your .csproj is located, usually in a folder in side the Content folder.

Once you have set this up, you can click the Generate Code button to generate code for your TitleScreen.

Note that Gum also generates code for all components referenced by your project, so it also generates ButtonStandard. If asked, click Yes to generate all necessary components.

Generate Code and click Yes to generate all components referenced by the TitleScreen

You can verify that your code has been properly generated by looking at your project in Visual Studio or your IDE of choice.

ButtonStandard and TitleScreen classes

Note that each screen and component generates two .cs files:

1. YourComponentOrScreenName.cs - this is called custom code and is where you can write code safely
2. YourComponentOrScreenName.Generated.cs - this is called generated code and is written by Gum. This code will be re-generated when you make changes in Gum, so if you write any code here it will be lost on re-generation.

Troubleshooting Code Generation

If code generation seems to not be working correctly, this section can provide some troubleshooting tips.

Verifying Output Library

Verify that the Output Library value is set to MonoGame + Forms. If you are not using this Output Library, code generation may not work properly.

You can also verify that your screens and components classes match the names in Gum without any suffix (such as Runtime).

Resetting Code Generation

If Gum has generated your code incorrectly, you can take the following steps to reset code generation:

1. Locate the Screens and Components folder in your code project and delete them. This will delete all generated and custom code. Be careful - you may want to create a backup if you have any custom code that you would like to preserve.
2. Open the Code Project Root folder and look for a .codsj file. Delete this file.
3. Close and re-open Gum
4. Select one of your screens or components
5. Click on the Code tab
6. Click the "Auto" button
7. Click the toggle icon to generate all code
8. Click the Generate button

Showing a Gum Screen in Your Game

To show the TitleScreen in game, we can use the newly-generated TitleScreen class as shown in the following snippet:

Full Code

protected override void Initialize()
{
    GumUI.Initialize(this, "GumProject/GumProject.gumx");

    var screen = new TitleScreen();
    screen.AddToRoot();

    base.Initialize();
}

Diff

protected override void Initialize()
{
    GumUI.Initialize(this, "GumProject/GumProject.gumx");

+   var screen = new TitleScreen();
+   screen.AddToRoot();

    base.Initialize();
}

The game now displays the TitleScreen.

TitleScreen displayed in a MonoGame project

The new code has 2 calls:

• new TitleScreen() - this instantiates the TitleScreen using the generated code. As mentioned above, this is a type-safe way to access the Gum screen. Note that it is possible to access the screen using strings as well, but doing so can be more error prone.
• screen.AddToRoot() - this call adds the screen to the root Gum object so that it is drawn and so it receives events. For example, we can mouse over and click on our buttons and they respond visually.

Buttons responding to cursor hover and click

Accessing Instances in Code

We can access the buttons in our TitleScreen using the generated code. We can access the buttons in our Game1 class, or we can access them in the TitleScreen.cs file. Both are perfectly fine, and which you do depends on whether you intend to have the Gum screen contained in a higher-level object that is specific to your game (such as a game scene), or if you want to keep all Gum code within the screen's custom code file. Either way, the code to interact with items is similar.

For example, the following code could be used to set the time when a button was clicked in the Game class. Notice that we access the button using the same name as is given in the Gum screen. If you changed the name of your button to something other than ButtonStandardInstance, then you should use that new name in code too:

Full Code

// In your Game class:
protected override void Initialize()
{
    GumUI.Initialize(this, "GumProject/GumProject.gumx");

    var screen = new TitleScreen();
    screen.ButtonStandardInstance.Click += (_, _) =>
        screen.ButtonStandardInstance.Text = DateTime.Now.ToString();
    screen.AddToRoot();

    base.Initialize();
}

Diff

// In your Game class:
protected override void Initialize()
{
    GumUI.Initialize(this, "GumProject/GumProject.gumx");

    var screen = new TitleScreen();
+   screen.ButtonStandardInstance.Click += (_, _) =>
+       screen.ButtonStandardInstance.Text = DateTime.Now.ToString();
    screen.AddToRoot();

    base.Initialize();
}

The button now responds to clicks by updating its text.

Button updating its Text to the current time

Alternatively, you can write code directly in the TitleScreen. Remember, TitleScreen.cs exists so you can write your own code. It contains a CustomInitialize method which is called when the Screen is first created. We can assign events in CustomInitialize as shown in the following code snippet:

Full Code

partial class TitleScreen
{
    partial void CustomInitialize()
    {
        ButtonStandardInstance1.Click += (_, _) =>
            ButtonStandardInstance1.Text = DateTime.Now.ToString();
    }
}

Diff

partial class TitleScreen
{
    partial void CustomInitialize()
    {
+       ButtonStandardInstance1.Click += (_, _) =>
+           ButtonStandardInstance1.Text = DateTime.Now.ToString();
    }
}

Remember, add your code to CustomInitialize, not the constructor.

Button click event handled in the TitleScreen class

Conclusion

This tutorial showed how to load a Gum screen in code and how to interact with objects. The next tutorial covers how to work with some of the more common component types.