4. Events on Gum Objects

Introduction

So far we’ve discussed how to use Gum to create screens which can be shown in Glue and edited at runtime. This page discusses how to use events to attach custom code to common UI actions such as clicking.

Similarities with IWindow

Although this tutorial is focused on Gum objects, the steps necessary for adding events to Gum objects is identical to the steps necessary for adding events to Entities which implement the IWindow interface. In fact, the GraphicalUiElement class implements the IWindow interface, so you can even add events to it in custom code.

For more information on IWindow in Glue, see the Implements IWindow page.

Importing a NineSliceButton

This tutorial will use a NineSliceButton, which can be imported from this file:

TODO: Upload NineSliceButton.gucx once Justin fixes permissions.

To import this file:

  1. Save the file to disk somewhere – remember where you saved it
  2. Open Gum
  3. Right-click on the Components folder
  4. Select “Import Component”
  5. Select the NineSliceButton.gucx file that you saved
  6. Click OK, and click OK if told that the file will be copied.

The Component should now appear in Gum:
NineSliceButtonInGum.PNG

Adding a Click event to the Button

Next, we need to mark the Button as being clickable. To do this in Gum:

  1. Verify NineSliceButton is selected
  2. Check the “HasEvents” check box

Adding a NineSliceButton to your Screen

Now that you have a NineSliceButton component, you can add it to your Gum screen:

  1. Select the MainMenuGum screen
  2. Drag+drop the NineSliceButton into the edit window of Gum

DragDropNineSliceButton.png

Accessing the NineSliceButtonInstance in Glue

Now that you have a NineSliceButton in your MainGumScreen, you can access it in Glue the same way we accessed the ColoredRectangleInstance:

  1. Open or focus Glue
  2. Expand the MainMenu screen
  3. Expand the Files node under the MainMenu screen
  4. Drag+drop the MainMenuGum.gusx file onto the Objects node
  5. Select NineSliceButtonInstance in the Source Name drop-down
  6. Click OK

This will allow Glue to access the NineSliceButtonInstance in your screen. Keep in mind that this provides access only to the NineSliceButtonInstance. If your Gum screen has multiple objects which you’d like to access in Glue (or in source), you will have to repeat the above steps for each object.

Of course, if you don’t need to access an object in Gum or in Code, you do not have to create an object for int in Glue – only for the objects which require some interactivity.

Creating a Click event for NineSliceButtonInstance

Next, we’ll create a Click event for NineSliceButtonInstance. This will be a block of code which will run whenever the NinceSliceButtonInstance is clicked. To do this:

  1. Make sure Objects is expanded under MainMenu in Glue
  2. Drag+drop NinceSliceButtonInstance onto the “Events” folder under MainMenu
    DragDropButtonOnEvents.png
  3. Select the “Click” event from the “Event:” dropdown

  4. Click OK

Now you have a function which you can add any valid C# code and it will execute when the button is clicked. Note that we are creating an event on the NineSliceButton object, which is a Gum component. At the time of this writing, the only components can have events attached to them. Standard objects, such as Sprite and ColoredRectangle instances, must be wrapped in a component to have events.

Editing the event in Visual Studio

To edit the code that executes when the button has been clicked in Visual Studio:

  1. Open the project in Visual Studio
  2. Navigate to MainMenu.Event.cs
    MainMenuEventVisualStudio.PNG
  3. Add the following code in OnNinceSliceButtonInstanceClick:

If you run the game now and click on the button you will notice that it gets wider every time it is clicked. Of course, this is not a very practical example. In a real game, you could move to the next screen or switch the logical or visual state of your game elements as appropriate.

Where is my mouse cursor? FlatRedBall projects have the mouse cursor invisible by default. To make the mouse cursor visible, see this page: Microsoft.Xna.Framework.Game#Showing_Cursor

Diagnosing Problems

The most common reason for events not firing is that the cursor is not actually detecting being over the Gum object with events. To check, you can add the following code in your Screen’s CustomActivity:

Displaying the WindowOver may help you figure out why clicks are not occurring.

WindowOver Returns the Parent Window

This tutorial outlines the most basic situation – a single component “floating” in an empty screen. A common setup is to have components which are part of other components (such as a button which is part of a menu). For information on working with events and parent/child components, see the next tutorial in this series.

Conclusion

Now that you know how to add events to Gum objects you can create a fully functional UI system by combining the visual editing power of Gum with the code generation and project structure features of Glue.

<- 3. Gum objects in code — 5. Events on Gum Objects Part 2 ->