Tom Kliethermes

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.

8 POD Errors

The following errors were encountered while parsing the POD:

Around line 401:

You forgot a '=back' before '=head2'

Around line 404:

'=item' outside of any '=over'

Around line 487:

You forgot a '=back' before '=head2'

Around line 489:

'=item' outside of any '=over'

Around line 636:

You forgot a '=back' before '=head1'

Around line 640:

'=item' outside of any '=over'

Around line 675:

You forgot a '=back' before '=head1'

Around line 704:

=back without =over