SDL::Events(3pm)

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

NAME

6       SDL::Events - Bindings to the Events Category in SDL API
7
8   CATEGORY
9       Core, Events
10

SYNOPSIS

12       Most likely you just want to know how to get events for you app.
13
14         use SDL ':init';
15         use SDL::Event;
16         use SDL::Events ':all';
17
18         SDL::init(SDL_INIT_VIDEO); # Event can only be grabbed in the same thread as this
19
20         ...
21
22         my $event = SDL::Event->new(); # notices 'Event' ne 'Events'
23
24         while( 1 )
25         {
26             SDL::Events::pump_events();
27             while(  SDL::Events::poll_event($event) )
28             {
29                 #check by event type
30                 on_active() if $event->type == SDL_ACTIVEEVENT;
31                 ...
32             }
33         }
34

CONSTANTS

36       The constants are exported by default. You can avoid this by doing:
37
38        use SDL::Events ();
39
40       and access them directly:
41
42        SDL::Events::SDL_ACTIVEEVENT;
43
44       or by choosing the export tags below:
45
46       Export tag: ':type'
47
48        SDL_ACTIVEEVENT
49        SDL_KEYDOWN
50        SDL_KEYUP
51        SDL_MOUSEMOTION
52        SDL_MOUSEBUTTONDOWN
53        SDL_MOUSEBUTTONUP
54        SDL_JOYAXISMOTION
55        SDL_JOYBALLMOTION
56        SDL_JOYHATMOTION
57        SDL_JOYBUTTONDOWN
58        SDL_JOYBUTTONUP
59        SDL_QUIT
60        SDL_SYSWMEVENT
61        SDL_VIDEORESIZE
62        SDL_VIDEOEXPOSE
63        SDL_USEREVENT
64        SDL_NUMEVENTS
65
66       Export tag: ':mask'
67
68        SDL_EVENTMASK
69        SDL_ACTIVEEVENTMASK
70        SDL_KEYDOWNMASK
71        SDL_KEYUPMASK
72        SDL_KEYEVENTMASK
73        SDL_MOUSEMOTIONMASK
74        SDL_MOUSEBUTTONDOWNMASK
75        SDL_MOUSEBUTTONUPMASK
76        SDL_MOUSEEVENTMASK
77        SDL_JOYAXISMOTIONMASK
78        SDL_JOYBALLMOTIONMASK
79        SDL_JOYHATMOTIONMASK
80        SDL_JOYBUTTONDOWNMASK
81        SDL_JOYBUTTONUPMASK
82        SDL_JOYEVENTMASK
83        SDL_VIDEORESIZEMASK
84        SDL_VIDEOEXPOSEMASK
85        SDL_QUITMASK
86        SDL_SYSWMEVENTMASK
87        SDL_ALLEVENTS
88
89       Export tag: ':action'
90
91        SDL_ADDEVENT
92        SDL_PEEKEVENT
93        SDL_GETEVENT
94
95       Export tag: ':state'
96
97        SDL_QUERY
98        SDL_IGNORE
99        SDL_DISABLE / SDL_ENABLE
100        SDL_RELEASED / SDL_PRESSED
101
102       Export tag: ':hat'
103
104        SDL_HAT_CENTERED
105        SDL_HAT_UP / SDL_HAT_RIGHT / SDL_HAT_DOWN / SDL_HAT_LEFT
106        SDL_HAT_RIGHTUP / SDL_HAT_RIGHTDOWN / SDL_HAT_LEFTUP / SDL_HAT_LEFTDOWN
107
108       Export tag: ':app'
109
110        SDL_APPMOUSEFOCUS
111        SDL_APPINPUTFOCUS
112        SDL_APPACTIVE
113
114       Export tag: ':button'
115
116        SDL_BUTTON
117        SDL_BUTTON_LEFT / SDL_BUTTON_MIDDLE / SDL_BUTTON_RIGHT
118        SDL_BUTTON_WHEELUP / SDL_BUTTON_WHEELDOWN
119        SDL_BUTTON_X1 / SDL_BUTTON_X2
120        SDL_BUTTON_LMASK / SDL_BUTTON_MMASK / SDL_BUTTON_RMASK
121        SDL_BUTTON_X1MASK / SDL_BUTTON_X2MASK
122
123       Export tag: ':keysym'
124
125        SDLK_UNKNOWN
126        SDLK_FIRST
127        SDLK_BACKSPACE
128        SDLK_TAB
129        SDLK_CLEAR
130        SDLK_RETURN
131        SDLK_PAUSE
132        SDLK_ESCAPE
133        SDLK_SPACE
134        SDLK_EXCLAIM
135        SDLK_QUOTEDBL
136        SDLK_HASH
137        SDLK_DOLLAR
138        SDLK_AMPERSAND
139        SDLK_QUOTE
140        SDLK_LEFTPAREN / SDLK_RIGHTPAREN
141        SDLK_ASTERISK
142        SDLK_PLUS / SDLK_MINUS
143        SDLK_COMMA
144        SDLK_PERIOD
145        SDLK_0 .. SDLK_9
146        SDLK_COLON
147        SDLK_SEMICOLON
148        SDLK_LESS / SDLK_GREATER
149        SDLK_EQUALS
150        SDLK_QUESTION
151        SDLK_AT
152        SDLK_LEFTBRACKET / SDLK_RIGHTBRACKET
153        SDLK_SLASH / SDLK_BACKSLASH
154        SDLK_CARET
155        SDLK_UNDERSCORE
156        SDLK_BACKQUOTE
157        SDLK_a .. SDLK_z
158        SDLK_DELETE
159        SDLK_WORLD_0 .. SDLK_WORLD_95
160        SDLK_KP0 .. SDLK_KP9
161        SDLK_KP_PERIOD
162        SDLK_KP_DIVIDE / SDLK_KP_MULTIPLY
163        SDLK_KP_MINUS / SDLK_KP_PLUS
164        SDLK_KP_ENTER
165        SDLK_KP_EQUALS
166        SDLK_UP / SDLK_DOWN / SDLK_RIGHT / SDLK_LEFT
167        SDLK_INSERT
168        SDLK_HOME / SDLK_END
169        SDLK_PAGEUP / SDLK_PAGEDOWN
170        SDLK_F1 .. SDLK_F15
171        SDLK_NUMLOCK / SDLK_CAPSLOCK / SDLK_SCROLLOCK
172        SDLK_RSHIFT / SDLK_LSHIFT
173        SDLK_RCTRL  / SDLK_LCTRL
174        SDLK_RALT   / SDLK_LALT
175        SDLK_RMETA  / SDLK_LMETA
176        SDLK_LSUPER / SDLK_RSUPER
177        SDLK_MODE
178        SDLK_COMPOSE
179        SDLK_HELP
180        SDLK_PRINT
181        SDLK_SYSREQ
182        SDLK_BREAK
183        SDLK_MENU
184        SDLK_POWER
185        SDLK_EURO
186        SDLK_UNDO
187
188       Export tag ':keymod'
189
190        KMOD_NONE
191        KMOD_LSHIFT / KMOD_RSHIFT / KMOD_SHIFT
192        KMOD_LCTRL  / KMOD_RCTRL  / KMOD_CTRL
193        KMOD_LALT   / KMOD_RALT   / KMOD_ALT
194        KMOD_LMETA  / KMOD_RMETA  / KMOD_META
195        KMOD_NUM
196        KMOD_CAPS
197        KMOD_MODE
198        KMOD_RESERVED
199

METHODS

201   pump_events
202       Pumps the event loop, gathering events from the input devices.
203
204               pump_events();
205
206       pump_events gathers all the pending input information from devices and
207       places it on the event queue. Without calls to pump_events no events
208       would ever be placed on the queue.  Often the need for calls to
209       pump_events is hidden from the user since "poll_event" and "wait_event"
210       implicitly call pump_events.  However, if you are not polling or
211       waiting for events (e.g. you are filtering them), then you must call
212       pump_events to force an event queue update.
213
214   peep_events (event, num_events, action, mask)
215       Checks the event queue for messages and optionally returns them.
216
217               my $num_peep_events = SDL::Events::peep_events($event, 127, SDL_PEEKEVENT, SDL_ALLEVENTS);
218
219       If action is SDL_ADDEVENT, up to num_events events will be added to the
220       back of the event queue.
221
222       If action is SDL_PEEKEVENT, up to num_events events at the front of the
223       event queue, matching mask, will be returned and will not be removed
224       from the queue.
225
226       If action is SDL_GETEVENT, up to num_events events at the front of the
227       event queue, matching mask, will be returned and will be removed from
228       the queue.
229
230       The mask parameter is a bitwise OR of
231       SDL::Events::SDL_EVENTMASK(event_type), for all event types you are
232       interested in
233
234       This function is thread-safe.
235
236       You may have to call pump_events before calling this function.
237       Otherwise, the events may not be ready to be filtered when you call
238       peep_events.
239
240       Examples of mask:
241
242       SDL_EVENTMASK (SDL_KEYUP)
243       (SDL_EVENTMASK (SDL_MOUSEBUTTONDOWN) | SDL_EVENTMASK
244       (SDL_MOUSEBUTTONUP))
245       SDL_ALLEVENTS
246       SDL_KEYUPMASK
247       SDL_ALLEVENTS ^ SDL_QUITMASK
248
249       RETURN
250
251       Number of Events actually stored or -1 if there was an error
252
253   poll_event($event)
254       Polls for currently pending events.
255
256       If $event is not NULL, the next event is removed from the queue and
257       stored in the SDL::Event structure pointed to by $event.
258
259       As this function implicitly calls pump_events, you can only call this
260       function in the thread that set the video mode with
261       SDL::Video::set_video_mode.
262
263       RETURN
264
265       Returns 1 if there are any pending events, or 0 if there are none
266       available.
267
268   push_event($event)
269       Pushes an event onto the event queue
270
271       The event queue can actually be used as a two way communication
272       channel. Not only can events be read from the queue, but the user can
273       also push their own events onto it. event is a pointer to the event
274       structure you wish to push onto the queue.  The event is copied into
275       the queue, and the caller may dispose of the memory pointed to after
276       push_event returns.
277
278       Note: Pushing device input events onto the queue doesn't modify the
279       state of the device within SDL.
280
281       This function is thread safe, and can be called from other threads
282       safely.
283
284       RETURN
285
286       Returns 0 on success or -1 if the event couldn't be pushed.
287
288   wait_event($event)
289       Waits indefinitely for the next available $event, returning 0 if there
290       was an error while waiting for events, 1 otherwise.
291
292       If $event is not NULL, the next event is removed from the queue and
293       stored in $event.
294
295       As this function implicitly calls SDL_PumpEvents, you can only call
296       this function in the thread that SDL::Video::set_video_mode.
297
298       RETURN
299
300       0 if there was an error while waiting for events, 1 otherwise
301
302   set_event_filter
303       Sets up a filter to process all events
304
305               my $filter = sub { if($_[0]->type == SDL_ACTIVEEVENT){ return 0} else{ return 1; }};
306
307               SDL::Events::set_event_filter($filter);
308
309       PARAMETER
310
311       set_event_filter takes a coderef that it checks all events again. The
312       callback gets a event in the stack
313
314               sub { my $event_to_test = shift; ...}
315
316       to filter the event return a 0, to pass the filter return a 1.
317
318       One Caveat is if you are filtering SDL_QUIT the event will be filtered
319       if it is non-interrupt call ( Window closes normally ). If it is a
320       interrupt SDL_QUIT it will be process on the next event poll.
321
322       Events pushed onto to the queue with SDL::Events::push_events or
323       SDL::Events::peep_events do not get filtered.
324
325       This callback may run in a different thread.
326
327   get_key_state
328       Get a snapshot of the current keyboard state
329
330               my $keys_ref = SDL::Events::get_key_state();
331
332               print $keys_ref->[SDLK_RETURN]; # 1 if pressed , 0 if not pressed
333
334       Use SDL::Events::pump_events to update the state array.
335
336       This function gives you the current state after all events have been
337       processed, so if a key or button has been pressed and released before
338       you process events, then the pressed state will never show up in the
339       get_key_state call.
340
341       This function doesn't take into account whether shift has been pressed
342       or not.
343
344   get_mod_state
345       Get the state of the modifier keys
346
347       Returns the current state of modifier keys
348
349       Return value is an OR'd combination of  KMOD_*
350
351        SDL::Events::pump_events; #get latest mod_state in buffers
352
353        my $mod_state = SDL::Events::get_mod_state();
354
355        # Check which ones are pressed with
356
357        # no mod pressed?
358
359        print 'no_mod' if  ( $mod_state & KMOD_NONE );
360
361        # CTRL or ALT
362
363        print 'ctrl alt' if ($mod_state & KMOD_CTRL || $mod_state & KMOD_ALT );
364
365       MOD VALUES
366
367       KMOD_NONE
368       KMOD_LSHIFT
369       KMOD_RSHIFT
370       KMOD_LCTRL
371       KMOD_RCTRL
372       KMOD_LALT
373       KMOD_RALT
374       KMOD_LMETA
375       KMOD_RMETA
376       KMOD_NUM
377       KMOD_CAPS
378       KMOD_MODE
379       KMOD_CTRL
380           same as KMOD_LCTRL|KMOD_RCTRL
381
382       KMOD_SHIFT
383           same as KMOD_LSHIFT|KMOD_RSHIFT
384
385       KMOD_ALT
386           same as KMOD_LALT|KMOD_RALT
387
388       KMOD_META
389           same as KMOD_LMETA|KMOD_RMETA
390
391   set_mod_state
392       Get the state of the modifier keys
393
394       The inverse of SDL::Events::get_mod_state allows you to impose modifier
395       key states on your application.
396
397       Simply pass your desired modifier states into $modstate. This value can
398       be a OR'd combination of any KMOD* constant.
399
400        my $modstate = KMOD_LMETA | KMOD_LSHIFT;
401
402       Any KMOD_* constant see SDL::Events::get_mod_state for constants.
403        SDL::Events::set_mod_state( $modstate );
404
405   event_state
406       Allows you to set the state of processing certain events
407
408        SDL::Events::event_state( $type, $state );
409
410       A list of $type(s) can be found in SDL::Event
411
412       STATES
413
414       SDL_IGNORE
415           The event of $type will be automatically dropper from the event
416           queue and will not be filtered.
417
418       SDL_ENABLE
419           The event of $type will be processed normally. This is default.
420
421       SDL_QUERY
422           The current processing state of the $type will be returned
423
424   get_key_name
425       Gets the name of the a SDL virtual keysym
426
427        my $event = SDL::Event->new();
428
429        while( SDL::Events::poll_event($event) )
430        {
431          my $key = $event->key_sym;
432          $key_str = SDL::Events::get_key_name($key);
433        }
434
435       Returns a string with the name of the key sym.
436
437   enable_unicode
438       Enable/Disable UNICODE translation
439
440         my $previous_translation_mode = SDL::Events::enable_unicode( 1 ); #enable
441            $previous_translation_mode = SDL::Events::enable_unicode( 0 ); #disables
442
443       To obtain the character codes corresponding to received keyboard
444       events, Unicode translation must first be turned on using this
445       function. The translation incurs a slight overhead for each keyboard
446       event and is therefore disabled by default. For each subsequently
447       received key down event, the unicode member of the SDL::Event::key_sym
448       provided structure will be then contain the corresponding character
449       code, or otherwise zero.
450
451       A value of 1 for enabling, 0 for disabling and -1 for unchanged. -1 is
452       useful for querying the current translation mode.
453
454       Only key press events will be translated not release events.
455
456       Returns the previous translation mode as (1,0).
457
458   enable_key_repeat
459       Sets keyboard repeat rate
460
461        my $success = SDL::Events::enable_key_repeat( $delay, $interval );
462
463       Enables or disables the keyboard repeat rate. $delay specifies how long
464       the key must be pressed before it begins repeating, it then repeats at
465       the speed specified by $interval. Both $delay and $interval are
466       expressed in milliseconds.
467
468       Setting $delay to 0 disables key repeating completely. Good default
469       values are SDL_DEFAULT_REPEAT_DELAY and SDL_DEFAULT_REPEAT_INTERVAL.
470
471       Return 0 on success and -1 on fail.
472
473   get_mouse_state
474       Retrieves the current state of the mouse
475
476         my ($mask,$x,$y) = @{ SDL::Events::get_mouse_state( ) };
477
478         print 'Button Left pressed' if ($mask & SDL_BUTTON_LMASK);
479
480         print 'Button Right pressed' if ($mask & SDL_BUTTON_RMASK);
481
482         print 'Button Middle pressed' if ($mask & SDL_BUTTON_MMASK);
483
484         print $x.','.$y;
485
486       The current button state is returned as a button $bitmask, which can be
487       tested using the the above constants
488
489   get_relative_mouse_state
490       Retrieves the current relative state of the mouse
491
492         my ($mask,$x,$y) = @{ SDL::Events::get_mouse_state( ) };
493
494         print 'Button Left pressed' if ($mask & SDL_BUTTON_LMASK);
495
496         print 'Button Right pressed' if ($mask & SDL_BUTTON_RMASK);
497
498         print 'Button Middle pressed' if ($mask & SDL_BUTTON_MMASK);
499
500         print $x.','.$y; # this is relative to the last position of the mouse
501
502       The current button state is returned as a button $bitmask, which can be
503       tested using the the above constants
504
505   get_app_state
506       Gets the state of the application
507
508               my $app_state = SDL::Events::get_app_state();
509
510       The $app_state is a bitwise combination of:
511
512       SDL_APPMOUSEFOCUS
513           Application has mouse focus
514
515                   warn 'mouse focus' if $app_state & SDL_APPMOUSEFOCUS
516
517       SDL_APPINPUTFOCUS
518           Application has keyboard focus
519
520                   warn 'keyboard focus' if $app_state & SDL_APPINPUTFOCUS
521
522       SDL_APPACTIVE
523           Application is visible
524
525                   warn 'Application Visible' if $app_state & SDL_APPACTIVE
526
527   joystick_event_state
528       Enable/disable joystick event polling
529
530               my $status = SDL::Events::joystick_event_state( $state );
531
532       This function is used to enable or disable joystick event processing.
533       With joystick event processing disabled you will have to update
534       joystick states with SDL::Joystick::update and read the joystick
535       information manually. $state can be:
536
537       SDL_QUERY
538       SDL_ENABLE
539       SDL_IGNORE
540           Joystick event handling is default. Even if joystick event
541           processing is enabled, individual joysticks must be opened before
542           they generate events
543
544       Warning: Calling this function may delete all events currently in SDL's
545       event queue.
546
547       If $state is SDL_QUERY then the current state is returned, otherwise
548       the new processing state is returned.
549

AUTHORS

554       See "AUTHORS" in SDL.
555
556
557
558perl v5.34.0                      2021-07-22                    SDL::Events(3)

NAME

SYNOPSIS

CONSTANTS

METHODS

SEE ALSO

AUTHORS