1SDL::Event(3)         User Contributed Perl Documentation        SDL::Event(3)
2
3
4

NAME

6       SDL::Event - General event structure
7
8   CATEGORY
9       Core, Events, Structure
10

SYNOPSIS

12        use SDL::Event;  # for the event object itself
13        use SDL::Events; # functions for event queue handling
14
15        SDL::init(SDL_INIT_VIDEO);
16        my $event = SDL::Event->new();
17
18        while(1)
19        {
20            SDL::Events::pump_events();
21
22            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
33               last if $event->type == SDL_QUIT;
34            }
35
36            # your screen drawing code will be here
37        }
38

DESCRIPTION

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
43       "SDL::init(SDL_INIT_VIDEO);"
44
45       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
50       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

METHODS

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
63        use SDL::Event;
64
65        my $event = SDL::Event->new();
66
67   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
72        print 'heureka' if $event->type == SDL_MOUSEBUTTONDOWN;
73
74       Available type constants:
75
76       ·   SDL_ACTIVEEVENT - Application visibility event structure
77
78       ·   SDL_KEYDOWN - Keyboard event structure
79
80       ·   SDL_KEYUP - Keyboard event structure
81
82       ·   SDL_MOUSEMOTION - Mouse motion event structure
83
84       ·   SDL_MOUSEBUTTONDOWN - Mouse button event structure
85
86       ·   SDL_MOUSEBUTTONUP - Mouse button event structure
87
88       ·   SDL_JOYAXISMOTION - Joystick axis motion event structure
89
90       ·   SDL_JOYBALLMOTION - Joystick trackball motion event structure
91
92       ·   SDL_JOYHATMOTION - Joystick hat position change event structure
93
94       ·   SDL_JOYBUTTONDOWN - Joystick button event structure
95
96       ·   SDL_JOYBUTTONUP - Joystick button event structure
97
98       ·   SDL_VIDEORESIZE - Window resize event structure
99
100       ·   SDL_VIDEOEXPOSE - Window expose event
101
102       ·   SDL_QUIT - Quit requested event
103
104       ·   SDL_USEREVENT - A user-defined event type
105
106       ·   SDL_SYSWMEVENT - Platform-dependent window manager event.
107
108       Event types are grouped by masks. "SDL_EVENTMASK($type)" will return
109       the proper mask for the given "type".
110
111       Available event mask constants:
112
113       ·   SDL_ACTIVEEVENTMASK
114
115       ·   SDL_KEYDOWNMASK
116
117       ·   SDL_KEYUPMASK
118
119       ·   SDL_KEYEVENTMASK
120
121       ·   SDL_MOUSEMOTIONMASK
122
123       ·   SDL_MOUSEBUTTONDOWNMASK
124
125       ·   SDL_MOUSEBUTTONUPMASK
126
127       ·   SDL_MOUSEEVENTMASK
128
129       ·   SDL_JOYAXISMOTIONMASK
130
131       ·   SDL_JOYBALLMOTIONMASK
132
133       ·   SDL_JOYHATMOTIONMASK
134
135       ·   SDL_JOYBUTTONDOWNMASK
136
137       ·   SDL_JOYBUTTONUPMASK
138
139       ·   SDL_JOYEVENTMASK
140
141       ·   SDL_VIDEORESIZEMASK
142
143       ·   SDL_VIDEOEXPOSEMASK
144
145       ·   SDL_QUITMASK
146
147       ·   SDL_SYSWMEVENTMASK
148
149       This way you can check if a given "type" matches a mask:
150
151        (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
156        # and also true is:
157
158        (SDL_MOUSEEVENTMASK == SDL_EVENTMASK(SDL_MOUSEBUTTONDOWN)
159                             | SDL_EVENTMASK(SDL_MOUSEBUTTONUP)
160                             | SDL_EVENTMASK(SDL_MOUSEMOTION))
161
162   Application visibility events
163       "active" is used when an event of type "SDL_ACTIVEEVENT" is reported.
164
165       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
169       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
173       Finally, a "SDL_APPACTIVE" type event occurs when the application is
174       either minimised/iconified (gain=0) or restored.
175
176       A single event can have multiple values set in state.
177
178       Note: This event does not occur when an application window is first
179       created.
180
181       A new ActiveEvent (to fake focus loss) will be created like this:
182
183        my $event = SDL::Event->new();
184           $event->type(SDL_ACTIVEEVENT);
185           $event->active_gain(0);
186           $event->active_state(SDL_APPMOUSEFOCUS);
187
188        # I think this is wrong, ->active_type() should get SDL_APPMOUSEFOCUS, but what state gets?
189
190       active_gain
191
192       See "active". 0 if the event is a loss or 1 if it is a gain.
193
194       active_state
195
196       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
201   Keyboard events
202       "key" is used when an event of type "SDL_KEYDOWN" or "SDL_KEYUP" is
203       reported.
204
205       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
210       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
217       Note: Repeating "SDL_KEYDOWN" events will occur if key repeat is
218       enabled (see SDL::Events::enable_key_repeat).
219
220       key_state
221
222       "SDL_PRESSED" or "SDL_RELEASED"
223
224       key_scancode
225
226       The "scancode" field should generally be left alone, it is the
227       hardware-dependent scancode returned by the keyboard.
228
229       key_sym
230
231       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
235        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
248       key_mod
249
250       "mod" stores the current state of the keyboard modifiers as explained
251       in SDL_GetModState.
252
253       key_unicode
254
255       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
261        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
271       UNICODE translation does create a slight overhead so don't enable it
272       unless its needed.
273
274       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
278   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
285       motion_state
286
287       The button state can be interpreted using the "SDL_BUTTON" macro (see
288       SDL::Events::get_mouse_state).
289
290       motion_x, motion_y
291
292       The X/Y coordinates of the mouse
293
294       motion_xrel, motion_yrel
295
296       Relative motion in the X/Y direction.
297
298       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
303   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
312       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
316       button_which
317
318       The input device index
319
320       button_button
321
322       The mouse button index ("SDL_BUTTON_LEFT", "SDL_BUTTON_MIDDLE",
323       "SDL_BUTTON_RIGHT", "SDL_BUTTON_WHEELUP", "SDL_BUTTON_WHEELDOWN")
324
325       button_state
326
327       "SDL_PRESSED" or "SDL_RELEASED"
328
329       button_x, button_y
330
331       The X/Y coordinates of the mouse at press/release time
332
333   Joystick axis events
334       A "SDL_JOYAXISMOTION" event occurs whenever a user moves an axis on the
335       joystick.
336
337       jaxis_which
338
339       The field "jaxis_which" is the index of the joystick that reported the
340       event.
341
342       jaxis_axis
343
344       The "jaxis_axis" is the index of the axis (for a more detailed
345       explanation see the Joystick section).
346
347       jaxis_value
348
349       "jaxis_value" is the current position of the axis (range: -32768 to
350       32767).
351
352   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
356       jbutton_which
357
358       The field "jbutton_which" is the index of the joystick that reported
359       the event.
360
361       jbutton_button
362
363       The "jbutton_button" is the index of the button (for a more detailed
364       explanation see the Joystick section).
365
366       jbutton_state
367
368       "jbutton_state" is the current state of the button which is either
369       "jbutton_SDL_PRESSED" or "jbutton_SDL_RELEASED".
370
371   Joystick hat events
372       A "SDL_JOYHATMOTION" event occurs when ever a user moves a hat on the
373       joystick.
374
375       jhat_which
376
377       The field "jhat_which" is the index of the joystick that reported the
378       event.
379
380       jhat_hat
381
382       "jhat_hat" is the index of the hat (for a more detailed explanation see
383       the Joystick section).
384
385       jhat_value
386
387       "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
391       ·   "SDL_HAT_CENTERED"
392
393       ·   "SDL_HAT_UP"
394
395       ·   "SDL_HAT_RIGHT"
396
397       ·   "SDL_HAT_DOWN"
398
399       ·   "SDL_HAT_LEFT"
400
401       The following defines are also provided:
402
403       ·   "SDL_HAT_RIGHTUP"
404
405       ·   "SDL_HAT_RIGHTDOWN"
406
407       ·   "SDL_HAT_LEFTUP"
408
409       ·   "SDL_HAT_LEFTDOWN"
410
411   Joystick trackball events
412       A "SDL_JOYBALLMOTION" event occurs when a user moves a trackball on the
413       joystick.
414
415       jball_which
416
417       The field "jball_which" is the index of the joystick that reported the
418       event.
419
420       jball_ball
421
422       "jball_ball" is the index of the trackball (for a more detailed
423       explanation see the Joystick section).
424
425       jball_xrel, jball_yrel
426
427       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
431   Window resize events
432       resize_w, resize_h
433
434       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
441   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
446   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
453       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
459        int SDL_GetWMInfo(SDL_SysWMinfo *info);
460
461       See <http://www.libsdl.org/cgi/docwiki.cgi/SDL_SysWMEvent>
462
463       syswm_msg
464
465   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
472        my $event = SDL::Event->new();
473           $event->type ( SDL_USEREVENT + 3 );
474           $event->user_code(10);
475           $event->user_data1('hello event');
476
477        SDL::Events::push_event($event);
478
479       user_code
480
481       User defined event code (integer).
482
483       user_data1, user_data2
484
485       User defined data.
486
487   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
495       Note: The macro SDL_QuitRequested will return non-zero if a quit event
496       is pending
497

AUTHORS

499       See "AUTHORS" in SDL.
500

SEE ALSO

502       perl
503
504
505
506perl v5.28.1                      2019-02-02                     SDL::Event(3)
Impressum