Gamepad Support

Introduction

Gum Forms supports using a gamepad to control the UI. In general, when using a gamepad a single UI control has focus. Pressing up or down on the gamepad moves focus to the next item. Each forms control can support different interaction. For example, Buttons can be clicked, but a ListBox supports selecting items within the ListBox.

For information on using gamepads for tabbing, see the Tabbing page.

Enabling Gamepad Controls

To enable gamepad support in your screen:

1. Be sure to have a gamepad plugged in. Any gamepad that is usable in MonoGame will also work as a gamepad in Gum Forms

2. Add the gamepad to the FrameworkElement.GamepadsForUiControl. You can add multiple gamepads for multiplayer games.

3. Set the initial control to have focus by setting its IsFocused = true

For example, the following code enables gamepad control for a game assuming MyButton is a valid button:

// Initialize
// The first gamepad:
var gamepad = GumUI.Gamepads[0];
// If this code is run multiple times then the gamepad
// may get added multiple times as well. To be safe, clear
// the list:
FrameworkElement.GamePadsForUiControl.Clear();
FrameworkElement.GamePadsForUiControl.Add(gamepad);
MyButton.IsFocused = true;

Button Control Click

By default a gamepad's A button can be used to select the focused control. If the focused control is a Button then pressing a gamepad's A button. The following example code shows how to detect clicks on a button which happen with the gamepad:

// Initialize
FrameworkElement.GamePadsForUiControl.AddRange(
    GumUI.Gamepads);

TopButton.IsFocused = true;
TopButton.Click += (_, _) =>
    TextInstance.Text = $"Top button clicked at {DateTime.Now}";

BottomButton.Click += (_, _) =>
    TextInstance.Text = $"Bottom button clicked at {DateTime.Now}";

Pressing the A button raises the focused button's Click event.

Pressing the A button clicks the highlighted Button

Handling buttons specifically can be handled by subscribing to ControllerButtonPushed.

// Initialize
TopButton.ControllerButtonPushed += (button) =>
    TextInstance.Text = $"Top button button pushed: {button} @ {DateTime.Now}";

Buttons can respond to any gamepad button push

The Click event may be raised with InputEventArgs containing the gamepad. Remember, clicks can happen a variety of ways including the mouse or even being directly invoked, so you need to check whether the second parameter is of type InputEventArgs and if the device is a GamePad.

// Initialize
TopButton.Click += HandleClick;

// later, define the Click event:
private void HandleClick(object sender, EventArgs args)
{
    // Click events can come from the cursor or even manually invoked with
    // no backing input device, so checks are needed
    if(args is InputEventArgs inputEventArgs &&
        inputEventArgs.InputDevice is MonoGameGum.Input.GamePad gamePad)
    {
        var index = Array.IndexOf(GumService.Default.Gamepads, gamePad);
        TextInstance.Text = $"Clicked with gamepad index {index} at {DateTime.Now}";
    }
}

Output from clicking on a button with a gamepad

If additional flexibility is needed, gamepad events can be polled in an Update method.

// Update
var gamepads = FrameworkElement.GamePadsForUiControl;
for (int i = 0; i < gamepads.Count; i++)
{
    var gamepad = gamepads[i];

    if(gamepad.ButtonPushed(Microsoft.Xna.Framework.Input.Buttons.A))
    {
        var focusedElement = InteractiveGue.CurrentInputReceiver;

        if(focusedElement != null)
        {
            TextInstance.Text =
                $"Gamepad {i} pressed A on {focusedElement} of type " +
                $"{focusedElement?.GetType()}";
        }
    }
}

ListBox Navigation

When a ListBox has focus, pressing up or down on the D-pad (or tilting the left stick up or down) moves the selection through the list. The SelectionChanged event fires each time the selected item changes.

The following example adds items to a ListBox, enables gamepad input, and reacts to selection changes:

// Initialize
var listBox = new ListBox();
listBox.Width = 200;
listBox.Height = 150;
listBox.Items.Add("Option 1");
listBox.Items.Add("Option 2");
listBox.Items.Add("Option 3");
listBox.Items.Add("Option 4");
listBox.AddToRoot();

listBox.SelectionChanged += (_, args) =>
    TextInstance.Text = $"Selected: {listBox.SelectedObject}";

FrameworkElement.GamePadsForUiControl.Clear();
FrameworkElement.GamePadsForUiControl.AddRange(GumUI.Gamepads);
listBox.IsFocused = true;

Try on XnaFiddle.NET

Pressing down selects the next item and pressing up selects the previous item. The selection does not wrap when it reaches the first or last item.

Slider Adjustment

When a Slider has focus, pressing left or right on the D-pad (or tilting the left stick left or right) decreases or increases the slider's Value by SmallChange. By default, a Slider sets IsUsingLeftAndRightGamepadDirectionsForNavigation to false so that left and right inputs adjust the value rather than moving focus to another control.

The following example creates a Slider with a range of 0–100, enables gamepad input, and displays the current value:

// Initialize
var slider = new Slider();
slider.Width = 200;
slider.Minimum = 0;
slider.Maximum = 100;
slider.Value = 50;
slider.SmallChange = 10;
slider.AddToRoot();

var label = new Label();
label.Y = 40;
label.Text = $"Value: {slider.Value}";
label.AddToRoot();

slider.ValueChanged += (_, _) =>
    label.Text = $"Value: {slider.Value}";

FrameworkElement.GamePadsForUiControl.Clear();
FrameworkElement.GamePadsForUiControl.AddRange(GumUI.Gamepads);
slider.IsFocused = true;

Try on XnaFiddle.NET

Each left or right press changes Value by the amount set in SmallChange. You can also set LargeChange for larger increments when clicking the track area with a mouse or cursor.