This file is indexed.

/usr/lib/perl5/pods/SDL/Events.pod is in libsdl-perl 2.540-1.

This file is owned by root:root, with mode 0o644.

The actual contents of the file can be viewed below.

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
=head1 NAME

SDL::Events - Bindings to the Events Category in SDL API

=head2 CATEGORY

Core, Events

=head1 SYNOPSIS

Most likely you just want to know how to get events for you app.

  use SDL ':init';
  use SDL::Event;
  use SDL::Events ':all';

  SDL::init(SDL_INIT_VIDEO); # Event can only be grabbed in the same thread as this 

  ...

  my $event = SDL::Event->new(); # notices 'Event' ne 'Events'

  while( 1 )
  {
      SDL::Events::pump_events();
      while(  SDL::Events::poll_event($event) )
      {
          #check by event type
          on_active() if $event->type == SDL_ACTIVEEVENT; 
          ...
      }
  }

=head1 CONSTANTS

The constants are exported by default. You can avoid this by doing:

 use SDL::Events ();

and access them directly:

 SDL::Events::SDL_ACTIVEEVENT;

or by choosing the export tags below:

Export tag: ':type'

 SDL_ACTIVEEVENT
 SDL_KEYDOWN
 SDL_KEYUP
 SDL_MOUSEMOTION
 SDL_MOUSEBUTTONDOWN
 SDL_MOUSEBUTTONUP
 SDL_JOYAXISMOTION
 SDL_JOYBALLMOTION
 SDL_JOYHATMOTION
 SDL_JOYBUTTONDOWN
 SDL_JOYBUTTONUP
 SDL_QUIT
 SDL_SYSWMEVENT
 SDL_VIDEORESIZE
 SDL_VIDEOEXPOSE
 SDL_USEREVENT
 SDL_NUMEVENTS

Export tag: ':mask'

 SDL_EVENTMASK
 SDL_ACTIVEEVENTMASK
 SDL_KEYDOWNMASK
 SDL_KEYUPMASK
 SDL_KEYEVENTMASK
 SDL_MOUSEMOTIONMASK
 SDL_MOUSEBUTTONDOWNMASK
 SDL_MOUSEBUTTONUPMASK
 SDL_MOUSEEVENTMASK
 SDL_JOYAXISMOTIONMASK
 SDL_JOYBALLMOTIONMASK
 SDL_JOYHATMOTIONMASK
 SDL_JOYBUTTONDOWNMASK
 SDL_JOYBUTTONUPMASK
 SDL_JOYEVENTMASK
 SDL_VIDEORESIZEMASK
 SDL_VIDEOEXPOSEMASK
 SDL_QUITMASK
 SDL_SYSWMEVENTMASK
 SDL_ALLEVENTS

Export tag: ':action'

 SDL_ADDEVENT
 SDL_PEEKEVENT
 SDL_GETEVENT

Export tag: ':state'

 SDL_QUERY
 SDL_IGNORE
 SDL_DISABLE / SDL_ENABLE
 SDL_RELEASED / SDL_PRESSED

Export tag: ':hat'

 SDL_HAT_CENTERED
 SDL_HAT_UP / SDL_HAT_RIGHT / SDL_HAT_DOWN / SDL_HAT_LEFT
 SDL_HAT_RIGHTUP / SDL_HAT_RIGHTDOWN / SDL_HAT_LEFTUP / SDL_HAT_LEFTDOWN

Export tag: ':app'

 SDL_APPMOUSEFOCUS
 SDL_APPINPUTFOCUS
 SDL_APPACTIVE

Export tag: ':button'

 SDL_BUTTON
 SDL_BUTTON_LEFT / SDL_BUTTON_MIDDLE / SDL_BUTTON_RIGHT
 SDL_BUTTON_WHEELUP / SDL_BUTTON_WHEELDOWN
 SDL_BUTTON_X1 / SDL_BUTTON_X2
 SDL_BUTTON_LMASK / SDL_BUTTON_MMASK / SDL_BUTTON_RMASK
 SDL_BUTTON_X1MASK / SDL_BUTTON_X2MASK

Export tag: ':keysym'

 SDLK_UNKNOWN
 SDLK_FIRST
 SDLK_BACKSPACE
 SDLK_TAB
 SDLK_CLEAR
 SDLK_RETURN
 SDLK_PAUSE
 SDLK_ESCAPE
 SDLK_SPACE
 SDLK_EXCLAIM
 SDLK_QUOTEDBL
 SDLK_HASH
 SDLK_DOLLAR
 SDLK_AMPERSAND
 SDLK_QUOTE
 SDLK_LEFTPAREN / SDLK_RIGHTPAREN
 SDLK_ASTERISK
 SDLK_PLUS / SDLK_MINUS
 SDLK_COMMA
 SDLK_PERIOD
 SDLK_0 .. SDLK_9
 SDLK_COLON
 SDLK_SEMICOLON
 SDLK_LESS / SDLK_GREATER
 SDLK_EQUALS
 SDLK_QUESTION
 SDLK_AT
 SDLK_LEFTBRACKET / SDLK_RIGHTBRACKET
 SDLK_SLASH / SDLK_BACKSLASH
 SDLK_CARET
 SDLK_UNDERSCORE
 SDLK_BACKQUOTE
 SDLK_a .. SDLK_z
 SDLK_DELETE
 SDLK_WORLD_0 .. SDLK_WORLD_95
 SDLK_KP0 .. SDLK_KP9
 SDLK_KP_PERIOD
 SDLK_KP_DIVIDE / SDLK_KP_MULTIPLY
 SDLK_KP_MINUS / SDLK_KP_PLUS
 SDLK_KP_ENTER
 SDLK_KP_EQUALS
 SDLK_UP / SDLK_DOWN / SDLK_RIGHT / SDLK_LEFT
 SDLK_INSERT
 SDLK_HOME / SDLK_END
 SDLK_PAGEUP / SDLK_PAGEDOWN
 SDLK_F1 .. SDLK_F15
 SDLK_NUMLOCK / SDLK_CAPSLOCK / SDLK_SCROLLOCK
 SDLK_RSHIFT / SDLK_LSHIFT
 SDLK_RCTRL  / SDLK_LCTRL
 SDLK_RALT   / SDLK_LALT
 SDLK_RMETA  / SDLK_LMETA
 SDLK_LSUPER / SDLK_RSUPER
 SDLK_MODE
 SDLK_COMPOSE
 SDLK_HELP
 SDLK_PRINT
 SDLK_SYSREQ
 SDLK_BREAK
 SDLK_MENU
 SDLK_POWER
 SDLK_EURO
 SDLK_UNDO

Export tag ':keymod'

 KMOD_NONE
 KMOD_LSHIFT / KMOD_RSHIFT / KMOD_SHIFT
 KMOD_LCTRL  / KMOD_RCTRL  / KMOD_CTRL
 KMOD_LALT   / KMOD_RALT   / KMOD_ALT
 KMOD_LMETA  / KMOD_RMETA  / KMOD_META
 KMOD_NUM
 KMOD_CAPS
 KMOD_MODE
 KMOD_RESERVED

=head1 METHODS

=head2 pump_events

Pumps the event loop, gathering events from the input devices.

	pump_events();

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 
ever be placed on the queue. 
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. 
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.


=head2 peep_events (event, num_events, action, mask) 

Checks the event queue for messages and optionally returns them.  

	my $num_peep_events = SDL::Events::peep_events($event, 127, SDL_PEEKEVENT, SDL_ALLEVENTS);

If action is SDL_ADDEVENT, up to num_events events will be added to the back of the event queue.

If action is SDL_PEEKEVENT, up to numevents events at the front of the event queue, matching mask, will be returned and will not be removed from 
the queue.

If action is SDL_GETEVENT, up to numevents events at the front of the event queue, matching mask, will be returned and will be removed from the 
queue.

The mask parameter is a bitwise OR of SDL::Events::SDL_EVENTMASK(event_type), for all event types you are interested in

This function is thread-safe.

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.

Examples of mask:

=over

=item SDL_EVENTMASK (SDL_KEYUP)

=item (SDL_EVENTMASK (SDL_MOUSEBUTTONDOWN) | SDL_EVENTMASK (SDL_MOUSEBUTTONUP))
    
=item SDL_ALLEVENTS
   
=item SDL_KEYUPMASK
    
=item SDL_ALLEVENTS ^ SDL_QUITMASK

=back 

=head3 RETURN

Number of Events actually stored or -1 if there was an error

=head2 poll_event($event)

Polls for currently pending events. 

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.

As this function implicitly calls pump_events, you can only call this function in the thread that set the video mode with 
L<SDL::Video::set_video_mode|SDL::Video/"set_video_mode">. 

=head3 RETURN

Returns 1 if there are any pending events, or 0 if there are none available. 

=head2 push_event($event)

Pushes an event onto the event queue 

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 
their own events onto it. event is a pointer to the event structure you wish to push onto the queue. 
The event is copied into the queue, and the caller may dispose of the memory pointed to after push_event returns.

Note: Pushing device input events onto the queue doesn't modify the state of the device within SDL. 

This function is thread safe, and can be called from other threads safely.

=head3 RETURN

Returns 0 on success or -1 if the event couldn't be pushed.

=head2 wait_event($event)

Waits indefinitely for the next available $event, returning 0 if there was an error while waiting for events, 1 otherwise.

If $event is not NULL, the next event is removed from the queue and stored in $event.

As this function implicitly calls SDL_PumpEvents, you can only call this function in the thread that 
L<SDL::Video::set_video_mode|SDL::Video/"set_video_mode">.  

=head3 RETURN

0 if there was an error while waiting for events, 1 otherwise

=head2 set_event_filter

Sets up a filter to process all events 

	my $filter = sub { if($_[0]->type == SDL_ACTIVEEVENT){ return 0} else{ return 1; }};

	SDL::Events::set_event_filter($filter);

=head3 PARAMETER

set_event_filter takes a coderef that it checks all events again. The callback gets a event in the stack

	sub { my $event_to_test = shift; ...}

to filter the event return a 0, to pass the filter return a 1. 

One B<Caveat> is if you are filtering SDL_QUIT the event will be filtered if it is non-intterupt call ( Window closes normally ). If it is a 
interrupt SDL_QUIT it will be process on the next event poll. 

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"> 
do not get filtered.

This callback may run in a different thread. 

=head2 get_key_state

Get a snapshot of the current keyboard state

	my $keys_ref = SDL::Events::get_key_state();

	print $keys_ref->[SDLK_RETURN]; # 1 if pressed , 0 if not pressed

Use L<SDL::Events::pump_events|SDL::Events/"pump_events"> to update the state array.

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 
process events, then the pressed state will never show up in the get_key_state call.

This function doesn't take into account whether shift has been pressed or not.

=head2 get_mod_state

Get the state of the modifier keys

Returns the current state of modifier keys

Return value is an OR'd combination of  KMOD_*

 SDL::Events::pump_events; #get latest mod_state in buffers

 my $mod_state = SDL::Events::get_mod_state();

 # Check which ones are pressed with 

 # no mod pressed?
 
 print 'no_mod' if  ( $mod_state & KMOD_NONE );

 # CTRL or ALT 

 print 'ctrl alt' if ($mod_state & KMOD_CTRL || $mod_state & KMOD_ALT );

=head3 MOD VALUES

=over 

=item KMOD_NONE

=item KMOD_LSHIFT

=item KMOD_RSHIFT

=item KMOD_LCTRL

=item KMOD_RCTRL

=item KMOD_LALT

=item KMOD_RALT

=item KMOD_LMETA

=item KMOD_RMETA

=item KMOD_NUM

=item KMOD_CAPS

=item KMOD_MODE

=item KMOD_CTRL 

same as KMOD_LCTRL|KMOD_RCTRL

=item KMOD_SHIFT

same as KMOD_LSHIFT|KMOD_RSHIFT

=item KMOD_ALT

same as KMOD_LALT|KMOD_RALT

=item KMOD_META

same as KMOD_LMETA|KMOD_RMETA

=back

=head2 set_mod_state

Get the state of the modifier keys

The inverse of L<SDL::Events::get_mod_state|SDL::Events/"get_mod_state"> allows you to impose modifier key states on your application.

Simply pass your desired modifier states into $modstate. This value can be a OR'd combination of any KMOD* constant.

 my $modstate = KMOD_LMETA | KMOD_LSHIFT;

Any KMOD_* constant see L<SDL::Events::get_mod_state|SDL::Events/"get_mod_state"> for constants.
 SDL::Events::set_mod_state( $modstate );

=head2 event_state 

Allows you to set the state of processing certain events

 SDL::Events::event_state( $type, $state );

A list of $type(s) can be found in L<SDL::Event>

=head3 STATES

=over 4

=item SDL_IGNORE

The event of $type will be automatically dropper from the event queue and will not be filtered.

=item SDL_ENABLE

The event of $type will be processed normally. This is default.

=item SDL_QUERY

The current processing state of the $type will be returned

=back

=head2 get_key_name

Gets the name of the a SDL virtual keysym

 my $event = SDL::Event->new();

 while( SDL::Events::poll_event($event) )
 {
   my $key = $event->key_sym;
   $key_str = SDL::Events::get_key_name($key);
 }

Returns a string with the name of the key sym.

=head2 enable_unicode 

Enable/Disable UNICODE translation

  my $previous_translation_mode = SDL::Events::enable_unicode( 1 ); #enable
     $previous_translation_mode = SDL::Events::enable_unicode( 0 ); #disables

To obtain the character codes corresponding to received keyboard events, Unicode translation must first be turned on using this function. The 
translation incurs a slight overhead for each keyboard event and is therefore disabled by default. For each subsequently recieved key down event, 
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 
otherwise zero.

A value of 1 for enabling, 0 for disabling and -1 for unchanged. -1 is useful for querying the current translation mode.

Only key press events will be translated not release events.

Returns the previous translation mode as (1,0).

=head2 enable_key_repeat 

Sets keyboard repeat rate

 my $success = SDL::Events::enable_key_repeat( $delay, $interval );

Enables or disables the keyboard repeat rate. $delay specifies how long the key must be pressed before it begins repeating, it then repleats at the 
speed specified by $interval. Both $delay and $interval are expressed in milliseconds.

Setting $delay to 0 disables key repeating completely. Good default values are SDL_DEFAULT_REPEAT_DELAY and SDL_DEFAULT_REPEAT_INTERVAL.

Return 0 on success and -1 on fail.

=head2 get_mouse_state 

Retrieves the current state of the mouse

  my ($mask,$x,$y) = @{ SDL::Events::get_mouse_state( ) };

  print 'Button Left pressed' if ($mask & SDL_BUTTON_LMASK);    

  print 'Button Right pressed' if ($mask & SDL_BUTTON_RMASK);   

  print 'Button Middle pressed' if ($mask & SDL_BUTTON_MMASK);  

  print $x.','.$y;

The current button state is returned as a button $bitmask, which can be tested using the the above constants 

=head2 get_relative_mouse_state 

Retrieves the current relative state of the mouse

  my ($mask,$x,$y) = @{ SDL::Events::get_mouse_state( ) };

  print 'Button Left pressed' if ($mask & SDL_BUTTON_LMASK);    

  print 'Button Right pressed' if ($mask & SDL_BUTTON_RMASK);   

  print 'Button Middle pressed' if ($mask & SDL_BUTTON_MMASK);  

  print $x.','.$y; # this is relative to the last position of the mouse

The current button state is returned as a button $bitmask, which can be tested using the the above constants 


=head2 get_app_state 

Gets the state of the application

	my $app_state = SDL::Events::get_app_state();

The $app_state is a bitwise combination of:

=over 

=item SDL_APPMOUSEFOCUS

Application has mouse focus

	warn 'mouse focus' if $app_state & SDL_APPMOUSEFOCUS

=item SDL_APPINPUTFOCUS

Application has keyboard focus

	warn 'keyboard focus' if $app_state & SDL_APPINPUTFOCUS


=item SDL_APPACTIVE

Application is visible

	warn 'Application Visible' if $app_state & SDL_APPACTIVE

=back 

=head2 joystick_event_state 

Enable/disable joystick event polling

	my $status = SDL::Events::joystick_event_state( $state );

This function is used to enable or disable joystick event processing. With joystick event processing disabled you will have to update joystick 
states with L<SDL::Joystick::update|SDL::Joystick/"update"> and read the joystick information manually. $state can be:

=over 

=item SDL_QUERY

=item SDL_ENABLE 

=item SDL_IGNORE

Joystick event handling is default. Even if joystick event processing is enabled, individual joysticks must be opened before they generate events

=back

B<Warning:> Calling this function may delete all events currently in SDL's event queue.

If $state is SDL_QUERY then the current state is returned, otherwise the new processing state is returned.

=head1 SEE ALSO

L<SDL::Event>, L<SDL::Video>

=head1 AUTHORS

See L<SDL/AUTHORS>.