Qt Gamepad is an add-on library that enables Qt applications to support the use of gamepad hardware and in some cases remote control equipment. The module provides both QML and C++ interfaces. The primary target audience are embedded devices with fullscreen user interfaces, and mobile applications targeting TV-like form factors.

The currently supported platforms are:

• Windows (Win32 desktop, via XInput 1.3 & 1.4)
• Linux (evdev)
• Linux (SDL2)
• Android
• macOS, iOS, tvOS (including the tvOS remote)

This module provides classes that can:

• Read input events from game controllers (Button and Axis events),
• expose these events both to C++ and Qt Quick (QML),
• provide basic gamepad layout configurability, and
• provide optional key and mouse event generation upon gamepad button presses.

Note: The API is designed with XBox and similar controllers in mind. Joysticks are not in scope for this module. A number of third-party gamepads may be supported as well, however, some of these may need custom configuration steps in order to map the button/trigger codes the device or driver in question provides onto what QtGamepad expects. This can be done by the configureButtons example that can also save the generated layout persistently for use by other applications.

Getting Started

Before you start using the APIs provided by this module, ensure that the gamepad is detected by your development environment.

Linux

On standard Linux distributions such as Ubuntu, gamepads such as XBox or PlayStation controllers are detected out-of-the-box. To check if the gamepad is detected, grep the dmesg logs using:

dmesg | grep "<gamepad-make>"

If you do not see the entries for the gamepad you are using, check if the joystick package is installed. If not, install the package and grep the dmesg logs again.

It is strongly recommended to verify that the gamepad's input device is present, and is sending events, via the lsinput and evtest utilities.

PlayStation controllers will likely need the help of an additional tool like xboxdrv. Once installed, and having a PS3 controller connected via USB, the following will ensure correct operation with QtGamepad:

sudo xboxdrv --detach-kernel-driver --mimic-xpad -s

Qt Gamepad uses a plugin-based, multi-backend architecture. This means that on some platforms, like Linux, there are multiple backends available. In case of Linux, the choices are:

• evdev - a backend reading events directly from the evdev input device
• sdl2 - a backend using the Gamepad module of SDL2. This plugin is only built when SDL2 is present at build time, and therefore will typically be missing from the pre-built Qt packages. This backend likely has broader support for various hardware, at the expense of an additional third-party dependency.

To force a given backend, set the QT_GAMEPAD environment variable to the name of the desired backend.

The availability of gamepad devices is monitored via libudev, assuming Qt was built with libudev support enabled. This means that connecting wired gamepads or wireless dongles is possible also while an application is running.

Note: wireless dongles may report one or more input devices even when no actual controllers have been connected to them. Qt Gamepad will interpret this as having connected gamepads present.

With the evdev backend, to explicitly specify the input device to use, set the environment variable QT_GAMEPAD_DEVICE to the desired /dev/input/event* node. This should not be needed normally, but can be useful in case multiple gamepads are connected and only one of them is interesting to the application.

Windows

The Windows Plug-n-Play service automatically installs the necessary drivers when the gamepad is connected through a USB port for the first time. Once the drivers are installed, select Control Panel > Device and Printers and check if the gamepad is listed under the Devices section.

To test whether gamepad input is detected, select Gamepad Controller Settings from the context menu, select Properties > Test, and start testing. You can also run the quickGamepad example to test.

Android

The Android backend uses the InputDevice API.

macOS, iOS, tvOS

This backend uses the GCController API.

Besides game controllers, it also supports the tvOS remote (microGamepad). The mapping for this is the following:

• X button - play/pause
• A button - pressing the touch area
• left thumbstick - the touch area

Troubleshooting

Some backends (evdev on Linux and xinput on Windows) and the plugin loader utilize the logging category qt.gamepad. Enabling this will print useful information on the debug output.

Examples

The examples demonstrate how to handle input from a gamepad using the QML and C++ APIs.

API Reference

• Qt Gamepad QML Types
• Qt Gamepad C++ Classes