DESCRIPTION

        Joystick allows input from game control devices.  Currently, Joystick has only been
        developed for Win32API.

REQUIRMENTS

        To use Joystick you must have the Win32::API package installed.

SYNOPSIS

        use Win32API::Joystick;
        
        #returns number of POSSIBLE joystick devices in Windows
        $number_of_joysticks = Joystick::joyGetNumDevs; 
        
        #create joystick object
        $my_joystick = Joystick->new(0):        #joystick devices start at zero 
        
        #many attributes can be retrieved (see EXPLANATION).
        print "x axis max is $my_joystick->{XMAX}\n";
        
        #returns position of x,y,z axes and button status
        ($x, $y, $z, $button) =$my_joy->joyGetPos;  

CONSTRUCTOR

        The constructor takes the device number of the game controller you wish to use, returns a
        blessed reference if joystick is connected and working, and 0 if not. Device numbers for
        windows joysticks start at 0. You can determine how many game controllers windows has
        listed in the control panel by calling WinJoy::joyGetNumDevs.  This returns the number of
        devices LISTED, not the number that are connected and working.  The constructor does not
        throw an exception when the object cannot be created since often you may encounter
        joysticks listed in windows that aren't there or don't work.

EXPLANATION

ATTRIBUTES

        When the Joystick object is created, several attributes are extracted from the device's
        configuration in windows.  They can be accessed this way:

        $my_joystick_object->{ATTRIBUTE}

        General information on joystick:
        NUMBUTTONS MAXBUTTONS NUMAXES MAXAXES

        x,y,z,r,u,and v axes minimum and maximum values:
        XMIN XMAX YMIN YMAX ZMIN ZMAX RMIN RMAX UMIN UMAX VMIN VMAX

        Axes center values (if the axes exists):
        XCENT YCENT ZCENT RCENT UCENT VCENT
        
        Windows driver information:
        DRIVER REGKEY OEMVXD

GETTING POSITION

        The method joyGetPos returns four things.  The first three are x,y, and z positions. The
        fourth is the button status.  The single number for the button status is a sum of values
        for all the buttons that are being depressed.  This is how it is calculated:
        
        button1 = 1
        button2 = 2
        button3 = 4
        button4 = 8
        button5 = 16
        ...

        So, if buttons 1 and 3 were being depressed at the same time, the button status would be
        5.

BUGS

        The windows API call that returns the position of the joystick axes will only return
        x, y, and z values.  In the case that you have a joystick that has more than x,y, and z
        (r,u, and v) you will not be able to read those values. (There is an extended joystick
      info that may be implimented in the future)

TODO

        Create a Joystick module for use with Device under Unix/Linux.  Add capability to get
      extended joystick info, such as POV positions, and axes on sticks with more than 3 axes.

AUTHOR

        Ben Lilley bdlilley@cpan.org

COPYRIGHT

        (C) Copyright 2000, Ben Lilley all rights reserverd
        This module may freely distributed in accordance with the artistic license.