NAME

SDL::Event - a SDL perl extension

SYNOPSIS

 $event = new SDL::Event;

DESCRIPTION

        SDL::Event->new(); creates a SDL_Event structure, into
which events may be stored.

$event->type()

        This function returns the event type which will be one of
the values: SDL_ACTIVEEVENT, SDL_KEYDOWN, SDL_KEYUP, SDL_MOUSEMOTION, 
SDL_MOUSEBUTTONDOWN, SDL_MOUSEBUTTONUP, SDL_QUIT,SDL_SYSWMEVENT.

Gathering Events

        $event->poll();
        $event->pump();
        $event->wait();

These three methods can be used to gather new events. Poll and pump should be used together. Pump will collect events, and poll will read events from the stack, returning 0 if no events were found. Similarly wait will wait for an event to occur, and then return.

Active Events

These events indicate a change in the state of the application. The methods which access the event's properties are:

        $event->gain();
        $event->state();

The possible states that an event may return are: SDL_APPMOUSEFOCUS, SDL_APPINPUTFOCUS, and SDL_APPACTIVE.

Key Events

Everytime a key is pressed or release, while the app has input focus, a key event will be generated. The following methods provide access to the event's fileds:

        $event->key_state();
        $event->key_name();
        $event->key_sym();
        $event->key_mod();
        $event->key_unicode();
        $event->key_scancode();

Key_state will return either SDL_PRESSED or SDL_RELEASED. Key_name will return a string giving the name of the key. Sym will return the SDL key symbol code, which can be checked against the SDLK_* entries as specified in the SDL documentation. (ie sym 27 is SDLK_ESCAPE). Likewise, key_mod will return the current modifier state of the key and can be or'ed against the KMOD_* masks as per the SDL documentation.

To enable unicode support, one must first call

        $event->set_unicode(1);

there after each event will fill out the unicode field. The key_unicode function returns the integer of the unicode key. Similarly, key_scancode will return the raw scancode from the key event.

Mouse Events

There are two types of mouse related events, motion and button. The exact type is important as there are separate methodss for reading from each. For motion events one should use:

        $event->motion_state();
        $event->motion_x();
        $event->motion_y();
        $event->motion_xrel();
        $event->motion_yrel();

For button events the following are applicable:

        $event->button_state();
        $event->button_x();
        $event->button_y();
        $event->button();

Button_state will either be SDL_PRESSED or SDL_RELEASED, while button will contain the number of the button pressed, 1, 2, 3, etc.

Other things

Additionally, you can use the method 'set' to make the SDL ignore or re-enable event types. For example, you can ignore all SDL_SYSWMEVENT events with the command:

        $event->set(SDL_SYSWMEVENT,SDL_IGNORE);

This is highly recommended as you will have to process fewer events this way. You can also enable key repeats using the method:

        $event->set_key_repeat(delay,interval);

It should be noted that there is currently no support for the SYSWMEVENT events in this structure, as these are really best dealt with C level code. This may change in the future.

AUTHOR

David J. Goehrig

SEE ALSO

perl(1) SDL::App(3).

cpanm SDL::sdlpl

perl -MCPAN -e shell
install SDL::sdlpl