CATEGORY

new

 use SDL::Event;

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

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_EVENTMASK(SDL_JOYBUTTONDOWN)   & SDL_MOUSEEVENTMASK) # is false
 (SDL_EVENTMASK(SDL_MOUSEBUTTONDOWN) & SDL_MOUSEEVENTMASK) # is true
 (SDL_EVENTMASK(SDL_MOUSEBUTTONUP)   & SDL_MOUSEEVENTMASK) # is true
 (SDL_EVENTMASK(SDL_MOUSEMOTION)     & SDL_MOUSEEVENTMASK) # is true
 
 # and also true is:
 
 (SDL_MOUSEEVENTMASK == SDL_EVENTMASK(SDL_MOUSEBUTTONDOWN) 
                      | SDL_EVENTMASK(SDL_MOUSEBUTTONUP) 
                      | SDL_EVENTMASK(SDL_MOUSEMOTION))

Application visibility events

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?

active_gain

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

active_state

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).

Keyboard events

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::Events::enable_key_repeat).

key_state

"SDL_PRESSED" or "SDL_RELEASED"

key_scancode

The "scancode" field should generally be left alone, it is the hardware-dependent scancode returned by the keyboard.

key_sym

The "sym" field is extremely useful. It is the SDL-defined value of the key (see the keysym definitions in SDLKey). This field is very useful when you are checking for certain key presses, like so:

 while(poll_event($event))
 {
     switch($event->type)
     {
         case SDL_KEYDOWN:
             move_left() if($event->key_sym == SDLK_LEFT);
             break;
         .
         .
         .
     }
 }

key_mod

"mod" stores the current state of the keyboard modifiers as explained in SDL_GetModState.

key_unicode

The "unicode" field is only used when UNICODE translation is enabled with SDL::Events::enable_unicode. If "unicode" is non-zero then this is the UNICODE character corresponding to the keypress. If the high 9 bits of the character are 0, then this maps to the equivalent ASCII character:

 my $char;
 if(($event->key_unicode & 0xFF80) == 0)
 {
     $char = $event->key_unicode & 0x7F;
 }
 else
 {
     print("An International Character.\n");
 }

UNICODE translation does create a slight overhead so don't enable it unless its needed.

NOTE: Key release events (SDL_KEYUP) won't necessarily (ever?) contain unicode information. See <http://lists.libsdl.org/pipermail/sdl-libsdl.org/2005-January/048355.html>

Mouse motion events

motion_state

The button state can be interpreted using the "SDL_BUTTON" macro (see SDL::Events::get_mouse_state).

motion_x, motion_y

The X/Y coordinates of the mouse

motion_xrel, motion_yrel

Relative motion in the X/Y direction.

If the cursor is hidden (SDL_ShowCursor(0)) and the input is grabbed (SDL_WM_GrabInput(SDL_GRAB_ON)), then the mouse will give relative motion events even when the cursor reaches the edge of the screen. This is currently only implemented on Windows and Linux/Unix-alikes.

Mouse button events

Mouse wheel events are reported as buttons 4 (up) and 5 (down). Two events are generated i.e. you get a "SDL_MOUSEBUTTONDOWN" followed by a "SDL_MOUSEBUTTONUP" event.

button_which

The input device index

button_button

The mouse button index ("SDL_BUTTON_LEFT", "SDL_BUTTON_MIDDLE", "SDL_BUTTON_RIGHT", "SDL_BUTTON_WHEELUP", "SDL_BUTTON_WHEELDOWN")

button_state

"SDL_PRESSED" or "SDL_RELEASED"

button_x, button_y

The X/Y coordinates of the mouse at press/release time

Joystick axis events

jaxis_which

The field "jaxis_which" is the index of the joystick that reported the event.

jaxis_axis

The "jaxis_axis" is the index of the axis (for a more detailed explanation see the Joystick section).

jaxis_value

"jaxis_value" is the current position of the axis (range: -32768 to 32767).

Joystick button events

jbutton_which

The field "jbutton_which" is the index of the joystick that reported the event.

jbutton_button

The "jbutton_button" is the index of the button (for a more detailed explanation see the Joystick section).

jbutton_state

"jbutton_state" is the current state of the button which is either "jbutton_SDL_PRESSED" or "jbutton_SDL_RELEASED".

Joystick hat events

jhat_which

The field "jhat_which" is the index of the joystick that reported the event.

jhat_hat

"jhat_hat" is the index of the hat (for a more detailed explanation see the Joystick section).

jhat_value

"jhat_value" is the current position of the hat. It is a bitwise OR'd combination of the following values (whose meanings should be pretty obvious):

• "SDL_HAT_CENTERED"
• "SDL_HAT_UP"
• "SDL_HAT_RIGHT"
• "SDL_HAT_DOWN"
• "SDL_HAT_LEFT"

The following defines are also provided:

• "SDL_HAT_RIGHTUP"
• "SDL_HAT_RIGHTDOWN"
• "SDL_HAT_LEFTUP"
• "SDL_HAT_LEFTDOWN"

Joystick trackball events

jball_which

The field "jball_which" is the index of the joystick that reported the event.

jball_ball

"jball_ball" is the index of the trackball (for a more detailed explanation see the Joystick section).

jball_xrel, jball_yrel

Trackballs only return relative motion, this is the change in position on the ball since it was last polled (last cycle of the event loop) and it is stored in "jball_xrel" and "jball_yrel".

Window resize events

When "SDL_RESIZABLE" is passed as a flag to "SDL_SetVideoMode" the user is allowed to resize the applications window. When the window is resized an "SDL_VIDEORESIZE" is reported, with the new window width and height values stored in the resize structure's "resize_w" and "resize_h". When an "SDL_VIDEORESIZE" is received the window should be resized to the new dimensions using SDL_SetVideoMode.

Window expose events

System window manager events

If you want to obtain system-specific information about the window manager, you can fill in the version member of a SDL_SysWMinfo structure (details can be found in SDL_syswm.h, which must be included) using the SDL_VERSION() macro found in SDL_version.h, and pass it to the function:

 int SDL_GetWMInfo(SDL_SysWMinfo *info);

See <http://www.libsdl.org/cgi/docwiki.cgi/SDL_SysWMEvent>

syswm_msg

User defined events

 my $event = SDL::Event->new();
    $event->type ( SDL_USEREVENT + 3 );
    $event->user_code(10);
    $event->user_data1('hello event');

 SDL::Events::push_event($event);

user_code

User defined event code (integer).

user_data1, user_data2

User defined data.

Quit event

Note: The macro SDL_QuitRequested will return non-zero if a quit event is pending