:mod:`pygame2.sdl.joystick` -- SDL joystick I/O wrapper wrapper module
======================================================================

The joystick module manages the joystick devices on a computer
(there can be more than one). Joystick devices include trackballs
and video-game-style gamepads, and the module allows the use of
multiple buttons and "hats".


.. module:: pygame2.sdl.joystick
   :synopsis: SDL joystick I/O wrapper wrapper module

Module Functions
----------------
.. function:: get_name (index) -> str

  Gets the physical device name of a Joystick.

  Gets the physical device name of a Joystick. The *index*
  specifies the device to get the name for and must be in the range [0,
  :meth:`num_joysticks` - 1].



.. function:: init () -> None

  Initializes the joystick subsystem of the SDL library.



.. function:: num_joysticks () -> int

  Gets the number of detected and available joysticks for the system.



.. function:: opened (index) -> bool

  Gets, whether the specified joystick is opened for access or not.

  Gets, whether the specified joystick is opened for access or
  not. The *index* specifies the joystick device to get the state for
  and must be in the range [0, :meth:`num_joysticks` - 1].



.. function:: quit () -> None

  Shuts down the joystick subsystem of the SDL library.

  Shuts down the joystick subsystem of the SDL library and closes all
  existing Joystick objects (leaving them intact).

  After calling this function, you should not invoke any class,
  method or function related to the joystick subsystem as they are
  likely to fail or might give unpredictable results.



.. function:: event_state (state) -> int

  Enables or disable joystick event polling.

  Enables or disables joystick event processing. If the joystick
  event processing is disabled, you will have to update the joystick
  states manually using :meth:`update` and read the information
  manually using the specific attributes and methods. Otherwise,
  joystick events are consumed and process by the
  :mod:`pygame2.sdl.event` module.

  The *state* argument can be :const:`ENABLE` or :const:`IGNORE` for
  enabling or disabling the event processing or :const:`QUERY` to receive
  the current state. The return value also will be one of those three
  constants.



.. function:: update () -> None

  Updates the joystick states (in case event processing is disabled).



.. function:: was_init () -> bool

  Returns, whether the joystick subsystem of the SDL library is
  initialized.



Joystick
--------
.. class:: Joystick (index) -> Joystick

  Creates a new Joystick object for the specified physical device.

  The Joystick object allows you to access information about the
  underlying physical device, such as the axes, hats and button
  states.

  The *index* must be in the range [0,
  :meth:`pygame2.sdl.joystick.num_joysticks` - 1].  This will also
  open the Joystick initially.


Attributes
^^^^^^^^^^
.. attribute:: Joystick.index

  Gets the physical device index of the Joystick.

.. attribute:: Joystick.name

  Gets the physical device name of the Joystick.

.. attribute:: Joystick.num_axes

  Gets the number of axes available on the Joystick.

.. attribute:: Joystick.num_balls

  Gets the number of balls available on the Joystick.

.. attribute:: Joystick.num_buttons

  Gets the number of buttons available on the Joystick.

.. attribute:: Joystick.num_hats

  Gets the number of hats available on the Joystick.

.. attribute:: Joystick.opened

  Gets, whether the Joystick is open or not.

Methods
^^^^^^^
.. method:: Joystick.close () -> None

  Closes the access to the underlying joystick device.

  Calling or accessing any other method or attribute of the
  Joystick after closing it will cause an exception to be
  thrown. To reaccess the Joystick, you have to :meth:`open` it
  again.


.. method:: Joystick.get_axis (index) -> int

  Gets the current position of the specified axis.

  Gets the current position of the specified axis. The axis *index*
  must be a valid value within the range [0, :attr:`num_axes` - 1].


.. method:: Joystick.get_ball (index) -> int, int

  Gets the relative movement of a trackball.

  Gets the relative movement of a trackball since the last call to
  :meth:`get_ball`. The ball *index* must be a valid value within the
  range [0, :attr:`num_balls` - 1].


.. method:: Joystick.get_button (index) -> bool

  Gets the state of a button.

  Gets the current pressed state of a button. The button *index*
  must be a valid value within the range [0, :attr:`num_buttons` - 1].


.. method:: Joystick.get_hat (index) -> int

  Gets the state of a hat.

  Gets the current state of a hat. The return value will be a
  bitwise OR'd combination of the hat constants as specified in the
  :mod:`pygame2.sdl.constants` module. The hat *index* must be a valid
  value within the range [0, :attr:`num_hats` - 1].


.. method:: Joystick.open () -> None

  Opens the (closed) Joystick.

  Opens the (closed) Joystick. If the Joystick is already open, this
  method will have no effect.



