Gum Screens
Last updated
Was this helpful?
Last updated
Was this helpful?
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.
To add a new Screen:
Open the project in the Gum tool
Right-click on the Screens folder and select Add Screen
Name the screen TitleScreen and click OK
The newly created TitleScreen is now in the Screens folder.
We can add instances to Gum Screen by drag+dropping the files onto the Game screen.
Add a ButtonStandard to TitleScreen.
Instances can also be created by selecting the TitleScreen, then drag+dropping the item in the editor window.
Add a ButtonStandard instance by dropping Components/Controls/ButtonStandard onto 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.
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:
Click on the Code tab
Click the Auto Setup Code Generation button. Gum locates your .csproj file and sets up default values.
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.
You can verify that your code has been properly generated by looking at your project in Visual Studio or your IDE of choice.
Note that each screen and component generates two .cs files:
YourComponentOrScreenName.cs - this is called custom code and is where you can write code safely
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.
To show the TitleScreen in game, we can use the newly-generated TitleScreen class as shown in the following snippet:
The game now displays the TitleScreen.
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.
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:
The button now responds to clicks by updating its text.
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:
Remember, add your code to CustomInitialize, not the constructor.
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.