1SDL::Event(3) User Contributed Perl Documentation SDL::Event(3)
2
6 SDL::Event - General event structure
7 CATEGORY
9 Core, Events, Structure
10
12 use SDL::Event; # for the event object itself
13 use SDL::Events; # functions for event queue handling
14 SDL::init(SDL_INIT_VIDEO);
16 my $event = SDL::Event->new();
17 while(1)
19 {
20 SDL::Events::pump_events();
21 if(SDL::Events::poll_event($event))
23 {
24 if($event->type == SDL_MOUSEBUTTONDOWN)
25 {
26 # now you can handle the details
27 $event->button_which;
28 $event->button_button;
29 $event->button_x;
30 $event->button_y;
31 }
32 last if $event->type == SDL_QUIT;
34 }
35 # your screen drawing code will be here
37 }
38
40 Event handling allows your application to receive input from the user.
41 Event handling is initalised (along with video) with a call to:
42 "SDL::init(SDL_INIT_VIDEO);"
44 Internally, SDL stores all the events waiting to be handled in an event
46 queue. Using functions like "SDL::Events::poll_event()",
47 "SDL::Events::peep_events" and "SDL::Events::wait_event()" you can
48 observe and handle waiting input events.
49 The key to event handling in SDL is the "SDL::Event" union. The event
51 queue itself is composed of a series of "SDL::Event" unions, one for
52 each waiting event. "SDL::Event" unions are read from the queue with
53 the "SDL::Events::poll_event()" function and it is then up to the
54 application to process the information stored with them.
55
57 new
58 "new" creates an empty event-object, which can be used store
59 information. Either by calling "poll_event($event)" that transfers one
60 event from the queue into our object or by setting all the needed data
61 manually in order to push the event to the queue.
62 use SDL::Event;
64 my $event = SDL::Event->new();
66 type
68 SDL::Event is a union of all event structures used in SDL, using it is
69 a simple matter of knowing which union member relates to which event
70 "type".
71 print 'heureka' if $event->type == SDL_MOUSEBUTTONDOWN;
73 Available type constants:
75 • SDL_ACTIVEEVENT - Application visibility event structure
77 • SDL_KEYDOWN - Keyboard event structure
79 • SDL_KEYUP - Keyboard event structure
81 • SDL_MOUSEMOTION - Mouse motion event structure
83 • SDL_MOUSEBUTTONDOWN - Mouse button event structure
85 • SDL_MOUSEBUTTONUP - Mouse button event structure
87 • SDL_JOYAXISMOTION - Joystick axis motion event structure
89 • SDL_JOYBALLMOTION - Joystick trackball motion event structure
91 • SDL_JOYHATMOTION - Joystick hat position change event structure
93 • SDL_JOYBUTTONDOWN - Joystick button event structure
95 • SDL_JOYBUTTONUP - Joystick button event structure
97 • SDL_VIDEORESIZE - Window resize event structure
99 • SDL_VIDEOEXPOSE - Window expose event
101 • SDL_QUIT - Quit requested event
103 • SDL_USEREVENT - A user-defined event type
105 • SDL_SYSWMEVENT - Platform-dependent window manager event.
107 Event types are grouped by masks. "SDL_EVENTMASK($type)" will return
109 the proper mask for the given "type".
110 Available event mask constants:
112 • SDL_ACTIVEEVENTMASK
114 • SDL_KEYDOWNMASK
116 • SDL_KEYUPMASK
118 • SDL_KEYEVENTMASK
120 • SDL_MOUSEMOTIONMASK
122 • SDL_MOUSEBUTTONDOWNMASK
124 • SDL_MOUSEBUTTONUPMASK
126 • SDL_MOUSEEVENTMASK
128 • SDL_JOYAXISMOTIONMASK
130 • SDL_JOYBALLMOTIONMASK
132 • SDL_JOYHATMOTIONMASK
134 • SDL_JOYBUTTONDOWNMASK
136 • SDL_JOYBUTTONUPMASK
138 • SDL_JOYEVENTMASK
140 • SDL_VIDEORESIZEMASK
142 • SDL_VIDEOEXPOSEMASK
144 • SDL_QUITMASK
146 • SDL_SYSWMEVENTMASK
148 This way you can check if a given "type" matches a mask:
150 (SDL_EVENTMASK(SDL_JOYBUTTONDOWN) & SDL_MOUSEEVENTMASK) # is false
152 (SDL_EVENTMASK(SDL_MOUSEBUTTONDOWN) & SDL_MOUSEEVENTMASK) # is true
153 (SDL_EVENTMASK(SDL_MOUSEBUTTONUP) & SDL_MOUSEEVENTMASK) # is true
154 (SDL_EVENTMASK(SDL_MOUSEMOTION) & SDL_MOUSEEVENTMASK) # is true
155 # and also true is:
157 (SDL_MOUSEEVENTMASK == SDL_EVENTMASK(SDL_MOUSEBUTTONDOWN)
159 | SDL_EVENTMASK(SDL_MOUSEBUTTONUP)
160 | SDL_EVENTMASK(SDL_MOUSEMOTION))
161 Application visibility events
163 "active" is used when an event of type "SDL_ACTIVEEVENT" is reported.
164 When the mouse leaves or enters the window area a "SDL_APPMOUSEFOCUS"
166 type activation event occurs, if the mouse entered the window then gain
167 will be 1, otherwise gain will be 0.
168 A "SDL_APPINPUTFOCUS" type activation event occurs when the application
170 loses or gains keyboard focus. This usually occurs when another
171 application is made active.
172 Finally, a "SDL_APPACTIVE" type event occurs when the application is
174 either minimised/iconified (gain=0) or restored.
175 A single event can have multiple values set in state.
177 Note: This event does not occur when an application window is first
179 created.
180 A new ActiveEvent (to fake focus loss) will be created like this:
182 my $event = SDL::Event->new();
184 $event->type(SDL_ACTIVEEVENT);
185 $event->active_gain(0);
186 $event->active_state(SDL_APPMOUSEFOCUS);
187 # I think this is wrong, ->active_type() should get SDL_APPMOUSEFOCUS, but what state gets?
189 active_gain
191 See "active". 0 if the event is a loss or 1 if it is a gain.
193 active_state
195 A bitmask of the following values: SDL_APPMOUSEFOCUS if mouse focus was
197 gained or lost, SDL_APPINPUTFOCUS if input focus was gained or lost,
198 and SDL_APPACTIVE if the application was iconified (gain=0) or
199 restored(gain=1).
200 Keyboard events
202 "key" is used when an event of type "SDL_KEYDOWN" or "SDL_KEYUP" is
203 reported.
204 The type and state actually report the same information, they just use
206 different values to do it. A keyboard event generally occurs when a
207 key is released ("type=SDL_KEYUP" or "key_state=SDL_RELEASED") and when
208 a key is pressed ("type=SDL_KEYDOWN" or "key_state=SDL_PRESSED").
209 The "SDLK_CAPSLOCK" and "SDLK_NUMLOCK" keys are special cases and
211 report an "SDL_KEYDOWN" when first pressed, then an "SDL_RELEASED" when
212 released and pressed again. For these keys "KEYUP" and "KEYDOWN" events
213 are therefore analogous to the state of the caps lock and num lock LEDs
214 rather than the keys themselves. These special cases are required for
215 compatibility with Sun workstations.
216 Note: Repeating "SDL_KEYDOWN" events will occur if key repeat is
218 enabled (see SDL::Events::enable_key_repeat).
219 key_state
221 "SDL_PRESSED" or "SDL_RELEASED"
223 key_scancode
225 The "scancode" field should generally be left alone, it is the
227 hardware-dependent scancode returned by the keyboard.
228 key_sym
230 The "sym" field is extremely useful. It is the SDL-defined value of the
232 key (see the keysym definitions in SDLKey). This field is very useful
233 when you are checking for certain key presses, like so:
234 while(poll_event($event))
236 {
237 switch($event->type)
238 {
239 case SDL_KEYDOWN:
240 move_left() if($event->key_sym == SDLK_LEFT);
241 break;
242 .
243 .
244 .
245 }
246 }
247 key_mod
249 "mod" stores the current state of the keyboard modifiers as explained
251 in SDL_GetModState.
252 key_unicode
254 The "unicode" field is only used when UNICODE translation is enabled
256 with SDL::Events::enable_unicode. If "unicode" is non-zero then this
257 is the UNICODE character corresponding to the keypress. If the high 9
258 bits of the character are 0, then this maps to the equivalent ASCII
259 character:
260 my $char;
262 if(($event->key_unicode & 0xFF80) == 0)
263 {
264 $char = $event->key_unicode & 0x7F;
265 }
266 else
267 {
268 print("An International Character.\n");
269 }
270 UNICODE translation does create a slight overhead so don't enable it
272 unless its needed.
273 NOTE: Key release events (SDL_KEYUP) won't necessarily (ever?) contain
275 unicode information. See
276 <http://lists.libsdl.org/pipermail/sdl-libsdl.org/2005-January/048355.html>
277 Mouse motion events
279 Simply put, a SDL_MOUSEMOTION type event occurs when a user moves the
280 mouse within the application window or when SDL_WarpMouse is called.
281 Both the absolute ("motion_x" and "motion_y") and relative
282 ("motion_xrel" and "motion_yrel") coordinates are reported along with
283 the current button states ("motion_state").
284 motion_state
286 The button state can be interpreted using the "SDL_BUTTON" macro (see
288 SDL::Events::get_mouse_state).
289 motion_x, motion_y
291 The X/Y coordinates of the mouse
293 motion_xrel, motion_yrel
295 Relative motion in the X/Y direction.
297 If the cursor is hidden (SDL_ShowCursor(0)) and the input is grabbed
299 (SDL_WM_GrabInput(SDL_GRAB_ON)), then the mouse will give relative
300 motion events even when the cursor reaches the edge of the screen.
301 This is currently only implemented on Windows and Linux/Unix-alikes.
302 Mouse button events
304 When a mouse button press or release is detected, the number of the
305 button pressed (from 1 to 255, with 1 usually being the left button and
306 2 the right) is placed into "button_button". The position of the mouse
307 when this event occurred is stored in the "button_x" and the "button_y"
308 fields. Like a keyboard event, information on whether the event was a
309 press or a release event is stored in both the "button_type" and
310 "button_state" fields, but this should be obvious.
311 Mouse wheel events are reported as buttons 4 (up) and 5 (down). Two
313 events are generated i.e. you get a "SDL_MOUSEBUTTONDOWN" followed by a
314 "SDL_MOUSEBUTTONUP" event.
315 button_which
317 The input device index
319 button_button
321 The mouse button index ("SDL_BUTTON_LEFT", "SDL_BUTTON_MIDDLE",
323 "SDL_BUTTON_RIGHT", "SDL_BUTTON_WHEELUP", "SDL_BUTTON_WHEELDOWN")
324 button_state
326 "SDL_PRESSED" or "SDL_RELEASED"
328 button_x, button_y
330 The X/Y coordinates of the mouse at press/release time
332 Joystick axis events
334 A "SDL_JOYAXISMOTION" event occurs whenever a user moves an axis on the
335 joystick.
336 jaxis_which
338 The field "jaxis_which" is the index of the joystick that reported the
340 event.
341 jaxis_axis
343 The "jaxis_axis" is the index of the axis (for a more detailed
345 explanation see the Joystick section).
346 jaxis_value
348 "jaxis_value" is the current position of the axis (range: -32768 to
350 32767).
351 Joystick button events
353 A "SDL_JOYBUTTONDOWN" or "SDL_JOYBUTTONUP" event occurs when ever a
354 user presses or releases a button on a joystick.
355 jbutton_which
357 The field "jbutton_which" is the index of the joystick that reported
359 the event.
360 jbutton_button
362 The "jbutton_button" is the index of the button (for a more detailed
364 explanation see the Joystick section).
365 jbutton_state
367 "jbutton_state" is the current state of the button which is either
369 "jbutton_SDL_PRESSED" or "jbutton_SDL_RELEASED".
370 Joystick hat events
372 A "SDL_JOYHATMOTION" event occurs when ever a user moves a hat on the
373 joystick.
374 jhat_which
376 The field "jhat_which" is the index of the joystick that reported the
378 event.
379 jhat_hat
381 "jhat_hat" is the index of the hat (for a more detailed explanation see
383 the Joystick section).
384 jhat_value
386 "jhat_value" is the current position of the hat. It is a bitwise OR'd
388 combination of the following values (whose meanings should be pretty
389 obvious):
390 • "SDL_HAT_CENTERED"
392 • "SDL_HAT_UP"
394 • "SDL_HAT_RIGHT"
396 • "SDL_HAT_DOWN"
398 • "SDL_HAT_LEFT"
400 The following defines are also provided:
402 • "SDL_HAT_RIGHTUP"
404 • "SDL_HAT_RIGHTDOWN"
406 • "SDL_HAT_LEFTUP"
408 • "SDL_HAT_LEFTDOWN"
410 Joystick trackball events
412 A "SDL_JOYBALLMOTION" event occurs when a user moves a trackball on the
413 joystick.
414 jball_which
416 The field "jball_which" is the index of the joystick that reported the
418 event.
419 jball_ball
421 "jball_ball" is the index of the trackball (for a more detailed
423 explanation see the Joystick section).
424 jball_xrel, jball_yrel
426 Trackballs only return relative motion, this is the change in position
428 on the ball since it was last polled (last cycle of the event loop) and
429 it is stored in "jball_xrel" and "jball_yrel".
430 Window resize events
432 resize_w, resize_h
433 When "SDL_RESIZABLE" is passed as a flag to "SDL_SetVideoMode" the user
435 is allowed to resize the applications window. When the window is
436 resized an "SDL_VIDEORESIZE" is reported, with the new window width and
437 height values stored in the resize structure's "resize_w" and
438 "resize_h". When an "SDL_VIDEORESIZE" is received the window should be
439 resized to the new dimensions using SDL_SetVideoMode.
440 Window expose events
442 A "VIDEOEXPOSE" event is triggered when the screen has been modified
443 outside of the application, usually by the window manager and needs to
444 be redrawn.
445 System window manager events
447 The system window manager event contains a system-specific information
448 about unknown window manager events. If you enable this event using
449 "SDL_EventState", it will be generated whenever unhandled events are
450 received from the window manager. This can be used, for example, to
451 implement cut-and-paste in your application.
452 If you want to obtain system-specific information about the window
454 manager, you can fill in the version member of a SDL_SysWMinfo
455 structure (details can be found in SDL_syswm.h, which must be included)
456 using the SDL_VERSION() macro found in SDL_version.h, and pass it to
457 the function:
458 int SDL_GetWMInfo(SDL_SysWMinfo *info);
460 See <http://www.libsdl.org/cgi/docwiki.cgi/SDL_SysWMEvent>
462 syswm_msg
464 User defined events
466 This event is unique, it is never created by SDL but only by the user.
467 The event can be pushed onto the event queue using
468 "SDL::Events::push_event". The contents of the structure members are
469 completely up to the programmer, the only requirement is that type is a
470 value from "SDL_USEREVENT" to "SDL_NUMEVENTS-1" (inclusive)
471 my $event = SDL::Event->new();
473 $event->type ( SDL_USEREVENT + 3 );
474 $event->user_code(10);
475 $event->user_data1('hello event');
476 SDL::Events::push_event($event);
478 user_code
480 User defined event code (integer).
482 user_data1, user_data2
484 User defined data.
486 Quit event
488 As can be seen, the "SDL_QuitEvent" structure serves no useful purpose.
489 The event itself, on the other hand, is very important. If you filter
490 out or ignore a quit event then it is impossible for the user to close
491 the window. On the other hand, if you do accept a quit event then the
492 application window will be closed, and screen updates will still report
493 success even though the application will no longer be visible.
494 Note: The macro SDL_QuitRequested will return non-zero if a quit event
496 is pending
497
499 See "AUTHORS" in SDL.
500
502 perl
503perl v5.34.0 2021-07-22 SDL::Event(3)