NAME¶
SDL::Event - General event structure
CATEGORY¶
Core, Events, Structure
SYNOPSIS¶
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
}
DESCRIPTION¶
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.
METHODS¶
new¶
"new" creates an empty event-object, which can be used store
information. Either by calling "poll_event($event)" that transfers
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();
type¶
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_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¶
"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?
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¶
"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::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¶
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::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.
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 occurred 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.
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¶
A "SDL_JOYAXISMOTION" event occurs whenever a user moves an axis on
the joystick.
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).
A "SDL_JOYBUTTONDOWN" or "SDL_JOYBUTTONUP" event occurs when
ever a user presses or releases a button on a joystick.
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¶
A "SDL_JOYHATMOTION" event occurs when ever a user moves a hat on the
joystick.
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¶
A "SDL_JOYBALLMOTION" event occurs when a user moves a trackball on
the joystick.
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¶
resize_w, resize_h
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¶
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.
System window manager events¶
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.
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¶
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)
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¶
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.
Note: The macro SDL_QuitRequested will return non-zero if a quit event is
pending
AUTHORS¶
See "AUTHORS" in SDL.
SEE ALSO¶
perl