File: event.rsd

package info (click to toggle)
ruby-sdl 2.2.0-1
  • links: PTS, VCS
  • area: main
  • in suites: bookworm, bullseye, buster, sid, stretch
  • size: 1,544 kB
  • ctags: 1,359
  • sloc: cpp: 7,598; ansic: 4,498; ruby: 2,246; makefile: 106; sh: 102
file content (1483 lines) | stat: -rw-r--r-- 28,134 bytes parent folder | download | duplicates (2)
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
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
1287
1288
1289
1290
1291
1292
1293
1294
1295
1296
1297
1298
1299
1300
1301
1302
1303
1304
1305
1306
1307
1308
1309
1310
1311
1312
1313
1314
1315
1316
1317
1318
1319
1320
1321
1322
1323
1324
1325
1326
1327
1328
1329
1330
1331
1332
1333
1334
1335
1336
1337
1338
1339
1340
1341
1342
1343
1344
1345
1346
1347
1348
1349
1350
1351
1352
1353
1354
1355
1356
1357
1358
1359
1360
1361
1362
1363
1364
1365
1366
1367
1368
1369
1370
1371
1372
1373
1374
1375
1376
1377
1378
1379
1380
1381
1382
1383
1384
1385
1386
1387
1388
1389
1390
1391
1392
1393
1394
1395
1396
1397
1398
1399
1400
1401
1402
1403
1404
1405
1406
1407
1408
1409
1410
1411
1412
1413
1414
1415
1416
1417
1418
1419
1420
1421
1422
1423
1424
1425
1426
1427
1428
1429
1430
1431
1432
1433
1434
1435
1436
1437
1438
1439
1440
1441
1442
1443
1444
1445
1446
1447
1448
1449
1450
1451
1452
1453
1454
1455
1456
1457
1458
1459
1460
1461
1462
1463
1464
1465
1466
1467
1468
1469
1470
1471
1472
1473
1474
1475
1476
1477
1478
1479
1480
1481
1482
1483
= Event
* ((<Event system Overview>))
* ((<SDL::Event>))
* ((<SDL::Event::Active>))
* ((<SDL::Event::KeyDown>))
* ((<SDL::Event::KeyUp>))
* ((<SDL::Event::MouseMotion>))
* ((<SDL::Event::MouseButtonDown>))
* ((<SDL::Event::MouseButtonUp>))
* ((<SDL::Event::JoyAxis>))
* ((<SDL::Event::JoyBall>))
* ((<SDL::Event::JoyHat>))
* ((<SDL::Event::JoyButtonDown>))
* ((<SDL::Event::JoyButtonUp>))
* ((<SDL::Event::Quit>))
* ((<SDL::Event::SysWM>))
* ((<SDL::Event::VideoResize>))
* ((<SDL::Event::VideoExpose>))
* ((<SDL::Key>))
* ((<SDL::Mouse>))
* Methdos for Event
TOC

== Event system Overview
Event handling allows your application to receive input from the user.
Event handling is initalised (along with video) with a call to:
  SDL_Init(SDL_INIT_VIDEO);
Internally, SDL stores all the events waiting to be handled in an event queue.
Using functions like @[Event.poll] and @[Event.wait]
you can observe and handle waiting input events.

The key to event handling in SDL is the subclasses of @[Event].
The event queue itself is composed of a series of 
instance of (subclasses of) @[Event], one for each waiting event.
Those objects are read from queue with the @[Event.poll] and it is
then up to the application to process the information stored with them.

Subclasses of @[Event] is following:
* @[Event::Active]
* @[Event::KeyDown]
* @[Event::KeyUp]
* @[Event::MouseMotion]
* @[Event::MouseButtonDown]
* @[Event::MouseButtonUp]
* @[Event::JoyAxis]
* @[Event::JoyBall]
* @[Event::JoyHat]
* @[Event::JoyButtonDown]
* @[Event::JoyButtonUp]
* @[Event::Quit]
* @[Event::SysWM]
* @[Event::VideoResize]
* @[Event::VideoExpose]

Those classes have two uses.
* Reading events on the event queue.
* Placing events on the event queue.

Reading events from the event queue is done with @[Event.poll].
We'll use @[Event.poll] and step through an example.
@[Event.poll] removes the next event from the event queue, 
if there are no events on the queue it returns nil
otherwise it returns event object. 
We use a while loop to process each event in turn.

  while event = SDL::Event.poll

We know that if @[Event.poll] removes an event from the queue then the event information will
be placed in returned object, but we also know that the class of that object will represent
the type of event. So we handle each event type seperately we use a switch statement.

  case event

We need to know what kind of events we're looking for ((*and*)) the event type's of those events.
So lets assume we want to detect where the user is moving the mouse pointer within our application.
We look through our event types and notice that @[Event::MouseMotion] is, more than likely,
the event we're looking for. A little more research tells use that
mouse motion events are handled within the @[Event::MouseMotion].
We can check for the mouse motion event type within our switch statement like so:

  when SDL::Event::MouseMotion

All we need do now is read the information out of this object as instance 
of @[Event::MouseMotion].
  
    puts "We got a motion event"
    puts "Current mouse position is: (#{event.x}, #{event.y})"
  else
    puts "Unhandled Event!"
  end
  end
  puts "Event queue is empty."

It is also possible to push events onto the event queue.
[Event.push]  allows you to place events onto the event queue.
You can use it to post fake input events if you wished.

== SDL::Event
This class handle events. All objects returned by @[Event.poll] are
instances of subclasses of SDL::Event.

== Compatiblity
The class that used to be known as SDL::Event is remove.
The class now called SDL::Event was called SDL::Event2 before.
A constant SDL::Event2 remains as alias of SDL::Event because of compatiblity with older version.

== SDL::Event::Active
Class for Application visibility event.

This event raises when the mouse leaves or enters the window area,
the application loses or gains keyboard focus,
or the application is either minimised/iconified or restored.

@[Event::Active#state] returns which event occurs.

* NOTES

  This event does not occur when an application window is first created.

METHODS(Event::Active)

== SDL::Event::KeyDown

Class for keyboard down event.

METHODS(Event::KeyDown)

== SDL::Event::KeyUp

Class for key up event.

METHODS(Event::KeyUp)

== SDL::Event::MouseMotion

Class for mouse motion event.

Simply put, a event of this type occurs 
when a user moves the mouse within the application window or when [Mouse.warp] is called.
Both the absolute coordinate (@[Event::MouseMotion#x] and @[Event::MouseMotion#y]) and
relative coordinate (@[Event::MouseMotion#xrel] and @[Event::MouseMotion#yrel]) 
are reported along with the current button states (@[Event::MouseMotion#state]).

METHODS(Event::MouseMotion)

== SDL::Event::MouseButtonDown
Class for mouse button press event.

This type of event occurs when a mouse button press is detected.

METHODS(Event::MouseButtonDown)

== SDL::Event::MouseButtonUp
Class for mouse button release event.

This type of event occurs when a mouse button release is detected.

METHODS(Event::MouseButtonUp)

== SDL::Event::JoyAxis
Class for joystick axis motion event. 

This event occurs when ever a user moves an axis on the joystick. 

METHODS(Event::JoyAxis)

* SEEALSO
  @[Joystick#num_axes], @[Joystick#axis]

== SDL::Event::JoyBall
Class for joystick ball motion event.

This type of event occurs when a user moves a trackball on the joystick.

METHODS(Event::JoyBall)

* SEEALSO

  @[Joystick#num_balls], @[Joystick#ball]

== SDL::Event::JoyHat
Class for joystick hat position change event.

METHODS(Event::JoyHat)

* SEEALSO
  
  @[Joystick#num_hats], @[Joystick#hat]

== SDL::Event::JoyButtonDown
Class for joystick button press event.

This event occurs when a user presses a button on a joystick.

METHODS(Event::JoyButtonDown)

* SEEALSO

  @[Joystick#num_buttons], @[Joystick#button]

== SDL::Event::JoyButtonUp
Class for joystick button release event.

This event occurs when a user releases a button on a joystick.

METHODS(Event::JoyButtonUp)

* SEEALSO

  @[Joystick#num_buttons], @[Joystick#button]

== SDL::Event::Quit
Class for quit reqested event.

This event is very important.
If you filter out or ignore a quit event then it is impossible for the user to
close the window. On the other hand, if you do accept a quit event then the application window will be
closed, and screen updates will still report success event though the application will no longer be
visible.

== SDL::Event::SysWM
Class for platform-dependent window manager event.

Event of this type occurs when unknown window manager event happens.
You can never know the detail of this event.
Only you can to do is to ignore this event.

== SDL::Event::VideoResize
Class for window resize event.

When SDL::RESIZABLE is passed as a $[flag] to 
@[Screen.open] the user is allowed to resize the applications
window. When the window is resized an event of this type is report,
with the new window width and height values stored in @[Event::VideoResize#w] and
 @[Event::VideoResize#h] respectively.

When this event is recieved the window should be resized
to the new dimensions using @[Screen.open].

== SDL::Event::VideoExpose
Class for video expose event.

This event is triggered when the screen has been modified outside of the application, usually by
the window manager and needs to be redrawn.

== SDL::Key
Module for keyboard input.

This module defines some keyboard-related constants and 
module functions.

METHODS(Key)

=== Key symbol
Key symbol constants definitions.
* SDL::Key::BACKSPACE  '\b'  backspace  
* SDL::Key::TAB  '\t' tab  
* SDL::Key::CLEAR     clear
* SDL::Key::RETURN  '\r'  return
* SDL::Key::PAUSE    pause
* SDL::Key::ESCAPE  '^['  escape
* SDL::Key::SPACE  ' '   space
* SDL::Key::EXCLAIM  '!'   exclaim
* SDL::Key::QUOTEDBL  '"'   quotedbl
* SDL::Key::HASH  '#'   hash
* SDL::Key::DOLLAR  '$'   dollar
* SDL::Key::AMPERSAND  '&'  ampersand
* SDL::Key::QUOTE  '''  quote
* SDL::Key::LEFTPAREN  '('   left parenthesis
* SDL::Key::RIGHTPAREN  ')'  right parenthesis
* SDL::Key::ASTERISK  '*'  asterisk
* SDL::Key::PLUS  '+'  plus sign
* SDL::Key::COMMA  ','  comma
* SDL::Key::MINUS  '-'  minus sign
* SDL::Key::PERIOD  '.'  period
* SDL::Key::SLASH  '/'  forward slash
* SDL::Key::K0  '0'  0
* SDL::Key::K1  '1'  1
* SDL::Key::K2  '2'  2
* SDL::Key::K3  '3'  3
* SDL::Key::K4  '4'  4
* SDL::Key::K5  '5'  5
* SDL::Key::K6  '6'  6
* SDL::Key::K7  '7'  7
* SDL::Key::K8  '8'  8
* SDL::Key::K9  '9'  9
* SDL::Key::COLON  ':'  colon
* SDL::Key::SEMICOLON  ';'  semicolon
* SDL::Key::LESS  '&lt;'  less-than sign
* SDL::Key::EQUALS  '='   equals sign
* SDL::Key::GREATER  '&gt;'   greater-than sign
* SDL::Key::QUESTION  '?'   question mark
* SDL::Key::AT  '@'   at
* SDL::Key::LEFTBRACKET  '['   left bracket
* SDL::Key::BACKSLASH  '\'   backslash
* SDL::Key::RIGHTBRACKET  ']'   right bracket
* SDL::Key::CARET  '^'   caret
* SDL::Key::UNDERSCORE  '_'   underscore
* SDL::Key::BACKQUOTE  '`'   grave
* SDL::Key::A  'a'  a  
* SDL::Key::B  'b'  b  
* SDL::Key::C  'c'  c  
* SDL::Key::D  'd'  d  
* SDL::Key::E  'e'  e  
* SDL::Key::F  'f'  f  
* SDL::Key::G  'g'  g  
* SDL::Key::H  'h'  h  
* SDL::Key::I  'i'  i  
* SDL::Key::J  'j'  j  
* SDL::Key::K  'k'  k  
* SDL::Key::L  'l'  l  
* SDL::Key::M  'm'  m  
* SDL::Key::N  'n'  n  
* SDL::Key::O  'o'  o  
* SDL::Key::P  'p'  p  
* SDL::Key::Q  'q'  q  
* SDL::Key::R  'r'  r  
* SDL::Key::S  's'  s  
* SDL::Key::T  't'  t  
* SDL::Key::U  'u'  u  
* SDL::Key::V  'v'  v  
* SDL::Key::W  'w'  w  
* SDL::Key::X  'x'  x  
* SDL::Key::Y  'y'  y  
* SDL::Key::Z  'z'  z  
* SDL::Key::DELETE  '^?'  delete  
* SDL::Key::KP0     keypad 0
* SDL::Key::KP1     keypad 1
* SDL::Key::KP2     keypad 2
* SDL::Key::KP3     keypad 3
* SDL::Key::KP4     keypad 4
* SDL::Key::KP5     keypad 5
* SDL::Key::KP6     keypad 6
* SDL::Key::KP7     keypad 7
* SDL::Key::KP8     keypad 8
* SDL::Key::KP9     keypad 9
* SDL::Key::KP_PERIOD  '.'   keypad period
* SDL::Key::KP_DIVIDE  '/'   keypad divide
* SDL::Key::KP_MULTIPLY  '*'   keypad multiply
* SDL::Key::KP_MINUS  '-'   keypad minus
* SDL::Key::KP_PLUS  '+'   keypad plus
* SDL::Key::KP_ENTER  '\r'   keypad enter
* SDL::Key::KP_EQUALS  '='   keypad equals
* SDL::Key::UP     up arrow
* SDL::Key::DOWN     down arrow
* SDL::Key::RIGHT     right arrow
* SDL::Key::LEFT     left arrow
* SDL::Key::INSERT    insert  
* SDL::Key::HOME    home  
* SDL::Key::END    end  
* SDL::Key::PAGEUP    page up  
* SDL::Key::PAGEDOWN    page down  
* SDL::Key::F1    F1  
* SDL::Key::F2    F2  
* SDL::Key::F3    F3  
* SDL::Key::F4    F4  
* SDL::Key::F5    F5  
* SDL::Key::F6    F6  
* SDL::Key::F7    F7  
* SDL::Key::F8    F8  
* SDL::Key::F9    F9  
* SDL::Key::F10    F10  
* SDL::Key::F11    F11  
* SDL::Key::F12    F12  
* SDL::Key::F13    F13  
* SDL::Key::F14    F14  
* SDL::Key::F15    F15  
* SDL::Key::NUMLOCK    numlock  
* SDL::Key::CAPSLOCK    capslock  
* SDL::Key::SCROLLOCK    scrollock  
* SDL::Key::RSHIFT     right shift
* SDL::Key::LSHIFT     left shift
* SDL::Key::RCTRL     right ctrl
* SDL::Key::LCTRL     left ctrl
* SDL::Key::RALT     right alt
* SDL::Key::LALT     left alt
* SDL::Key::RMETA     right meta
* SDL::Key::LMETA     left meta
* SDL::Key::LSUPER     left windows key
* SDL::Key::RSUPER     right windows key
* SDL::Key::MODE     mode shift
* SDL::Key::HELP    help  
* SDL::Key::PRINT    print-screen  
* SDL::Key::SYSREQ    SysRq  
* SDL::Key::BREAK    break  
* SDL::Key::MENU    menu  
* SDL::Key::POWER    power  
* SDL::Key::EURO     euro

== SDL::Mouse
Module for mouse input.

This module defines some mouse constants and module functions.

METHODS(Mouse)
== Methods
%%%
NAME poll
MOD Event
TYPE .
PURPOSE Polls for currently pending events.
RVAL Event/nil

PROTO
poll

DESC
Polls for currently pending events, and returns event object if there
are any pending events, or nil if there are none
available.

If event object is returned, the next event is removed from 
the queue and stored in that area.

EXAMPLE
while event = SDL::Event.poll # Loop until there are no events left on the queue
  case event # Process the appropiate event type
  when SDL::Event::KeyDown # Handle a KEYDOWN event
    puts "Oh! Key press"
  when SDL::Event::MouseMotion
    .
    .
    .
  else # Report an unhandled event
    puts "I don't know what this event is!"
  end
end

SEEALSO
Event
Event.wait

%%
NAME wait
MOD Event
TYPE .
PURPOSE Waits indefinitely for the next available event.
RVAL Event/nil

PROTO
wait

DESC
Waits indefinitely for the next available event and return that event.

If event object is returned, the next event is removed
from the queue and stored in that area.

EXCEPTION
Raise @[Error] if there was an error while waiting
for events.

NOTES
In Ruby 1.9 and above, this method releases the global VM lock (GVL) prior to
calling the underlying SDL_WaitEvent function.  This allows other Ruby threads to
continue executing while waiting for an event.

In Ruby 1.8 and below, there is no way to release the GVL, so all Ruby threads
suspend execution until this method finishes.

This method may return nil when Ruby/SDL encounters an unknown type of event.
You should treat this case.

SEEALSO
Event.poll

%%
NAME push
MOD Event
TYPE .
PURPOSE Pushes an event onto the event queue.

PROTO
push(event)

DESC
Push $[event] onto event queue.

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

EXCEPTION *

SEEALSO
Event.poll

%%
NAME app_state
MOD Event
TYPE .
PURPOSE Get the state of the application.
RVAL UINT

PROTO
app_state
appState

DESC
This method returns the current state of the application. 
The value returned is a bitwise combination of:
:SDL::Event::APPMOUSEFOCUS
  The application has mouse focus. 
:SDL::Event::APPINPUTFOCUS
  The application has keyboard focus.
:SDL::Event::APPACTIVE
  The application is visible.

SEEALSO
Event::Active

%%
NAME enable_unicode
MOD Event
TYPE .
PURPOSE Enable UNICODE translation

PROTO
enable_unicode
enableUNICODE

DESC
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 received key down event, 
@[Event::KeyDown#unicode] will then contain the corresponding character code, 
or zero for keysyms that do not correspond to any character code.

NOTES
Note that only key press events will be translated, not release events.

SEEALSO
Event.disable_unicode
Event.enable_unicode?

%%
NAME disable_unicode
MOD Event
TYPE .
PURPOSE Disable UNICODE translation

PROTO
disable_unicode
disableUNICODE

DESC
Disables Unicode keyboard translation. Please see @[Event.enable_unicode]
in detail.

%%
NAME enable_unicode?
MOD Event
TYPE .
PURPOSE Get whether UNICODE translation is enabled.
RVAL true/false

PROTO
enable_unicode?
enableUNICODE?

DESC
Returns true if Unicode keyboard translation is enabled, otherwise
returns false. Please see @[Event.enable_unicode] in detail.

%%
NAME gain
TYPE #
MOD Event::Active
PURPOSE Returns whether gaining visibility or not
RVAL true/false

PROTO
gain

DESC
Returns true if the mouse enters the window, the application gains keyboard focus, or
minimized/iconcified window is restored.
Otherwise returns false.

SEEALSO
Event::Active
Event::Active#state

%%
NAME state
MOD Event::Active
TYPE #
PURPOSE Gets the type of visibility event.
RVAL SDL::Event::APPMOUSEFOCUS/SDL::Event::APPINPUTFOCUS/SDL::Event::APPACTIVE

PROTO
state

DESC
Returns one of following three constants:
* SDL::Event::APPMOUSEFOCUS

  This event occurs when the mouse leaves or enters the window area.

* SDL::Event::APPINPUTFOCUS

  THis event occurs when the application loses or gains input focus.

* SDL::Event::APPACTIVE

  This event occurs when the application is either minimized/iconcified or restored.

SEEALSO
Event::Active
Event::Active#gain

%%
NAME press
MOD Event::KeyDown
TYPE #
PURPOSE Returns true.
RVAL true

PROTO
press

DESC
Always returns true.

SEEALSO
Event::KeyUp#press

%%
NAME sym
MOD Event::KeyDown
TYPE #
PURPOSE Get the key symbol of pressed key
RVAL Integer

PROTO
sym

DESC
Returns pressed ((<Key symbol>)).

SEEALSO
Event::KeyDown#unicode

%%
NAME mod
MOD Event::KeyDown
TYPE #
PURPOSE Current key modifier
RVAL UINT

PROTO
mod

DESC
Returns the current state of keyboard modifiers as explained in @[Key.mod_state].

SEEALSO
Key.mod_state

%%
NAME unicode
MOD Event::KeyDown
TYPE #
PURPOSE Translated character
RVAL UINT

PROTO
unicode

DESC
Returns the UNICODE character corresponding to the keypress if Unicode translation
is enabled with @[Event.enable_unicode]. 
If the high 9 bits of the character are 0, then this
maps to the equivalent ASCII character:

Returns zero if unicode translation is disabled.

%%
NAME press
MOD Event::KeyUp
TYPE #
PURPOSE Whether key is pressed
RVAL false

PROTO
press

DESC
Always returns false.

SEEALSO
Event::KeyDown#press

%%
NAME sym
MOD Event::KeyUp
TYPE #
PURPOSE Get the key symbol of released key
RVAL Integer

PROTO
sym

DESC
Returns the released ((<Key symbol>))

%%
NAME mod
MOD Event::KeyUp
TYPE #
PURPOSE Current key modifier
RVAL UINT

PROTO
mod

DESC
Returns the current state of keyboard modifiers as explained in @[Key.mod_state].

SEEALSO
Key.mod_state

%%
NAME state
MOD Event::MouseMotion
TYPE #
PURPOSE The current button state
RVAL UINT

PROTO
state

DESC
Returns the current button state.
The value returned is a bitwise combination of:

:SDL::Mouse::BUTTON_LMASK
  Left button
:SDL::Mouse::BUTTON_MMASK
  Middle button
:SDL::Mouse::BUTTON_RMASK
  Right button

SEEALSO
Mouse.state

%%
NAME x
MOD Event::MouseMotion
TYPE #
PURPOSE The X coordinate of the mouse
RVAL UINT

PROTO
x

DESC
Returns the X coordinate of the mouse.

SEEALSO
Mouse.state

%%
NAME y
MOD Event::MouseMotion
TYPE #
PURPOSE the X coordinate of the mouse.
RVAL UINT

PROTO
y

DESC
Returns the Y coordinate of the mouse.

SEEALSO
Mouse.state

%%
NAME xrel
MOD Event::MouseMotion
TYPE #
PURPOSE Relative motion in the X direction
RVAL Integer

PROTO
xrel

DESC
Returns relative motion in the X direction.

%%
NAME yrel
MOD Event::MouseMotion
TYPE #
PURPOSE Relative motion in the Y direction
RVAL Integer

PROTO
yrel

DESC
Returns relative motion in the Y direction.

%%
NAME button
MOD Event::MouseButtonDown
TYPE #
PURPOSE The mouse button index

PROTO
button

DESC
Returns number of the button pressed:
* SDL::Mouse::BUTTON_LEFT
* SDL::Mouse::BUTTON_MIDDLE
* SDL::Mouse::BUTTON_RIGHT

%%
NAME press
MOD Event::MouseButtonDown
TYPE #
PURPOSE Whether mouse button is pressed or not
RVAL true

PROTO
press

DESC
Always returns true.

SEEALSO
Event::MouseButtonUp#press

%%
NAME x
MOD Event::MouseButtonDown
TYPE #
PURPOSE The X coordinate of the mouse at press time.
RVAL UINT

PROTO
x

DESC
Returns the X coordinate of the mouse.

SEEALSO
Mouse.state

%%
NAME y
MOD Event::MouseButtonDown
TYPE #
PURPOSE The Y coordinate of the mouse at press time
RVAL UINT

PROTO
y

DESC
Returns the Y coordinate of the mouse at press time.

SEEALSO
Mouse.state

%%
NAME button
MOD Event::MouseButtonUp
TYPE #
PURPOSE The mouse button index

PROTO
button

DESC
Returns number of the button released:
* SDL::Mouse::BUTTON_LEFT
* SDL::Mouse::BUTTON_MIDDLE
* SDL::Mouse::BUTTON_RIGHT

%%
NAME press
MOD Event::MouseButtonUp
TYPE #
PURPOSE Whether mouse button is pressed or not
RVAL false

PROTO
press

DESC
Always returns false.

SEEALSO
Event::MouseButtonDown#press

%%
NAME x
MOD Event::MouseButtonUp
TYPE #
PURPOSE The X coordinate of the mouse at release time
RVAL UINT

PROTO
x

DESC
Returns the X coordinate of the mouse at release time.

SEEALSO
Mouse.state

%%
NAME y
MOD Event::MouseButtonUp
TYPE #
PURPOSE The Y coordinate of the mouse at release time.
RVAL UINT

PROTO
y

DESC
Returns the Y coordinate of the mouse at release time.

SEEALSO
Mouse.state

%%
NAME which
MOD Event::JoyAxis
TYPE #
PURPOSE Joystick device index
RVAL Integer

PROTO
which

DESC
Returns the index of the joystick that reported the event.

SEEALSO
Joystick
Joystick#num_axes

%%
NAME axis
MOD Event::JoyAxis
TYPE #
PURPOSE JoyAxis axis index
RVAL Integer

PROTO
axis

DESC
Returns the index of the axis that reported the event.

SEEALSO
Joystick

%%
NAME value
MOD Event::JoyAxis
TYPE #
PURPOSE Axis value
RVAL -32767 - 32767

PROTO
value

DESC
Returns the position of the axis in -32767 .. 32767.

SEEALSO
Joystick
Joystick#axis

%%
NAME which
MOD Event::JoyBall
TYPE #
PURPOSE Joystick device index
RVAL Integer

PROTO
which

DESC
Returns the index of the joystick that reported the event.

SEEALSO
Joystick

%%
NAME ball
MOD Event::JoyBall
TYPE #
PURPOSE Joystick trackball index
RVAL Integer

PROTO
ball

DESC
Returns the index of the trackball that reported the event.

SEEALSO
Joystick
Joystick#num_balls

%%
NAME xrel
MOD Event::JoyBall
TYPE #
PURPOSE The relative motion in the X direction
RVAL Integer

PROTO
xrel

DESC
Returns the relative motion in the X direction as Integer.
This value is the change in position on the ball since it was last polled.

SEEALSO
Joystick
Joystick#ball

%%
NAME yrel
MOD Event::JoyBall
TYPE #
PURPOSE The relative motion in the Y direction.

RVAL Integer

PROTO
yrel

DESC
Returns the relative motion in the Y direction as Integer.
This value is the change in position on the ball since it was last polled.

SEEALSO
Joystick
Joystick#ball

%%
NAME which
MOD Event::JoyHat
TYPE #
PURPOSE Joystick device index
RVAL Integer

PROTO
which

DESC
Returns the index of the joystick that reported the event.

SEEALSO
Joystick

%%
NAME hat
MOD Event::JoyHat
TYPE #
PURPOSE Joystick hat index
RVAL Integer

PROTO
hat

DESC
Returns the index of the hat that reported the event.

SEEALSO
Joystick
Joystick#num_hats

%%
NAME value
MOD Event::JoyHat
TYPE #
PURPOSE Hat position
RVAL UINT

PROTO
value

DESC
Returns the current position of the hat. It is a logically OR'd
combination of the following values (whose meanings should be pretty obvious:) :

* SDL::Joystick::HAT_CENTERED
* SDL::Joystick::HAT_UP
* SDL::Joystick::HAT_RIGHT
* SDL::Joystick::HAT_DOWN
* SDL::Joystick::HAT_LEFT

The following defines are also provided:
* SDL::Joystick::HAT_RIGHTUP
* SDL::Joystick::HAT_RIGHTDOWN
* SDL::Joystick::HAT_LEFTUP
* SDL::Joystick::HAT_LEFTDOWN

%%
NAME which
MOD Event::JoyButtonDown
TYPE #
PURPOSE Joystick device index
RVAL Integer

PROTO
which

DESC
Returns the index of the joystick that reported the event.

SEEALSO
Joystick

%%
NAME button
MOD Event::JoyButtonDown
TYPE #
PURPOSE Joystick button index
RVAL Integer

PROTO
button

DESC
Returns the index of the button that reported the event.

SEEALSO
Joystick
Joystick#num_buttons

%%
NAME press
MOD Event::JoyButtonDown
TYPE #
PURPOSE Joystick button is pressed or released
RVAL true

PROTO
press

DESC
Returns whether this event is button press event.
Always returns true.

SEEALSO
Event::JoyButtonUp#press
Joystick#button

%%
NAME which
MOD Event::JoyButtonUp
TYPE #
PURPOSE Joystick device index
RVAL Integer

PROTO
which

DESC
Returns the index of the joystick that reported the event.

SEEALSO
Joystick

%%
NAME button
MOD Event::JoyButtonUp
TYPE #
PURPOSE Joystick button index
RVAL Integer

PROTO
button

DESC
Returns the index of the button that reported the event.

SEEALSO
Joystick
Joystick#num_buttons

%%
NAME press
MOD Event::JoyButtonUp
TYPE #
PURPOSE Joystick button is pressed or released
RVAL false

PROTO
press

DESC
Returns whether this event is button press event.
Always returns false.

SEEALSO
Event::JoyButtonDown#press
Joystick#button

%%
NAME w
MOD Event::VideoResize
TYPE #
PURPOSE New width of the window.
RVAL Integer

PROTO
w

DESC
Returns the new width of the window when window is resized.

%%
NAME h
MOD Event::VideoResize
TYPE #
PURPOSE New height of the window 
RVAL Integer

PROTO
h

DESC
Returns the new width of the window when window is resized.

%%
NAME scan
MOD Key
TYPE .
PURPOSE Get a snapshot of the current keyboard state

PROTO
scan

DESC
Gets a snapshot of the current keyboard state.
You can check this state with @[Key.press?].

NOTE
Call @[Event.poll] or @[Event.wait] to update the state.

SEEALSO
Key.press?
Event::KeyDown
Event::KeyUp
Event.poll

%%
NAME press?
MOD Key
TYPE .
PURPOSE Get the current keyboard state.
RVAL true/false

PROTO
press?(key)

DESC
Returns true if $[key] is pressed, otherwise returns false.
Please use ((<Key symbol>)) as parameter.

SEEALSO
Key.scan
Event::KeyDown
Event::KeyUp

%%
NAME mod_state
MOD Key
TYPE .
PURPOSE Get the state of modifier keys.
RVAL UINT

PROTO
mod_state
modState

DESC
Returns the current state of the modifier keys (CTRL, ALT, etc.).
The return value can be an OR'd combination of:
:SDL::Key::MOD_NONE
:SDL::Key::MOD_LSHIFT
:SDL::Key::MOD_RSHIFT
:SDL::Key::MOD_LCTRL
:SDL::Key::MOD_RCTRL
:SDL::Key::MOD_LALT
:SDL::Key::MOD_RALT
:SDL::Key::MOD_LMETA
:SDL::Key::MOD_RMETA
:SDL::Key::MOD_NUM
:SDL::Key::MOD_CAPS
:SDL::Key::MOD_MODE
 
SDL also defines the following symbols for convenience:
* SDL::Key::MOD_CTRL = SDL::Key::MOD_LCTRL|SDL::Key::MOD_RCTRL
* SDL::Key::MOD_SHIFT = SDL::Key::MOD_LSHIFT|SDL::Key::MOD_RSHIFT
* SDL::Key::MOD_ALT = SDL::Key::MOD_LALT|SDL::Key::MOD_RALT
* SDL::Key::MOD_META = SDL::Key::MOD_LMETA|SDL::Key::MOD_RMETA

SEEALSO
Key.scan

%%
NAME get_key_name
MOD Key
TYPE .
PURPOSE Get the name of an SDL virtual keysym
RVAL String

PROTO
get_key_name(key)
getKeyName(key)

DESC
Returns the SDL-defined name of the $[key] ((<key symbol|Key symbol>)).

%%
NAME enable_key_repeat
MOD Key
TYPE .
PURPOSE Set keyboard repeat rate.

PROTO
enable_key_repeat(delay,interval)
enableKeyRepeat(delay,interval)

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

Good default values are SDL::Key::DEFAULT_REPEAT_DELAY and 
SDL::Key::DEFAULT_REPEAT_INTERVAL.

EXCEPTION *

SEEALSO
Key.disable_key_repeat

%%
NAME disable_key_repeat
MOD Key
TYPE .
PURPOSE Disable key repeat.

PROTO
disable_key_repeat
disableKeyRepeat

DESC
Disables key repeat.

EXCEPTION *

SEEALSO
Key.enable_key_repeat

%%
NAME state
MOD Mouse
TYPE .
PURPOSE Retrieve the current state of the mouse
RVAL [Integer, Integer, true/false, true/false, true/false]
PROTO
state

DESC
Returns an array of five element:
  [ X coordinate, Y coordinate, left button is pressed?, middle button is pressed?, right button is pressed?]

EXAMPLE
x, y, lbutton, * = SDL::Mouse.state
if lbutton
  print "Left Mouse Button is pressed \n"
end

SEEALSO
Event::MouseMotion
Event::MouseButtonDown
Event::MouseButtonUp

%%
NAME warp
MOD Mouse
TYPE .
PURPOSE Set the position of the mouse cursor.

PROTO
warp(x,y)

DESC
Set the position of the mouse cursor (generates a mouse motion event).

SEEALSO
Event::MouseMotion

%%
NAME show
MOD Mouse
TYPE .
PURPOSE Toggle the cursor is shown on the screen.

PROTO
show

DESC
Shows cursor.

The cursor starts off displayed, but can be turned off.

SEEALSO
Mouse.hide
Mouse.show?

%%
NAME hide
MOD Mouse
TYPE .
PURPOSE Hide cursor.

PROTO
hide

DESC
Hide cursor.

SEEALSO
Mouse.show
Mouse.show?

%%
NAME show?
MOD Mouse
TYPE .
PURPOSE Get the state of mouse cursor.
RVAL true/false

PROTO
show?

DESC
Returns true if mouse cursor is shown, otherwise returns false.

SEEALSO
Mouse.show
Mouse.hide

%%
NAME set_cursor
MOD Mouse
TYPE .
PURPOSE Set the currently active mouse cursor.

PROTO
set_cursor(bitmap,white,black,transparent,inverted,hot_x=0,hot_y=0)
setCursor(bitmap,white,black,transparent,inverted,hot_x=0,hot_y=0)

DESC
Sets the currently active cursor to the specified one. If the cursor is currently visible, the change
will be immediately represented on the display.

$[bitmap] is shape of cursor, given by the instance of @[Surface].
$[white] is white color pixel value in $[bitmap], 
$[black] is black color pixel value in $[bitmap], 
$[transparent] is transparent pixel value in $[bitmap], 
$[inverted] is inverted pixel value in $[bitmap].
The cursor width must be a multiple of 8 bits.

SEEALSO
Surface