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.

TODO: SDL_EVENTMASK()

active is a member of the SDL::Event union and 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?

Create a new SDL::Event object.

perl