/lib/pods/SDL/Events.pod

http://github.com/PerlGameDev/SDL · Unknown · 584 lines · 366 code · 218 blank · 0 comment · 0 complexity · 7e08f8541623d8f36dccfb224d51491c MD5 · raw file

  1. =head1 NAME
  2. SDL::Events - Bindings to the Events Category in SDL API
  3. =head2 CATEGORY
  4. Core, Events
  5. =head1 SYNOPSIS
  6. Most likely you just want to know how to get events for you app.
  7. use SDL ':init';
  8. use SDL::Event;
  9. use SDL::Events ':all';
  10. SDL::init(SDL_INIT_VIDEO); # Event can only be grabbed in the same thread as this
  11. ...
  12. my $event = SDL::Event->new(); # notices 'Event' ne 'Events'
  13. while( 1 )
  14. {
  15. SDL::Events::pump_events();
  16. while( SDL::Events::poll_event($event) )
  17. {
  18. #check by event type
  19. on_active() if $event->type == SDL_ACTIVEEVENT;
  20. ...
  21. }
  22. }
  23. =head1 CONSTANTS
  24. The constants are exported by default. You can avoid this by doing:
  25. use SDL::Events ();
  26. and access them directly:
  27. SDL::Events::SDL_ACTIVEEVENT;
  28. or by choosing the export tags below:
  29. Export tag: ':type'
  30. SDL_ACTIVEEVENT
  31. SDL_KEYDOWN
  32. SDL_KEYUP
  33. SDL_MOUSEMOTION
  34. SDL_MOUSEBUTTONDOWN
  35. SDL_MOUSEBUTTONUP
  36. SDL_JOYAXISMOTION
  37. SDL_JOYBALLMOTION
  38. SDL_JOYHATMOTION
  39. SDL_JOYBUTTONDOWN
  40. SDL_JOYBUTTONUP
  41. SDL_QUIT
  42. SDL_SYSWMEVENT
  43. SDL_VIDEORESIZE
  44. SDL_VIDEOEXPOSE
  45. SDL_USEREVENT
  46. SDL_NUMEVENTS
  47. Export tag: ':mask'
  48. SDL_EVENTMASK
  49. SDL_ACTIVEEVENTMASK
  50. SDL_KEYDOWNMASK
  51. SDL_KEYUPMASK
  52. SDL_KEYEVENTMASK
  53. SDL_MOUSEMOTIONMASK
  54. SDL_MOUSEBUTTONDOWNMASK
  55. SDL_MOUSEBUTTONUPMASK
  56. SDL_MOUSEEVENTMASK
  57. SDL_JOYAXISMOTIONMASK
  58. SDL_JOYBALLMOTIONMASK
  59. SDL_JOYHATMOTIONMASK
  60. SDL_JOYBUTTONDOWNMASK
  61. SDL_JOYBUTTONUPMASK
  62. SDL_JOYEVENTMASK
  63. SDL_VIDEORESIZEMASK
  64. SDL_VIDEOEXPOSEMASK
  65. SDL_QUITMASK
  66. SDL_SYSWMEVENTMASK
  67. SDL_ALLEVENTS
  68. Export tag: ':action'
  69. SDL_ADDEVENT
  70. SDL_PEEKEVENT
  71. SDL_GETEVENT
  72. Export tag: ':state'
  73. SDL_QUERY
  74. SDL_IGNORE
  75. SDL_DISABLE / SDL_ENABLE
  76. SDL_RELEASED / SDL_PRESSED
  77. Export tag: ':hat'
  78. SDL_HAT_CENTERED
  79. SDL_HAT_UP / SDL_HAT_RIGHT / SDL_HAT_DOWN / SDL_HAT_LEFT
  80. SDL_HAT_RIGHTUP / SDL_HAT_RIGHTDOWN / SDL_HAT_LEFTUP / SDL_HAT_LEFTDOWN
  81. Export tag: ':app'
  82. SDL_APPMOUSEFOCUS
  83. SDL_APPINPUTFOCUS
  84. SDL_APPACTIVE
  85. Export tag: ':button'
  86. SDL_BUTTON
  87. SDL_BUTTON_LEFT / SDL_BUTTON_MIDDLE / SDL_BUTTON_RIGHT
  88. SDL_BUTTON_WHEELUP / SDL_BUTTON_WHEELDOWN
  89. SDL_BUTTON_X1 / SDL_BUTTON_X2
  90. SDL_BUTTON_LMASK / SDL_BUTTON_MMASK / SDL_BUTTON_RMASK
  91. SDL_BUTTON_X1MASK / SDL_BUTTON_X2MASK
  92. Export tag: ':keysym'
  93. SDLK_UNKNOWN
  94. SDLK_FIRST
  95. SDLK_BACKSPACE
  96. SDLK_TAB
  97. SDLK_CLEAR
  98. SDLK_RETURN
  99. SDLK_PAUSE
  100. SDLK_ESCAPE
  101. SDLK_SPACE
  102. SDLK_EXCLAIM
  103. SDLK_QUOTEDBL
  104. SDLK_HASH
  105. SDLK_DOLLAR
  106. SDLK_AMPERSAND
  107. SDLK_QUOTE
  108. SDLK_LEFTPAREN / SDLK_RIGHTPAREN
  109. SDLK_ASTERISK
  110. SDLK_PLUS / SDLK_MINUS
  111. SDLK_COMMA
  112. SDLK_PERIOD
  113. SDLK_0 .. SDLK_9
  114. SDLK_COLON
  115. SDLK_SEMICOLON
  116. SDLK_LESS / SDLK_GREATER
  117. SDLK_EQUALS
  118. SDLK_QUESTION
  119. SDLK_AT
  120. SDLK_LEFTBRACKET / SDLK_RIGHTBRACKET
  121. SDLK_SLASH / SDLK_BACKSLASH
  122. SDLK_CARET
  123. SDLK_UNDERSCORE
  124. SDLK_BACKQUOTE
  125. SDLK_a .. SDLK_z
  126. SDLK_DELETE
  127. SDLK_WORLD_0 .. SDLK_WORLD_95
  128. SDLK_KP0 .. SDLK_KP9
  129. SDLK_KP_PERIOD
  130. SDLK_KP_DIVIDE / SDLK_KP_MULTIPLY
  131. SDLK_KP_MINUS / SDLK_KP_PLUS
  132. SDLK_KP_ENTER
  133. SDLK_KP_EQUALS
  134. SDLK_UP / SDLK_DOWN / SDLK_RIGHT / SDLK_LEFT
  135. SDLK_INSERT
  136. SDLK_HOME / SDLK_END
  137. SDLK_PAGEUP / SDLK_PAGEDOWN
  138. SDLK_F1 .. SDLK_F15
  139. SDLK_NUMLOCK / SDLK_CAPSLOCK / SDLK_SCROLLOCK
  140. SDLK_RSHIFT / SDLK_LSHIFT
  141. SDLK_RCTRL / SDLK_LCTRL
  142. SDLK_RALT / SDLK_LALT
  143. SDLK_RMETA / SDLK_LMETA
  144. SDLK_LSUPER / SDLK_RSUPER
  145. SDLK_MODE
  146. SDLK_COMPOSE
  147. SDLK_HELP
  148. SDLK_PRINT
  149. SDLK_SYSREQ
  150. SDLK_BREAK
  151. SDLK_MENU
  152. SDLK_POWER
  153. SDLK_EURO
  154. SDLK_UNDO
  155. Export tag ':keymod'
  156. KMOD_NONE
  157. KMOD_LSHIFT / KMOD_RSHIFT / KMOD_SHIFT
  158. KMOD_LCTRL / KMOD_RCTRL / KMOD_CTRL
  159. KMOD_LALT / KMOD_RALT / KMOD_ALT
  160. KMOD_LMETA / KMOD_RMETA / KMOD_META
  161. KMOD_NUM
  162. KMOD_CAPS
  163. KMOD_MODE
  164. KMOD_RESERVED
  165. =head1 METHODS
  166. =head2 pump_events
  167. Pumps the event loop, gathering events from the input devices.
  168. pump_events();
  169. pump_events gathers all the pending input information from devices and places it on the event queue. Without calls to pump_events no events would
  170. ever be placed on the queue.
  171. Often the need for calls to pump_events is hidden from the user since L</poll_event> and L</wait_event> implicitly call pump_events.
  172. However, if you are not polling or waiting for events (e.g. you are filtering them), then you must call pump_events to force an event queue update.
  173. =head2 peep_events (event, num_events, action, mask)
  174. Checks the event queue for messages and optionally returns them.
  175. my $num_peep_events = SDL::Events::peep_events($event, 127, SDL_PEEKEVENT, SDL_ALLEVENTS);
  176. If action is SDL_ADDEVENT, up to num_events events will be added to the back of the event queue.
  177. If action is SDL_PEEKEVENT, up to num_events events at the front of the event queue, matching mask, will be returned and will not be removed from
  178. the queue.
  179. If action is SDL_GETEVENT, up to num_events events at the front of the event queue, matching mask, will be returned and will be removed from the
  180. queue.
  181. The mask parameter is a bitwise OR of SDL::Events::SDL_EVENTMASK(event_type), for all event types you are interested in
  182. This function is thread-safe.
  183. You may have to call pump_events before calling this function. Otherwise, the events may not be ready to be filtered when you call peep_events.
  184. Examples of mask:
  185. =over
  186. =item SDL_EVENTMASK (SDL_KEYUP)
  187. =item (SDL_EVENTMASK (SDL_MOUSEBUTTONDOWN) | SDL_EVENTMASK (SDL_MOUSEBUTTONUP))
  188. =item SDL_ALLEVENTS
  189. =item SDL_KEYUPMASK
  190. =item SDL_ALLEVENTS ^ SDL_QUITMASK
  191. =back
  192. =head3 RETURN
  193. Number of Events actually stored or -1 if there was an error
  194. =head2 poll_event($event)
  195. Polls for currently pending events.
  196. If $event is not NULL, the next event is removed from the queue and stored in the L<SDL::Event> structure pointed to by $event.
  197. As this function implicitly calls pump_events, you can only call this function in the thread that set the video mode with
  198. L<SDL::Video::set_video_mode|SDL::Video/"set_video_mode">.
  199. =head3 RETURN
  200. Returns 1 if there are any pending events, or 0 if there are none available.
  201. =head2 push_event($event)
  202. Pushes an event onto the event queue
  203. The event queue can actually be used as a two way communication channel. Not only can events be read from the queue, but the user can also push
  204. their own events onto it. event is a pointer to the event structure you wish to push onto the queue.
  205. The event is copied into the queue, and the caller may dispose of the memory pointed to after push_event returns.
  206. Note: Pushing device input events onto the queue doesn't modify the state of the device within SDL.
  207. This function is thread safe, and can be called from other threads safely.
  208. =head3 RETURN
  209. Returns 0 on success or -1 if the event couldn't be pushed.
  210. =head2 wait_event($event)
  211. Waits indefinitely for the next available $event, returning 0 if there was an error while waiting for events, 1 otherwise.
  212. If $event is not NULL, the next event is removed from the queue and stored in $event.
  213. As this function implicitly calls SDL_PumpEvents, you can only call this function in the thread that
  214. L<SDL::Video::set_video_mode|SDL::Video/"set_video_mode">.
  215. =head3 RETURN
  216. 0 if there was an error while waiting for events, 1 otherwise
  217. =head2 set_event_filter
  218. Sets up a filter to process all events
  219. my $filter = sub { if($_[0]->type == SDL_ACTIVEEVENT){ return 0} else{ return 1; }};
  220. SDL::Events::set_event_filter($filter);
  221. =head3 PARAMETER
  222. set_event_filter takes a coderef that it checks all events again. The callback gets a event in the stack
  223. sub { my $event_to_test = shift; ...}
  224. to filter the event return a 0, to pass the filter return a 1.
  225. One B<Caveat> is if you are filtering SDL_QUIT the event will be filtered if it is non-interrupt call ( Window closes normally ). If it is a
  226. interrupt SDL_QUIT it will be process on the next event poll.
  227. Events pushed onto to the queue with L<SDL::Events::push_events|SDL::Events/"push_events"> or L<SDL::Events::peep_events|SDL::Events/"peep_events">
  228. do not get filtered.
  229. This callback may run in a different thread.
  230. =head2 get_key_state
  231. Get a snapshot of the current keyboard state
  232. my $keys_ref = SDL::Events::get_key_state();
  233. print $keys_ref->[SDLK_RETURN]; # 1 if pressed , 0 if not pressed
  234. Use L<SDL::Events::pump_events|SDL::Events/"pump_events"> to update the state array.
  235. This function gives you the current state after all events have been processed, so if a key or button has been pressed and released before you
  236. process events, then the pressed state will never show up in the get_key_state call.
  237. This function doesn't take into account whether shift has been pressed or not.
  238. =head2 get_mod_state
  239. Get the state of the modifier keys
  240. Returns the current state of modifier keys
  241. Return value is an OR'd combination of KMOD_*
  242. SDL::Events::pump_events; #get latest mod_state in buffers
  243. my $mod_state = SDL::Events::get_mod_state();
  244. # Check which ones are pressed with
  245. # no mod pressed?
  246. print 'no_mod' if ( $mod_state & KMOD_NONE );
  247. # CTRL or ALT
  248. print 'ctrl alt' if ($mod_state & KMOD_CTRL || $mod_state & KMOD_ALT );
  249. =head3 MOD VALUES
  250. =over
  251. =item KMOD_NONE
  252. =item KMOD_LSHIFT
  253. =item KMOD_RSHIFT
  254. =item KMOD_LCTRL
  255. =item KMOD_RCTRL
  256. =item KMOD_LALT
  257. =item KMOD_RALT
  258. =item KMOD_LMETA
  259. =item KMOD_RMETA
  260. =item KMOD_NUM
  261. =item KMOD_CAPS
  262. =item KMOD_MODE
  263. =item KMOD_CTRL
  264. same as KMOD_LCTRL|KMOD_RCTRL
  265. =item KMOD_SHIFT
  266. same as KMOD_LSHIFT|KMOD_RSHIFT
  267. =item KMOD_ALT
  268. same as KMOD_LALT|KMOD_RALT
  269. =item KMOD_META
  270. same as KMOD_LMETA|KMOD_RMETA
  271. =back
  272. =head2 set_mod_state
  273. Get the state of the modifier keys
  274. The inverse of L<SDL::Events::get_mod_state|SDL::Events/"get_mod_state"> allows you to impose modifier key states on your application.
  275. Simply pass your desired modifier states into $modstate. This value can be a OR'd combination of any KMOD* constant.
  276. my $modstate = KMOD_LMETA | KMOD_LSHIFT;
  277. Any KMOD_* constant see L<SDL::Events::get_mod_state|SDL::Events/"get_mod_state"> for constants.
  278. SDL::Events::set_mod_state( $modstate );
  279. =head2 event_state
  280. Allows you to set the state of processing certain events
  281. SDL::Events::event_state( $type, $state );
  282. A list of $type(s) can be found in L<SDL::Event>
  283. =head3 STATES
  284. =over 4
  285. =item SDL_IGNORE
  286. The event of $type will be automatically dropper from the event queue and will not be filtered.
  287. =item SDL_ENABLE
  288. The event of $type will be processed normally. This is default.
  289. =item SDL_QUERY
  290. The current processing state of the $type will be returned
  291. =back
  292. =head2 get_key_name
  293. Gets the name of the a SDL virtual keysym
  294. my $event = SDL::Event->new();
  295. while( SDL::Events::poll_event($event) )
  296. {
  297. my $key = $event->key_sym;
  298. $key_str = SDL::Events::get_key_name($key);
  299. }
  300. Returns a string with the name of the key sym.
  301. =head2 enable_unicode
  302. Enable/Disable UNICODE translation
  303. my $previous_translation_mode = SDL::Events::enable_unicode( 1 ); #enable
  304. $previous_translation_mode = SDL::Events::enable_unicode( 0 ); #disables
  305. To obtain the character codes corresponding to received keyboard events, Unicode translation must first be turned on using this function. The
  306. translation incurs a slight overhead for each keyboard event and is therefore disabled by default. For each subsequently received key down event,
  307. the unicode member of the L<SDL::Event::key_sym|SDL::Event/"key_sym"> provided structure will be then contain the corresponding character code, or
  308. otherwise zero.
  309. A value of 1 for enabling, 0 for disabling and -1 for unchanged. -1 is useful for querying the current translation mode.
  310. Only key press events will be translated not release events.
  311. Returns the previous translation mode as (1,0).
  312. =head2 enable_key_repeat
  313. Sets keyboard repeat rate
  314. my $success = SDL::Events::enable_key_repeat( $delay, $interval );
  315. Enables or disables the keyboard repeat rate. $delay specifies how long the key must be pressed before it begins repeating, it then repeats at the
  316. speed specified by $interval. Both $delay and $interval are expressed in milliseconds.
  317. Setting $delay to 0 disables key repeating completely. Good default values are SDL_DEFAULT_REPEAT_DELAY and SDL_DEFAULT_REPEAT_INTERVAL.
  318. Return 0 on success and -1 on fail.
  319. =head2 get_mouse_state
  320. Retrieves the current state of the mouse
  321. my ($mask,$x,$y) = @{ SDL::Events::get_mouse_state( ) };
  322. print 'Button Left pressed' if ($mask & SDL_BUTTON_LMASK);
  323. print 'Button Right pressed' if ($mask & SDL_BUTTON_RMASK);
  324. print 'Button Middle pressed' if ($mask & SDL_BUTTON_MMASK);
  325. print $x.','.$y;
  326. The current button state is returned as a button $bitmask, which can be tested using the the above constants
  327. =head2 get_relative_mouse_state
  328. Retrieves the current relative state of the mouse
  329. my ($mask,$x,$y) = @{ SDL::Events::get_mouse_state( ) };
  330. print 'Button Left pressed' if ($mask & SDL_BUTTON_LMASK);
  331. print 'Button Right pressed' if ($mask & SDL_BUTTON_RMASK);
  332. print 'Button Middle pressed' if ($mask & SDL_BUTTON_MMASK);
  333. print $x.','.$y; # this is relative to the last position of the mouse
  334. The current button state is returned as a button $bitmask, which can be tested using the the above constants
  335. =head2 get_app_state
  336. Gets the state of the application
  337. my $app_state = SDL::Events::get_app_state();
  338. The $app_state is a bitwise combination of:
  339. =over
  340. =item SDL_APPMOUSEFOCUS
  341. Application has mouse focus
  342. warn 'mouse focus' if $app_state & SDL_APPMOUSEFOCUS
  343. =item SDL_APPINPUTFOCUS
  344. Application has keyboard focus
  345. warn 'keyboard focus' if $app_state & SDL_APPINPUTFOCUS
  346. =item SDL_APPACTIVE
  347. Application is visible
  348. warn 'Application Visible' if $app_state & SDL_APPACTIVE
  349. =back
  350. =head2 joystick_event_state
  351. Enable/disable joystick event polling
  352. my $status = SDL::Events::joystick_event_state( $state );
  353. This function is used to enable or disable joystick event processing. With joystick event processing disabled you will have to update joystick
  354. states with L<SDL::Joystick::update|SDL::Joystick/"update"> and read the joystick information manually. $state can be:
  355. =over
  356. =item SDL_QUERY
  357. =item SDL_ENABLE
  358. =item SDL_IGNORE
  359. Joystick event handling is default. Even if joystick event processing is enabled, individual joysticks must be opened before they generate events
  360. =back
  361. B<Warning:> Calling this function may delete all events currently in SDL's event queue.
  362. If $state is SDL_QUERY then the current state is returned, otherwise the new processing state is returned.
  363. =head1 SEE ALSO
  364. L<SDL::Event>, L<SDL::Video>
  365. =head1 AUTHORS
  366. See L<SDL/AUTHORS>.