NAME

Allegro::Mouse - Allegro mouse object

SYNOPSIS

   use Allegro;

   $al = Allegro->new() or die;

DESCRIPTION

The Allegro::Mouse object provides an interface to the Allegro mouse routines. Allegro v4 only supports one mouse.

METHODS

new - create a new mouse object

Creates a new mouse object.

   $mouse = $al->Mouse();

shutdown - shutdown mouse driver

Disables this mouse object.

poll - polls mouse driver

Polls the mouse driver. This is not required to be called explicitly to use button or position.

button - returns mouse button information

Returns the status of the mouse button(s).

   $b1 = $mouse->button(0);
   $b2 = $mouse->button(1);

If given a parameter, will return the status as a true/false value of whether that button is pressed.

   @buttons = $mouse->button;

If no parameter is given, returns an array containing the status of each mouse button.

position - returns mouse position

Returns mouse position.

   $x = $mouse->position('x');
   $y = $mouse->position('y');
   $z = $mouse->position('z');

If supplied a parameter, returns the position of the mouse for that axis.

   @pos = $mouse->position;

If no parameter is given, returns an array containing the position for each axis.

show - shows mouse on screen or bitmap

Displays the mouse automatically onto a Display or Bitmap object.

   $mouse->show($disp);

This will continuously update the mouse by drawing it onto the specified bitmap. This may lead to problems if you are drawing to the bitmap while the mouse pointer is being draw. See freeze and scare below.

hide - hides mouse

Disables automatic mouse display on screen/bitmap.

scare - scares mouse

Hides mouse temporarily before a drawing operation if needed.

   $mouse->scare(x => $x, y => $y, width => $w, height => $h);

x, y, width, height are the area that is affected. Defaults to the entire screen. to the entire screen.

unscare - unscares mouse

Disables temporary mouse hiding.

freeze - freeze mouse pointer

Disables mouse movement. Use this if you are drawing on the same bitmap on which the mouse is displayed. This avoids have to hide the mouse, but you must not draw over the mouse pointer.

unfreeze - unfreeze mouse pointer

Re-enables mouse movement.

clip - set mouse clipping rectangle

Sets a clipping rectangle for mouse movement. The mouse will not be able to move out if this area.

   $mouse->clip(x => $x, y => $y, width => $w, height => $h);

speed - set mouse movement speed

Sets the mouse movement speed.

   $mouse->speed(x => 2, y => 2);

x (optional) - horizontal speed
y (optional) - vertical speed

set - set mouse position

Set the mouse's current position.

   $mouse->set(x => 10, y => 10, z => -2);

The z parameter is optional.

sprite - set mouse pointer

Changes the pointer used for the mouse.

   $mouse->sprite(bitmap => $bitmap,
                  x      => 0,
                  y      => 0);

bitmap (optional) - mouse sprite
x, y (optional) - point to use as mouse focus

mickeys - get mouse mickeys

Returns an array of how far the mouse has moved since the last call to this method.

   ($xm, $ym) = $mouse->mickeys;

AUTHOR

Colin O'Leary <colin@mx3.org>

COPYRIGHT