From f2f2b6153a2a818ca940a4df5b7dafc743ef2d2f Mon Sep 17 00:00:00 2001
From: Mitchell Stokes <mogurijin@gmail.com>
Date: Fri, 21 Dec 2012 02:28:59 +0000
Subject: BGE: Adding a Python interface for handling joysticks without needing
 logic bricks. These new SCA_PythonJoystick objects can be accessed using
 bge.logic.joysticks, which is a list of joysticks. The length of the list is
 the number of maximum supported joysticks, and indexes that do not have a
 joystick available are set to None. This means joysticks can be checked for
 using something like:

if bge.logic.joysticks[0]:
    activate_player_one()

if bge.logic.joysticks[1]:
    activate_player_two()

etc..

The interface exposed by SCA_PythonJoystick is very similar to the joystick logic brick except for one key difference: axis values are normalized to a -1.0 to 1.0 range instead of -32767 to 32767, which is what the logic brick exposed.
---
 doc/python_api/rst/bge.logic.rst |  4 +++
 doc/python_api/rst/bge.types.rst | 72 ++++++++++++++++++++++++++++++++++++++--
 2 files changed, 74 insertions(+), 2 deletions(-)

(limited to 'doc')

diff --git a/doc/python_api/rst/bge.logic.rst b/doc/python_api/rst/bge.logic.rst
index 7d20aa31a36..ee39f7659ca 100644
--- a/doc/python_api/rst/bge.logic.rst
+++ b/doc/python_api/rst/bge.logic.rst
@@ -125,6 +125,10 @@ Variables
 
    The current mouse wrapped in an :class:`~bge.types.SCA_PythonMouse` object.
 
+.. data:: joysticks
+
+   A list of attached joysticks. The list size it he maximum number of supported joysticks. If no joystick is available for a given slot, the slot is set to None.
+
 *****************
 General functions
 *****************
diff --git a/doc/python_api/rst/bge.types.rst b/doc/python_api/rst/bge.types.rst
index 8cf9ccb794c..85429a00791 100644
--- a/doc/python_api/rst/bge.types.rst
+++ b/doc/python_api/rst/bge.types.rst
@@ -141,6 +141,74 @@ Types
       
       :type: boolean
 
+.. class:: SCA_PythonJoystick(PyObjectPlus)
+
+   A Python interface to a joystick.
+
+   .. attribute:: name
+
+      The name assigned to the joystick by the operating system. (read-only)
+	  
+      :type: string
+
+   .. attribute:: activeButtons
+
+      A list of active button values. (read-only)
+	  
+      :type: list
+
+   .. attribute:: axisValues
+
+      The state of the joysticks axis as a list of values :data:`numAxis` long. (read-only).
+
+      :type: list of ints.
+
+      Each specifying the value of an axis between -1.0 and 1.0 depending on how far the axis is pushed, 0 for nothing.
+      The first 2 values are used by most joysticks and gamepads for directional control. 3rd and 4th values are only on some joysticks and can be used for arbitary controls.
+
+      * left:[-1.0, 0.0, ...]
+      * right:[1.0, 0.0, ...]
+      * up:[0.0, -1.0, ...]
+      * down:[0.0, 1.0, ...]
+
+   .. attribute:: hatValues
+
+      The state of the joysticks hats as a list of values :data:`numHats` long. (read-only).
+
+      :type: list of ints
+
+      Each specifying the direction of the hat from 1 to 12, 0 when inactive.
+
+      Hat directions are as follows...
+
+      * 0:None
+      * 1:Up
+      * 2:Right
+      * 4:Down
+      * 8:Left
+      * 3:Up - Right
+      * 6:Down - Right
+      * 12:Down - Left
+      * 9:Up - Left
+
+   .. attribute:: numAxis
+
+      The number of axes for the joystick at this index. (read-only).
+
+      :type: integer
+
+   .. attribute:: numButtons
+
+      The number of buttons for the joystick at this index. (read-only).
+
+      :type: integer
+
+   .. attribute:: numHats
+
+      The number of hats for the joystick at this index. (read-only).
+
+      :type: integer
+
 .. class:: SCA_IObject(CValue)
 
    This class has no python functions
@@ -3977,7 +4045,7 @@ Types
 
       :type: list of ints.
 
-      Each spesifying the value of an axis between -32767 and 32767 depending on how far the axis is pushed, 0 for nothing.
+      Each specifying the value of an axis between -32767 and 32767 depending on how far the axis is pushed, 0 for nothing.
       The first 2 values are used by most joysticks and gamepads for directional control. 3rd and 4th values are only on some joysticks and can be used for arbitary controls.
 
       * left:[-32767, 0, ...]
@@ -4001,7 +4069,7 @@ Types
 
       :type: list of ints
 
-      Each spesifying the direction of the hat from 1 to 12, 0 when inactive.
+      Each specifying the direction of the hat from 1 to 12, 0 when inactive.
 
       Hat directions are as follows...
 
-- 
cgit v1.2.3