diff --git a/wxPython/demo/Joystick.py b/wxPython/demo/Joystick.py index 03ba8e98c7..8704c867d7 100644 --- a/wxPython/demo/Joystick.py +++ b/wxPython/demo/Joystick.py @@ -969,8 +969,100 @@ def runTest(frame, nb, log): #---------------------------------------------------------------------------- overview = """\ + + +

wx.Joystick

+This demo illustrates the use of the wx.Joystick class, which is an interface to +one or more joysticks attached to your system. +

The data that can be retrieved from the joystick comes in four basic flavors. +All of these are illustrated in the demo. In fact, this demo illustrates everything +you can get from the wx.Joystick control. +

+ +

Getting data from the joystick can be event-driven thanks to four event types associated +with wx.JoystickEvent, or the joystick can be polled programatically to get data on +a regular basis. + +

Data types

+ +Data from the joystick comes in two flavors: that which defines the boundaries, and that +which defines the current state of the stick. Thus, we have Get*Max() and Get*Min() +methods for all axes, the max number of axes, the max number of buttons, and so on. In +general, this data can be read once and stored to speed computation up. + +

Analog Input

+ +Analog input (the axes) is delivered as a whole, positive number. If you need to know +if the axis is at zero (centered) or not, you will first have to calculate that center +based on the max and min values. The demo shows a bar graph for each axis expressed +in native numerical format, plus a 'centered' X-Y axis compas showing the relationship +of that input to the calculcated stick position. + +Analog input may be jumpy and spurious, so the control has a means of 'smoothing' the +analog data by setting a movement threshold. This demo sets the threshold to 10, but +you can set it at any valid value between the min and max. + +

Button Input

+ +Button state is retrieved as one int that contains each button state mapped to a bit. +You get the state of a button by AND-ing its bit against the returned value, in the form + +
+     # assume buttonState is what the stick returned, and buttonBit 
+     # is the bit you want to examine
+     
+     if (buttonState & ( 1 << buttonBit )) :
+         # button pressed, do something with it
+
+ +

The problem here is that some OSs return a 32-bit value for up to 32 buttons +(imagine that stick!). Python V2.3 will generate an exception for bit +values over 30. For that reason, this demo is limited to 16 buttons. + +

Note that more than one button can be pressed at a time, so be sure to check all of them! + + +

POV Input

+ +POV hats come in two flavors: four-way, and continuous. four-way POVs are restricted to +the cardinal points of the compass; continuous, or CTS POV hats can deliver input in +.01 degree increments, theoreticaly. The data is returned as a whole number; the last +two digits are to the right of the decimal point, so in order to use this information, +you need to divide by 100 right off the bat. + +

Different methods are provided to retrieve the POV data for a CTS hat +versus a four-way hat. + +

Caveats

+ +The wx.Joystick control is in many ways incomplete at the C++ library level, but it is +not insurmountable. In short, while the joystick interface can be event-driven, +the wx.JoystickEvent class lacks event binders for all event types. Thus, you cannot +rely on wx.JoystickEvents to tell you when something has changed, necessarilly. + + + +

Fortunately, there is an easy workaround. In the top level frame, create a wx.Timer +that will poll the stick at a set interval. Of course, if you do this, you might as +well forgo catching wxEVT_JOYSTICK_* events at all and rely on the timer to do the +polling. + +

Ideally, the timer should be a one-shot; after it fires, collect and process data as +needed, then re-start the timer, possibly using wx.CallAfter(). + + + """ #----------------------------------------------------------------------------