02 – Working With Controls in Code

Introduction

This tutorial shows you how to access FlatRedBall.Forms controls in code to perform common logic like assigning event handlers and accessing properties.

For an in-depth look at every control in FlatRedBall.Forms, see the reference section:

Controls

Setup

The previous tutorial showed how to create a new project with a Button control. Most controls require no additional code to work – just drag+drop the control into a screen and it will have full functionality. For this tutorial we’ll create an instance of the following controls:

  • Button (multiple versions exist, but ButtonStandard is the most common)
  • CheckBox
  • ListBox
  • TextBox

All controls are present in the Components/Controls folder.

To create these controls, drag drop them into the GameScreenGum, as was shown in the previous tutorial for the Button.

Working with Button

Now we can access all of our controls from the Gum screen in code. To add an event to the Button:

  1. Open the project in Visual Studio
  2. Go to your screen’s code file (GameScreen.cs, for example)
  3. Add the following code to the GameScreen:
FlatRedBall.Forms.Controls.Button button;
void CustomInitialize()
{
    button = GameScreenGum.ButtonInstance.FormsControl;
    button.Click += HandleButtonClick;
}

private void HandleButtonClick(object sender, EventArgs e)
{
    button.Text = "Clicked\n" + System.DateTime.Now.ToString();
}

This results in the button updating its text to indicate when it was last clicked:

Code Details

Let’s take a look at a few parts of the code. First, we should note that the code above is all compile-time protected. This means:

  • Any changes in the Gum project may result in a compile error, notifying you that something has to change in the code
  • Visual Studio provides intellisense (code completion) to help you fill in the code

In the code above we accessed the button through the GameScreenGum.ButtonInstance property. Note that ButtonInstance  is the same name as the object in Gum.

The ButtonInstance  contains a FormsControl  property, which gives us access to the FlatRedBall.Forms.Control.Button  instance. GameScreenGum  provides access to all objects contained within the GameScreenGum screen, whether they represent FlatRedBall.Forms objects or not. Only the Forms objects will have a FormsControl  property, providing access to the specific type of Forms control (in this case Button ).

Once we have access to the button we can interact with it in a standard way, such as by assigning a click event or by setting its Text  property.

Working with CheckBox

The CheckBox  control can be used to allow the user to set true/false values. Just like with Button , before we’ll get a reference to the CheckBox  through the screen.

FlatRedBall.Forms.Controls.CheckBox checkBox;
void CustomInitialize()
{
    checkBox = GameScreenGum.CheckBoxInstance.FormsControl;
    checkBox.Text = "Remember Password";
    checkBox.Click += HandleCheckboxClicked;
}

private void HandleCheckboxClicked(object sender, EventArgs e)
{
    FlatRedBall.Debugging.Debugger.CommandLineWrite(
        "Checkbox IsChecked: " + checkBox.IsChecked);
}

Clicking the CheckBox  results in the value being printed to the screen.

Working with ListBox

The ListBox control is used to display options or a collection of current items to the user (such as active quests). The following code adds items to the list box whenever the user presses a key on the keyboard. Note that this code requires code in CustomActivity  to read input from the keyboard.

FlatRedBall.Forms.Controls.ListBox listBox;
void CustomInitialize()
{
    listBox = GameScreenGum.ListBoxInstance.FormsControl;
}

void CustomActivity(bool firstTimeCalled)
{
    var keyboard = InputManager.Keyboard;
    if(keyboard.KeyPushed(Microsoft.Xna.Framework.Input.Keys.A))
    {
        listBox.Items.Add("Key A");
    }
    if (keyboard.KeyPushed(Microsoft.Xna.Framework.Input.Keys.B))
    {
        listBox.Items.Add("Key B");
    }
    if (keyboard.KeyPushed(Microsoft.Xna.Framework.Input.Keys.C))
    {
        listBox.Items.Add("Key C");
    }
}

Typing the A, B, or C characters on the keyboard results in items added to the list box:

Working with TextBox

The TextBox control provides free-form input support for users to enter string values like a character’s name. Note that at the time of this writing the TextBox relies on the MonoGame key bindings which do not consider different keyboard configurations (such as languages other than English).

The following code can be used to react to any changes in the TextBox Text property and print it out to the screen.

FlatRedBall.Forms.Controls.TextBox textBox;
void CustomInitialize()
{
    textBox = GameScreenGum.TextBoxInstance.FormsControl;
    textBox.TextChanged += HandleTextBoxTextChanged;
}

private void HandleTextBoxTextChanged(object sender, EventArgs e)
{
    FlatRedBall.Debugging.Debugger.CommandLineWrite(
        "Text box text: " + textBox.Text);
}

Note that the TextChanged event will be raised for each new character (including spaces) or whenever a character is deleted.