3. Gum objects in code

Introduction

So far we’ve covered how to create a new Gum project in your Glue project and how to add Gum screens to your Glue screens. This gets us a considerable amount of functionality already, but it’s very likely that you’ll need to interact with Gum objects in code. For example, you may use code to dynamically set the visibility of certain UI elements according to the game’s state.

This tutorial will explain how to work with the GraphicalUiElement in code – the class that is at the heart of Gum. For information on how to fully create a component in code (as opposed to relying on its creation in Gum), see this page.

Option 1 – Adding Objects in Glue

If you’ve been following along the previous tutorials, then you should have a Screen that has two Gum objects: a Text and a ColoredRectangle.

For this tutorial will make some modifications to the ColoredRectangle in our custom code.

The first step is to create a Glue object. To do this:

  1. Open or bring Glue into focus
  2. Expand Screens
  3. Expand MainMenu
  4. Expand Files
  5. Drag+drop the .gusx file onto the Objects item
  6. Use the dropdown next to Source Name: to select ColoredRectangleInstance
  7. Click OK

Note that the Source Name: drop down contains all instances in your Gum project. We selected the ColoredRectangleInstance for this example, but you could select any instance when working on an actual game.

 

Note that the ColoredRectangle in Glue is not a new ColoredRectangle instance – it is a reference to the ColoredRectangle inside the MainMenuGum screen. Adding it here in Glue allows code to access and modify this object, as we’ll see in the next step. If you do not access an object using this method, it will still be createated when the MainMenuGum screen is loaded.

Option 2 – Getting Objects by Name

The steps above show how to access a Gum object by adding an Object to the Glue screen. This approach has the benefit of reducing the possibility of coding errors, but if you have a lot of objects that you are accessing then your screen object list may get very large.

Alternatively, you can access an object purely in code. For example, the following shows how to create a ColoredRectangleInstance purely in code. This code could be added to MainMenu.cs to get a reference to the ColoredRectangleInstance from the MainMenuGum screen:

ColoredRectangleRuntime ColoredRectangleInstance;
void CustomInitialize()
{
 ColoredRectangleInstance = MainMenuGum.GetGraphicalUiElementByName("ColoredRectangleInstance")
   as ColoredRectangleRuntime;
}

Notice that we use the name ColoredRectangleInstance. This needs to match the name of the instance in the Gum screen exactly, including capitalization:

Also, notice that we use the type ColoredRectangleRuntime. We did this because the type in code should match the type in your Gum project. Glue automatically generates classes for every type in your Gum project, but it will always append Runtime to the end of the name. Therefore, the type ColoredRectangle in Gum becomes ColoredRectangleRuntime in code.

Modifying Gum Objects in Code

Now that we have a ColoredRectangleInstance under our Glue MainMenu screen, we can access the ColoredRectangleInstance in the code the same way we access any other object. For example, to set the ColoredRectangleInstance’s Y value to 250, you can add the following code to your MainMenu’s CustomInitialize. To do this:

  1. Open your Visual Studio project
  2. Navigate to MainMenu.cs (which will be in your Screens folder in Visual Studio)
  3. Modify CustomInitialize so it looks like this:
void CustomInitialize()
{
    this.ColoredRectangleInstance.Y = 250;
}

Similarly, objects from Gum can be modified in CustomActivity. You can modify your MainMenu’s CustomActivity so it looks like this:

void CustomActivity(bool firstTimeCalled)
{
    this.ColoredRectangleInstance.X += .1f;
}

MovingColoredRectangleFromGum.png

Incrementing Score

The example above shows how to move the rectangle. For this example we will modify the Text object to display score. We will increment the score whenever the player presses the space bar. This is just a simple example to show how to show a score. A real game may increase the score on an event such as when a bullet hits an enemy.

We will access the TextInstance purely in code – but if you are more comfortable using the drag+drop approach to access the Text object, feel free to do that instead.

To display a score, modify the MainMenu code:

TextRuntime TextInstance;
int score = 0;
void CustomInitialize()
{
 TextInstance = MainMenuGum.GetGraphicalUiElementByName("TextInstance")
   as TextRuntime;

 TextInstance.Text = score.ToString();
}

void CustomActivity(bool firstTimeCalled)
{
 if(InputManager.Keyboard.KeyPushed(Microsoft.Xna.Framework.Input.Keys.Space))
 {
   score++;
   TextInstance.Text = score.ToString();
 }
}

Again, keep in mind that we need to access the TextInstance using the exact name in Gum:

Gum Coordinate System

I’ve you’ve spent some time in Gum you may notice that the coordinate system in Gum behaves differently than the coordinate system in FlatRedBall. By default (0,0) is located at the center of the screen in FlatRedBall, but (0,0) represents the top-left corner of the screen in Gum.

Also, increasing the Y value of an object will move it up in FlatRedBall, but increasing the Y value of a Gum object will move it down. You can try this by modifying your code to change the Y of the ColoredRectangleInstance in CustomActivity.

When used with Glue, Gum objects will behave identically to how they behave in the Gum tool. This not only applies to Y positioning but as we will see in later tutorials with position and width unit types as well.

Conclusion

This tutorial has shown how to access objects from Gum in code. Just like objects from FlatRedBall file types (like .scnx and .shcx), Glue will generate objects which we can edit in code with full compile-time protection and Visual Studio IntelliSense.

The next tutorial will show you how to use UI events (such as Click) on Gum components.

<- 2. Screens in Gum — 4. Events on Gum Objects ->