-
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)
{
@@ -157,22 +165,22 @@ which union member relates to which event type
.
Available type constants:
Event types are grouped by masks. SDL_EVENTMASK($type)
will return the proper mask for the given type
.
@@ -213,8 +221,8 @@ which union member relates to which event
type
.
-
+
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.
@@ -245,8 +253,8 @@ This usually occurs when another application is made active.
SDL_APPINPUTFOCUS if input focus was gained or lost, and SDL_APPACTIVE if the application was iconified (gain=0) or restored(gain=1).
-
key
-
+
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
)
@@ -255,7 +263,7 @@ and when a key is pressed (type=SDL_KEYDOWN
or key_state=SDL_
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
).
+
Note: Repeating SDL_KEYDOWN
events will occur if key repeat is enabled (see enable_key_repeat).
key_state
@@ -265,164 +273,294 @@ These special cases are required for compatibility with Sun workstations.
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 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
-
motion
-
+
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 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 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.
+
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.
+
The mouse button index (SDL_BUTTON_LEFT
, SDL_BUTTON_MIDDLE
, SDL_BUTTON_RIGHT
, SDL_BUTTON_WHEELUP
,
+SDL_BUTTON_WHEELDOWN
)
+
SDL_PRESSED
or SDL_RELEASED
+
The X/Y coordinates of the mouse at press/release time
-
jaxis
-
+
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 explaination 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.
+
The field jbutton_which
is the index of the joystick that reported the event.
+
The jbutton_button
is the index of the button (for a more detailed explanation see the Joystick section).
+
jbutton_state
is the current state of the button which is either jbutton_SDL_PRESSED
+or jbutton_SDL_RELEASED
.
-
jhat
-
+
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
+
+
-
jball
-
+
Joystrick 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
.
-
resize
-
+
Window resize events
+
-
resize_x, resize_y
-
+
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.
-
expose
-
+
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.
-
syswm
-
+
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
-
+
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
-
quit
-
-
Create a new SDL::Event object.
+
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
-
AUTHOR
Top
-
+
AUTHORS
Top
+
SEE ALSO
Top
\ No newline at end of file