SDL::Event - General event structure
Core, Events, Structure
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) { SDL::Events::pump_events(); if(SDL::Events::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.
SDL::Events::poll_event()
SDL::Events::peep_events
SDL::Events::wait_event()
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.
SDL::Event
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.
new
poll_event($event)
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.
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.
SDL_EVENTMASK($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.
active
SDL_ACTIVEEVENT
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.
SDL_APPMOUSEFOCUS
A SDL_APPINPUTFOCUS type activation event occurs when the application loses or gains keyboard focus. This usually occurs when another application is made active.
SDL_APPINPUTFOCUS
Finally, a SDL_APPACTIVE type event occurs when the application is either minimised/iconified (gain=0) or restored.
SDL_APPACTIVE
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.
key
SDL_KEYDOWN
SDL_KEYUP
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).
type=SDL_KEYUP
key_state=SDL_RELEASED
type=SDL_KEYDOWN
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.
SDLK_CAPSLOCK
SDLK_NUMLOCK
SDL_RELEASED
KEYUP
KEYDOWN
Note: Repeating SDL_KEYDOWN events will occur if key repeat is enabled (see SDL::Events::enable_key_repeat).
SDL_PRESSED or SDL_RELEASED
SDL_PRESSED
The scancode field should generally be left alone, it is the hardware-dependent scancode returned by the keyboard.
scancode
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:
sym
while(poll_event($event)) { switch($event->type) { case SDL_KEYDOWN: move_left() if($event->key_sym == SDLK_LEFT); break; . . . } }
mod stores the current state of the keyboard modifiers as explained in SDL_GetModState.
mod
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:
unicode
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
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_x
motion_y
motion_xrel
motion_yrel
motion_state
The button state can be interpreted using the SDL_BUTTON macro (see SDL::Events::get_mouse_state).
SDL_BUTTON
The X/Y coordinates of the mouse
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.
When a mouse button press or release is detected, the number of the button pressed (from 1 to 255, with 1 usually being the left button and 2 the right) is placed into button_button. The position of the mouse when this event occured is stored in the button_x and the button_y fields. Like a keyboard event, information on whether the event was a press or a release event is stored in both the button_type and button_state fields, but this should be obvious.
button_button
button_x
button_y
button_type
button_state
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.
SDL_MOUSEBUTTONDOWN
SDL_MOUSEBUTTONUP
The input device index
The mouse button index (SDL_BUTTON_LEFT, SDL_BUTTON_MIDDLE, SDL_BUTTON_RIGHT, SDL_BUTTON_WHEELUP, SDL_BUTTON_WHEELDOWN)
SDL_BUTTON_LEFT
SDL_BUTTON_MIDDLE
SDL_BUTTON_RIGHT
SDL_BUTTON_WHEELUP
SDL_BUTTON_WHEELDOWN
The X/Y coordinates of the mouse at press/release time
A SDL_JOYAXISMOTION event occurs whenever a user moves an axis on the joystick.
SDL_JOYAXISMOTION
The field jaxis_which is the index of the joystick that reported the event.
jaxis_which
The jaxis_axis is the index of the axis (for a more detailed explaination see the Joystick section).
jaxis_axis
jaxis_value is the current position of the axis (range: -32768 to 32767).
jaxis_value
A SDL_JOYBUTTONDOWN or SDL_JOYBUTTONUP event occurs when ever a user presses or releases a button on a joystick.
SDL_JOYBUTTONDOWN
SDL_JOYBUTTONUP
The field jbutton_which is the index of the joystick that reported the event.
jbutton_which
The jbutton_button is the index of the button (for a more detailed explanation see the Joystick section).
jbutton_button
jbutton_state is the current state of the button which is either jbutton_SDL_PRESSED or jbutton_SDL_RELEASED.
jbutton_state
jbutton_SDL_PRESSED
jbutton_SDL_RELEASED
A SDL_JOYHATMOTION event occurs when ever a user moves a hat on the joystick.
SDL_JOYHATMOTION
The field jhat_which is the index of the joystick that reported the event.
jhat_which
jhat_hat is the index of the hat (for a more detailed explanation see the Joystick section).
jhat_hat
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):
jhat_value
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
A SDL_JOYBALLMOTION event occurs when a user moves a trackball on the joystick.
SDL_JOYBALLMOTION
The field jball_which is the index of the joystick that reported the event.
jball_which
jball_ball is the index of the trackball (for a more detailed explanation see the Joystick section).
jball_ball
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.
jball_xrel
jball_yrel
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.
SDL_RESIZABLE
SDL_SetVideoMode
SDL_VIDEORESIZE
resize_w
resize_h
A VIDEOEXPOSE event is triggered when the screen has been modified outside of the application, usually by the window manager and needs to be redrawn.
VIDEOEXPOSE
The system window manager event contains a system-specific information about unknown window manager events. If you enable this event using SDL_EventState, it will be generated whenever unhandled events are received from the window manager. This can be used, for example, to implement cut-and-paste in your application.
SDL_EventState
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
This event is unique, it is never created by SDL but only by the user. The event can be pushed onto the event queue using SDL::Events::push_event. The contents of the structure members are completely up to the programmer, the only requirement is that type is a value from SDL_USEREVENT to SDL_NUMEVENTS-1 (inclusive)
SDL::Events::push_event
SDL_USEREVENT
SDL_NUMEVENTS-1
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 defined event code (integer).
User defined data.
As can be seen, the SDL_QuitEvent structure serves no useful purpose. The event itself, on the other hand, is very important. If you filter out or ignore a quit event then it is impossible for the user to close the window. On the other hand, if you do accept a quit event then the application window will be closed, and screen updates will still report success even though the application will no longer be visible.
SDL_QuitEvent
Note: The macro SDL_QuitRequested will return non-zero if a quit event is pending
See "AUTHORS" in SDL.
perl
To install SDL, copy and paste the appropriate command in to your terminal.
cpanm
cpanm SDL
CPAN shell
perl -MCPAN -e shell install SDL
For more information on module installation, please visit the detailed CPAN module installation guide.