]> git.saurik.com Git - wxWidgets.git/blobdiff - wxPython/demo/Joystick.py
Docsrings for wxSplitterWindow
[wxWidgets.git] / wxPython / demo / Joystick.py
index 03ba8e98c7cbc9b75c768f0f44e7b9cef6aab30f..219dbd139f0d59ba01c37308cd7f9cf16466ec21 100644 (file)
@@ -5,7 +5,7 @@
 # Author:      Jeff Grimmett (grimmtoo@softhome.net), adapted from original
 #              .wdr-derived demo
 #
 # Author:      Jeff Grimmett (grimmtoo@softhome.net), adapted from original
 #              .wdr-derived demo
 #
-# Created:     01/02/04
+# Created:     02-Jan-2004
 # RCS-ID:      $Id$
 # Copyright:
 # Licence:     wxWindows license
 # RCS-ID:      $Id$
 # Copyright:
 # Licence:     wxWindows license
 import  math
 import  wx
 
 import  math
 import  wx
 
+haveJoystick = True
+if wx.Platform == "__WXMAC__":
+    haveJoystick = False
+
 #----------------------------------------------------------------------------
 
 #----------------------------------------------------------------------------
 
-# For convenience
-spacer = (10, 10)
+# Once all supported versions of Python support 32-bit integers on all
+# platforms, this can go up to 32.
 MAX_BUTTONS = 16
 
 #----------------------------------------------------------------------------
 MAX_BUTTONS = 16
 
 #----------------------------------------------------------------------------
@@ -963,14 +967,115 @@ class JoystickDemoPanel(wx.Panel):
 #----------------------------------------------------------------------------
 
 def runTest(frame, nb, log):
 #----------------------------------------------------------------------------
 
 def runTest(frame, nb, log):
-    win = JoystickDemoPanel(nb, log)
-    return win
+    if haveJoystick:
+        win = JoystickDemoPanel(nb, log)
+        return win
+    else:
+        dlg = wx.MessageDialog(
+                frame, 'wx.Joystick is not available on this platform.',
+                'Sorry', wx.OK | wx.ICON_INFORMATION
+                )
+        dlg.ShowModal()
+        dlg.Destroy()
+    
 
 #----------------------------------------------------------------------------
 
 overview = """\
 
 #----------------------------------------------------------------------------
 
 overview = """\
-
-
+<html>
+<body>
+<h1>wx.Joystick</h1>
+This demo illustrates the use of the wx.Joystick class, which is an interface to
+one or more joysticks attached to your system.
+
+<p>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 <b>can</b> get from the wx.Joystick control.
+
+<ul>
+<li>Static information such as Manufacturer ID and model name,
+<li>Analog input from up to six axes, including X and Y for the actual stick,
+<li>Button input from the fire button and any other buttons that the stick has,
+<li>and the POV control (a kind of mini-joystick on top of the joystick) that many sticks come with.
+</ul>
+
+<p>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.
+
+<h2>Data types</h2>
+
+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.
+
+<h3>Analog Input</h3>
+
+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 compass showing the relationship
+of that input to the calculated 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.
+
+<h3>Button Input</h3>
+
+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
+
+<pre>
+     # assume buttonState is what the stick returned, and buttonBit 
+     # is the bit you want to examine
+     
+     if (buttonState & ( 1 &lt;&lt; buttonBit )) :
+         # button pressed, do something with it
+</pre>
+
+<p>The problem here is that some OSs return a 32-bit value for up to 32 buttons 
+(imagine <i>that</i> stick!). Python V2.3 will generate an exception for bit 
+values over 30. For that reason, this demo is limited to 16 buttons.
+
+<p>Note that more than one button can be pressed at a time, so be sure to check all of them!
+     
+
+<h3>POV Input</h3>
+
+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 considered to be to the right of the decimal point, so in order to 
+use this information, you need to divide by 100 right off the bat. 
+
+<p>Different methods are provided to retrieve the POV data for a CTS hat 
+versus a four-way hat.
+
+<h2>Caveats</h2>
+
+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 <i>can</i> 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.
+
+<ul>
+<li>There are no events associated with the POV control.
+<li>There are no events associated with the Rudder
+<li>There are no events associated with the U and V axes.
+</ul>
+
+<p>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. 
+
+<p>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().
+
+</body>
+</html>
 """
 
 #----------------------------------------------------------------------------
 """
 
 #----------------------------------------------------------------------------
@@ -978,4 +1083,4 @@ overview = """\
 if __name__ == '__main__':
     import sys,os
     import run
 if __name__ == '__main__':
     import sys,os
     import run
-    run.main(['', os.path.basename(sys.argv[0])])
+    run.main(['', os.path.basename(sys.argv[0])] + sys.argv[1:])