NAME

SDL::App::FPS::Button - a clickable area (aka button) for SDL::App::FPS

SYNOPSIS

use SDL::FPS::App;
use SDL::FPS::App::Button;

$app = SDL::FPS::App->new( ... );

my $button = $app->add_button( $x,$y,$w,$h,
  BUTTON_CLICK, BUTTON_RECTANGULAR, BUTTON_MOUSE_LEFT, sub { ... } );

EXPORTS

Exports on request the following symbols:

Event types:

BUTTON_IN
BUTTON_OUT
BUTTON_HOVER
BUTTON_DOWN
BUTTON_UP
BUTTON_CLICK

Button shapes:

BUTTON_RECTANGULAR
BUTTON_ELLIPTIC

Mouse button types:

BUTTON_MOUSE_LEFT
BUTTON_MOUSE_RIGHT
BUTTON_MOUSE_MIDDLE
BUTTON_MOUSE_WHEEL_DOWN
BUTTON_MOUSE_WHEEL_UP
BUTTON_MOUSE_MIDDLE

DESCRIPTION

This package provides a class for rectangular, elliptic or round 'clickable' areas, which you can use as buttons.

Each of these buttons will watch for SDL_MOUSEMOVED, SDL_MOUSEBUTTONUP and SDL_MOUSEBUTTONDOWND events and when they occured, call the corrosponding callback function.

CALLBACK

Once the specific event occurs, the given callback code (CODE ref) is called with the following parameters:

&{$callback}($self,$button,@arguments);

$self is the app the object resides in (e.g. the object of type SDL::App::FPS), $button is the button itself, and the additional arguments are whatever was passed when new() was called.

METHODS

new()

my $button = SDL::App::FPS::Button->new(
	$app,$x,$y,$w,$h,$type,$button,$shape,$callback,@args);

Creates a new button, and registers it with the application $app. $type is one of the following event types:

BUTTON_IN	 The mouse was moved from the outside to the
		 inside the area, happens only when the mouse
		 crossed the border from outside to inside
BUTTON_OUT	 Like BUTTON_IN, but in the other direction
BUTTON_HOVER	 Happens whenever the mouse is moved and the
		 pointers final position is inside the area
		 In most cases you want to use BUTTON_IN instead
BUTTON_DOWN	 A mouse button was pressed inside the area
BUTTON_UP	 A mouse button was released inside the area
BUTTON_CLICK	 A mouse button was pressed inside the area and
		 then released again inside the area

The last type gives a user a chance to move the mouse pointer out of the area while holding it pressed and so prevent the callback from happening.

You can use || or + add them together, the callback will then happen when any one of these events occured:

my $button = SDL::App::FPS::Button->new(
	$app,$x,$y,$w,$h,BUTTON_DOWN+BUTTON_UP,
	$button,$shape,$callback,@args);

Please note that for a single click inside the area, both pressed and released events will occur, resulting in the callback being called twice.

For types BUTTON_IN, BUTTON_OUT and BUTTON_HOVER, the $button argument will be ignored.

The $button argument is one of the three mouse buttons BUTTON_MOUSE_LEFT, BUTTON_MOUSE_RIGHT or BUTTON_MOUSE_MIDDLE. You can add them together to trigger the callback for more than one button, like:

my $button = SDL::App::FPS::Button->new(
	$app,$x,$y,$w,$h,BUTTON_CLICK,
	BUTTON_MOUSE_LEFT+BUTTON_MOUSE_RIGHT,
	$shape,$callback,@args);

$shape is one of the two BUTTON_RECTANGULAR or BUTTON_ELLIPTIC shapes.

move_to()

$button->move_to($x,$y);

Move the button center to the new coordinates $x and $y.

resize()

$button->resize($w,$h);

Resize the button's width and height to $w and $h.

is_active()

if ($button->is_active())
  {
  ...
  }

Returns true if the button is active.

deactivate()

$button->deactivate();

Deactivate the button. It will no longer respond to mouse clicks.

activate()

$button->activate();

Re-activate the button. It will now again respond to mouse clicks.

hit()

$button->hit($x,$y);

Returns true if the point $x,$y is inside the button area.

id()

$group->id();

Returns the ID of the group itself.

x()

$button->x(8);
if ($button->x() < 78)
  {
  ...
  }

Get/set the button's x coordinate.

y()

$button->y(1);
if ($button->y() < 28)
  {
  ...
  }

Get/set the button's y coordinate.

width()

$button->width(1);
if ($button->width() < 28)
  {
  ...
  }

Get/set the button's width (aka size in X direction).

height()

$button->height(1);
if ($button->height() < 28)
  {
  ...
  }

Get/set the button's height (aka size in Y direction).

BUGS

None known yet.

AUTHORS

(c) 2002, 2003 Tels <http://bloodgate.com/>

SEE ALSO

SDL:App::FPS, SDL::App and SDL.