Mercurial > pygame
view docs/ref/joystick.html @ 3172:d1b367fc08bc tests-returncode
Use a return code of 1 when the tests fail.
| author | Thomas Kluyver <takowl@gmail.com> |
|---|---|
| date | Wed, 09 Jan 2013 10:13:57 +0000 |
| parents | 0a3be7313aa4 |
| children |
line wrap: on
line source
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> <html xmlns="http://www.w3.org/1999/xhtml"> <head> <meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> <title>pygame.joystick — Pygame v1.9.2 documentation</title> <link rel="stylesheet" href="../_static/pygame.css" type="text/css" /> <link rel="stylesheet" href="../_static/pygments.css" type="text/css" /> <script type="text/javascript"> var DOCUMENTATION_OPTIONS = { URL_ROOT: '../', VERSION: '1.9.2', COLLAPSE_INDEX: false, FILE_SUFFIX: '.html', HAS_SOURCE: true }; </script> <script type="text/javascript" src="../_static/jquery.js"></script> <script type="text/javascript" src="../_static/underscore.js"></script> <script type="text/javascript" src="../_static/doctools.js"></script> <link rel="shortcut icon" href="../_static/pygame.ico"/> <link rel="top" title="Pygame v1.9.2 documentation" href="../index.html" /> <link rel="next" title="pygame.key" href="key.html" /> <link rel="prev" title="pygame.image" href="image.html" /> </head> <body> <div class="document"> <div class="header"> <table> <tr> <td class="logo"> <a href="http://www.pygame.org/"> <img src="../_static/pygame_tiny.png"/> </a> <h5>pygame documentation</h5> </td> <td class="pagelinks"> <p class="top"> || <a href="http://www.pygame.org/">Pygame Home</a> || <a href="../index.html">Help Contents</a> || <a href="../genindex.html">Reference Index</a> || </p> <p class="bottom"> <a href="camera.html">camera</a> || <a href="cdrom.html">cdrom</a> || <a href="color.html">Color</a> || <a href="cursors.html">cursors</a> || <a href="display.html">display</a> || <a href="draw.html">draw</a> || <a href="event.html">event</a> || <a href="examples.html">examples</a> || <a href="font.html">font</a> || <a href="freetype.html">freetype</a> || <a href="gfxdraw.html">gfxdraw</a> || <a href="image.html">image</a> || <a href="joystick.html">joystick</a> || <a href="key.html">key</a> || <a href="locals.html">locals</a> || <a href="mask.html">mask</a> || <a href="math.html">math</a> || <a href="midi.html">midi</a> || <a href="mixer.html">mixer</a> || <a href="mouse.html">mouse</a> || <a href="movie.html">movie</a> || <a href="music.html">music</a> || <a href="overlay.html">Overlay</a> || <a href="pixelarray.html">PixelArray</a> || <a href="pixelcopy.html">pixelcopy</a> || <a href="pygame.html">pygame</a> || <a href="rect.html">Rect</a> || <a href="scrap.html">scrap</a> || <a href="sndarray.html">sndarray</a> || <a href="sprite.html">sprite</a> || <a href="surface.html">Surface</a> || <a href="surfarray.html">surfarray</a> || <a href="tests.html">tests</a> || <a href="time.html">time</a> || <a href="transform.html">transform</a> || <a href="pygame.html#module-pygame.version">version</a> </p> </td> </tr> </table> </div> <div class="documentwrapper"> <div class="body"> <div class="sectionwrapper"> <div class="section" id="module-pygame.joystick"> <span id="pygame-joystick"></span><dl class="definition module"> <dt class="title module"> <tt class="docutils literal"><span class="pre">pygame.joystick</span></tt></dt> <dd><div class="line-block"> <div class="line"><span class="summaryline">pygame module for interacting with joystick devices</span></div> </div> <table border="1" class="toc docutils"> <colgroup> <col width="34%" /> <col width="1%" /> <col width="65%" /> </colgroup> <tbody valign="top"> <tr><td><a class="toc reference external" href="joystick.html#pygame.joystick.init">pygame.joystick.init</a></td> <td>—</td> <td>initialize the joystick module</td> </tr> <tr><td><a class="toc reference external" href="joystick.html#pygame.joystick.quit">pygame.joystick.quit</a></td> <td>—</td> <td>uninitialize the joystick module</td> </tr> <tr><td><a class="toc reference external" href="joystick.html#pygame.joystick.get_init">pygame.joystick.get_init</a></td> <td>—</td> <td>true if the joystick module is initialized</td> </tr> <tr><td><a class="toc reference external" href="joystick.html#pygame.joystick.get_count">pygame.joystick.get_count</a></td> <td>—</td> <td>number of joysticks on the system</td> </tr> <tr><td><a class="toc reference external" href="joystick.html#pygame.joystick.Joystick">pygame.joystick.Joystick</a></td> <td>—</td> <td>create a new Joystick object</td> </tr> </tbody> </table> <p>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”.</p> <p>To get initialise the joystick module and get a list of Joystick instances use the following code:</p> <div class="highlight-python"><div class="highlight"><pre><span class="n">pygame</span><span class="o">.</span><span class="n">joystick</span><span class="o">.</span><span class="n">init</span><span class="p">()</span> <span class="n">joysticks</span> <span class="o">=</span> <span class="p">[</span><span class="n">pygame</span><span class="o">.</span><span class="n">joystick</span><span class="o">.</span><span class="n">Joystick</span><span class="p">(</span><span class="n">x</span><span class="p">)</span> <span class="k">for</span> <span class="n">x</span> <span class="ow">in</span> <span class="nb">range</span><span class="p">(</span><span class="n">pygame</span><span class="o">.</span><span class="n">joystick</span><span class="o">.</span><span class="n">get_count</span><span class="p">())]</span> </pre></div> </div> <p>The following event types will be generated by the joysticks</p> <div class="highlight-python"><pre>JOYAXISMOTION JOYBALLMOTION JOYBUTTONDOWN JOYBUTTONUP JOYHATMOTION</pre> </div> <p>The event queue needs to be pumped frequently for some of the methods to work. So call one of pygame.event.get, pygame.event.wait, or pygame.event.pump regularly.</p> <dl class="definition function"> <dt class="title" id="pygame.joystick.init"> <tt class="descclassname">pygame.joystick.</tt><tt class="descname">init</tt><big>(</big><big>)</big><a class="headerlink" href="#pygame.joystick.init" title="Permalink to this definition">¶</a></dt> <dd><div class="line-block"> <div class="line"><span class="summaryline">initialize the joystick module</span></div> <div class="line"><span class="signature">init() -> None</span></div> </div> <p>This function is called automatically by <tt class="docutils literal"><span class="pre">pygame.init()</span></tt>.</p> <p>It initializes the joystick module. This will scan the system for all joystick devices. The module must be initialized before any other functions will work.</p> <p>It is safe to call this function more than once.</p> </dd></dl> <dl class="definition function"> <dt class="title" id="pygame.joystick.quit"> <tt class="descclassname">pygame.joystick.</tt><tt class="descname">quit</tt><big>(</big><big>)</big><a class="headerlink" href="#pygame.joystick.quit" title="Permalink to this definition">¶</a></dt> <dd><div class="line-block"> <div class="line"><span class="summaryline">uninitialize the joystick module</span></div> <div class="line"><span class="signature">quit() -> None</span></div> </div> <p>Uninitialize the joystick module. After you call this any existing joystick objects will no longer work.</p> <p>It is safe to call this function more than once.</p> </dd></dl> <dl class="definition function"> <dt class="title" id="pygame.joystick.get_init"> <tt class="descclassname">pygame.joystick.</tt><tt class="descname">get_init</tt><big>(</big><big>)</big><a class="headerlink" href="#pygame.joystick.get_init" title="Permalink to this definition">¶</a></dt> <dd><div class="line-block"> <div class="line"><span class="summaryline">true if the joystick module is initialized</span></div> <div class="line"><span class="signature">get_init() -> bool</span></div> </div> <p>Test if the <tt class="docutils literal"><span class="pre">pygame.joystick.init()</span></tt> function has been called.</p> </dd></dl> <dl class="definition function"> <dt class="title" id="pygame.joystick.get_count"> <tt class="descclassname">pygame.joystick.</tt><tt class="descname">get_count</tt><big>(</big><big>)</big><a class="headerlink" href="#pygame.joystick.get_count" title="Permalink to this definition">¶</a></dt> <dd><div class="line-block"> <div class="line"><span class="summaryline">number of joysticks on the system</span></div> <div class="line"><span class="signature">get_count() -> count</span></div> </div> <p>Return the number of joystick devices on the system. The count will be 0 if there are no joysticks on the system.</p> <p>When you create Joystick objects using <tt class="docutils literal"><span class="pre">Joystick(id)</span></tt>, you pass an integer that must be lower than this count.</p> </dd></dl> <dl class="definition class"> <dt class="title" id="pygame.joystick.Joystick"> <em class="property">class </em><tt class="descclassname">pygame.joystick.</tt><tt class="descname">Joystick</tt><a class="headerlink" href="#pygame.joystick.Joystick" title="Permalink to this definition">¶</a></dt> <dd><div class="line-block"> <div class="line"><span class="summaryline">create a new Joystick object</span></div> <div class="line"><span class="signature">Joystick(id) -> Joystick</span></div> </div> <table border="1" class="toc docutils"> <colgroup> <col width="43%" /> <col width="1%" /> <col width="56%" /> </colgroup> <tbody valign="top"> <tr><td><a class="toc reference external" href="joystick.html#pygame.joystick.Joystick.init">pygame.joystick.Joystick.init</a></td> <td>—</td> <td>initialize the Joystick</td> </tr> <tr><td><a class="toc reference external" href="joystick.html#pygame.joystick.Joystick.quit">pygame.joystick.Joystick.quit</a></td> <td>—</td> <td>uninitialize the Joystick</td> </tr> <tr><td><a class="toc reference external" href="joystick.html#pygame.joystick.Joystick.get_init">pygame.joystick.Joystick.get_init</a></td> <td>—</td> <td>check if the Joystick is initialized</td> </tr> <tr><td><a class="toc reference external" href="joystick.html#pygame.joystick.Joystick.get_id">pygame.joystick.Joystick.get_id</a></td> <td>—</td> <td>get the Joystick ID</td> </tr> <tr><td><a class="toc reference external" href="joystick.html#pygame.joystick.Joystick.get_name">pygame.joystick.Joystick.get_name</a></td> <td>—</td> <td>get the Joystick system name</td> </tr> <tr><td><a class="toc reference external" href="joystick.html#pygame.joystick.Joystick.get_numaxes">pygame.joystick.Joystick.get_numaxes</a></td> <td>—</td> <td>get the number of axes on a Joystick</td> </tr> <tr><td><a class="toc reference external" href="joystick.html#pygame.joystick.Joystick.get_axis">pygame.joystick.Joystick.get_axis</a></td> <td>—</td> <td>get the current position of an axis</td> </tr> <tr><td><a class="toc reference external" href="joystick.html#pygame.joystick.Joystick.get_numballs">pygame.joystick.Joystick.get_numballs</a></td> <td>—</td> <td>get the number of trackballs on a Joystick</td> </tr> <tr><td><a class="toc reference external" href="joystick.html#pygame.joystick.Joystick.get_ball">pygame.joystick.Joystick.get_ball</a></td> <td>—</td> <td>get the relative position of a trackball</td> </tr> <tr><td><a class="toc reference external" href="joystick.html#pygame.joystick.Joystick.get_numbuttons">pygame.joystick.Joystick.get_numbuttons</a></td> <td>—</td> <td>get the number of buttons on a Joystick</td> </tr> <tr><td><a class="toc reference external" href="joystick.html#pygame.joystick.Joystick.get_button">pygame.joystick.Joystick.get_button</a></td> <td>—</td> <td>get the current button state</td> </tr> <tr><td><a class="toc reference external" href="joystick.html#pygame.joystick.Joystick.get_numhats">pygame.joystick.Joystick.get_numhats</a></td> <td>—</td> <td>get the number of hat controls on a Joystick</td> </tr> <tr><td><a class="toc reference external" href="joystick.html#pygame.joystick.Joystick.get_hat">pygame.joystick.Joystick.get_hat</a></td> <td>—</td> <td>get the position of a joystick hat</td> </tr> </tbody> </table> <p>Create a new joystick to access a physical device. The id argument must be a value from 0 to pygame.joystick.get_count()-1.</p> <p>To access most of the Joystick methods, you’ll need to <tt class="docutils literal"><span class="pre">init()</span></tt> the Joystick. This is separate from making sure the joystick module is initialized. When multiple Joysticks objects are created for the same physical joystick device (i.e., they have the same <tt class="docutils literal"><span class="pre">ID</span></tt> number), the state and values for those Joystick objects will be shared.</p> <p>The Joystick object allows you to get information about the types of controls on a joystick device. Once the device is initialized the Pygame event queue will start receiving events about its input.</p> <p>You can call the <tt class="docutils literal"><span class="pre">Joystick.get_name()</span></tt> and <tt class="docutils literal"><span class="pre">Joystick.get_id()</span></tt> functions without initializing the Joystick object.</p> <dl class="definition method"> <dt class="title" id="pygame.joystick.Joystick.init"> <tt class="descname">init</tt><big>(</big><big>)</big><a class="headerlink" href="#pygame.joystick.Joystick.init" title="Permalink to this definition">¶</a></dt> <dd><div class="line-block"> <div class="line"><span class="summaryline">initialize the Joystick</span></div> <div class="line"><span class="signature">init() -> None</span></div> </div> <p>The Joystick must be initialized to get most of the information about the controls. While the Joystick is initialized the Pygame event queue will receive events from the Joystick input.</p> <p>It is safe to call this more than once.</p> </dd></dl> <dl class="definition method"> <dt class="title" id="pygame.joystick.Joystick.quit"> <tt class="descname">quit</tt><big>(</big><big>)</big><a class="headerlink" href="#pygame.joystick.Joystick.quit" title="Permalink to this definition">¶</a></dt> <dd><div class="line-block"> <div class="line"><span class="summaryline">uninitialize the Joystick</span></div> <div class="line"><span class="signature">quit() -> None</span></div> </div> <p>This will unitialize a Joystick. After this the Pygame event queue will no longer receive events from the device.</p> <p>It is safe to call this more than once.</p> </dd></dl> <dl class="definition method"> <dt class="title" id="pygame.joystick.Joystick.get_init"> <tt class="descname">get_init</tt><big>(</big><big>)</big><a class="headerlink" href="#pygame.joystick.Joystick.get_init" title="Permalink to this definition">¶</a></dt> <dd><div class="line-block"> <div class="line"><span class="summaryline">check if the Joystick is initialized</span></div> <div class="line"><span class="signature">get_init() -> bool</span></div> </div> <p>Returns True if the <tt class="docutils literal"><span class="pre">init()</span></tt> method has already been called on this Joystick object.</p> </dd></dl> <dl class="definition method"> <dt class="title" id="pygame.joystick.Joystick.get_id"> <tt class="descname">get_id</tt><big>(</big><big>)</big><a class="headerlink" href="#pygame.joystick.Joystick.get_id" title="Permalink to this definition">¶</a></dt> <dd><div class="line-block"> <div class="line"><span class="summaryline">get the Joystick ID</span></div> <div class="line"><span class="signature">get_id() -> int</span></div> </div> <p>Returns the integer <tt class="docutils literal"><span class="pre">ID</span></tt> that represents this device. This is the same value that was passed to the <tt class="docutils literal"><span class="pre">Joystick()</span></tt> constructor. This method can safely be called while the Joystick is not initialized.</p> </dd></dl> <dl class="definition method"> <dt class="title" id="pygame.joystick.Joystick.get_name"> <tt class="descname">get_name</tt><big>(</big><big>)</big><a class="headerlink" href="#pygame.joystick.Joystick.get_name" title="Permalink to this definition">¶</a></dt> <dd><div class="line-block"> <div class="line"><span class="summaryline">get the Joystick system name</span></div> <div class="line"><span class="signature">get_name() -> string</span></div> </div> <p>Returns the system name for this joystick device. It is unknown what name the system will give to the Joystick, but it should be a unique name that identifies the device. This method can safely be called while the Joystick is not initialized.</p> </dd></dl> <dl class="definition method"> <dt class="title" id="pygame.joystick.Joystick.get_numaxes"> <tt class="descname">get_numaxes</tt><big>(</big><big>)</big><a class="headerlink" href="#pygame.joystick.Joystick.get_numaxes" title="Permalink to this definition">¶</a></dt> <dd><div class="line-block"> <div class="line"><span class="summaryline">get the number of axes on a Joystick</span></div> <div class="line"><span class="signature">get_numaxes() -> int</span></div> </div> <p>Returns the number of input axes are on a Joystick. There will usually be two for the position. Controls like rudders and throttles are treated as additional axes.</p> <p>The <tt class="docutils literal"><span class="pre">pygame.JOYAXISMOTION</span></tt> events will be in the range from -1.0 to 1.0. A value of 0.0 means the axis is centered. Gamepad devices will usually be -1, 0, or 1 with no values in between. Older analog joystick axes will not always use the full -1 to 1 range, and the centered value will be some area around 0. Analog joysticks usually have a bit of noise in their axis, which will generate a lot of rapid small motion events.</p> </dd></dl> <dl class="definition method"> <dt class="title" id="pygame.joystick.Joystick.get_axis"> <tt class="descname">get_axis</tt><big>(</big><big>)</big><a class="headerlink" href="#pygame.joystick.Joystick.get_axis" title="Permalink to this definition">¶</a></dt> <dd><div class="line-block"> <div class="line"><span class="summaryline">get the current position of an axis</span></div> <div class="line"><span class="signature">get_axis(axis_number) -> float</span></div> </div> <p>Returns the current position of a joystick axis. The value will range from -1 to 1 with a value of 0 being centered. You may want to take into account some tolerance to handle jitter, and joystick drift may keep the joystick from centering at 0 or using the full range of position values.</p> <p>The axis number must be an integer from zero to get_numaxes()-1.</p> </dd></dl> <dl class="definition method"> <dt class="title" id="pygame.joystick.Joystick.get_numballs"> <tt class="descname">get_numballs</tt><big>(</big><big>)</big><a class="headerlink" href="#pygame.joystick.Joystick.get_numballs" title="Permalink to this definition">¶</a></dt> <dd><div class="line-block"> <div class="line"><span class="summaryline">get the number of trackballs on a Joystick</span></div> <div class="line"><span class="signature">get_numballs() -> int</span></div> </div> <p>Returns the number of trackball devices on a Joystick. These devices work similar to a mouse but they have no absolute position; they only have relative amounts of movement.</p> <p>The <tt class="docutils literal"><span class="pre">pygame.JOYBALLMOTION</span></tt> event will be sent when the trackball is rolled. It will report the amount of movement on the trackball.</p> </dd></dl> <dl class="definition method"> <dt class="title" id="pygame.joystick.Joystick.get_ball"> <tt class="descname">get_ball</tt><big>(</big><big>)</big><a class="headerlink" href="#pygame.joystick.Joystick.get_ball" title="Permalink to this definition">¶</a></dt> <dd><div class="line-block"> <div class="line"><span class="summaryline">get the relative position of a trackball</span></div> <div class="line"><span class="signature">get_ball(ball_number) -> x, y</span></div> </div> <p>Returns the relative movement of a joystick button. The value is a x, y pair holding the relative movement since the last call to get_ball.</p> <p>The ball number must be an integer from zero to get_numballs()-1.</p> </dd></dl> <dl class="definition method"> <dt class="title" id="pygame.joystick.Joystick.get_numbuttons"> <tt class="descname">get_numbuttons</tt><big>(</big><big>)</big><a class="headerlink" href="#pygame.joystick.Joystick.get_numbuttons" title="Permalink to this definition">¶</a></dt> <dd><div class="line-block"> <div class="line"><span class="summaryline">get the number of buttons on a Joystick</span></div> <div class="line"><span class="signature">get_numbuttons() -> int</span></div> </div> <p>Returns the number of pushable buttons on the joystick. These buttons have a boolean (on or off) state.</p> <p>Buttons generate a <tt class="docutils literal"><span class="pre">pygame.JOYBUTTONDOWN</span></tt> and <tt class="docutils literal"><span class="pre">pygame.JOYBUTTONUP</span></tt> event when they are pressed and released.</p> </dd></dl> <dl class="definition method"> <dt class="title" id="pygame.joystick.Joystick.get_button"> <tt class="descname">get_button</tt><big>(</big><big>)</big><a class="headerlink" href="#pygame.joystick.Joystick.get_button" title="Permalink to this definition">¶</a></dt> <dd><div class="line-block"> <div class="line"><span class="summaryline">get the current button state</span></div> <div class="line"><span class="signature">get_button(button) -> bool</span></div> </div> <p>Returns the current state of a joystick button.</p> </dd></dl> <dl class="definition method"> <dt class="title" id="pygame.joystick.Joystick.get_numhats"> <tt class="descname">get_numhats</tt><big>(</big><big>)</big><a class="headerlink" href="#pygame.joystick.Joystick.get_numhats" title="Permalink to this definition">¶</a></dt> <dd><div class="line-block"> <div class="line"><span class="summaryline">get the number of hat controls on a Joystick</span></div> <div class="line"><span class="signature">get_numhats() -> int</span></div> </div> <p>Returns the number of joystick hats on a Joystick. Hat devices are like miniature digital joysticks on a joystick. Each hat has two axes of input.</p> <p>The <tt class="docutils literal"><span class="pre">pygame.JOYHATMOTION</span></tt> event is generated when the hat changes position. The position attribute for the event contains a pair of values that are either -1, 0, or 1. A position of (0, 0) means the hat is centered.</p> </dd></dl> <dl class="definition method"> <dt class="title" id="pygame.joystick.Joystick.get_hat"> <tt class="descname">get_hat</tt><big>(</big><big>)</big><a class="headerlink" href="#pygame.joystick.Joystick.get_hat" title="Permalink to this definition">¶</a></dt> <dd><div class="line-block"> <div class="line"><span class="summaryline">get the position of a joystick hat</span></div> <div class="line"><span class="signature">get_hat(hat_number) -> x, y</span></div> </div> <p>Returns the current position of a position hat. The position is given as two values representing the <tt class="docutils literal"><span class="pre">X</span></tt> and <tt class="docutils literal"><span class="pre">Y</span></tt> position for the hat. (0, 0) means centered. A value of -1 means left/down and a value of 1 means right/up: so (-1, 0) means left; (1, 0) means right; (0, 1) means up; (1, 1) means upper-right; etc.</p> <p>This value is digital, <tt class="docutils literal"><span class="pre">i.e.</span></tt>, each coordinate can be -1, 0 or 1 but never in-between.</p> <p>The hat number must be between 0 and get_numhats()-1.</p> </dd></dl> </dd></dl> </dd></dl> </div> </div> </div> </div> <div class="clearer"></div> </div> <div class="related"> <h3>Navigation</h3> <ul> <li class="right" style="margin-right: 10px"> <a href="../genindex.html" title="General Index" accesskey="I">index</a></li> <li class="right" > <a href="key.html" title="pygame.key" accesskey="N">next</a> |</li> <li class="right" > <a href="image.html" title="pygame.image" accesskey="P">previous</a> |</li> <li><a href="../index.html">Pygame v1.9.2 documentation</a> »</li> <script type="text/javascript" src="jquery.plugin.docscomments.js"></script> </ul> </div> <div class="footer"> © Copyright 2011, Pygame Developers. </div> </body> </html>
