1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
|
/****************************************************************************
**
** Copyright (C) 2017 The Qt Company Ltd.
** Contact: https://www.qt.io/licensing/
**
** This file is part of the documentation of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:FDL$
** Commercial License Usage
** Licensees holding valid commercial Qt licenses may use this file in
** accordance with the commercial license agreement provided with the
** Software or, alternatively, in accordance with the terms contained in
** a written agreement between you and The Qt Company. For licensing terms
** and conditions see https://www.qt.io/terms-conditions. For further
** information use the contact form at https://www.qt.io/contact-us.
**
** GNU Free Documentation License Usage
** Alternatively, this file may be used under the terms of the GNU Free
** Documentation License version 1.3 as published by the Free Software
** Foundation and appearing in the file included in the packaging of
** this file. Please review the following information to ensure
** the GNU Free Documentation License version 1.3 requirements
** will be met: https://www.gnu.org/licenses/fdl-1.3.html.
** $QT_END_LICENSE$
**
****************************************************************************/
/*!
\page qtgamepad-index.html
\title Qt Gamepad
\brief A cross-platform library to facilitate the use of gamepad hardware in Qt and Qt Quick applications.
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:
\list
\li Windows (Win32 desktop, via XInput 1.3 & 1.4)
\li Linux (evdev)
\li Linux (SDL2)
\li Android
\li macOS, iOS, tvOS (including the tvOS remote)
\endlist
This module provides classes that can:
\list
\li Read input events from game controllers (Button and Axis events),
\li expose these events both to C++ and Qt Quick (QML),
\li provide basic gamepad layout configurability, and
\li provide optional key and mouse event generation upon gamepad button presses.
\endlist
\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
\l{Qt Gamepad Configure Buttons Example}{configureButtons} example that can also
save the generated layout persistently for use by other applications.
\section1 Getting Started
Before you start using the APIs provided by this module, ensure that the
gamepad is detected by your development environment.
\section2 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, \c grep the \c dmesg logs using:
\badcode
dmesg | grep "<gamepad-make>"
\endcode
If you do not see the entries for the gamepad you are using, check if
the \c joystick package is installed. If not, install the package and \c grep
the \c dmesg logs again.
It is strongly recommended to verify that the gamepad's input device is
present, and is sending events, via the \c lsinput and \c evtest utilities.
PlayStation controllers will likely need the help of an additional tool like
\l{https://github.com/xboxdrv/xboxdrv}{xboxdrv}. Once installed, and having a
PS3 controller connected via USB, the following will ensure correct operation
with QtGamepad:
\badcode
sudo xboxdrv --detach-kernel-driver --mimic-xpad -s
\endcode
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:
\list
\li \c evdev - a backend reading events directly from the evdev input device
\li \c 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.
\endlist
To force a given backend, set the \c QT_GAMEPAD environment variable to the
name of the desired backend.
The availability of gamepad devices is monitored via \c 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 \c evdev backend, to explicitly specify the input device to use, set
the environment variable \c{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.
\section2 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 \uicontrol{Control Panel > Device and Printers}
and check if the gamepad is listed under the \uicontrol Devices section.
To test whether gamepad input is detected, select
\uicontrol {Gamepad Controller Settings} from the context menu, select
\uicontrol {Properties > Test}, and start testing. You can also run the
\l{Qt Gamepad Qt Quick Example}{quickGamepad} example to test.
\section2 Android
The Android backend uses the \c InputDevice API.
\section2 macOS, iOS, tvOS
This backend uses the \c GCController API.
Besides game controllers, it also supports the tvOS remote (microGamepad). The
mapping for this is the following:
\list
\li \c{X button} - play/pause
\li \c{A button} - pressing the touch area
\li \c{left thumbstick} - the touch area
\endlist
\section2 Troubleshooting
Some backends (\c evdev on Linux and \c xinput on Windows) and the plugin
loader utilize the logging category \c{qt.gamepad}. Enabling this will print
useful information on the debug output.
\section1 Examples
The \l{Qt Gamepad Examples}{examples} demonstrate how to handle input from a
gamepad using the QML and C++ APIs.
\section1 API Reference
\list
\li \l{Qt Gamepad QML Types}
\li \l{Qt Gamepad C++ Classes}
\endlist
*/
|
