Getting started - AderitoSilva/XInputium GitHub Wiki

XInputium was made with the goal of providing powerful features, but without requiring you to write too much code to get things done. Its API offers several ways for you to consume it, but in this page we will cover the most simple way, which is event based.

Installation

Install XInputium on your .NET project using a NuGet package:

Install-Package XInputium

See XInputium page at NuGet.org for more information.

Hello, universe!

Once you install XInputium's NuGet page on your application, it's now time to start using it. Before going deeper into details about how to consume XInputium API, let's just have a first glance on how a simple application would use XInputium. The following example, creates an XGamepad class instance, which we would keep during our application's lifetime, subscribes to one of its events, and requests an update to the input loop at every application render frame. You need an XInput compatible device connected to your system to get the example to work.

// First, lets create an `XGamepad` instance. This has all the features we need to access a gamepad.
XGamepad gamepad = new();  // This uses the first gamepad it finds connected on the system.

// Subscribe to the `ButtonPressed` event, which will fire whenever a button is pressed.
gamepad.ButtonPressed += (s, e) => Debug.WriteLine($"Hello, universe!. You pressed button '{e.Button}'.");

// Call this on every app/game frame. Any input events will fire now.
gamepad.Update();

In the previous basic example, you would typically call gamepad.Update() method whenever your game or application is rendering a new frame. You call this method to progress the internal XGamepad's input loop by one more iteration. Once you call this method, the internal input loop will update its state with fresh data from the device and will trigger any events accordingly.

The full functional hypothetical application code that makes use of the code above would look like the following:

using System.Diagnostics;  // This is for `Debug` class.
using XInputium;  // This is for the event arguments.
using XInputium.XInput;  // This is for the `XGamepad` and `XInputButton` classes.

namespace MyApplication;

// This is a hypothetical application window class.
public class MyApplicationWindow : Window
{

    private readonly XGamepad gamepad;

    // This is the application window constructor.
    public MyApplicationWindow()
    {
        gamepad = new();
        gamepad.ButtonPressed += Gamepad_ButtonPressed;
    }

    // This is the event handler that handles the `ButtonPressed` event.
    private void Gamepad_ButtonPressed(object? sender, DigitalButtonEventArgs<XInputButton> e)
    {
        Debug.WriteLine($"Hello, universe!. You pressed button '{e.Button}'.");
    }

    // This is the hypothetical application method that would be called on every graphics engine render.
    protected override void OnRender()
    {
        gamepad.Update();
    }

}

The previous example assumes a hypothetical application framework that provides the Window class, as the base class for creating your own window, and an OnRender protected method on that window, that is called when the graphical engine is rendering a new frame. Each application or game framework has its own set of types and members, and its own way of achieving the results in the example above.

Going deeper

The "Hello, universe!" section above, gave you an idea on how to get your first application to work with XInput using XInputium, without entering into details about what that code means and how the API is structured — its goal is to give you a simple first look. XInputium offers many features, and, to get the most out of them, a deeper understanding about the API is beneficial. The following are pages that describe XInputium in more detail, which you're strongly encouraged to read if you wish to understand XInputium API:

• Introduction — Learn more about what XInputium is and understand the features it provides.
• The fundamentals — Get to know the principles of XInputium API and learn how to use it.
• Tutorials — Learn how to code specific tasks related to XInput, by following tutorials that show you how to perform these tasks using XInputium.