/lib/pods/SDL/Event.pod

http://github.com/PerlGameDev/SDL · Unknown · 570 lines · 333 code · 237 blank · 0 comment · 0 complexity · 7b7934f2a01312d54a1a0212289c541e MD5 · raw file

  1. =head1 NAME
  2. SDL::Event - General event structure
  3. =head2 CATEGORY
  4. Core, Events, Structure
  5. =head1 SYNOPSIS
  6. use SDL::Event; # for the event object itself
  7. use SDL::Events; # functions for event queue handling
  8. SDL::init(SDL_INIT_VIDEO);
  9. my $event = SDL::Event->new();
  10. while(1)
  11. {
  12. SDL::Events::pump_events();
  13. if(SDL::Events::poll_event($event))
  14. {
  15. if($event->type == SDL_MOUSEBUTTONDOWN)
  16. {
  17. # now you can handle the details
  18. $event->button_which;
  19. $event->button_button;
  20. $event->button_x;
  21. $event->button_y;
  22. }
  23. last if $event->type == SDL_QUIT;
  24. }
  25. # your screen drawing code will be here
  26. }
  27. =head1 DESCRIPTION
  28. Event handling allows your application to receive input from the user.
  29. Event handling is initalised (along with video) with a call to:
  30. C<SDL::init(SDL_INIT_VIDEO);>
  31. Internally, SDL stores all the events waiting to be handled in an event queue.
  32. Using functions like C<SDL::Events::poll_event()>, C<SDL::Events::peep_events>
  33. and C<SDL::Events::wait_event()> you can observe and handle waiting input events.
  34. The key to event handling in SDL is the C<SDL::Event> union.
  35. The event queue itself is composed of a series of C<SDL::Event> unions, one for each waiting event.
  36. C<SDL::Event> unions are read from the queue with the C<SDL::Events::poll_event()> function
  37. and it is then up to the application to process the information stored with them.
  38. =head1 METHODS
  39. =head2 new
  40. C<new> creates an empty event-object, which can be used store information.
  41. Either by calling C<poll_event($event)> that transfers one event from the queue into our object
  42. or by setting all the needed data manually in order to push the event to the queue.
  43. use SDL::Event;
  44. my $event = SDL::Event->new();
  45. =head2 type
  46. SDL::Event is a union of all event structures used in SDL, using it is a simple matter of knowing
  47. which union member relates to which event C<type>.
  48. print 'heureka' if $event->type == SDL_MOUSEBUTTONDOWN;
  49. Available type constants:
  50. =over 4
  51. =item *
  52. L<SDL_ACTIVEEVENT|/Application_visibility_events> - Application visibility event structure
  53. =item *
  54. L<SDL_KEYDOWN|/Keyboard_events> - Keyboard event structure
  55. =item *
  56. L<SDL_KEYUP|/Keyboard_events> - Keyboard event structure
  57. =item *
  58. L<SDL_MOUSEMOTION|/Mouse_motion_events> - Mouse motion event structure
  59. =item *
  60. L<SDL_MOUSEBUTTONDOWN|/Mouse_button_events> - Mouse button event structure
  61. =item *
  62. L<SDL_MOUSEBUTTONUP|/Mouse_button_events> - Mouse button event structure
  63. =item *
  64. L<SDL_JOYAXISMOTION|/Joystick_axis_events> - Joystick axis motion event structure
  65. =item *
  66. L<SDL_JOYBALLMOTION|/Joystick_trackball_events> - Joystick trackball motion event structure
  67. =item *
  68. L<SDL_JOYHATMOTION|/Joystick_hat_events> - Joystick hat position change event structure
  69. =item *
  70. L<SDL_JOYBUTTONDOWN|/Joystick_button_events> - Joystick button event structure
  71. =item *
  72. L<SDL_JOYBUTTONUP|/Joystick_button_events> - Joystick button event structure
  73. =item *
  74. L<SDL_VIDEORESIZE|/Window_resize_events> - Window resize event structure
  75. =item *
  76. L<SDL_VIDEOEXPOSE|/Window_expose_events> - Window expose event
  77. =item *
  78. L<SDL_QUIT|/Quit_event> - Quit requested event
  79. =item *
  80. L<SDL_USEREVENT|/User_defined_events> - A user-defined event type
  81. =item *
  82. L<SDL_SYSWMEVENT|/System_window_manager_events> - Platform-dependent window manager event.
  83. =back
  84. Event types are grouped by masks. C<SDL_EVENTMASK($type)> will return the proper mask for the given C<type>.
  85. Available event mask constants:
  86. =over 4
  87. =item *
  88. SDL_ACTIVEEVENTMASK
  89. =item *
  90. SDL_KEYDOWNMASK
  91. =item *
  92. SDL_KEYUPMASK
  93. =item *
  94. SDL_KEYEVENTMASK
  95. =item *
  96. SDL_MOUSEMOTIONMASK
  97. =item *
  98. SDL_MOUSEBUTTONDOWNMASK
  99. =item *
  100. SDL_MOUSEBUTTONUPMASK
  101. =item *
  102. SDL_MOUSEEVENTMASK
  103. =item *
  104. SDL_JOYAXISMOTIONMASK
  105. =item *
  106. SDL_JOYBALLMOTIONMASK
  107. =item *
  108. SDL_JOYHATMOTIONMASK
  109. =item *
  110. SDL_JOYBUTTONDOWNMASK
  111. =item *
  112. SDL_JOYBUTTONUPMASK
  113. =item *
  114. SDL_JOYEVENTMASK
  115. =item *
  116. SDL_VIDEORESIZEMASK
  117. =item *
  118. SDL_VIDEOEXPOSEMASK
  119. =item *
  120. SDL_QUITMASK
  121. =item *
  122. SDL_SYSWMEVENTMASK
  123. =back
  124. This way you can check if a given C<type> matches a mask:
  125. (SDL_EVENTMASK(SDL_JOYBUTTONDOWN) & SDL_MOUSEEVENTMASK) # is false
  126. (SDL_EVENTMASK(SDL_MOUSEBUTTONDOWN) & SDL_MOUSEEVENTMASK) # is true
  127. (SDL_EVENTMASK(SDL_MOUSEBUTTONUP) & SDL_MOUSEEVENTMASK) # is true
  128. (SDL_EVENTMASK(SDL_MOUSEMOTION) & SDL_MOUSEEVENTMASK) # is true
  129. # and also true is:
  130. (SDL_MOUSEEVENTMASK == SDL_EVENTMASK(SDL_MOUSEBUTTONDOWN)
  131. | SDL_EVENTMASK(SDL_MOUSEBUTTONUP)
  132. | SDL_EVENTMASK(SDL_MOUSEMOTION))
  133. =head2 Application visibility events
  134. C<active> is used when an event of type C<SDL_ACTIVEEVENT> is reported.
  135. When the mouse leaves or enters the window area a C<SDL_APPMOUSEFOCUS> type activation event occurs,
  136. if the mouse entered the window then B<gain> will be 1, otherwise B<gain> will be 0.
  137. A C<SDL_APPINPUTFOCUS> type activation event occurs when the application loses or gains keyboard focus.
  138. This usually occurs when another application is made active.
  139. Finally, a C<SDL_APPACTIVE> type event occurs when the application is either minimised/iconified (B<gain>=0) or restored.
  140. A single event can have multiple values set in B<state>.
  141. B<Note:> This event does not occur when an application window is first created.
  142. A new ActiveEvent (to fake focus loss) will be created like this:
  143. my $event = SDL::Event->new();
  144. $event->type(SDL_ACTIVEEVENT);
  145. $event->active_gain(0);
  146. $event->active_state(SDL_APPMOUSEFOCUS);
  147. # I think this is wrong, ->active_type() should get SDL_APPMOUSEFOCUS, but what state gets?
  148. =head3 active_gain
  149. See C<active>. 0 if the event is a loss or 1 if it is a gain.
  150. =head3 active_state
  151. A bitmask of the following values: SDL_APPMOUSEFOCUS if mouse focus was gained or lost,
  152. SDL_APPINPUTFOCUS if input focus was gained or lost, and SDL_APPACTIVE if the application was iconified (gain=0) or restored(gain=1).
  153. =head2 Keyboard events
  154. C<key> is used when an event of type C<SDL_KEYDOWN> or C<SDL_KEYUP> is reported.
  155. The type and state actually report the same information, they just use different values to do it.
  156. A keyboard event generally occurs when a key is released (C<type=SDL_KEYUP> or C<key_state=SDL_RELEASED>)
  157. and when a key is pressed (C<type=SDL_KEYDOWN> or C<key_state=SDL_PRESSED>).
  158. The C<SDLK_CAPSLOCK> and C<SDLK_NUMLOCK> keys are special cases and report an C<SDL_KEYDOWN> when first pressed,
  159. then an C<SDL_RELEASED> when released and pressed again. For these keys C<KEYUP> and C<KEYDOWN> events are therefore
  160. analogous to the state of the caps lock and num lock LEDs rather than the keys themselves.
  161. These special cases are required for compatibility with Sun workstations.
  162. B<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">).
  163. =head3 key_state
  164. C<SDL_PRESSED> or C<SDL_RELEASED>
  165. =head3 key_scancode
  166. The C<scancode> field should generally be left alone, it is the hardware-dependent scancode returned by the keyboard.
  167. =head3 key_sym
  168. The C<sym> field is extremely useful. It is the SDL-defined value of the key (see the keysym definitions in SDLKey).
  169. This field is very useful when you are checking for certain key presses, like so:
  170. while(poll_event($event))
  171. {
  172. switch($event->type)
  173. {
  174. case SDL_KEYDOWN:
  175. move_left() if($event->key_sym == SDLK_LEFT);
  176. break;
  177. .
  178. .
  179. .
  180. }
  181. }
  182. =head3 key_mod
  183. C<mod> stores the current state of the keyboard modifiers as explained in SDL_GetModState.
  184. =head3 key_unicode
  185. The C<unicode> field is only used when UNICODE translation is enabled with L<SDL::Events::enable_unicode|SDL::Events/"enable_unicode">.
  186. If C<unicode> is non-zero then this is the UNICODE character corresponding to the keypress.
  187. If the high 9 bits of the character are 0, then this maps to the equivalent ASCII character:
  188. my $char;
  189. if(($event->key_unicode & 0xFF80) == 0)
  190. {
  191. $char = $event->key_unicode & 0x7F;
  192. }
  193. else
  194. {
  195. print("An International Character.\n");
  196. }
  197. UNICODE translation does create a slight overhead so don't enable it unless its needed.
  198. NOTE: Key release events (SDL_KEYUP) won't necessarily (ever?) contain unicode information.
  199. See L<http://lists.libsdl.org/pipermail/sdl-libsdl.org/2005-January/048355.html>
  200. =head2 Mouse motion events
  201. Simply put, a SDL_MOUSEMOTION type event occurs when a user moves the mouse within the
  202. application window or when SDL_WarpMouse is called. Both the absolute (C<motion_x> and C<motion_y>)
  203. and relative (C<motion_xrel> and C<motion_yrel>) coordinates are reported along with the current
  204. button states (C<motion_state>).
  205. =head3 motion_state
  206. The button state can be interpreted using the C<SDL_BUTTON> macro (see L<SDL::Events::get_mouse_state|SDL::Events/"get_mouse_state">).
  207. =head3 motion_x, motion_y
  208. The X/Y coordinates of the mouse
  209. =head3 motion_xrel, motion_yrel
  210. Relative motion in the X/Y direction.
  211. If the cursor is hidden (SDL_ShowCursor(0)) and the input is grabbed (SDL_WM_GrabInput(SDL_GRAB_ON)),
  212. then the mouse will give relative motion events even when the cursor reaches the edge of the screen.
  213. This is currently only implemented on Windows and Linux/Unix-alikes.
  214. =head2 Mouse button events
  215. When a mouse button press or release is detected, the number of the button pressed (from 1 to 255,
  216. with 1 usually being the left button and 2 the right) is placed into C<button_button>. The position of the mouse
  217. when this event occurred is stored in the C<button_x> and the C<button_y> fields. Like a keyboard event,
  218. information on whether the event was a press or a release event is stored in both the C<button_type>
  219. and C<button_state> fields, but this should be obvious.
  220. Mouse wheel events are reported as buttons 4 (up) and 5 (down). Two events are generated i.e. you get
  221. a C<SDL_MOUSEBUTTONDOWN> followed by a C<SDL_MOUSEBUTTONUP> event.
  222. =head3 button_which
  223. The input device index
  224. =head3 button_button
  225. The mouse button index (C<SDL_BUTTON_LEFT>, C<SDL_BUTTON_MIDDLE>, C<SDL_BUTTON_RIGHT>, C<SDL_BUTTON_WHEELUP>,
  226. C<SDL_BUTTON_WHEELDOWN>)
  227. =head3 button_state
  228. C<SDL_PRESSED> or C<SDL_RELEASED>
  229. =head3 button_x, button_y
  230. The X/Y coordinates of the mouse at press/release time
  231. =head2 Joystick axis events
  232. A C<SDL_JOYAXISMOTION> event occurs whenever a user moves an axis on the joystick.
  233. =head3 jaxis_which
  234. The field C<jaxis_which> is the index of the joystick that reported the event.
  235. =head3 jaxis_axis
  236. The C<jaxis_axis> is the index of the axis (for a more detailed explanation see the Joystick section).
  237. =head3 jaxis_value
  238. C<jaxis_value> is the current position of the axis (range: -32768 to 32767).
  239. =head2 Joystick button events
  240. A C<SDL_JOYBUTTONDOWN> or C<SDL_JOYBUTTONUP> event occurs when ever a user presses
  241. or releases a button on a joystick.
  242. =head3 jbutton_which
  243. The field C<jbutton_which> is the index of the joystick that reported the event.
  244. =head3 jbutton_button
  245. The C<jbutton_button> is the index of the button (for a more detailed explanation see the Joystick section).
  246. =head3 jbutton_state
  247. C<jbutton_state> is the current state of the button which is either C<jbutton_SDL_PRESSED>
  248. or C<jbutton_SDL_RELEASED>.
  249. =head2 Joystick hat events
  250. A C<SDL_JOYHATMOTION> event occurs when ever a user moves a hat on the joystick.
  251. =head3 jhat_which
  252. The field C<jhat_which> is the index of the joystick that reported the event.
  253. =head3 jhat_hat
  254. C<jhat_hat> is the index of the hat (for a more detailed explanation see the Joystick section).
  255. =head3 jhat_value
  256. C<jhat_value> is the current position of the hat. It is a bitwise OR'd combination of the following
  257. values (whose meanings should be pretty obvious):
  258. =over 4
  259. =item *
  260. C<SDL_HAT_CENTERED>
  261. =item *
  262. C<SDL_HAT_UP>
  263. =item *
  264. C<SDL_HAT_RIGHT>
  265. =item *
  266. C<SDL_HAT_DOWN>
  267. =item *
  268. C<SDL_HAT_LEFT>
  269. =back
  270. The following defines are also provided:
  271. =over 4
  272. =item *
  273. C<SDL_HAT_RIGHTUP>
  274. =item *
  275. C<SDL_HAT_RIGHTDOWN>
  276. =item *
  277. C<SDL_HAT_LEFTUP>
  278. =item *
  279. C<SDL_HAT_LEFTDOWN>
  280. =back
  281. =head2 Joystick trackball events
  282. A C<SDL_JOYBALLMOTION> event occurs when a user moves a trackball on the joystick.
  283. =head3 jball_which
  284. The field C<jball_which> is the index of the joystick that reported the event.
  285. =head3 jball_ball
  286. C<jball_ball> is the index of the trackball (for a more detailed explanation see the Joystick section).
  287. =head3 jball_xrel, jball_yrel
  288. Trackballs only return relative motion, this is the change in position on the ball since it was last
  289. polled (last cycle of the event loop) and it is stored in C<jball_xrel> and C<jball_yrel>.
  290. =head2 Window resize events
  291. =head3 resize_w, resize_h
  292. When C<SDL_RESIZABLE> is passed as a flag to C<SDL_SetVideoMode> the user is allowed to resize the
  293. applications window. When the window is resized an C<SDL_VIDEORESIZE> is reported, with the new
  294. window width and height values stored in the resize structure's C<resize_w> and C<resize_h>.
  295. When an C<SDL_VIDEORESIZE> is received the window should be resized to the new dimensions using
  296. SDL_SetVideoMode.
  297. =head2 Window expose events
  298. A C<VIDEOEXPOSE> event is triggered when the screen has been modified outside of the application,
  299. usually by the window manager and needs to be redrawn.
  300. =head2 System window manager events
  301. The system window manager event contains a system-specific information about unknown window manager
  302. events. If you enable this event using C<SDL_EventState>, it will be generated whenever unhandled
  303. events are received from the window manager. This can be used, for example, to implement cut-and-paste
  304. in your application.
  305. If you want to obtain system-specific information about the window manager, you can fill in the
  306. version member of a SDL_SysWMinfo structure (details can be found in SDL_syswm.h, which must be included)
  307. using the SDL_VERSION() macro found in SDL_version.h, and pass it to the function:
  308. int SDL_GetWMInfo(SDL_SysWMinfo *info);
  309. See L<http://www.libsdl.org/cgi/docwiki.cgi/SDL_SysWMEvent>
  310. =head3 syswm_msg
  311. =head2 User defined events
  312. This event is unique, it is never created by SDL but only by the user. The event can be pushed onto
  313. the event queue using C<SDL::Events::push_event>. The contents of the structure members are completely up to the
  314. programmer, the only requirement is that type is a value from C<SDL_USEREVENT> to C<SDL_NUMEVENTS-1> (inclusive)
  315. my $event = SDL::Event->new();
  316. $event->type ( SDL_USEREVENT + 3 );
  317. $event->user_code(10);
  318. $event->user_data1('hello event');
  319. SDL::Events::push_event($event);
  320. =head3 user_code
  321. User defined event code (integer).
  322. =head3 user_data1, user_data2
  323. User defined data.
  324. =head2 Quit event
  325. As can be seen, the C<SDL_QuitEvent> structure serves no useful purpose. The event itself, on the other hand,
  326. is very important. If you filter out or ignore a quit event then it is impossible for the user to close the
  327. window. On the other hand, if you do accept a quit event then the application window will be closed, and
  328. screen updates will still report success even though the application will no longer be visible.
  329. B<Note>: The macro SDL_QuitRequested will return non-zero if a quit event is pending
  330. =head1 AUTHORS
  331. See L<SDL/AUTHORS>.
  332. =head1 SEE ALSO
  333. L<perl>