SDL::Event - General event structure
+Core, Events, Structure
+ + use SDL::Event; # for the event object itself
- use SDL::Events qw(pump_events poll_event); # functions for event queue handling
+ use SDL::Event; # for the event object itself
+ use SDL::Events; # functions for event queue handling
SDL::init(SDL_INIT_VIDEO);
my $event = SDL::Event->new();
while(1)
{
- pump_events();
+ SDL::Events::pump_events();
- if(poll_event($event))
+ if(SDL::Events::poll_event($event))
{
if($event->type == SDL_MOUSEBUTTONDOWN)
{
@@ -170,12 +160,12 @@ or by setting all the needed data manually in order to push the event to the que
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;
+ print 'heureka' if $event->type == SDL_MOUSEBUTTONDOWN;
Available type constants:
- - SDL_ACTIVEEVENT - Application visibility event structure
+ - SDL_ACTIVEEVENT - Application visibility event structure
- SDL_KEYDOWN - Keyboard event structure
- SDL_KEYUP - Keyboard event structure
- SDL_MOUSEMOTION - Mouse motion event structure
@@ -193,12 +183,47 @@ which union member relates to which event type.
- SDL_SYSWMEVENT - Platform-dependent window manager event.
-TODO: SDL_EVENTMASK()
+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
-
-active is a member of the SDL::Event union and is used when an event of type SDL_ACTIVEEVENT is reported.
+Application visibility events
+
+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.
@@ -217,238 +242,325 @@ This usually occurs when another application is made active.
-active_type
-
-
-
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).
-key
-
-
-
-key_type
-
+Keyboard events
+
+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).
key_state
-
-
-key_keysym
-
+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_EnableUNICODE.
+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");
+ }
-
-motion
-
+
+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
-motion_type
-
+Mouse motion events
+
+Simply put, a SDL_MOUSEMOTION type event occurs when a user moves the mouse within the
+application window or when SDL_WarpMouse is called. Both the absolute (motion_x and motion_y)
+and relative (motion_xrel and motion_yrel) coordinates are reported along with the current
+button states (motion_state).
motion_state
+The button state can be interpreted using the SDL_BUTTON macro (see SDL_GetMouseState).
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.
-button
-
-button_type
-