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:
- Save the file to disk somewhere – remember where you saved it
- Open Gum
- Right-click on the Components folder
- Select “Import Component”
- Select the NineSliceButton.gucx file that you saved
- Click OK, and click OK if told that the file will be copied.
The Component should now appear in Gum:
Adding a Click event to the Button
Next, we need to mark the Button as being clickable. To do this in Gum:
- Verify NineSliceButton is selected
- 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:
- Select the MainMenuGum screen
- Drag+drop the NineSliceButton into the edit window of Gum
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:
- Open or focus Glue
- Expand the MainMenu screen
- Expand the Files node under the MainMenu screen
- Drag+drop the MainMenuGum.gusx file onto the Objects node
- Select NineSliceButtonInstance in the Source Name drop-down
- 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:
- Make sure Objects is expanded under MainMenu in Glue
- Drag+drop NinceSliceButtonInstance onto the “Events” folder under MainMenu
- Select the “Click” event from the “Event:” dropdown
- 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:
- Open the project in Visual Studio
- Navigate to MainMenu.Event.cs
- Add the following code in OnNinceSliceButtonInstanceClick:
void OnNinceSliceButtonInstanceClick (FlatRedBall.Gui.IWindow callingWindow)
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
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.
Events on Non-Components
Currently events such as Click are only available on Gum runtime objects which are components. This means that a free-floating Sprite, ColoredRectangle, or Text object in a Gum screen will not have Gum events raised on it.
Note that non-components (such as Containers) can contain instances of components (such as a list of stacked buttons), and those contained components can raise events. The next tutorial will cover events on children components in more depth.
Furthermore, note that although a non-component will never raise events (and will not be set as the GuiManager.Cursor.WindowOver ), the HasCursorOver method will still properly check the cursor against the bounds of the calling object.
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.