- fixed errors with bge epydocs
[blender.git] / source / gameengine / PyDoc / SCA_JoystickSensor.py
1 # $Id$
2 # Documentation for SCA_RandomSensor
3 from SCA_ISensor import *
4
5 class SCA_JoystickSensor(SCA_ISensor):
6         """
7         This sensor detects player joystick events.
8         
9         Properties:
10         
11         @ivar axisPosition: (read-only) The state of the joysticks axis as a list of 4 values, each spesifying the value of an axis between -32767 and 32767 depending on how far the axis is pushed, 0 for nothing. 
12                             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.
13                             left:[-32767, 0, ...], right:[32767, 0, ...], up:[0, -32767, ...], down:[0, 32767, ...]
14         @type axisPosition: [integer, integer, integer, integer]
15         @ivar numAxis: (read-only) The number of axes for the joystick at this index.
16         @type numAxis: integer
17         @ivar numButtons: (read-only) The number of buttons for the joystick at this index.
18         @type numButtons: integer
19         @ivar numHats: (read-only) The number of hats for the joystick at this index.
20         @type numHats: integer
21         @ivar connected: (read-only) True if a joystick is connected at this joysticks index.
22         @type connected: boolean
23         @ivar index: The joystick index to use (from 0 to 7). The first joystick is always 0.
24         @type index: integer
25         @ivar threshold: Axis threshold. Joystick axis motion below this threshold wont trigger an event. Use values between (0 and 32767), lower values are more sensitive.
26         @type threshold: integer
27         @ivar button: The button index the sensor reacts to (first button = 0). When the "All Events" toggle is set, this option has no effect.
28         @type button: integer
29         @ivar axis: The axis this sensor reacts to, as a list of two values [axisIndex, axisDirection]
30                     axisIndex: the axis index to use when detecting axis movement, 1=primary directional control, 2=secondary directional control.
31                     axisDirection: 0=right, 1=up, 2=left, 3=down
32         @type axis: [integer, integer]
33         @ivar hat: The hat the sensor reacts to, as a list of two values: [hatIndex, hatDirection]
34                     hatIndex: the hat index to use when detecting hat movement, 1=primary hat, 2=secondary hat.
35                     hatDirection: 0-11
36         @type hat: [integer, integer]
37         """
38         
39         def getButtonActiveList():
40                 """
41                 Returns a list containing the indicies of the currently pressed buttons.
42                 @rtype: list
43                 """
44         def getButtonStatus(buttonIndex):
45                 """
46                 Returns a bool of the current pressed state of the specified button.
47                 @param buttonIndex: the button index, 0=first button
48                 @type buttonIndex: integer
49                 @rtype: bool
50                 """
51         def getIndex():
52                 """
53                 DEPRECATED: use the 'index' property.
54                 Returns the joystick index to use (from 1 to 8).
55                 @rtype: integer
56                 """
57         def setIndex(index):
58                 """
59                 DEPRECATED: use the 'index' property.
60                 Sets the joystick index to use. 
61                 @param index: The index of this joystick sensor, Clamped between 1 and 8.
62                 @type index: integer
63                 @note: This is only useful when you have more then 1 joystick connected to your computer - multiplayer games.
64                 """
65         def getAxis():
66                 """
67                 DEPRECATED: use the 'axis' property.
68                 Returns the current axis this sensor reacts to. See L{getAxisValue()<SCA_JoystickSensor.getAxisValue>} for the current axis state.
69                 @rtype: list
70                 @return: 2 values returned are [axisIndex, axisDirection] - see L{setAxis()<SCA_JoystickSensor.setAxis>} for their purpose.
71                 @note: When the "All Events" toggle is set, this option has no effect.
72                 """
73         def setAxis(axisIndex, axisDirection):
74                 """
75                 DEPRECATED: use the 'axis' property.
76                 @param axisIndex: Set the axis index to use when detecting axis movement.
77                 @type axisIndex: integer from 1 to 2
78                 @param axisDirection: Set the axis direction used for detecting motion. 0:right, 1:up, 2:left, 3:down.
79                 @type axisDirection: integer from 0 to 3
80                 @note: When the "All Events" toggle is set, this option has no effect.
81                 """
82         def getAxisValue():
83                 """
84                 DEPRECATED: use the 'axisPosition' property.
85                 Returns the state of the joysticks axis. See differs to L{getAxis()<SCA_JoystickSensor.getAxis>} returning the current state of the joystick.
86                 @rtype: list
87                 @return: 4 values, each spesifying the value of an axis between -32767 and 32767 depending on how far the axis is pushed, 0 for nothing. 
88
89                         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.
90
91                         left:[-32767, 0, ...], right:[32767, 0, ...], up:[0, -32767, ...], down:[0, 32767, ...]
92                 @note: Some gamepads only set the axis on and off like a button.
93                 """
94         def getThreshold():
95                 """
96                 DEPRECATED: use the 'threshold' property.
97                 Get the axis threshold. See L{setThreshold()<SCA_JoystickSensor.setThreshold>} for details.
98                 @rtype: integer
99                 """
100         def setThreshold(threshold):
101                 """
102                 DEPRECATED: use the 'threshold' property.
103                 Set the axis threshold.
104                 @param threshold: Joystick axis motion below this threshold wont trigger an event. Use values between (0 and 32767), lower values are more sensitive.
105                 @type threshold: integer
106                 """
107         def getButton():
108                 """
109                 DEPRECATED: use the 'button' property.
110                 Returns the button index the sensor reacts to. See L{getButtonValue()<SCA_JoystickSensor.getButtonValue>} for a list of pressed buttons.
111                 @rtype: integer
112                 @note: When the "All Events" toggle is set, this option has no effect.
113                 """
114         def setButton(index):
115                 """
116                 DEPRECATED: use the 'button' property.
117                 Sets the button index the sensor reacts to when the "All Events" option is not set.
118                 @note: When the "All Events" toggle is set, this option has no effect.
119                 """
120         def getButtonValue():
121                 """
122                 DEPRECATED: use the 'getButtonActiveList' method.
123                 Returns a list containing the indicies of the currently pressed buttons.
124                 @rtype: list
125                 """
126         def getHat():
127                 """
128                 DEPRECATED: use the 'hat' property.
129                 Returns the current hat direction this sensor is set to.
130                 [hatNumber, hatDirection].
131                 @rtype: list
132                 @note: When the "All Events" toggle is set, this option has no effect.
133                 """
134         def setHat(index,direction):
135                 """
136                 DEPRECATED: use the 'hat' property.
137                 Sets the hat index the sensor reacts to when the "All Events" option is not set.
138                 @type index: integer
139                 """
140         def getNumAxes():
141                 """
142                 DEPRECATED: use the 'numAxis' property.
143                 Returns the number of axes for the joystick at this index.
144                 @rtype: integer
145                 """
146         def getNumButtons():
147                 """
148                 DEPRECATED: use the 'numButtons' property.
149                 Returns the number of buttons for the joystick at this index.
150                 @rtype: integer
151                 """
152         def getNumHats():
153                 """
154                 DEPRECATED: use the 'numHats' property.
155                 Returns the number of hats for the joystick at this index.
156                 @rtype: integer
157                 """
158         def isConnected():
159                 """
160                 DEPRECATED: use the 'connected' property.
161                 Returns True if a joystick is detected at this joysticks index.
162                 @rtype: bool
163                 """