> For the complete documentation index, see [llms.txt](https://docs.flatredball.com/gum/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.flatredball.com/gum/code/events-and-interactivity/gamepad-support.md).

# 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](https://docs.flatredball.com/gum/code/events-and-interactivity/tabbing-moving-focus.md) 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:

```csharp
// 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:

```csharp
// 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.

<figure><img src="https://2695663588-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M_fzQmxQ1VeUFHcoo2c%2Fuploads%2Fgit-blob-4f4011b5853327d2378a6f55063aa4174f674f4b%2F09_09%2057%2016.gif?alt=media" alt=""><figcaption><p>Pressing the A button clicks the highlighted Button</p></figcaption></figure>

Handling buttons specifically can be handled by subscribing to `ControllerButtonPushed`.

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

<figure><img src="https://2695663588-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M_fzQmxQ1VeUFHcoo2c%2Fuploads%2Fgit-blob-f844874823b48d6be276457f9a2de74f5da829d5%2F09_10%2001%2014.gif?alt=media" alt=""><figcaption><p>Buttons can respond to any gamepad button push</p></figcaption></figure>

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.

```csharp
// 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(GumUI.Gamepads, gamePad);
        TextInstance.Text = $"Clicked with gamepad index {index} at {DateTime.Now}";
    }
}
```

<figure><img src="https://2695663588-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M_fzQmxQ1VeUFHcoo2c%2Fuploads%2Fgit-blob-c57f46ba5cb9edc66d6a29a9cc9e86f410db7501%2F10_05%2038%2036.png?alt=media" alt=""><figcaption><p>Output from clicking on a button with a gamepad</p></figcaption></figure>

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

```csharp
// 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()}";
        }
    }
}
```

<figure><img src="https://2695663588-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M_fzQmxQ1VeUFHcoo2c%2Fuploads%2Fgit-blob-66e935ab628b7ee108a34ff2a33e92a2efd7f657%2F09_10%2056%2013.png?alt=media" alt=""><figcaption></figcaption></figure>

## 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:

```csharp
// 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();

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

```csharp
// 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}";

GumUI.UseGamepadDefaults();
listBox.IsFocused = true;
```

[Try on XnaFiddle.NET](https://xnafiddle.net/#snippet=H4sIAAAAAAAACqVSYUtCMRT9LvgfLqMPSvJSKwLFwDRNCBRTIhjEdBddPTfZ9tIS_3v3zZQ0yKB92e69595zdrZVNgPAOq6dzFgFvE2wEDJKK69ErD6Q0uxNWIiV8zdmCTXQuID7TZTLV7n-qkSPSvop1cvF4rfsHarJ1FO6dFk8BA-JxVGJ2KOm8GLwPkcXNdUMtVNGp-U0FdVHzsSJxx9j_zGg43HmorqUOc66c09oKHGW_x1RPoo4P4q42EdQbWD6xvjgJdfBazHCeOt0et74nJ6ip9TKq-IuHuAydZeznkXnIJmfSbPQQEQTMcO5kOANjKdCTxAcxjhORXC26z_k3-p62GIboVfCaQ1yzwUQduLyULvmesU10NqTccLZphFlBVb7s1B2Ry-0rwP7OrC1LIlcGPt6GyM9mo_aFPeEdC1jh6phtLcmjhoxChv0_Q1Pd-qnonP0L4adgCEj3N7DUMc4cXSvWvj2VZbNrLOZT_A5IeIQAwAA)

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](https://docs.flatredball.com/gum/code/controls/listbox.md#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:

```csharp
// 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}";

GumUI.UseGamepadDefaults();
slider.IsFocused = true;
```

[Try on XnaFiddle.NET](https://xnafiddle.net/#snippet=H4sIAAAAAAAACo2SUWvCMBDH3wW_w1H2oExCHduL0oHUKcKEoXVjUJC4HjMsTSRJp5v43XeN4oJP9qn3-9_d_67XfbMBEE3suCqjHjhTYccToYQTXIpfJBx9cwNWigINJKBwC3MftNr9XB05exOFW5N6F8cXcEGtLClkwYbc8exng5YNRYnKCq1quUZssLJaVg7_y6c0RVmVVBv0nPLdCXZDq1cuKyT4ELB5yaVM11x91ko3UAZFkemZ1s6vkKt6QclXKE_7PdfvXvOUvRO_j89hhjtH5CaPvG0P9uEUhzw6Z14ahXnHyQq4TaC17MCyDcljrva5AnquNzr4xiPDS9xq8_Ukkb6sY2OKX3hhR9osRKqVM1qyVCI_nu26fBp_Vg_ZouMtJj5nQznB3SdU8FFZWiPxv08_ajYOzcYfiDE4m1gCAAA)

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.

## Custom Input Sources (Steam Input)

Steam Input shows controllers to your game as Xbox controllers by default, so the code above works with Steam Input without changes.

To drive Gum Forms from another input source, such as Steam Input actions read through Steamworks.NET, create your own `Gum.Input.GamePad` and fill it each frame. Gum Forms handles focus, repeat rate, and deadzones the same way it does for a physical gamepad.

The following example maps Steam Input actions to a `GamePad`. It assumes your Steam Input configuration has a `MenuControls` action set with `menu_select` and `menu_cancel` digital actions and a `menu_move` analog action:

```csharp
// Class scope
Gum.Input.GamePad steamGamePad = new Gum.Input.GamePad();
Steamworks.InputHandle_t[] controllerHandles = new Steamworks.InputHandle_t[Steamworks.Constants.STEAM_INPUT_MAX_COUNT];
Steamworks.InputActionSetHandle_t menuActionSet;
Steamworks.InputDigitalActionHandle_t selectAction;
Steamworks.InputDigitalActionHandle_t cancelAction;
Steamworks.InputAnalogActionHandle_t moveAction;

// Initialize
Steamworks.SteamInput.Init(false);
menuActionSet = Steamworks.SteamInput.GetActionSetHandle("MenuControls");
selectAction = Steamworks.SteamInput.GetDigitalActionHandle("menu_select");
cancelAction = Steamworks.SteamInput.GetDigitalActionHandle("menu_cancel");
moveAction = Steamworks.SteamInput.GetAnalogActionHandle("menu_move");

FrameworkElement.GamePadsForUiControl.Clear();
FrameworkElement.GamePadsForUiControl.Add(steamGamePad);
MyButton.IsFocused = true;

// Update, before GumUI.Update
Steamworks.SteamInput.RunFrame();
int controllerCount = Steamworks.SteamInput.GetConnectedControllers(controllerHandles);
steamGamePad.SetConnected(controllerCount > 0);

if (controllerCount > 0)
{
    var controller = controllerHandles[0];
    Steamworks.SteamInput.ActivateActionSet(controller, menuActionSet);

    var select = Steamworks.SteamInput.GetDigitalActionData(controller, selectAction);
    var cancel = Steamworks.SteamInput.GetDigitalActionData(controller, cancelAction);
    var move = Steamworks.SteamInput.GetAnalogActionData(controller, moveAction);

    steamGamePad.SetButtonState(Gum.Input.GamepadButton.A, select.bState != 0);
    steamGamePad.SetButtonState(Gum.Input.GamepadButton.B, cancel.bState != 0);
    steamGamePad.SetLeftStickPosition(move.x, move.y);
}

steamGamePad.Activity(gameTime.TotalGameTime.TotalSeconds);
GumUI.Update(gameTime);
```

Call `Activity` once per frame after setting every button and stick, and before `GumUI.Update`. Left stick positions use -1 to +1 on each axis, with positive Y pointing up.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.flatredball.com/gum/code/events-and-interactivity/gamepad-support.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
