288 lines
9.1 KiB
Plaintext
288 lines
9.1 KiB
Plaintext
|
.. include:: common.txt
|
||
|
|
|
||
|
|
:mod:`pygame._sdl2.controller`
|
||
|
|
==============================
|
||
|
|
|
||
|
|
.. module:: pygame._sdl2.controller
|
||
|
|
:synopsis: pygame module to work with controllers
|
||
|
|
|
||
|
|
| :sl:`Pygame module to work with controllers.`
|
||
|
|
|
||
|
|
This module offers control over common controller types like the dualshock 4 or
|
||
|
|
the xbox 360 controllers: They have two analog sticks, two triggers, two shoulder buttons,
|
||
|
|
a dpad, 4 buttons on the side, 2 (or 3) buttons in the middle.
|
||
|
|
|
||
|
|
Pygame uses xbox controllers naming conventions (like a, b, x, y for buttons) but
|
||
|
|
they always refer to the same buttons. For example ``CONTROLLER_BUTTON_X`` is
|
||
|
|
always the leftmost button of the 4 buttons on the right.
|
||
|
|
|
||
|
|
Controllers can generate the following events::
|
||
|
|
|
||
|
|
CONTROLLERAXISMOTION, CONTROLLERBUTTONDOWN, CONTROLLERBUTTONUP,
|
||
|
|
CONTROLLERDEVICEREMAPPED, CONTROLLERDEVICEADDED, CONTROLLERDEVICEREMOVED
|
||
|
|
|
||
|
|
Additionally if pygame is built with SDL 2.0.14 or higher the following events can also be generated
|
||
|
|
(to get the version of sdl pygame is built with use :meth:`pygame.version.SDL`)::
|
||
|
|
|
||
|
|
CONTROLLERTOUCHPADDOWN, CONTROLLERTOUCHPADMOTION, CONTROLLERTOUCHPADUP
|
||
|
|
|
||
|
|
These events can be enabled/disabled by :meth:`pygame._sdl2.controller.set_eventstate`
|
||
|
|
Note that controllers can generate joystick events as well. This function only toggles
|
||
|
|
events related to controllers.
|
||
|
|
|
||
|
|
.. note::
|
||
|
|
See the :mod:`pygame.joystick` for a more versatile but more advanced api.
|
||
|
|
|
||
|
|
.. versionadded:: 2 This module requires SDL2.
|
||
|
|
|
||
|
|
.. function:: init
|
||
|
|
|
||
|
|
| :sl:`initialize the controller module`
|
||
|
|
| :sg:`init() -> None`
|
||
|
|
|
||
|
|
Initialize the controller module.
|
||
|
|
|
||
|
|
.. ## pygame._sdl2.controller.init ##
|
||
|
|
|
||
|
|
.. function:: quit
|
||
|
|
|
||
|
|
| :sl:`Uninitialize the controller module.`
|
||
|
|
| :sg:`quit() -> None`
|
||
|
|
|
||
|
|
Uninitialize the controller module.
|
||
|
|
|
||
|
|
.. ## pygame._sdl2.controller.quit ##
|
||
|
|
|
||
|
|
.. function:: get_init
|
||
|
|
|
||
|
|
| :sl:`Returns True if the controller module is initialized.`
|
||
|
|
| :sg:`get_init() -> bool`
|
||
|
|
|
||
|
|
Test if ``pygame._sdl2.controller.init()`` was called.
|
||
|
|
|
||
|
|
.. ## pygame._sdl2.controller.get_init ##
|
||
|
|
|
||
|
|
.. function:: set_eventstate
|
||
|
|
|
||
|
|
| :sl:`Sets the current state of events related to controllers`
|
||
|
|
| :sg:`set_eventstate(state) -> None`
|
||
|
|
|
||
|
|
Enable or disable events connected to controllers.
|
||
|
|
|
||
|
|
.. note::
|
||
|
|
Controllers can still generate joystick events, which will not be toggled by this function.
|
||
|
|
|
||
|
|
.. versionchanged:: 2.0.2: Changed return type from int to None
|
||
|
|
|
||
|
|
.. ## pygame._sdl2.controller.set_eventstate ##
|
||
|
|
|
||
|
|
.. function:: get_eventstate
|
||
|
|
|
||
|
|
| :sl:`Gets the current state of events related to controllers`
|
||
|
|
| :sg:`get_eventstate() -> bool`
|
||
|
|
|
||
|
|
Returns the current state of events related to controllers, True meaning
|
||
|
|
events will be posted.
|
||
|
|
|
||
|
|
.. versionadded:: 2.0.2
|
||
|
|
|
||
|
|
.. ## pygame._sdl2.controller.get_eventstate ##
|
||
|
|
|
||
|
|
.. function:: get_count
|
||
|
|
|
||
|
|
| :sl:`Get the number of joysticks connected`
|
||
|
|
| :sg:`get_count() -> int`
|
||
|
|
|
||
|
|
Get the number of joysticks connected.
|
||
|
|
|
||
|
|
.. ## pygame._sdl2.controller.get_count ##
|
||
|
|
|
||
|
|
.. function:: is_controller
|
||
|
|
|
||
|
|
| :sl:`Check if the given joystick is supported by the game controller interface`
|
||
|
|
| :sg:`is_controller(index) -> bool`
|
||
|
|
|
||
|
|
Returns True if the index given can be used to create a controller object.
|
||
|
|
|
||
|
|
.. ## pygame._sdl2.controller.is_controller ##
|
||
|
|
|
||
|
|
.. function:: name_forindex
|
||
|
|
|
||
|
|
| :sl:`Get the name of the controller`
|
||
|
|
| :sg:`name_forindex(index) -> name or None`
|
||
|
|
|
||
|
|
Returns the name of controller, or None if there's no name or the
|
||
|
|
index is invalid.
|
||
|
|
|
||
|
|
.. ## pygame._sdl2.controller.name_forindex ##
|
||
|
|
|
||
|
|
.. class:: Controller
|
||
|
|
|
||
|
|
| :sl:`Create a new Controller object.`
|
||
|
|
| :sg:`Controller(index) -> Controller`
|
||
|
|
|
||
|
|
Create a new Controller object. Index should be integer between
|
||
|
|
0 and ``pygame._sdl2.controller.get_count()``. Controllers also
|
||
|
|
can be created from a ``pygame.joystick.Joystick`` using
|
||
|
|
``pygame._sdl2.controller.from_joystick``. Controllers are
|
||
|
|
initialized on creation.
|
||
|
|
|
||
|
|
.. method:: quit
|
||
|
|
|
||
|
|
| :sl:`uninitialize the Controller`
|
||
|
|
| :sg:`quit() -> None`
|
||
|
|
|
||
|
|
Close a Controller object. After this the pygame event queue will no longer
|
||
|
|
receive events from the device.
|
||
|
|
|
||
|
|
It is safe to call this more than once.
|
||
|
|
|
||
|
|
.. ## Controller.quit ##
|
||
|
|
|
||
|
|
.. method:: get_init
|
||
|
|
|
||
|
|
| :sl:`check if the Controller is initialized`
|
||
|
|
| :sg:`get_init() -> bool`
|
||
|
|
|
||
|
|
Returns True if the Controller object is currently initialised.
|
||
|
|
|
||
|
|
.. ## Controller.get_init ##
|
||
|
|
|
||
|
|
.. staticmethod:: from_joystick
|
||
|
|
|
||
|
|
| :sl:`Create a Controller from a pygame.joystick.Joystick object`
|
||
|
|
| :sg:`from_joystick(joystick) -> Controller`
|
||
|
|
|
||
|
|
Create a Controller object from a ``pygame.joystick.Joystick`` object
|
||
|
|
|
||
|
|
.. ## Controller.from_joystick ##
|
||
|
|
|
||
|
|
.. method:: attached
|
||
|
|
|
||
|
|
| :sl:`Check if the Controller has been opened and is currently connected.`
|
||
|
|
| :sg:`attached() -> bool`
|
||
|
|
|
||
|
|
Returns True if the Controller object is opened and connected.
|
||
|
|
|
||
|
|
.. ## Controller.attached ##
|
||
|
|
|
||
|
|
.. method:: as_joystick
|
||
|
|
|
||
|
|
| :sl:`Returns a pygame.joystick.Joystick() object`
|
||
|
|
| :sg:`as_joystick() -> Joystick object`
|
||
|
|
|
||
|
|
Returns a pygame.joystick.Joystick() object created from this controller's index
|
||
|
|
|
||
|
|
.. ## Controller.as_joystick ##
|
||
|
|
|
||
|
|
.. method:: get_axis
|
||
|
|
|
||
|
|
| :sl:`Get the current state of a joystick axis`
|
||
|
|
| :sg:`get_axis(axis) -> int`
|
||
|
|
|
||
|
|
Get the current state of a trigger or joystick axis.
|
||
|
|
The axis argument must be one of the following constants::
|
||
|
|
|
||
|
|
CONTROLLER_AXIS_LEFTX, CONTROLLER_AXIS_LEFTY,
|
||
|
|
CONTROLLER_AXIS_RIGHTX, CONTROLLER_AXIS_RIGHTY,
|
||
|
|
CONTROLLER_AXIS_TRIGGERLEFT, CONTROLLER_AXIS_TRIGGERRIGHT
|
||
|
|
|
||
|
|
Joysticks can return a value between -32768 and 32767. Triggers however
|
||
|
|
can only return a value between 0 and 32768.
|
||
|
|
|
||
|
|
.. ## Controller.get_axis ##
|
||
|
|
|
||
|
|
.. method:: get_button
|
||
|
|
|
||
|
|
| :sl:`Get the current state of a button`
|
||
|
|
| :sg:`get_button(button) -> bool`
|
||
|
|
|
||
|
|
Get the current state of a button, True meaning it is pressed down.
|
||
|
|
The button argument must be one of the following constants::
|
||
|
|
|
||
|
|
CONTROLLER_BUTTON_A, CONTROLLER_BUTTON_B,
|
||
|
|
CONTROLLER_BUTTON_X, CONTROLLER_BUTTON_Y
|
||
|
|
CONTROLLER_BUTTON_DPAD_UP, CONTROLLER_BUTTON_DPAD_DOWN,
|
||
|
|
CONTROLLER_BUTTON_DPAD_LEFT, CONTROLLER_BUTTON_DPAD_RIGHT,
|
||
|
|
CONTROLLER_BUTTON_LEFTSHOULDER, CONTROLLER_BUTTON_RIGHTSHOULDER,
|
||
|
|
CONTROLLER_BUTTON_LEFTSTICK, CONTROLLER_BUTTON_RIGHTSTICK,
|
||
|
|
CONTROLLER_BUTTON_BACK, CONTROLLER_BUTTON_GUIDE,
|
||
|
|
CONTROLLER_BUTTON_START
|
||
|
|
|
||
|
|
|
||
|
|
.. ## Controller.get_button ##
|
||
|
|
|
||
|
|
.. method:: get_mapping
|
||
|
|
|
||
|
|
| :sl:`Get the mapping assigned to the controller`
|
||
|
|
| :sg:`get_mapping() -> mapping`
|
||
|
|
|
||
|
|
Returns a dict containing the mapping of the Controller. For more
|
||
|
|
information see :meth:`Controller.set_mapping()`
|
||
|
|
|
||
|
|
.. versionchanged:: 2.0.2: Return type changed from ``str`` to ``dict``
|
||
|
|
|
||
|
|
.. ## Contorller.get_mapping ##
|
||
|
|
|
||
|
|
.. method:: set_mapping
|
||
|
|
|
||
|
|
| :sl:`Assign a mapping to the controller`
|
||
|
|
| :sg:`set_mapping(mapping) -> int`
|
||
|
|
|
||
|
|
Rebind buttons, axes, triggers and dpads. The mapping should be a
|
||
|
|
dict containing all buttons, hats and axes. The easiest way to get this
|
||
|
|
is to use the dict returned by :meth:`Controller.get_mapping`. To edit
|
||
|
|
this mapping assign a value to the original button. The value of the
|
||
|
|
dictionary must be a button, hat or axis represented in the following way:
|
||
|
|
|
||
|
|
* For a button use: bX where X is the index of the button.
|
||
|
|
* For a hat use: hX.Y where X is the index and the Y is the direction (up: 1, right: 2, down: 3, left: 4).
|
||
|
|
* For an axis use: aX where x is the index of the axis.
|
||
|
|
|
||
|
|
An example of mapping::
|
||
|
|
|
||
|
|
mapping = controller.get_mapping() # Get current mapping
|
||
|
|
mapping["a"] = "b3" # Remap button a to y
|
||
|
|
mapping["y"] = "b0" # Remap button y to a
|
||
|
|
controller.set_mapping(mapping) # Set the mapping
|
||
|
|
|
||
|
|
|
||
|
|
The function will return 1 if a new mapping is added or 0 if an existing one is updated.
|
||
|
|
|
||
|
|
.. versionchanged:: 2.0.2: Renamed from ``add_mapping`` to ``set_mapping``
|
||
|
|
.. versionchanged:: 2.0.2: Argument type changed from ``str`` to ``dict``
|
||
|
|
|
||
|
|
.. ## Contorller.set_mapping ##
|
||
|
|
|
||
|
|
.. method:: rumble
|
||
|
|
|
||
|
|
| :sl:`Start a rumbling effect`
|
||
|
|
| :sg:`rumble(low_frequency, high_frequency, duration) -> bool`
|
||
|
|
|
||
|
|
Start a rumble effect on the controller, with the specified strength ranging
|
||
|
|
from 0 to 1. Duration is length of the effect, in ms. Setting the duration
|
||
|
|
to 0 will play the effect until another one overwrites it or
|
||
|
|
:meth:`Controller.stop_rumble` is called. If an effect is already
|
||
|
|
playing, then it will be overwritten.
|
||
|
|
|
||
|
|
Returns True if the rumble was played successfully or False if the
|
||
|
|
controller does not support it or :meth:`pygame.version.SDL` is below 2.0.9.
|
||
|
|
|
||
|
|
.. versionadded:: 2.0.2
|
||
|
|
|
||
|
|
.. ## Contorller.rumble ##
|
||
|
|
|
||
|
|
.. method:: stop_rumble
|
||
|
|
|
||
|
|
| :sl:`Stop any rumble effect playing`
|
||
|
|
| :sg:`stop_rumble() -> None`
|
||
|
|
|
||
|
|
Stops any rumble effect playing on the controller. See
|
||
|
|
:meth:`Controller.rumble` for more information.
|
||
|
|
|
||
|
|
.. versionadded:: 2.0.2
|
||
|
|
|
||
|
|
.. ## Contorller.stop_rumble ##
|
||
|
|
|
||
|
|
.. ## pygame._sdl2.controller ##
|