SDL::Event - General event structure

 use SDL::Event;                             # for the event object itself
 use SDL::Events qw(pump_events poll_event); # functions for event queue handling

 SDL::init(SDL_INIT_VIDEO);
 my $event = SDL::Event->new();

 while(1)
 {
     pump_events();

     if(poll_event($event))
     {
        if($event->type == SDL_MOUSEBUTTONDOWN)
        {
            # now you can handle the details
            $event->button_which;
            $event->button_button;
            $event->button_x;
            $event->button_y;
        }

        last if $event->type == SDL_QUIT;
     }

     # your screen drawing code will be here
 }

Event handling allows your application to receive input from the user. Event handling is initalised (along with video) with a call to:

SDL::init(SDL_INIT_VIDEO);

Internally, SDL stores all the events waiting to be handled in an event queue. Using functions like SDL::Events::poll_event(), SDL::Events::peep_events and SDL::Events::wait_event() you can observe and handle waiting input events.

The key to event handling in SDL is the SDL::Event union. The event queue itself is composed of a series of SDL::Event unions, one for each waiting event. SDL::Event unions are read from the queue with the SDL::Events::poll_event() function and it is then up to the application to process the information stored with them.

new creates an empty event-object, which can be used store information. Either by calling poll_event($event) that transferes one event from the queue into our object or by setting all the needed data manually in order to push the event to the queue.

 use SDL::Event;

 my $event = SDL::Event->new();

SDL::Event is a union of all event structures used in SDL, using it is a simple matter of knowing which union member relates to which event type.

 print 'heureka' if $event->type == SDL_MOUSEBUTTONDOWN;

Available type constants:

• SDL_ACTIVEEVENT - Application visibility event structure
• SDL_KEYDOWN - Keyboard event structure
• SDL_KEYUP - Keyboard event structure
• SDL_MOUSEMOTION - Mouse motion event structure
• SDL_MOUSEBUTTONDOWN - Mouse button event structure
• SDL_MOUSEBUTTONUP - Mouse button event structure
• SDL_JOYAXISMOTION - Joystick axis motion event structure
• SDL_JOYBALLMOTION - Joystick trackball motion event structure
• SDL_JOYHATMOTION - Joystick hat position change event structure
• SDL_JOYBUTTONDOWN - Joystick button event structure
• SDL_JOYBUTTONUP - Joystick button event structure
• SDL_VIDEORESIZE - Window resize event structure
• SDL_VIDEOEXPOSE - Window expose event
• SDL_QUIT - Quit requested event
• SDL_USEREVENT - A user-defined event type
• SDL_SYSWMEVENT - Platform-dependent window manager event.

Event types are grouped by masks. SDL_EVENTMASK($type) will return the proper mask for the given type.

Available event mask constants:

• SDL_ACTIVEEVENTMASK
• SDL_KEYDOWNMASK
• SDL_KEYUPMASK
• SDL_KEYEVENTMASK
• SDL_MOUSEMOTIONMASK
• SDL_MOUSEBUTTONDOWNMASK
• SDL_MOUSEBUTTONUPMASK
• SDL_MOUSEEVENTMASK
• SDL_JOYAXISMOTIONMASK
• SDL_JOYBALLMOTIONMASK
• SDL_JOYHATMOTIONMASK
• SDL_JOYBUTTONDOWNMASK
• SDL_JOYBUTTONUPMASK
• SDL_JOYEVENTMASK
• SDL_VIDEORESIZEMASK
• SDL_VIDEOEXPOSEMASK
• SDL_QUITMASK
• SDL_SYSWMEVENTMASK

This way you can check if a given type matches a mask:

 (SDL_JOYBUTTONDOWN   & SDL_MOUSEEVENTMASK) # is false
 (SDL_MOUSEBUTTONDOWN & SDL_MOUSEEVENTMASK) # is true
 (SDL_MOUSEBUTTONUP   & SDL_MOUSEEVENTMASK) # is true
 (SDL_MOUSEMOTION     & SDL_MOUSEEVENTMASK) # is true

 # and also true is:

 (SDL_MOUSEEVENTMASK == SDL_EVENTMASK(SDL_MOUSEBUTTONDOWN) 
                      | SDL_EVENTMASK(SDL_MOUSEBUTTONUP) 
                      | SDL_EVENTMASK(SDL_MOUSEMOTION))

active is used when an event of type SDL_ACTIVEEVENT is reported.

When the mouse leaves or enters the window area a SDL_APPMOUSEFOCUS type activation event occurs, if the mouse entered the window then gain will be 1, otherwise gain will be 0.

A SDL_APPINPUTFOCUS type activation event occurs when the application loses or gains keyboard focus. This usually occurs when another application is made active.

Finally, a SDL_APPACTIVE type event occurs when the application is either minimised/iconified (gain=0) or restored.

A single event can have multiple values set in state.

Note: This event does not occur when an application window is first created.

A new ActiveEvent (to fake focus loss) will be created like this:

 my $event = SDL::Event->new();
    $event->type(SDL_ACTIVEEVENT);
    $event->active_gain(0);
    $event->active_state(SDL_APPMOUSEFOCUS);

 # I think this is wrong, ->active_type() should get SDL_APPMOUSEFOCUS, but what state gets?

See active. 0 if the event is a loss or 1 if it is a gain.

A bitmask of the following values: SDL_APPMOUSEFOCUS if mouse focus was gained or lost, SDL_APPINPUTFOCUS if input focus was gained or lost, and SDL_APPACTIVE if the application was iconified (gain=0) or restored(gain=1).

key is used when an event of type SDL_KEYDOWN or SDL_KEYUP is reported.

The type and state actually report the same information, they just use different values to do it. A keyboard event generally occurs when a key is released (type=SDL_KEYUP or key_state=SDL_RELEASED) and when a key is pressed (type=SDL_KEYDOWN or key_state=SDL_PRESSED).

The SDLK_CAPSLOCK and SDLK_NUMLOCK keys are special cases and report an SDL_KEYDOWN when first pressed, then an SDL_RELEASED when released and pressed again. For these keys KEYUP and KEYDOWN events are therefore analogous to the state of the caps lock and num lock LEDs rather than the keys themselves. These special cases are required for compatibility with Sun workstations.

Note: Repeating SDL_KEYDOWN events will occur if key repeat is enabled (see SDL_EnableKeyRepeat).

SDL_PRESSED or SDL_RELEASED

Create a new SDL::Event object.

perl