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.