.. 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 contoller`
    | :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.contoller.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 ##