/lib/pods/SDL/Event.pod

  1
  2=head1 NAME
  3
  4SDL::Event - General event structure
  5
  6=head2 CATEGORY
  7
  8Core, Events, Structure
  9
 10=head1 SYNOPSIS
 11
 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 
 39=head1 DESCRIPTION
 40
 41Event handling allows your application to receive input from the user. 
 42Event handling is initalised (along with video) with a call to:
 43
 44C<SDL::init(SDL_INIT_VIDEO);>
 45
 46Internally, SDL stores all the events waiting to be handled in an event queue. 
 47Using functions like C<SDL::Events::poll_event()>, C<SDL::Events::peep_events> 
 48and C<SDL::Events::wait_event()> you can observe and handle waiting input events.
 49
 50The key to event handling in SDL is the C<SDL::Event> union. 
 51The event queue itself is composed of a series of C<SDL::Event> unions, one for each waiting event. 
 52C<SDL::Event> unions are read from the queue with the C<SDL::Events::poll_event()> function 
 53and it is then up to the application to process the information stored with them. 
 54
 55=head1	METHODS
 56
 57=head2	new
 58
 59C<new> creates an empty event-object, which can be used store information. 
 60Either by calling C<poll_event($event)> that transfers one event from the queue into our object 
 61or by setting all the needed data manually in order to push the event to the queue.
 62
 63 use SDL::Event;
 64
 65 my $event = SDL::Event->new();
 66 
 67=head2	type
 68
 69SDL::Event is a union of all event structures used in SDL, using it is a simple matter of knowing 
 70which union member relates to which event C<type>.
 71
 72 print 'heureka' if $event->type == SDL_MOUSEBUTTONDOWN;
 73
 74Available type constants:
 75
 76=over 4
 77
 78=item *
 79
 80L<SDL_ACTIVEEVENT|/Application_visibility_events> - Application visibility event structure 
 81
 82=item *
 83
 84L<SDL_KEYDOWN|/Keyboard_events> - Keyboard event structure 
 85
 86=item *
 87
 88L<SDL_KEYUP|/Keyboard_events> - Keyboard event structure 
 89
 90=item *
 91
 92L<SDL_MOUSEMOTION|/Mouse_motion_events> - Mouse motion event structure 
 93
 94=item *
 95
 96L<SDL_MOUSEBUTTONDOWN|/Mouse_button_events> - Mouse button event structure 
 97
 98=item *
 99
100L<SDL_MOUSEBUTTONUP|/Mouse_button_events> - Mouse button event structure 
101
102=item *
103
104L<SDL_JOYAXISMOTION|/Joystick_axis_events> - Joystick axis motion event structure 
105
106=item *
107
108L<SDL_JOYBALLMOTION|/Joystick_trackball_events> - Joystick trackball motion event structure 
109
110=item *
111
112L<SDL_JOYHATMOTION|/Joystick_hat_events> - Joystick hat position change event structure 
113
114=item *
115
116L<SDL_JOYBUTTONDOWN|/Joystick_button_events> - Joystick button event structure 
117
118=item *
119
120L<SDL_JOYBUTTONUP|/Joystick_button_events> - Joystick button event structure 
121
122=item *
123
124L<SDL_VIDEORESIZE|/Window_resize_events> - Window resize event structure 
125
126=item *
127
128L<SDL_VIDEOEXPOSE|/Window_expose_events> - Window expose event 
129
130=item *
131
132L<SDL_QUIT|/Quit_event> - Quit requested event 
133
134=item *
135
136L<SDL_USEREVENT|/User_defined_events> - A user-defined event type 
137
138=item *
139
140L<SDL_SYSWMEVENT|/System_window_manager_events> - Platform-dependent window manager event. 
141
142=back
143
144Event types are grouped by masks. C<SDL_EVENTMASK($type)> will return the proper mask for the given C<type>.
145
146Available event mask constants:
147
148=over 4
149
150=item *
151
152SDL_ACTIVEEVENTMASK
153
154=item *
155
156SDL_KEYDOWNMASK
157
158=item *
159
160SDL_KEYUPMASK
161
162=item *
163
164SDL_KEYEVENTMASK
165
166=item *
167
168SDL_MOUSEMOTIONMASK
169
170=item *
171
172SDL_MOUSEBUTTONDOWNMASK
173
174=item *
175
176SDL_MOUSEBUTTONUPMASK
177
178=item *
179
180SDL_MOUSEEVENTMASK
181
182=item *
183
184SDL_JOYAXISMOTIONMASK
185
186=item *
187
188SDL_JOYBALLMOTIONMASK
189
190=item *
191
192SDL_JOYHATMOTIONMASK
193
194=item *
195
196SDL_JOYBUTTONDOWNMASK
197
198=item *
199
200SDL_JOYBUTTONUPMASK
201
202=item *
203
204SDL_JOYEVENTMASK
205
206=item *
207
208SDL_VIDEORESIZEMASK
209
210=item *
211
212SDL_VIDEOEXPOSEMASK
213
214=item *
215
216SDL_QUITMASK
217
218=item *
219
220SDL_SYSWMEVENTMASK
221
222=back
223
224This way you can check if a given C<type> matches a mask:
225
226 (SDL_EVENTMASK(SDL_JOYBUTTONDOWN)   & SDL_MOUSEEVENTMASK) # is false
227 (SDL_EVENTMASK(SDL_MOUSEBUTTONDOWN) & SDL_MOUSEEVENTMASK) # is true
228 (SDL_EVENTMASK(SDL_MOUSEBUTTONUP)   & SDL_MOUSEEVENTMASK) # is true
229 (SDL_EVENTMASK(SDL_MOUSEMOTION)     & SDL_MOUSEEVENTMASK) # is true
230 
231 # and also true is:
232 
233 (SDL_MOUSEEVENTMASK == SDL_EVENTMASK(SDL_MOUSEBUTTONDOWN) 
234                      | SDL_EVENTMASK(SDL_MOUSEBUTTONUP) 
235                      | SDL_EVENTMASK(SDL_MOUSEMOTION))
236
237=head2 Application visibility events
238
239C<active> is used when an event of type C<SDL_ACTIVEEVENT> is reported.
240
241When the mouse leaves or enters the window area a C<SDL_APPMOUSEFOCUS> type activation event occurs, 
242if the mouse entered the window then B<gain> will be 1, otherwise B<gain> will be 0. 
243
244A C<SDL_APPINPUTFOCUS> type activation event occurs when the application loses or gains keyboard focus. 
245This usually occurs when another application is made active. 
246
247Finally, a C<SDL_APPACTIVE> type event occurs when the application is either minimised/iconified (B<gain>=0) or restored. 
248
249A single event can have multiple values set in B<state>.
250
251B<Note:> This event does not occur when an application window is first created. 
252
253A new ActiveEvent (to fake focus loss) will be created like this:
254
255 my $event = SDL::Event->new();
256    $event->type(SDL_ACTIVEEVENT);
257    $event->active_gain(0);
258    $event->active_state(SDL_APPMOUSEFOCUS);
259
260 # I think this is wrong, ->active_type() should get SDL_APPMOUSEFOCUS, but what state gets?
261
262=head3 active_gain
263
264See C<active>. 0 if the event is a loss or 1 if it is a gain.
265
266=head3 active_state
267
268A bitmask of the following values: SDL_APPMOUSEFOCUS if mouse focus was gained or lost, 
269SDL_APPINPUTFOCUS if input focus was gained or lost, and SDL_APPACTIVE if the application was iconified (gain=0) or restored(gain=1).
270
271=head2 Keyboard events
272
273C<key> is used when an event of type C<SDL_KEYDOWN> or C<SDL_KEYUP> is reported.
274
275The type and state actually report the same information, they just use different values to do it. 
276A keyboard event generally occurs when a key is released (C<type=SDL_KEYUP> or C<key_state=SDL_RELEASED>) 
277and when a key is pressed (C<type=SDL_KEYDOWN> or C<key_state=SDL_PRESSED>). 
278
279The C<SDLK_CAPSLOCK> and C<SDLK_NUMLOCK> keys are special cases and report an C<SDL_KEYDOWN> when first pressed, 
280then an C<SDL_RELEASED> when released and pressed again. For these keys C<KEYUP> and C<KEYDOWN> events are therefore 
281analogous to the state of the caps lock and num lock LEDs rather than the keys themselves. 
282These special cases are required for compatibility with Sun workstations.
283
284B<Note:> Repeating C<SDL_KEYDOWN> events will occur if key repeat is enabled (see L<SDL::Events::enable_key_repeat|SDL::Events/"enable_key_repeat">). 
285
286=head3 key_state
287
288C<SDL_PRESSED> or C<SDL_RELEASED>
289
290=head3 key_scancode
291
292The C<scancode> field should generally be left alone, it is the hardware-dependent scancode returned by the keyboard.
293
294=head3 key_sym
295
296The C<sym> field is extremely useful. It is the SDL-defined value of the key (see the keysym definitions in SDLKey). 
297This field is very useful when you are checking for certain key presses, like so: 
298
299 while(poll_event($event))
300 {
301     switch($event->type)
302     {
303         case SDL_KEYDOWN:
304             move_left() if($event->key_sym == SDLK_LEFT);
305             break;
306         .
307         .
308         .
309     }
310 }
311
312=head3 key_mod
313
314C<mod> stores the current state of the keyboard modifiers as explained in SDL_GetModState.
315
316=head3 key_unicode
317
318The C<unicode> field is only used when UNICODE translation is enabled with L<SDL::Events::enable_unicode|SDL::Events/"enable_unicode">. 
319If C<unicode> is non-zero then this is the UNICODE character corresponding to the keypress. 
320If the high 9 bits of the character are 0, then this maps to the equivalent ASCII character:
321
322 my $char;
323 if(($event->key_unicode & 0xFF80) == 0)
324 {
325     $char = $event->key_unicode & 0x7F;
326 }
327 else
328 {
329     print("An International Character.\n");
330 }
331
332UNICODE translation does create a slight overhead so don't enable it unless its needed.
333
334NOTE: Key release events (SDL_KEYUP) won't necessarily (ever?) contain unicode information. 
335See L<http://lists.libsdl.org/pipermail/sdl-libsdl.org/2005-January/048355.html>
336
337=head2 Mouse motion events
338
339Simply put, a SDL_MOUSEMOTION type event occurs when a user moves the mouse within the 
340application window or when SDL_WarpMouse is called. Both the absolute (C<motion_x> and C<motion_y>) 
341and relative (C<motion_xrel> and C<motion_yrel>) coordinates are reported along with the current 
342button states (C<motion_state>).
343
344=head3 motion_state
345
346The button state can be interpreted using the C<SDL_BUTTON> macro (see L<SDL::Events::get_mouse_state|SDL::Events/"get_mouse_state">). 
347
348=head3 motion_x, motion_y
349
350The X/Y coordinates of the mouse
351
352=head3 motion_xrel, motion_yrel
353
354Relative motion in the X/Y direction.
355
356If the cursor is hidden (SDL_ShowCursor(0)) and the input is grabbed (SDL_WM_GrabInput(SDL_GRAB_ON)), 
357then the mouse will give relative motion events even when the cursor reaches the edge of the screen. 
358This is currently only implemented on Windows and Linux/Unix-alikes.
359
360=head2 Mouse button events
361
362When a mouse button press or release is detected, the number of the button pressed (from 1 to 255, 
363with 1 usually being the left button and 2 the right) is placed into C<button_button>. The position of the mouse 
364when this event occurred is stored in the C<button_x> and the C<button_y> fields. Like a keyboard event,
365information on whether the event was a press or a release event is stored in both the C<button_type> 
366and C<button_state> fields, but this should be obvious.
367
368Mouse wheel events are reported as buttons 4 (up) and 5 (down). Two events are generated i.e. you get 
369a C<SDL_MOUSEBUTTONDOWN> followed by a C<SDL_MOUSEBUTTONUP> event.
370
371=head3 button_which
372
373The input device index
374
375=head3 button_button
376
377The mouse button index (C<SDL_BUTTON_LEFT>, C<SDL_BUTTON_MIDDLE>, C<SDL_BUTTON_RIGHT>, C<SDL_BUTTON_WHEELUP>, 
378C<SDL_BUTTON_WHEELDOWN>)
379
380=head3 button_state
381
382C<SDL_PRESSED> or C<SDL_RELEASED>
383
384=head3 button_x, button_y
385
386The X/Y coordinates of the mouse at press/release time
387
388=head2 Joystick axis events
389
390A C<SDL_JOYAXISMOTION> event occurs whenever a user moves an axis on the joystick.
391
392=head3 jaxis_which
393
394The field C<jaxis_which> is the index of the joystick that reported the event.
395
396=head3 jaxis_axis
397
398The C<jaxis_axis> is the index of the axis (for a more detailed explanation see the Joystick section).
399
400=head3 jaxis_value
401
402C<jaxis_value> is the current position of the axis (range: -32768 to 32767).
403
404=head2 Joystick button events
405
406A C<SDL_JOYBUTTONDOWN> or C<SDL_JOYBUTTONUP> event occurs when ever a user presses 
407or releases a button on a joystick.
408
409=head3 jbutton_which
410
411The field C<jbutton_which> is the index of the joystick that reported the event.
412
413=head3 jbutton_button
414
415The C<jbutton_button> is the index of the button (for a more detailed explanation see the Joystick section).
416
417=head3 jbutton_state
418
419C<jbutton_state> is the current state of the button which is either C<jbutton_SDL_PRESSED> 
420or C<jbutton_SDL_RELEASED>. 
421
422=head2 Joystick hat events
423
424A C<SDL_JOYHATMOTION> event occurs when ever a user moves a hat on the joystick. 
425
426=head3 jhat_which
427
428The field C<jhat_which> is the index of the joystick that reported the event.
429
430=head3 jhat_hat
431
432C<jhat_hat> is the index of the hat (for a more detailed explanation see the Joystick section).
433
434=head3 jhat_value
435
436C<jhat_value> is the current position of the hat. It is a bitwise OR'd combination of the following 
437values (whose meanings should be pretty obvious):
438
439=over 4
440
441=item *
442
443C<SDL_HAT_CENTERED>
444
445=item *
446
447C<SDL_HAT_UP>
448
449=item *
450
451C<SDL_HAT_RIGHT>
452
453=item *
454
455C<SDL_HAT_DOWN>
456
457=item *
458
459C<SDL_HAT_LEFT>
460
461=back
462
463The following defines are also provided:
464
465=over 4
466
467=item *
468
469C<SDL_HAT_RIGHTUP>
470
471=item *
472
473C<SDL_HAT_RIGHTDOWN>
474
475=item *
476
477C<SDL_HAT_LEFTUP>
478
479=item *
480
481C<SDL_HAT_LEFTDOWN>
482
483=back
484
485=head2 Joystick trackball events
486
487A C<SDL_JOYBALLMOTION> event occurs when a user moves a trackball on the joystick.
488
489=head3 jball_which
490
491The field C<jball_which> is the index of the joystick that reported the event.
492
493=head3 jball_ball
494
495C<jball_ball> is the index of the trackball (for a more detailed explanation see the Joystick section).
496
497=head3 jball_xrel, jball_yrel
498
499Trackballs only return relative motion, this is the change in position on the ball since it was last 
500polled (last cycle of the event loop) and it is stored in C<jball_xrel> and C<jball_yrel>.
501
502=head2 Window resize events
503
504=head3 resize_w, resize_h
505
506When C<SDL_RESIZABLE> is passed as a flag to C<SDL_SetVideoMode> the user is allowed to resize the 
507applications window. When the window is resized an C<SDL_VIDEORESIZE> is reported, with the new 
508window width and height values stored in the resize structure's C<resize_w> and C<resize_h>. 
509When an C<SDL_VIDEORESIZE> is received the window should be resized to the new dimensions using 
510SDL_SetVideoMode. 
511
512=head2 Window expose events
513
514A C<VIDEOEXPOSE> event is triggered when the screen has been modified outside of the application, 
515usually by the window manager and needs to be redrawn.
516
517=head2 System window manager events
518
519The system window manager event contains a system-specific information about unknown window manager 
520events. If you enable this event using C<SDL_EventState>, it will be generated whenever unhandled 
521events are received from the window manager. This can be used, for example, to implement cut-and-paste 
522in your application.
523
524If you want to obtain system-specific information about the window manager, you can fill in the 
525version member of a SDL_SysWMinfo structure (details can be found in SDL_syswm.h, which must be included) 
526using the SDL_VERSION() macro found in SDL_version.h, and pass it to the function:
527
528 int SDL_GetWMInfo(SDL_SysWMinfo *info);
529 
530See L<http://www.libsdl.org/cgi/docwiki.cgi/SDL_SysWMEvent>
531
532=head3 syswm_msg
533
534=head2 User defined events
535
536This event is unique, it is never created by SDL but only by the user. The event can be pushed onto
537the event queue using C<SDL::Events::push_event>. The contents of the structure members are completely up to the 
538programmer, the only requirement is that type is a value from C<SDL_USEREVENT> to C<SDL_NUMEVENTS-1> (inclusive)
539
540 my $event = SDL::Event->new();
541    $event->type ( SDL_USEREVENT + 3 );
542    $event->user_code(10);
543    $event->user_data1('hello event');
544
545 SDL::Events::push_event($event);
546
547=head3 user_code
548
549User defined event code (integer).
550
551=head3 user_data1, user_data2
552
553User defined data.
554
555=head2 Quit event
556
557As can be seen, the C<SDL_QuitEvent> structure serves no useful purpose. The event itself, on the other hand, 
558is very important. If you filter out or ignore a quit event then it is impossible for the user to close the 
559window. On the other hand, if you do accept a quit event then the application window will be closed, and 
560screen updates will still report success even though the application will no longer be visible.
561
562B<Note>: The macro SDL_QuitRequested will return non-zero if a quit event is pending 
563
564=head1 AUTHORS
565
566See L<SDL/AUTHORS>.
567
568=head1 SEE ALSO
569
570L<perl>