> For the complete documentation index, see [llms.txt](https://docs.flatredball.com/gum/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.flatredball.com/gum/code/getting-started/tutorials/gum-project-forms-tutorial/gum-screens.md).
# 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](/gum/gum-tool/tutorials-and-examples/intro-tutorials.md). 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
{% hint style="warning" %}
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.
{% endhint %}
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:
{% tabs %}
{% tab title="Full Code" %}
```csharp
protected override void Initialize()
{
GumUI.Initialize(this, "GumProject/GumProject.gumx");
var screen = new TitleScreen();
screen.AddToRoot();
base.Initialize();
}
```
{% endtab %}
{% tab title="Diff" %}
```diff
protected override void Initialize()
{
GumUI.Initialize(this, "GumProject/GumProject.gumx");
+ var screen = new TitleScreen();
+ screen.AddToRoot();
base.Initialize();
}
```
{% endtab %}
{% endtabs %}
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:
{% tabs %}
{% tab title="Full Code" %}
```csharp
// 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();
}
```
{% endtab %}
{% tab title="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();
}
{% endtab %}
{% endtabs %}
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:
{% tabs %}
{% tab title="Full Code" %}
{% endtab %}
{% endtabs %}
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.
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://docs.flatredball.com/gum/code/getting-started/tutorials/gum-project-forms-tutorial/gum-screens.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.