NAME

SDL::App::FPS::EventHandler - an event handler class for SDL::App::FPS

SYNOPSIS

        my $handler = SDL::App::FPS::EventHandler->new( $app,
                SDL_KEYDOWN,
                SDLK_SPACE,
                sub { my $self = shift; $self->pause(); },
        };

        my $handler2 = SDL::App::FPS::EventHandler->new( $app,
                SDL_MOUSEBUTTONDOWN,
                LEFTMOUSEBUTTON,
                sub { my $self = shift; $self->time_warp(2,2000); },
        };

DESCRIPTION

This package provides an event handler class.

Event handlers are register to watch out for certain external events like keypresses, mouse movements and so on, and when these happen, call a callback routine.

CALLBACK

Once the event has occured, the callback code (CODE ref) is called with the following parameters:

        &{$callback}($self,$handler,$event);

$self is the app the event handler resides in (e.g. the object of type SDL::App::FPS), $handler is the event handler itself, and $event the SDL::Event that caused the handler to be activated.

METHODS

new()

        my $handler = SDL::App::FPS::EventHandler->new(
                $app,
                $type,
                $kind,
                $callback,
        );

Creates a new event handler to watch out for $type events (SDL_KEYDOWN, SDL_MOUSEMOVED, SDL_MOUSEBUTTONDOWN etc) and then for $kind kind of it, like SDLK_SPACE. Mouse movement events ignore the $kind parameter.

$app is the ref to the application the handler resides in and is passed as first argument to the callback function when called.

Please note that this event handler only triggers when this key or button is pressed, regardless of any additional key modifier like SHIFT beeing pressed. See below for how to change this.

$kind can also be an array ref. This is used to pass a key plus one or more modifiers that need to be pressed to trigger the event. The default is that all listed modifiers must be pressed and additional modifiers are not ignored, e.g. they cause the event not to trigger:

        my $handler = SDL::App::FPS::EventHandler->new(
                $app,
                SLD_KEYDOWN,
                [ SDLK_a, KMOD_LSHIFT ],
                $callback
        );

The list of valid modifiers is:

        KMOD_NUM
        KMOD_CAPS
        KMOD_LCTRL
        KMOD_RCTRL
        KMOD_RSHIFT
        KMOD_LSHIFT
        KMOD_RALT
        KMOD_LALT

These shortcuts exists:

        KMOD_CTRL
        KMOD_SHIFT
        KMOD_ALT

This would only trigger when 'a' and left shift are pressed together.

        my $handler = SDL::App::FPS::EventHandler->new(
                $app,
                SLD_KEYDOWN,
                [ SDLK_a, KMOD_LSHIFT, KMOD_RSHIFT ],
                $callback
        );

This would only trigger when 'a' and left shift and right shift are pressed together.

        my $handler = SDL::App::FPS::EventHandler->new(
                $app,
                SLD_KEYDOWN,
                [ SDLK_a, KMOD_LSHIFT, KMOD_RSHIFT ],
                $callback
        );
        $handler->require_all_modifiers(0);

This would only trigger when 'a' and one of left shift or right shift are pressed together (but no additional modifiers), but not when 'a' without left and right shift is pressed (e.g. neither a nor Ctrl+a nor Ctrl+a+left shift would count).

        my $handler = SDL::App::FPS::EventHandler->new(
                $app,
                SLD_KEYDOWN,
                [ SDLK_a, KMOD_LSHIFT, KMOD_RSHIFT ],
                $callback
        );
        $handler->ignore_additional_modifiers(0);

This would only trigger when 'a' and left shift and right shift are pressed together, and additional modifiers will be ignored. E.g. neither left shift+a nor right shift+a would count, however, left ctrl + a + left shift + right shift would count.

When passing only one key as $kind, ignore_additional_key_modifiers() will be set to true as default.

See require_all_key_modifiers and ignore_additional_key_modifiers for changing the default behaviour.

is_active()

        $handler->is_active();

Returns true if the event handler is active, or false for inactive. Inactive event handlers ignore any events that might happen.

activate()

Set the event handler to active. Newly created ones are always active.

deactivate()

Set the event handler to inactive. Newly created ones are always active.

rebind()

        $handler->rebind(SDL_KEYUP, SDLK_P);

Set a new type and kind for the handler to watch out for.

rebind() will reset require_all_modifiers() and ignore_additional_modifiers() to the defaults like new() does.

require_all_modifiers()

        $eventhandler->require_all_modifiers(1);
        if ($eventhandler->require_all_modifiers())
          {
          ...
          }

Returns true or false. When passed an argument, sets a flag on whether this handlers requires all set key modifiers or not. When set to false, only one or some of the set key modifiers (SDLK_LSHIFT, SDLK_RCTRL etc) must be pressed to trigger the callback. When set to true, all of them must be pressed.

ignore_additional_modifiers()

        $eventhandler->ignore_additional_modifiers(1);
        if ($eventhandler->ignore_additional_modifiers())
          {
          ...
          }

Returns true or false. When passed an argument, sets a flag on whether this handlers ignores additional key modifiers. When set to false, only one or some of the set key modifiers (depending on require_all_modifiers()) (like SDLK_LSHIFT, SDLK_RCTRL etc) must be pressed to trigger the callback and no additional modifiers can be pressed. When set to true, additional modifiers can be pressed and the event still triggers.

id()

Return the handler's unique id.

char2key()

        $sdl_key = char2key($char);
        $sdl_key_a = char2key('a');

Converts a character like 'a' to a SDL key like SDLK_a.

char2type_kind()

        ($type,$sdl_key) = char2type_kind($char);
        ($type,$sdl_key) = char2type_kind('a');
        ($type,$sdl_key) = char2type_kind('PRINT');
        ($type,$sdl_key) = char2type_kind('ENTER');
        ($type,$sdl_key) = char2type_kind('LMB');       # left mouse button

Converts a character like 'a' to a SDL key like SDLK_a, and also returns the type (SDL_KEYDOWN or SDL_MOUSEBUTTONDOWN).

AUTHORS

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

SEE ALSO

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