Events on Gum Objects Part 2

Introduction

This tutorial continues our look at working with events on Gum objects. The previous tutorial covered the most basic situation - a clickable button in a screen. We'll expand upon the previous tutorial by creating a more complicated example - handling events on a popup container which displays a message and allows the user to click OK or Cancel. This tutorial covers the second property for controlling events: ExposeChildrenEvents.

HasEvents and ExposeChildrenEvents

HasEvents and ExposeChildrenEvents decide whether a component and its children are recognized as UI objects by the FlatRedBall engine. More specifically, they decide whether instances of these components are added to the GuiManager's windows list, and whether the GuiManager.Cursor can interact with these instances. Since each value can be independently set, then there are four possible combinations of values.

[row] [column md="3"] HasEvents / ExposeChildrenEvents [/column] [column md="4"] Description [/column] [column md="5"] Example [/column] [/row] [row] [column md="3"] True/False [/column] [column md="4"] The entire component is clickable, but individual parts of the component are not independently clickable. [/column] [column md="5"] A button made up of multiple sub-components (such as a NineSlice background, Text instance, and icon Sprite) which does not need each sub-component to be clickable. [/column] [/row] [row] [column md="3"] True/True [/column] [column md="4"] The entire component is clickable, as are individual sub-components. [/column] [column md="5"] A pop-up which should block clicks and also contains buttons which can be clicked. [/column] [/row] [row] [column md="3"] False/True [/column] [column md="4"] Only individual sub-components of the component will receive clicks. [/column] [column md="5"] A component which is used to perform layout on a collection of buttons, but the component as a whole has no visual component and should not receive clicks (or block clicks from receiving underlying UI). Only the individual buttons will receive clicks. [/column] [/row] [row] [column md="3"] False/False [/column] [column md="4"] The UI is completely ignored in the FlatRedBall UI system. [/column] [column md="5"] A decorative collection of UI which may overlap underlying UI elements but should not interfere with their click events. [/column] [/row]

Creating the Components

This tutorial uses three components:

1. Button - a clickable component

2. Label - a non-clickable component used to display a message to the user

3. Popup - a component containing a label and two buttons

Creating the Button Component

The Button component will need some kind of visual (such as a ColoredRectangle). We will include a Text object for the button, but it is not necessary for this tutorial. When finished your Button should look similar to the following image:

The only important detail for this component is to make sure the HasEvents value is set to true. We will look at ExposeChildrenEvents later.

Creating the Label Component

The label component is only a container with a single Text object. Functionally we could skip creating a Label component and add a Text object directly to the Popup component. We will be creating a Label component to show how to include some components in events (Buttons) and exclude others (Label). When finished your Label should look similar to the following image:

For this tutorial we want to make sure Label instances are not clickable, so make sure the HasEvents property is set to false.

Creating the Popup Component

Finally, we'll create our Popup Component. It should contain the following instances:

• Label

• Button OkButton

• Button CancelButton

• ColoredRectangle (or other visual objects) for the background

When finished, the popup will appear as shown in the following image:

Let's consider the event behavior we want for our popup object:

• We want each of the buttons in the popup to be clickable

• We do not want the label to be clickable

• We do not want the entire popup to raise events when it is clicked - only its buttons

This can be summarised as - the popup itself should not raise events, but its children should. We can get this combination of behaviour by setting the HasEvents value to false and the ExposeChildrenEvents value to true.

Adding a Popup to Our Game

Now that we have a fully-functional Popup instance, we can add it to our Gum screen (such as MainMenuGum).

Now that our popup is in our MainMenuGum, we can access it in our MainMenu.cs file in Visual Studio. For example, we can respond to click events on the OK and Cancel buttons by hiding the popup and displaying some debug text.

void CustomInitialize()
{
    var popup = GumScreen.PopupInstance;
    popup.OkButton.Click += HandleOkButtonClick;
    popup.CancelButton.Click += HandleCancelButtonClick;

}

private void HandleOkButtonClick(IWindow window)
{
    GumScreen.PopupInstance.Visible = false;
    FlatRedBall.Debugging.Debugger.CommandLineWrite("OK clicked");
}

private void HandleCancelButtonClick(IWindow window)
{
    GumScreen.PopupInstance.Visible = false;