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.
目前支持平台：
This module provides classes that can:
注意： 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. The can be done by the configureButtons example that can also save the generated layout persistently for use by other applications.
Before you start using the APIs provided by this module, ensure that the gamepad is detected by your development environment.
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.
注意： 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.
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 设备 章节。
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.
The Android backend uses the
InputDevice
API.
此后端使用
GCController
API.
Besides game controllers, it also supports the tvOS remote (microGamepad). The mapping for this is the following:
X button
- 播放/暂停
A button
- 按触摸区域
left thumbstick
- 触摸区域
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.
The examples demonstrate how to handle input from a gamepad using the QML and C++ APIs.