NAME

Win32::MultiMedia::Joystick - Perl extension for Win32 Joystick APIs

SYNOPSIS

   use Win32::MultiMedia::Joystick;
   my $joy1 = Win32::MultiMedia::Joystick->new();
   $joy1->update;
   print $joy1->X,"\t",$joy1->Y,"\t";
   print $joy1->Z,"\n" if $joy1->hasZ;
   print $joy1->B1;

DESCRIPTION

        Win32::MultiMedia::Joystick 

OO Methods

new(?number?,?raw?)

     my $joy1 = Win32::MultiMedia::Joystick->new();

     Creates a new Win32::MultiMedia::Joystick object 
     and populates the joystick capabilities info.
      Parameters:
        number: specifies which joystick to use. 
                defaults to JOY1 (which is actually 0)
        raw: if non 0, causes the access method to return 
              non calibrated data. defaults to 0

      Return value:
        A new Win32::MultiMedia::Joystick object or undef
        on failure

id

    Returns the JOYSTICKIDx value.

setRaw(bool)

    $joy1->setRaw(1) turns on raw mode.
    $joy1->setRaw(0) turns off raw mode.

isUsingRaw

    Returns true if the joystick object returns uncalibrated 
     data.

update

     Reads the joystick information from the system.
      Parameters: none
      Return value:
        1 on success: The info is updated.
        0 on failure: The info is untouched.
        Failure can be caused by a read attempt while the 
        system is updating the joystick info.

error

   print $joy->error;
   Returns the last error generated.
   In scalar context, returns the error number 
      (compare with JOYERR_x to determine cause)
   In array context, returns an array of the error number
     and text.

setCapture(hwnd, period, changed)

  $joy1->setCapture(hwnd, period, changed)
    Tells the joystick to send messages to the Win32 window 
    given by hwnd.
  Returns undef on failure.

releaseCapture

  $joy1->releaseCapture;
    Releases the joystick from the previous capture.
  Returns undef on failure.

threshold(?num?)

  Used with the "Capture" methods above.
  When called without parameters, it returns the current threshold
   value.
     print $joy1->threshold;
  When called with one parameter, sets the threshold value 
   for the captured joystick.
     $joy1->threshold(5);
  Returns undef on failure.

Methods for joystick values

X

   Returns the X value.

Y

   Returns the Y value.

Z

   Returns the Z value.

R

   Returns the R value.

U

   Returns the U value.

V

   Returns the V value.

ButtonNumber

   Returns the number of the button currently pressed.

Bx

   Returns true if button 'x' is pressed.
    'x' is in the range of 1 to 32
     ie.  $joy1->B1;

Buttons

   Returns the raw button data. Must be logically &'d with
     one of the JOY_BUTTONx constants.

POV

   Returns point of view (POV) value.
     This is a value in the range of 0 to 35,900 which 
     is the angle*100 or -1 if centered.
     if $joy->hasPOVCTS is true, the value is continuous.

POVCENTERED

   Returns true if POV is centered.

POVFORWARD

   Returns true if POV is forward.

POVRIGHT

   Returns true if POV is right.

POVBACKWARD

   Returns true if POV is backward.

POVLEFT

   Returns true if POV is left.

Methods for Joystick capabilities

hasZ

   Returns true if the joystick has a "Z" dimension.

hasR

   Returns true if the joystick has a "R" (4th or rudder) dimension.

hasU

   Returns true if the joystick has a "U" (5th) dimension.

hasV

   Returns true if the joystick has a "V" (6th) dimension.

MaxAxes

   Returns the maximum axis possible.

NumAxes

   Returns the actual number of axis.

MaxButtons

   Returns the maximum buttons possible.

NumButtons

   Returns the actual number of buttons.

PeriodMax

   Returns the maximum period

PeriodMin

   Returns the minimum period

Xmax

   Returns the max "X" value possible.

Xmin

   Returns the min "X" value possible.

Ymax

   Returns the max "Y" value possible.

Ymin

   Returns the min "Y" value possible.

Zmax

   Returns the max "Z" value possible.

Zmin

   Returns the min "Z" value possible

Rmax

   Returns the max "R" value possible.

Rmin

   Returns the min "R" value possible

Umax

   Returns the max "U" value possible.

Umin

   Returns the min "U" value possible

Vmax

   Returns the max "V" value possible.

Vmin

   Returns the min "V" value possible

hasPOV

   Returns true if the joystick has point of view.

hasPOV4DIR

   Returns true if the joystick reports descrete values for 
   point of view. 

hasPOVCTS

   Returns true if the joystick report continuous values for 

ProductID

   Returns the product ID of the joystick.

ManufacturerID

   Returns the manufacturer ID of the joystick.

Name

   Returns the product name of the joystick.

Non-OO interface

GetInfo(JOYSTICKID,?raw?)

   Returns a reference to a hash containing all the info
   listed in the Methods for joystick values section 
   above. undef on failure.
   if raw is given and non 0, causes the access mathod to return 
              non calibrated data. defaults to 0

GetNumDevs

   Returns the number of joysticks supported by the system,
     not the number of joysticks.

GetThreshold(JOYSTICKID)

  Identical to the $joy1->threshold OO method.

SetThreshold(JOYSTICKID)

  Identical to the $joy1->threshold($value) OO method.

SetCapture(hwnd, JOYSTICKID, Period, Changed)

  Identical to the $joy1->setCapture(...) OO method.

ReleaseCapture(JOYSTICKID)

  Identical to the $joy1->releaseCapture OO method.

Example

   #This loop prints out the X and Y values until Button1 is pressed
   use Win32::MultiMedia::Joystick;
   my $joy1 = Win32::MultiMedia::Joystick->new(); #defaults to JOY1
   while (!$joy1->B1)
   {
      $joy1->update;  #needs to be in the loop 
      print $joy1->X,",",$joy1->Y,"\n";
   }


   # non-OO
   use Win32::MultiMedia::Joystick qw(:direct :error);

   my $te = GetDevCaps(JOY1);
   while (my($k,$v)=each %$te)
   {
      print "$k\t\t= $v\n";
   }
   
   my $ji = GetInfo(JOY1);
   while (my($k,$v)=each %$ji)
   {
      print "$k\t\t= $v\n";
   }

EXPORT

   JOY1:  ID number of the first joystick
   JOY2:  ID number of the second joystick

  Things you can export:

   :direct       Exports the non-OO functions

   Constants   
   :error        Exports the error constants
   :button       Exports the constants for the 'Buttons' method.
   :pov          Exports the POV constants
   :messages     Exports the messages for captured joysticks

AUTHOR

        Tom Kliethermes  tomk@informix.com

SEE ALSO

perl(1), Microsoft Windows Platform SDK.