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
GumUI.UseGamepadDefaults();

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 Gum.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(Gum.Input.GamepadButton.A))
    {
        var focusedElement = InteractiveGue.CurrentInputReceiver;

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

ScrollViewer Right-Stick Scrolling

When a ScrollViewer (or a control built on it, such as ItemsControl, ListBox, or Menu) has top-level focus, tilting the right stick up or down scrolls the content vertically. The scroll speed is proportional to how far the stick is tilted and scales with elapsed time, so it feels the same regardless of frame rate. Horizontal scrolling from the stick is not yet supported.

The following example creates a ScrollViewer with tall content and enables gamepad input:

// Initialize
var scrollViewer = new ScrollViewer();
scrollViewer.Width = 200;
scrollViewer.Height = 200;

var tallContent = new ContainerRuntime();
tallContent.Width = 0;
tallContent.WidthUnits = Gum.DataTypes.DimensionUnitType.RelativeToParent;
tallContent.Height = 1000;
scrollViewer.AddChild(tallContent);
scrollViewer.AddToRoot();

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

Tilting the right stick up scrolls toward the top of the content; tilting it down scrolls toward the bottom. The default speed can be adjusted with GamepadStickScrollSpeed, which is measured in the same units as VerticalScrollBarValue per second at full stick deflection.

ListBox Navigation

When a ListBox is focused, press the A button to move focus into the items. Once the items have focus, pressing up or down on the D-pad (or tilting the left stick up or down) moves the highlighted selection through the list, and the SelectionChanged event fires each time the selected item changes. Pressing A again selects the highlighted item and returns focus to the top level; pressing B returns focus to the top level without selecting.

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

After running, press A to enter the list, then press down to move to the next item and up to move to the previous item. The selection does not wrap when it reaches the first or last item.

To have the list start with an item already focused — so the D-pad navigates immediately without first pressing A — see Keyboard and Gamepad Navigation on the ListBox page.

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.