aboutsummaryrefslogtreecommitdiff
path: root/X11/extensions/XIproto.txt
blob: f9d19f09d35092d54f9242fc68fb5ec6ea529805 (plain)
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
1484
1485
1486
1487
1488
1489
1490
1491
1492
1493
1494
1495
1496
1497
1498
1499
1500
1501
1502
1503
1504
1505
1506
1507
1508
1509
1510
1511
1512
1513
1514
1515
1516
1517
1518
1519
1520
1521
1522
1523
1524
1525
1526
1527
1528
1529
1530
1531
1532
1533
1534
1535
1536
1537
1538
1539
1540
1541
1542
1543
1544
1545
1546
1547
1548
1549
1550
1551
1552
1553
1554
1555
1556
1557
1558
1559
1560
1561
1562
1563
1564
1565
1566
1567
1568
1569
1570
1571
1572
1573
1574
1575
1576
1577
1578
1579
1580
1581
1582
1583
1584
1585
1586
1587
1588
1589
1590
1591
1592
1593
1594
1595
1596
1597
1598
1599
1600
1601
1602
1603
1604
1605
1606
1607
1608
1609
1610
1611
1612
1613
1614
1615
1616
1617
1618
1619
1620
1621
1622
1623
1624
1625
1626
1627
1628
1629
1630
1631
1632
1633
1634
1635
1636
1637
1638
1639
1640
1641
1642
1643
1644
1645
1646
1647
1648
1649
1650
1651
1652
1653
1654
1655
1656
1657
1658
1659
1660
1661
1662
1663
1664
1665
1666
1667
1668
1669
1670
1671
1672
1673
1674
1675
1676
1677
1678
1679
1680
1681
1682
1683
1684
1685
1686
1687
1688
1689
1690
1691
1692
1693
1694
1695
1696
1697
1698
1699
1700
1701
1702
1703
1704
1705
1706
1707
1708
1709
1710
1711
1712
1713
1714
1715
1716
1717
1718
1719
1720
1721
1722
1723
1724
1725
1726
1727
1728
1729
1730
1731
1732
1733
1734
1735
1736
1737
1738
1739
1740
1741
1742
1743
1744
1745
1746
1747
1748
1749
1750
1751
1752
1753
1754
1755
1756
1757
1758
1759
1760
1761
1762
1763
1764
1765
1766
1767
1768
1769
1770
1771
1772
1773
1774
1775
1776
1777
1778
1779
1780
1781
1782
1783
1784
1785
1786
1787
1788
1789
1790
1791
1792
1793
1794
1795
1796
1797
1798
1799
1800
1801
1802
1803
1804
1805
1806
1807
1808
1809
1810
1811
1812
1813
1814
1815
1816
1817
1818
1819
1820
1821
1822
1823
1824
1825
1826
1827
1828
1829
1830
1831
1832
1833
1834
1835
1836
1837
1838
1839
1840
1841
1842
1843
1844
1845
1846
1847
1848
1849
1850
1851
1852
1853
1854
1855
1856
1857
1858
1859
1860
1861
1862
1863
1864
1865
1866
1867
1868
1869
1870
1871
1872
1873
1874
1875
1876
1877
1878
1879
1880
1881
1882
1883
1884
1885
1886
1887
1888
1889
1890
1891
1892
1893
1894
1895
1896
1897
1898
1899
1900
1901
1902
1903
1904
1905
1906
1907
1908
1909
1910
1911
1912
1913
1914
1915
1916
1917
1918
1919
1920
1921
1922
1923
1924
1925
1926
1927
1928
1929
1930
1931
1932
1933
1934
1935
1936
1937
1938
1939
1940
1941
1942
1943
1944
1945
1946
1947
1948
1949
1950
1951
1952
1953
1954
1955
1956
1957
1958
1959
1960
1961
1962
1963
1964
1965
1966
1967
1968
1969
1970
1971
1972
1973
1974
1975
1976
1977
1978
1979
1980
1981
1982
1983
1984
1985
1986
1987
1988
1989
1990
1991
1992
1993
1994
1995
1996
1997
1998
1999
2000
2001
2002
2003
2004
2005
2006
2007
2008
2009
2010
2011
2012
2013
2014
2015
2016
2017
2018
2019
2020
2021
2022
2023
2024
2025
2026
2027
2028
2029
2030
2031
2032
2033
2034
2035
2036
2037
2038
2039
2040
2041
2042
2043
2044
2045
2046
2047
2048
2049
2050
2051
2052
2053
2054
2055
2056
2057
2058
2059
2060
2061
2062
2063
2064
2065
2066
2067
2068
2069
2070
2071
2072
2073
2074
2075
2076
2077
2078
2079
2080
2081
2082
2083
2084
2085
2086
2087
2088
2089
2090
2091
2092
2093
2094
2095
2096
2097
2098
2099
2100
2101
2102
2103
2104
2105
2106
2107
2108
2109
2110
2111
2112
2113
2114
2115
2116
2117
2118
2119
2120
2121
2122
2123
2124
2125
2126
2127
2128
2129
2130
2131
2132
2133
2134
2135
2136
2137
2138
2139
2140
2141
2142
2143
2144
2145
2146
2147
2148
2149
2150
2151
2152
2153
2154
2155
2156
2157
2158
2159
2160
2161
2162
2163
2164
2165
2166
2167
2168
2169
2170
2171
2172
2173
2174
2175
2176
2177
2178
2179
2180
2181
2182
2183
2184
2185
2186
2187
2188
2189
2190
2191
2192
2193
2194
2195
2196
2197
2198
2199
2200
2201
2202
2203
2204
2205
2206
2207
2208
2209
2210
2211
2212
2213
2214
2215
2216
2217
2218
2219
2220
2221
2222
2223
2224
2225
2226
2227
2228
2229
2230
2231
2232
2233
2234
2235
2236
2237
2238
2239
2240
2241
2242
2243
2244
2245
2246
2247
2248
2249
2250
2251
2252
2253
2254
2255
2256
2257
2258
2259
2260
2261
2262
2263
2264
2265
2266
2267
2268
2269
2270
2271
2272
2273
2274
2275
2276
2277
2278
2279
2280
2281
2282
2283
2284
2285
2286
2287
2288
2289
2290
2291
2292
2293
2294
2295
2296
2297
2298
2299
2300
2301
2302
2303
2304
2305
2306
2307
2308
2309
2310
2311
2312
2313
2314
2315
2316
2317
2318
2319
2320
2321
2322
2323
2324
2325
2326
2327
2328
2329
2330
2331
2332
2333
2334
2335
2336
2337
2338
2339
2340
2341
2342
2343
2344
2345
2346
2347
2348
2349
2350
2351
2352
2353
2354
2355
2356
2357
2358
2359
2360
2361
2362
2363
2364
2365
2366
2367
2368
2369
2370
2371
2372
2373
2374
2375
2376
2377
2378
2379
2380
2381
2382
2383
2384
2385
2386
2387
2388
2389
2390
2391
2392
2393
2394
2395
2396
2397
2398
2399
2400
2401
2402
2403
2404
2405
2406
2407
2408
2409
2410
2411
2412
2413
2414
2415
2416
2417
2418
2419
2420
2421
2422
2423
2424
2425
2426
2427
2428
2429
2430
2431
2432
2433
2434
2435
2436
2437
2438
2439
2440
2441
2442
2443
2444
2445
2446
2447
2448
2449
2450
2451
2452
2453
2454
2455
2456
2457
2458
2459
2460
2461
2462
2463
2464
2465
2466
2467
2468
2469
2470
2471
2472
2473
2474
2475
2476
2477
2478
2479
2480
2481
2482
2483
2484
2485
2486
2487
2488
2489
2490
2491
2492
2493
2494
2495
2496
2497
2498
2499
2500
2501
2502
2503
2504
2505
2506
2507
2508
2509
2510
2511
2512
2513
2514
2515
2516
2517
2518
2519
2520
2521
2522
2523
2524
2525
2526
2527
2528
2529
2530
2531
2532
2533
2534
2535
2536
2537
2538
2539
2540
2541
2542
2543
2544
           X11 Input Extension Protocol Specification
                      Version 1.0
                   X Consortium Standard
                 X Version 11, Release 6.8
               Mark Patrick, Ardent Computer
               George Sachs, Hewlett-Packard
               
                      Version 1.5
                    Peter Hutterer

   Copyright © 1989, 1990, 1991 by Hewlett-Packard Company and
   Ardent Computer

   Permission to use, copy, modify, and distribute this
   documentation for any purpose and without fee is hereby
   granted, provided that the above copyright notice and this
   permission notice appear in all copies. Ardent and
   Hewlett-Packard make no representations about the suitability
   for any purpose of the information in this document. It is
   provided "as is" without express or implied warranty. Copyright
   © 1989, 1990, 1991, 1992 X Consortium

   Permission is hereby granted, free of charge, to any person
   obtaining a copy of this software and associated documentation
   files (the “Software”), to deal in the Software without
   restriction, including without limitation the rights to use,
   copy, modify, merge, publish, distribute, sublicense, and/or
   sell copies of the Software, and to permit persons to whom the
   Software is furnished to do so, subject to the following
   conditions:

   The above copyright notice and this permission notice shall be
   included in all copies or substantial portions of the Software.

   THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND,
   EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
   OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
   NONINFRINGEMENT. IN NO EVENT SHALL THE X CONSORTIUM BE LIABLE
   FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
   OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
   CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
   THE SOFTWARE.

   Except as contained in this notice, the name of the X
   Consortium shall not be used in advertising or otherwise to
   promote the sale, use or other dealings in this Software
   without prior written authorization from the X Consortium. X
   Window System is a trademark of The Open Group.

   Copyright © 2008 by Peter Hutterer

   Permission is hereby granted, free of charge, to any person
   obtaining a copy of this software and associated documentation
   files (the "Software"), to deal in the Software without
   restriction, including without limitation the rights to use,
   copy, modify, merge, publish, distribute, sublicense, and/or
   sell copies of the Software, and to permit persons to whom the
   Software is furnished to do so, subject to the following
   conditions:

   The above copyright notice and this permission notice
   (including the next paragraph) shall be included in all copies
   or substantial portions of the Software.

   THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
   EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
   OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
   NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
   HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
   WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
   FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
   OTHER DEALINGS IN THE SOFTWARE.

1. Input Extension Overview

   This document defines an extension to the X11 protocol to
   support input devices other than the core X keyboard and
   pointer. An accompanying document defines a corresponding
   extension to Xlib (similar extensions for languages other than
   C are anticipated). This first section gives an overview of the
   input extension. The next section defines the new protocol
   requests defined by the extension. We conclude with a
   description of the new input events generated by the additional
   input devices.

   This document only describes the behaviour of servers supporting 
   up to the X Input Extension 1.5. For servers supporting the X 
   Input Extensions 2.0, see XI2proto.txt. New clients are discouraged
   from using this protocol specification. Instead, the use of XI 2.x 
   is recommended.

1.1 Design Approach

   The design approach of the extension is to define requests and
   events analogous to the core requests and events. This allows
   extension input devices to be individually distinguishable from
   each other and from the core input devices. These requests and
   events make use of a device identifier and support the
   reporting of n-dimensional motion data as well as other data
   that is not reportable via the core input events.

1.2 Core Input Devices

   The X server core protocol supports two input devices: a
   pointer and a keyboard. The pointer device has two major
   functions. First, it may be used to generate motion information
   that client programs can detect. Second, it may also be used to
   indicate the current location and focus of the X keyboard. To
   accomplish this, the server echoes a cursor at the current
   position of the X pointer. Unless the X keyboard has been
   explicitly focused, this cursor also shows the current location
   and focus of the X keyboard. The X keyboard is used to generate
   input that client programs can detect.

   In servers supporting XI 1.4 and above, the core pointer and
   the core keyboard are virtual devices that do not represent a
   physical device connected to the host computer.
   In servers supporting XI 2.0 and above, there may be multiple 
   core pointers and keyboards. Refer to XI2proto.txt for more 
   information.

   The X keyboard and X pointer are referred to in this document
   as the core devices, and the input events they generate
   (KeyPress, KeyRelease, ButtonPress, ButtonRelease, and
   MotionNotify) are known as the core input events. All other
   input devices are referred to as extension input devices and
   the input events they generate are referred to as extension
   input events.

   In servers supporting only XI 1.x, this input extension does
   not change the behavior or functionality of the core input
   devices, core events, or core protocol requests, with the
   exception of the core grab requests. These requests may affect
   the synchronization of events from extension devices. See the
   explanation in the section titled "Event Synchronization and
   Core Grabs".

   Selection of the physical devices to be initially used by the
   server as the core devices is left implementation-dependent.
   Requests are defined that allow client programs to change which
   physical devices are used as the core devices.

1.3 Extension Input Devices

   The input extension v1.x controls access to input devices other
   than the X keyboard and X pointer. It allows client programs to
   select input from these devices independently from each other
   and independently from the core devices.

   A client that wishes to access a specific device must first
   determine whether that device is connected to the X server.
   This is done through the ListInputDevices request, which will
   return a list of all devices that can be opened by the X
   server. A client can then open one or more of these devices
   using the OpenDevice request, specify what events they are
   interested in receiving, and receive and process input events
   from extension devices in the same way as events from the X
   keyboard and X pointer. Input events from these devices are of
   extension types ( DeviceKeyPress, DeviceKeyRelease,
   DeviceButtonPress, DeviceButtonRelease, DeviceMotionNotify,
   etc.) and contain a device identifier so that events of the
   same type coming from different input devices can be
   distinguished.

   Any kind of input device may be used as an extension input
   device. Extension input devices may have 0 or more keys, 0 or
   more buttons, and may report 0 or more axes of motion. Motion
   may be reported as relative movements from a previous position
   or as an absolute position. All valuators reporting motion
   information for a given extension input device must report the
   same kind of motion information (absolute or relative).

   This extension is designed to accommodate new types of input
   devices that may be added in the future. The protocol requests
   that refer to specific characteristics of input devices
   organize that information by input classes. Server implementors
   may add new classes of input devices without changing the
   protocol requests. Input classes are unique numbers registered
   with the X Consortium. Each extension input device may support
   multiple input classes.

   In XI 1.x, all extension input devices are treated like the
   core X keyboard in determining their location and focus. The
   server does not track the location of these devices on an
   individual basis, and therefore does not echo a cursor to
   indicate their current location. Instead, their location is
   determined by the location of the core X pointer. Like the core
   X keyboard, some may be explicitly focused. If they are not
   explicitly focused, their focus is determined by the location
   of the core X pointer.

   Most input events reported by the server to a client are of
   fixed size (32 bytes). In order to represent the change in
   state of an input device the extension may need to generate a
   sequence of input events. A client side library (such as Xlib)
   will typically take these raw input events and format them into
   a form more convenient to the client.

1.4 Event Classes

   In the core protocol a client registers interest in receiving
   certain input events directed to a window by modifying that
   window's event-mask. Most of the bits in the event mask are
   already used to specify interest in core X events. The input
   extension specifies a different mechanism by which a client can
   express interest in events generated by this extension.

   When a client opens a extension input device via the OpenDevice
   request, an XDevice structure is returned. Macros are provided
   that extract 32-bit numbers called event classes from that
   structure, that a client can use to register interest in
   extension events via the SelectExtensionEvent request. The
   event class combines the desired event type and device id, and
   may be thought of as the equivalent of core event masks.

1.5 Input Classes

   Some of the input extension requests divide input devices into
   classes based on their functionality. This is intended to allow
   new classes of input devices to be defined at a later time
   without changing the semantics of these requests. The following
   input device classes are currently defined:

   KEY
          The device reports key events.

   BUTTON
          The device reports button events.

   VALUATOR
          The device reports valuator data in motion events.

   PROXIMITY
          The device reports proximity events.

   FOCUS
          The device can be focused and reports focus events.

   FEEDBACK
          The device supports feedbacks.

   OTHER
          The ChangeDeviceNotify, DeviceMappingNotify, and
          DeviceStateNotify macros may be invoked passing the
          XDevice structure returned for this device.

   Each extension input device may support multiple input classes.
   Additional classes may be added in the future. Requests that
   support multiple input classes, such as the ListInputDevices
   function that lists all available input devices, organize the
   data they return by input class. Client programs that use these
   requests should not access data unless it matches a class
   defined at the time those clients were compiled. In this way,
   new classes can be added without forcing existing clients that
   use these requests to be recompiled.

2. Requests

   Extension input devices are accessed by client programs through
   the use of new protocol requests. This section summarizes the
   new requests defined by this extension. The syntax and type
   definitions used below follow the notation used for the X11
   core protocol.

2.1 Getting the Extension Version

   The GetExtensionVersion request returns version information
   about the input extension.

                       GetExtensionVersion
                               name: STRING
                       =>
                               present: BOOL
                               protocol-major-version: CARD16
                               protocol-minor-version: CARD16

   The protocol version numbers returned indicate the version of
   the input extension supported by the target X server. The
   version numbers can be compared to constants defined in the
   header file XI.h. Each version is a superset of the previous
   versions.

   The name must be the name of the Input Extension as defined 
   in the header file XI.h.

2.2 Listing Available Devices

   A client that wishes to access a specific device must first
   determine whether that device is connected to the X server.
   This is done through the ListInputDevices request, which will
   return a list of all devices that can be opened by the X
   server.

                   ListInputDevices
                   =>
                   input-devices: ListOfDeviceInfo

   where

                   DEVICEINFO:
                           [type: ATOM
                            id: CARD8
                            num_classes: CARD8
                            use: {IsXKeyboard, IsXPointer, IsXExtensionPointer,
                                  IsXExtensionKeyboard, IsExtensionDevice}
                            info: LISTofINPUTINFO
                            name: STRING8]

                   INPUTINFO: {KEYINFO, BUTTONINFO, VALUATORINFO}
                   KEYINFO:
                           [class: CARD8
                            length: CARD8
                            min-keycode: KEYCODE
                            max-keycode: KEYCODE
                            num-keys: CARD16]
                   BUTTONINFO:
                           [class: CARD8
                            length: CARD8
                            num-buttons: CARD16]
                   VALUATORINFO:
                           [class: CARD8
                            length: CARD8
                            num_axes: CARD8
                            mode: SETofDEVICEMODE
                            motion_buffer_size: CARD32
                            axes: LISTofAXISINFO]

                   AXISINFO:
                           [resolution: CARD32
                            min-val: CARD32
                            max-val: CARD32]
                   DEVICEMODE: {Absolute, Relative}

   Errors: None

   This request returns a list of all devices that can be opened
   by the X server, including the core X keyboard and X pointer.
   Some implementations may open all input devices as part of X
   initialization, while others may not open an input device until
   requested to do so by a client program.

   The information returned for each device is as follows:

   type
          The type field is of type Atom and indicates the nature
          of the device. Clients may determine device types by
          invoking the XInternAtom request passing one of the
          names defined in the header file XI.h. The following
          names have been defined to date:

                                      MOUSE
                                      TABLET
                                      KEYBOARD
                                      TOUCHSCREEN
                                      TOUCHPAD
                                      BUTTONBOX
                                      BARCODE
                                      KNOB_BOX
                                      TRACKBALL
                                      QUADRATURE
                                      SPACEBALL
                                      DATAGLOVE
                                      EYETRACKER
                                      CURSORKEYS
                                      FOOTMOUSE
                                      ID_MODULE
                                      ONE_KNOB
                                      NINE_KNOB
                                      JOYSTICK


   id
          The id is a small cardinal value in the range 0-128 that
          uniquely identifies the device. It is assigned to the
          device when it is initialized by the server. Some
          implementations may not open an input device until
          requested by a client program, and may close the device
          when the last client accessing it requests that it be
          closed. If a device is opened by a client program via
          XOpenDevice, then closed via XCloseDevice, then opened
          again, it is not guaranteed to have the same id after
          the second open request.

   num_classes
          The num_classes field is a small cardinal value in the
          range 0-255 that specifies the number of input classes
          supported by the device for which information is
          returned by ListInputDevices. Some input classes, such
          as class Focus and class Proximity do not have any
          information to be returned by ListInputDevices.

   use
          The use field specifies how the device is currently
          being used. If the value is IsXKeyboard, the device is
          currently being used as the X keyboard. If the value is
          IsXPointer, the device is currently being used as the X
          pointer. If the value is IsXExtensionPointer, the device
          is available for use as an extension pointer. If the value
          is IsXExtensionKeyboard, the device is available for use as
          and extension keyboard.
          Older versions of XI report all extension devices as
          IsXExtensionDevice.

   name
          The name field contains a pointer to a null-terminated
          string that corresponds to one of the defined device
          types.

   InputInfo
          InputInfo is one of: KeyInfo, ButtonInfo or
          ValuatorInfo. The first two fields are common to all
          three:

        class
                The class field is a cardinal value in the range
                0-255. It uniquely identifies the class of input
                for which information is returned.

        length
                The length field is a cardinal value in the range
                0-255. It specifies the number of bytes of data
                that are contained in this input class. The length
                includes the class and length fields.

          The remaining information returned for input class
          KEYCLASS is as follows:

        min_keycode
                min_keycode is of type KEYCODE. It specifies the
                minimum keycode that the device will report. The
                minimum keycode will not be smaller than 8.

        max_keycode
                max_keycode is of type KEYCODE. It specifies the
                maximum keycode that the device will report. The
                maximum keycode will not be larger than 255.

        num_keys
                num_keys is a cardinal value that specifies the
                number of keys that the device has.

          The remaining information returned for input class
          BUTTONCLASS is as follows:

        num_buttons
                num_buttons is a cardinal value that specifies the
                number of buttons that the device has.

          The remaining information returned for input class
          VALUATORCLASS is as follows:

        mode
                mode is a constant that has one of the following
                values: Absolute or Relative. Some devices allow
                the mode to be changed dynamically via the
                SetDeviceMode request.

        motion_buffer_size
                motion_buffer_size is a cardinal number that
                specifies the number of elements that can be
                contained in the motion history buffer for the
                device.

        axes
                The axes field contains a pointer to an AXISINFO
                struture.

          The information returned for each axis reported by the
          device is:

        resolution
                The resolution is a cardinal value in
                counts/meter.

        min_val
                The min_val field is a cardinal value in that
                contains the minimum value the device reports for
                this axis. For devices whose mode is Relative, the
                min_val field will contain 0.

        max_val
                The max_val field is a cardinal value in that
                contains the maximum value the device reports for
                this axis. For devices whose mode is Relative, the
                max_val field will contain 0.

2.3 Enabling Devices

   Client programs that wish to access an extension device must
   request that the server open that device. This is done via the
   OpenDevice request.

                   OpenDevice
                           id: CARD8
                   =>
                   DEVICE:
                           [device_id: XID
                            num_classes: INT32
                            classes: LISTofINPUTCLASSINFO]
                   INPUTCLASSINFO:
                            [input_class: CARD8
                            event_type_base: CARD8]

   Errors: Device

   This request returns the event classes to be used by the client
   to indicate which events the client program wishes to receive.
   Each input class may report several event classes. For example,
   input class Keys reports DeviceKeyPress and DeviceKeyRelease
   event classes. Input classes are unique numbers registered with
   the X Consortium. Input class Other exists to report event
   classes that are not specific to any one input class, such as
   DeviceMappingNotify, ChangeDeviceNotify, and DeviceStateNotify.

   The information returned for each device is as follows:

   device_id
          The device_id is a number that uniquely identifies the
          device.

   num_classes
          The num_classes field contains the number of input
          classes supported by this device.

   For each class of input supported by the device, the
   InputClassInfo structure contains the following information:

   input_class
          The input_class is a small cardinal number that
          identifies the class of input.

   event_type_base
          The event_type_base is a small cardinal number that
          specifies the event type of one of the events reported
          by this input class. This information is not directly
          used by client programs. Instead, the Device is used by
          macros that return extension event types and event
          classes. This is described in the section of this
          document entitled "Selecting Extension Device Events".

   The information in the InputClassInfo reflects the state of
   this device at the time the request was processed.

   Before it exits, the client program should explicitly request
   that the server close the device. This is done via the
   CloseDevice request.

   A client may open the same extension device more than once.
   Requests after the first successful one return an additional
   XDevice structure with the same information as the first, but
   otherwise have no effect. A single CloseDevice request will
   terminate that client's access to the device.

   Closing a device releases any active or passive grabs the
   requesting client has established. If the device is frozen only
   by an active grab of the requesting client, the queued events
   are released when the client terminates.

   If a client program terminates without closing a device, the
   server will automatically close that device on behalf of the
   client. This does not affect any other clients that may be
   accessing that device.

                       CloseDevice:
                               device: DEVICE

   Errors: Device

2.4 Changing The Mode Of A Device

   Some devices are capable of reporting either relative or
   absolute motion data. To change the mode of a device from
   relative to absolute, use the SetDeviceMode request. The valid
   values are Absolute or Relative.

   This request will fail and return DeviceBusy if another client
   already has the device open with a different mode. It will fail
   and return AlreadyGrabbed if another client has the device
   grabbed. The request will fail with a BadMatch error if the
   device has no valuators and reports no axes of motion. The
   request will fail with a BadMode error if the requested mode
   is not supported by the device.

                       SetDeviceMode
                               device:DEVICE
                               mode: {Absolute, Relative}
                       =>
                               status: {Success, DeviceBusy, AlreadyGrabbed}

   Errors: Device, Match, Mode

2.5 Initializing Valuators on an Input Device

   Some devices that report absolute positional data can be
   initialized to a starting value. Devices that are capable of
   reporting relative motion or absolute positional data may
   require that their valuators be initialized to a starting value
   after the mode of the device is changed to Absolute. To
   initialize the valuators on such a device, use the
   SetDeviceValuators request.

                   SetDeviceValuators
                           device: DEVICE
                           first_valuator: CARD8
                           num_valuators: CARD8
                           valuators: LISTOFINT32
                   =>
                           status: {Success, AlreadyGrabbed}

   Errors: Length, Device, Match, Value

   This request initializes the specified valuators on the
   specified extension input device. Valuators are numbered
   beginning with zero. Only the valuators in the range specified
   by first_valuator and num_valuators are set. If the number of
   valuators supported by the device is less than the expression
   first_valuator + num_valuators, a Value error will result.

   If the request succeeds, Success is returned. If the specifed
   device is grabbed by some other client, the request will fail
   and a status of AlreadyGrabbed will be returned.

2.6 Getting Input Device Controls

                   GetDeviceControl
                           device: DEVICE
                           control: XID
                   =>
                   controlState: {DeviceState}

   where

                   DeviceState: DeviceResolutionState

   Errors: Length, Device, Match, Value

   This request returns the current state of the specified device
   control. The device control must be supported by the target
   server and device or an error will result.

   If the request is successful, a pointer to a generic
   DeviceState structure will be returned. The information
   returned varies according to the specified control and is
   mapped by a structure appropriate for that control.

   GetDeviceControl will fail with a BadValue error if the server
   does not support the specified control. It will fail with a
   BadMatch error if the device does not support the specified
   control.

   Supported device controls and the information returned for them
   include:

                   DEVICE_RESOLUTION:
                       [control: CARD16
                       length: CARD16
                       num_valuators: CARD8
                       resolutions: LISTofCARD32
                       min_resolutions: LISTofCARD32
                       max_resolutions: LISTofCARD32]

   This device control returns a list of valuators and the range
   of valid resolutions allowed for each. Valuators are numbered
   beginning with 0. Resolutions for all valuators on the device
   are returned. For each valuator i on the device, resolutions[i]
   returns the current setting of the resolution,
   min_resolutions[i] returns the minimum valid setting, and
   max_resolutions[i] returns the maximum valid setting.

   When this control is specified, XGetDeviceControl will fail
   with a BadMatch error if the specified device has no valuators.

                   ChangeDeviceControl:
                           device: DEVICE
                           XID: controlId
                           control: DeviceControl

   where

                   DeviceControl: DeviceResolutionControl
                   =>
                           status: {Success, DeviceBusy, AlreadyGrabbed}

   Errors: Length, Device, Match, Value

   ChangeDeviceControl changes the specifed device control
   according to the values specified in the DeviceControl
   structure. The device control must be supported by the target
   server and device or an error will result.

   The information passed with this request varies according to
   the specified control and is mapped by a structure appropriate
   for that control.

   ChangeDeviceControl will fail with a BadValue error if the
   server does not support the specified control. It will fail
   with a BadMatch error if the server supports the specified
   control, but the requested device does not. The request will
   fail and return a status of DeviceBusy if another client
   already has the device open with a device control state that
   conflicts with the one specified in the request. It will fail
   with a status of AlreadyGrabbed if some other client has
   grabbed the specified device. If the request succeeds, Success
   is returned. If it fails, the device control is left unchanged.

   Supported device controls and the information specified for
   them include:

                   DEVICE_RESOLUTION:
                           [control: CARD16
                            length: CARD16
                            first_valuator: CARD8
                            num_valuators: CARD8
                            resolutions: LISTofCARD32]

   This device control changes the resolution of the specified
   valuators on the specified extension input device. Valuators
   are numbered beginning with zero. Only the valuators in the
   range specified by first_valuator and num_valuators are set. A
   value of -1 in the resolutions list indicates that the
   resolution for this valuator is not to be changed.
   num_valuators specifies the number of valuators in the
   resolutions list.

   When this control is specified, XChangeDeviceControl will fail
   with a BadMatch error if the specified device has no valuators.
   If a resolution is specified that is not within the range of
   valid values (as returned by XGetDeviceControl) the request
   will fail with a BadValue error. If the number of valuators
   supported by the device is less than the expression
   first_valuator + num_valuators, a BadValue error will result.

   If the request fails for any reason, none of the valuator
   resolutions will be changed.

   ChangeDeviceControl causes the server to send a DevicePresence
   event to interested clients.

2.7 Selecting Extension Device Events

   Extension input events are selected using the
   SelectExtensionEvent request.

                   SelectExtensionEvent
                           interest: LISTofEVENTCLASS
                           window: WINDOW

   Errors: Window, Class, Access

   This request specifies to the server the events within the
   specified window which are of interest to the client. As with
   the core XSelectInput function, multiple clients can select
   input on the same window.

   XSelectExtensionEvent requires a list of event classes. An
   event class is a 32-bit number that combines an event type and
   device id, and is used to indicate which event a client wishes
   to receive and from which device it wishes to receive it.
   Macros are provided to obtain event classes from the data
   returned by the XOpenDevice request. The names of these macros
   correspond to the desired events, i.e. the DeviceKeyPress is
   used to obtain the event class for DeviceKeyPress events. The
   syntax of the macro invocation is:
                    DeviceKeyPress (device, event_type, event_class);
                        device: DEVICE
                        event_type: INT
                        event_class: INT

   The value returned in event_type is the value that will be
   contained in the event type field of the XDeviceKeyPressEvent
   when it is received by the client. The value returned in
   event_class is the value that should be passed in making an
   XSelectExtensionEvent request to receive DeviceKeyPress events.

   For DeviceButtonPress events, the client may specify whether or
   not an implicit passive grab should be done when the button is
   pressed. If the client wants to guarantee that it will receive
   a DeviceButtonRelease event for each DeviceButtonPress event it
   receives, it should specify the DeviceButtonPressGrab event
   class as well as the DeviceButtonPress event class. This
   restricts the client in that only one client at a time may
   request DeviceButtonPress events from the same device and
   window if any client specifies this class.

   If any client has specified the DeviceButtonPressGrab class,
   any requests by any other client that specify the same device
   and window and specify DeviceButtonPress or
   DeviceButtonPressGrab will cause an Access error to be
   generated.

   If only the DeviceButtonPress class is specified, no implicit
   passive grab will be done when a button is pressed on the
   device. Multiple clients may use this class to specify the same
   device and window combination.

   A client may also specify the DeviceOwnerGrabButton class. If
   it has specified both the DeviceButtonPressGrab and the
   DeviceOwnerGrabButton classes, implicit passive grabs will
   activate with owner_events set to True. If only the
   DeviceButtonPressGrab class is specified, implicit passive
   grabs will activate with owner_events set to False.

   The client may select DeviceMotion events only when a button is
   down. It does this by specifying the event classes
   Button1Motion through Button5Motion, or ButtonMotion. An input
   device will only support as many button motion classes as it
   has buttons.

2.8 Determining Selected Events

   To determine which extension events are currently selected from
   a given window, use GetSelectedExtensionEvents.

                   GetSelectedExtensionEvents
                           window: WINDOW
                   =>
                           this-client: LISTofEVENTCLASS
                           all-clients: LISTofEVENTCLASS

   Errors: Window

   This request returns two lists specifying the events selected
   on the specified window. One list gives the extension events
   selected by this client from the specified window. The other
   list gives the extension events selected by all clients from
   the specified window. This information is equivalent to that
   returned by your-event-mask and all-event-masks in a
   GetWindowAttributes request.

2.9 Controlling Event Propagation

   Extension events propagate up the window hierarchy in the same
   manner as core events. If a window is not interested in an
   extension event, it usually propagates to the closest ancestor
   that is interested, unless the dont_propagate list prohibits
   it. Grabs of extension devices may alter the set of windows
   that receive a particular extension event.

   Client programs may control extension event propagation through
   the use of the following two requests.

   XChangeDeviceDontPropagateList adds an event to or deletes an
   event from the do_not_propagate list of extension events for
   the specified window. This list is maintained for the life of
   the window, and is not altered if the client terminates.

                   ChangeDeviceDontPropagateList
                           window: WINDOW
                           eventclass: LISTofEVENTCLASS
                           mode: {AddToList, DeleteFromList}

   Errors: Window, Class, Mode

   This function modifies the list specifying the events that are
   not propagated to the ancestors of the specified window. You
   may use the modes AddToList or DeleteFromList.

                   GetDeviceDontPropagateList
                           window: WINDOW
                           Errors: Window
                   =>
                           dont-propagate-list: LISTofEVENTCLASS

   This function returns a list specifying the events that are not
   propagated to the ancestors of the specified window.

2.10 Sending Extension Events

   One client program may send an event to another via the
   XSendExtensionEvent function.

   The event in the XEvent structure must be one of the events
   defined by the input extension, so that the X server can
   correctly byte swap the contents as necessary. The contents of
   the event are otherwise unaltered and unchecked by the X server
   except to force send_event to True in the forwarded event and
   to set the sequence number in the event correctly.

   XSendExtensionEvent returns zero if the conversion-to-wire
   protocol failed, otherwise it returns nonzero.

                   SendExtensionEvent
                           device: DEVICE
                           destination: WINDOW
                           propagate: BOOL
                           eventclass: LISTofEVENTCLASS
                           event: XEVENT

   Errors: Device, Value, Class, Window

2.11 Getting Motion History

                   GetDeviceMotionEvents
                           device: DEVICE
                           start, stop: TIMESTAMP or CurrentTime
                   =>
                           nevents_return: CARD32
                           mode_return: {Absolute, Relative}
                           axis_count_return: CARD8
                           events: LISTofDEVICETIMECOORD

   where

                   DEVICETIMECOORD:
                           [data: LISTofINT32
                            time: TIMESTAMP]

   Errors: Device, Match

   This request returns all positions in the device's motion
   history buffer that fall between the specified start and stop
   times inclusive. If the start time is in the future, or is
   later than the stop time, no positions are returned.

   The data field of the DEVICETIMECOORD structure is a sequence
   of data items. Each item is of type INT32, and there is one
   data item per axis of motion reported by the device. The number
   of axes reported by the device is returned in the axis_count
   variable.

   The value of the data items depends on the mode of the device,
   which is returned in the mode variable. If the mode is
   Absolute, the data items are the raw values generated by the
   device. These may be scaled by the client program using the
   maximum values that the device can generate for each axis of
   motion that it reports. The maximum and minimum values for each
   axis are reported by the ListInputDevices request.

   If the mode is Relative, the data items are the relative values
   generated by the device. The client program must choose an
   initial position for the device and maintain a current position
   by accumulating these relative values.

2.12 Changing The Core Devices

   These requests are provided to change which physical device is
   used as the X pointer or X keyboard. These requests are
   deprecated in servers supporting XI 1.4 and above, and will
   always return a a BadDevice error.

   Using these requests may change the characteristics of the core
   devices. The new pointer device may have a different number of
   buttons than the old one did, or the new keyboard device may
   have a different number of keys or report a different range of
   keycodes. Client programs may be running that depend on those
   characteristics. For example, a client program could allocate
   an array based on the number of buttons on the pointer device,
   and then use the button numbers received in button events as
   indicies into that array. Changing the core devices could cause
   such client programs to behave improperly or abnormally
   terminate.

   These requests change the X keyboard or X pointer device and
   generate an ChangeDeviceNotify event and a MappingNotify event.
   The ChangeDeviceNotify event is sent only to those clients that
   have expressed an interest in receiving that event via the
   XSelectExtensionEvent request. The specified device becomes the
   new X keyboard or X pointer device. The location of the core
   device does not change as a result of this request.

   These requests fail and return AlreadyGrabbed if either the
   specified device or the core device it would replace are
   grabbed by some other client. They fail and return GrabFrozen
   if either device is frozen by the active grab of another
   client.

   These requests fail with a BadDevice error if the specified
   device is invalid, or has not previously been opened via
   OpenDevice. To change the X keyboard device, use the
   ChangeKeyboardDevice request. The specified device must support
   input class Keys (as reported in the ListInputDevices request)
   or the request will fail with a BadMatch error. Once the device
   has successfully replaced one of the core devices, it is
   treated as a core device until it is in turn replaced by
   another ChangeDevice request, or until the server terminates.
   The termination of the client that changed the device will not
   cause it to change back. Attempts to use the CloseDevice
   request to close the new core device will fail with a BadDevice
   error.

   The focus state of the new keyboard is the same as the focus
   state of the old X keyboard. If the new keyboard was not
   initialized with a FocusRec, one is added by the
   ChangeKeyboardDevice request. The X keyboard is assumed to have
   a KbdFeedbackClassRec. If the device was initialized without a
   KbdFeedbackClassRec, one will be added by this request. The
   KbdFeedbackClassRec will specify a null routine as the control
   procedure and the bell procedure.

                   ChangeKeyboardDevice
                           device: DEVICE
                           Errors: Device, Match
                   =>
                           status: Success, AlreadyGrabbed, Frozen

   To change the X pointer device, use the ChangePointerDevice
   request. The specified device must support input class
   Valuators (as reported in the ListInputDevices request) or the
   request will fail with a BadMatch error. The valuators to be
   used as the x- and y-axes of the pointer device must be
   specified. Data from other valuators on the device will be
   ignored.

   The X pointer device does not contain a FocusRec. If the new
   pointer was initialized with a FocusRec, it is freed by the
   ChangePointerDevice request. The X pointer is assumed to have a
   ButtonClassRec and a PtrFeedbackClassRec. If the device was
   initialized without a ButtonClassRec or a PtrFeedbackClassRec,
   one will be added by this request. The ButtonClassRec added
   will have no buttons, and the PtrFeedbackClassRec will specify
   a null routine as the control procedure.

   If the specified device reports absolute positional
   information, and the server implementation does not allow such
   a device to be used as the X pointer, the request will fail
   with a BadDevice error.

   Once the device has successfully replaced one of the core
   devices, it is treated as a core device until it is in turn
   replaced by another ChangeDevice request, or until the server
   terminates. The termination of the client that changed the
   device will not cause it to change back. Attempts to use the
   CloseDevice request to close the new core device will fail with
   a BadDevice error.

                   ChangePointerDevice
                           device: DEVICE
                           xaxis: CARD8
                           yaxis: CARD8
                   =>
                           status: Success, AlreadyGrabbed, Frozen

   Errors: Device, Match

2.12 Event Synchronization And Core Grabs

   Implementation of the input extension requires an extension of
   the meaning of event synchronization for the core grab
   requests. This is necessary in order to allow window managers
   to freeze all input devices with a single request.

   The core grab requests require a pointer_mode and keyboard_mode
   argument. The meaning of these modes is changed by the input
   extension. For the XGrabPointer and XGrabButton requests,
   pointer_mode controls synchronization of the pointer device,
   and keyboard_mode controls the synchronization of all other
   input devices. For the XGrabKeyboard and XGrabKey requests,
   pointer_mode controls the synchronization of all input devices
   except the X keyboard, while keyboard_mode controls the
   synchronization of the keyboard. When using one of the core
   grab requests, the synchronization of extension devices is
   controlled by the mode specified for the device not being
   grabbed.

2.13 Extension Active Grabs

   Active grabs of extension devices are supported via the
   GrabDevice request in the same way that core devices are
   grabbed using the core GrabKeyboard request, except that a
   Device is passed as a function parameter. A list of events that
   the client wishes to receive is also passed. The UngrabDevice
   request allows a previous active grab for an extension device
   to be released.

   To grab an extension device, use the GrabDevice request. The
   device must have previously been opened using the OpenDevice
   request.

                   GrabDevice
                           device: DEVICE
                           grab-window: WINDOW
                           owner-events: BOOL
                           event-list: LISTofEVENTCLASS
                           this-device-mode: {Synchronous, Asynchronous}
                           other-device-mode: {Synchronous, Asynchronous}
                           time:TIMESTAMP or CurrentTime
                   =>
                           status: Success, AlreadyGrabbed, Frozen,
                                   InvalidTime, NotViewable

   Errors: Device, Window, Value

   This request actively grabs control of the specified input
   device. Further input events from this device are reported only
   to the grabbing client. This request overrides any previous
   active grab by this client for this device.

   The event-list parameter is a pointer to a list of event
   classes. These are used to indicate which events the client
   wishes to receive while the device is grabbed. Only event
   classes obtained from the grabbed device are valid.

   If owner-events is False, input events generated from this
   device are reported with respect to grab-window, and are only
   reported if selected by being included in the event-list. If
   owner-events is True, then if a generated event would normally
   be reported to this client, it is reported normally, otherwise
   the event is reported with respect to the grab-window, and is
   only reported if selected by being included in the event-list.
   For either value of owner-events, unreported events are
   discarded.

   If this-device-mode is Asynchronous, device event processing
   continues normally. If the device is currently frozen by this
   client, then processing of device events is resumed. If
   this-device-mode is Synchronous, the state of the grabbed
   device (as seen by means of the protocol) appears to freeze,
   and no further device events are generated by the server until
   the grabbing client issues a releasing AllowDeviceEvents
   request or until the device grab is released. Actual device
   input events are not lost while the device is frozen; they are
   simply queued for later processing.

   If other-device-mode is Asynchronous, event processing is
   unaffected by activation of the grab. If other-device-mode is
   Synchronous, the state of all input devices except the grabbed
   one (as seen by means of the protocol) appears to freeze, and
   no further events are generated by the server until the
   grabbing client issues a releasing AllowDeviceEvents request or
   until the device grab is released. Actual events are not lost
   while the devices are frozen; they are simply queued for later
   processing.

   This request generates DeviceFocusIn and DeviceFocusOut events.

   This request fails and returns:

   AlreadyGrabbed
          If the device is actively grabbed by some other client.

   NotViewable
          If grab-window is not viewable.

   InvalidTime
          If the specified time is earlier than the last-grab-time
          for the specified device or later than the current X
          server time. Otherwise, the last-grab-time for the
          specified device is set to the specified time and
          CurrentTime is replaced by the current X server time.

   Frozen
          If the device is frozen by an active grab of another
          client.

   If a grabbed device is closed by a client while an active grab
   by that client is in effect, that active grab will be released.
   Any passive grabs established by that client will be released.
   If the device is frozen only by an active grab of the
   requesting client, it is thawed.

   To release a grab of an extension device, use UngrabDevice.

                   UngrabDevice
                           device: DEVICE
                           time: TIMESTAMP or CurrentTime

   Errors: Device

   This request releases the device if this client has it actively
   grabbed (from either GrabDevice or GrabDeviceKey) and releases
   any queued events. If any devices were frozen by the grab,
   UngrabDevice thaws them. The request has no effect if the
   specified time is earlier than the last-device-grab time or is
   later than the current server time.

   This request generates DeviceFocusIn and DeviceFocusOut events.

   An UngrabDevice is performed automatically if the event window
   for an active device grab becomes not viewable.

2.14 Passively Grabbing A Key

   Passive grabs of buttons and keys on extension devices are
   supported via the GrabDeviceButton and GrabDeviceKey requests.
   These passive grabs are released via the UngrabDeviceKey and
   UngrabDeviceButton requests.

   To passively grab a single key on an extension device, use
   GrabDeviceKey. That device must have previously been opened
   using the OpenDevice request.

                   GrabDeviceKey
                           device: DEVICE
                           keycode: KEYCODE or AnyKey
                           modifiers: SETofKEYMASK or AnyModifier
                           modifier-device: DEVICE or NULL
                           grab-window: WINDOW
                           owner-events: BOOL
                           event-list: LISTofEVENTCLASS
                           this-device-mode: {Synchronous, Asynchronous}
                           other-device-mode: {Synchronous, Asynchronous}

   Errors: Device, Match, Access, Window, Value

   This request is analogous to the core GrabKey request. It
   establishes a passive grab on a device. Consequently, in the
   future:
     * IF the device is not grabbed and the specified key, which
       itself can be a modifier key, is logically pressed when the
       specified modifier keys logically are down on the specified
       modifier device (and no other keys are down),
     * AND no other modifier keys logically are down,
     * AND EITHER the grab window is an ancestor of (or is) the
       focus window OR the grab window is a descendent of the
       focus window and contains the pointer,
     * AND a passive grab on the same device and key combination
       does not exist on any ancestor of the grab window,
     * THEN the device is actively grabbed, as for GrabDevice, the
       last-device-grab time is set to the time at which the key
       was pressed (as transmitted in the DeviceKeyPress event),
       and the DeviceKeyPress event is reported.

   The interpretation of the remaining arguments is as for
   GrabDevice. The active grab is terminated automatically when
   logical state of the device has the specified key released
   (independent of the logical state of the modifier keys).

   Note that the logical state of a device (as seen by means of
   the X protocol) may lag the physical state if device event
   processing is frozen.

   A modifier of AnyModifier is equivalent to issuing the request
   for all possible modifier combinations (including the
   combination of no modifiers). It is not required that all
   modifiers specified have currently assigned keycodes. A key of
   AnyKey is equivalent to issuing the request for all possible
   keycodes. Otherwise, the key must be in the range specified by
   min-keycode and max-keycode in the ListInputDevices request. If
   it is not within that range, GrabDeviceKey generates a Value
   error.

   NULL may be passed for the modifier_device. If the
   modifier_device is NULL, the core X keyboard is used as the
   modifier_device.

   An Access error is generated if some other client has issued a
   GrabDeviceKey with the same device and key combination on the
   same window. When using AnyModifier or AnyKey, the request
   fails completely and the X server generates a Access error and
   no grabs are established if there is a conflicting grab for any
   combination.

   This request cannot be used to grab a key on the X keyboard
   device. The core GrabKey request should be used for that
   purpose.

   To release a passive grab of a single key on an extension
   device, use UngrabDeviceKey.

                   UngrabDeviceKey
                           device: DEVICE
                           keycode: KEYCODE or AnyKey
                           modifiers: SETofKEYMASK or AnyModifier
                           modifier-device: DEVICE or NULL
                           grab-window: WINDOW

   Errors: Device, Match, Window, Value, Alloc

   This request is analogous to the core UngrabKey request. It
   releases the key combination on the specified window if it was
   grabbed by this client. A modifier of AnyModifier is equivalent
   to issuing the request for all possible modifier combinations
   (including the combination of no modifiers). A key of AnyKey is
   equivalent to issuing the request for all possible keycodes.
   This request has no effect on an active grab.

   NULL may be passed for the modifier_device. If the
   modifier_device is NULL, the core X keyboard is used as the
   modifier_device.

2.15 Passively Grabbing A Button

   To establish a passive grab for a single button on an extension
   device, use GrabDeviceButton.

                   GrabDeviceButton
                           device: DEVICE
                           button: BUTTON or AnyButton
                           modifiers: SETofKEYMASK or AnyModifier
                           modifier-device: DEVICE or NULL
                           grab-window: WINDOW
                           owner-events: BOOL
                           event-list: LISTofEVENTCLASS
                           this-device-mode: {Synchronous, Asynchr
   onous}
                           other-device-mode: {Synchronous, Asynch
   ronous}

   Errors: Device, Match, Window, Access, Value

   This request is analogous to the core GrabButton request. It
   establishes an explicit passive grab for a button on an
   extension input device. Since the server does not track
   extension devices, no cursor is specified with this request.
   For the same reason, there is no confine-to parameter. The
   device must have previously been opened using the OpenDevice
   request.

   The GrabDeviceButton request establishes a passive grab on a
   device. Consequently, in the future,

   •
          IF the device is not grabbed and the specified button is
          logically pressed when the specified modifier keys
          logically are down (and no other buttons or modifier
          keys are down),

   •
          AND the grab window contains the device,

   •
          AND a passive grab on the same device and button/ key
          combination does not exist on any ancestor of the grab
          window,

   •
          THEN the device is actively grabbed, as for GrabDevice,
          the last-grab time is set to the time at which the
          button was pressed (as transmitted in the
          DeviceButtonPress event), and the DeviceButtonPress
          event is reported.

   The interpretation of the remaining arguments is as for
   GrabDevice. The active grab is terminated automatically when
   logical state of the device has all buttons released
   (independent of the logical state of the modifier keys).

   Note that the logical state of a device (as seen by means of
   the X protocol) may lag the physical state if device event
   processing is frozen.

   A modifier of AnyModifier is equivalent to issuing the request
   for all possible modifier combinations (including the
   combination of no modifiers). It is not required that all
   modifiers specified have currently assigned keycodes. A button
   of AnyButton is equivalent to issuing the request for all
   possible buttons. It is not required that the specified button
   be assigned to a physical button.

   NULL may be passed for the modifier_device. If the
   modifier_device is NULL, the core X keyboard is used as the
   modifier_device.

   An Access error is generated if some other client has issued a
   GrabDeviceButton with the same device and button combination on
   the same window. When using AnyModifier or AnyButton, the
   request fails completely and the X server generates a Access
   error and no grabs are established if there is a conflicting
   grab for any combination. The request has no effect on an
   active grab.

   This request cannot be used to grab a button on the X pointer
   device. The core GrabButton request should be used for that
   purpose.

   To release a passive grab of a button on an extension device,
   use UngrabDeviceButton.

                   UngrabDeviceButton
                           device: DEVICE
                           button: BUTTON or AnyButton
                           modifiers: SETofKEYMASK or AnyModifier
                           modifier-device: DEVICE or NULL
                           grab-window: WINDOW

   Errors: Device, Match, Window, Value, Alloc

   This request is analogous to the core UngrabButton request. It
   releases the passive button/key combination on the specified
   window if it was grabbed by the client. A modifiers of
   AnyModifier is equivalent to issuing the request for all
   possible modifier combinations (including the combination of no
   modifiers). A button of AnyButton is equivalent to issuing the
   request for all possible buttons. This request has no effect on
   an active grab. The device must have previously been opened
   using the OpenDevice request otherwise a Device error will be
   generated.

   NULL may be passed for the modifier_device. If the
   modifier_device is NULL, the core X keyboard is used as the
   modifier_device.

   This request cannot be used to ungrab a button on the X pointer
   device. The core UngrabButton request should be used for that
   purpose.

2.16 Thawing A Device

   To allow further events to be processed when a device has been
   frozen, use AllowDeviceEvents.

                   AllowDeviceEvents
                           device: DEVICE
                           event-mode: {AsyncThisDevice, SyncThisD
   evice, AsyncOtherDevices,
                           ReplayThisdevice, AsyncAll, or SyncAll}
                           time:TIMESTAMP or CurrentTime

   Errors: Device, Value

   The AllowDeviceEvents request releases some queued events if
   the client has caused a device to freeze. The request has no
   effect if the specified time is earlier than the last-grab time
   of the most recent active grab for the client, or if the
   specified time is later than the current X server time.

   The following describes the processing that occurs depending on
   what constant you pass to the event-mode argument:

   * If the specified device is frozen by the client, event
     processing for that device continues as usual. If the
     device is frozen multiple times by the client on behalf
     of multiple separate grabs, AsyncThisDevice thaws for
     all. AsyncThisDevice has no effect if the specified
     device is not frozen by the client, but the device need
     not be grabbed by the client.

   * If the specified device is frozen and actively grabbed
     by the client, event processing for that device
     continues normally until the next button or key event is
     reported to the client. At this time, the specified
     device again appears to freeze. However, if the reported
     event causes the grab to be released, the specified
     device does not freeze. SyncThisDevice has no effect if
     the specified device is not frozen by the client or is
     not grabbed by the client.

   * If the specified device is actively grabbed by the
     client and is frozen as the result of an event having
     been sent to the client (either from the activation of a
     GrabDeviceButton or from a previous AllowDeviceEvents
     with mode SyncThisDevice, but not from a Grab), the grab
     is released and that event is completely reprocessed.
     This time, however, the request ignores any passive
     grabs at or above (towards the root) the grab-window of
     the grab just released. The request has no effect if the
     specified device is not grabbed by the client or if it
     is not frozen as the result of an event.

   * If the remaining devices are frozen by the client, event
     processing for them continues as usual. If the other
     devices are frozen multiple times by the client on
     behalf of multiple separate grabs, AsyncOtherDevices
     “thaws” for all. AsyncOtherDevices has no effect if the
     devices are not frozen by the client, but those devices
     need not be grabbed by the client.

   * If all devices are frozen by the client, event
     processing (for all devices) continues normally until
     the next button or key event is reported to the client
     for a grabbed device (button event for the grabbed
     device, key or motion event for the device), at which
     time the devices again appear to freeze. However, if the
     reported event causes the grab to be released, then the
     devices do not freeze (but if any device is still
     grabbed, then a subsequent event for it will still cause
     all devices to freeze). SyncAll has no effect unless all
     devices are frozen by the client. If any device is
     frozen twice by the client on behalf of two separate
     grabs, SyncAll "thaws" for both (but a subsequent freeze
     for SyncAll will only freeze each device once).

   * If all devices are frozen by the client, event
     processing (for all devices) continues normally. If any
     device is frozen multiple times by the client on behalf
     of multiple separate grabs, AsyncAll "thaws" for all.
     AsyncAll has no effect unless all devices are frozen by
     the client.

     AsyncThisDevice, SyncThisDevice, and ReplayThisDevice
     have no effect on the processing of events from the
     remaining devices. AsyncOtherDevices has no effect on
     the processing of events from the specified device. When
     the event_mode is SyncAll or AsyncAll, the device
     parameter is ignored.

     It is possible for several grabs of different devices
     (by the same or different clients) to be active
     simultaneously. If a device is frozen on behalf of any
     grab, no event processing is performed for the device.
     It is possible for a single device to be frozen because
     of several grabs. In this case, the freeze must be
     released on behalf of each grab before events can again
     be processed.

2.17 Controlling Device Focus

   The current focus window for an extension input device can be
   determined using the GetDeviceFocus request. Extension devices
   are focused using the SetDeviceFocus request in the same way
   that the keyboard is focused using the SetInputFocus request,
   except that a device is specified as part of the request. One
   additional focus state, FollowKeyboard, is provided for
   extension devices.

   To get the current focus state, revert state, and focus time of
   an extension device, use GetDeviceFocus.

                   GetDeviceFocus
                           device: DEVICE
                   =>
                           focus: WINDOW, PointerRoot, FollowKeyboard, or None
                           revert-to: Parent, PointerRoot, FollowKeyboard, or None
                           focus-time: TIMESTAMP

   Errors: Device, Match

   This request returns the current focus state, revert-to state,
   and last-focus-time of an extension device.

   To set the focus of an extension device, use SetDeviceFocus.

                   SetDeviceFocus
                           device: DEVICE
                           focus: WINDOW, PointerRoot, FollowKeyboard, or None
                           revert-to: Parent, PointerRoot, FollowKeyboard, or None
                           focus-time: TIMESTAMP

   Errors: Device, Window, Value, Match

   This request changes the focus for an extension input device
   and the last-focus-change-time. The request has no effect if
   the specified time is earlier than the last-focus-change-time
   or is later than the current X server time. Otherwise, the
   last-focus-change-time is set to the specified time, with
   CurrentTime replaced by the current server time.

   The action taken by the server when this request is requested
   depends on the value of the focus argument:

   * If the focus argument is None, all input events from
     this device will be discarded until a new focus window
     is set. In this case, the revert-to argument is ignored.

   * If a window ID is assigned to the focus argument, it
     becomes the focus window of the device. If an input
     event from the device would normally be reported to this
     window or to one of its inferiors, the event is reported
     normally. Otherwise, the event is reported relative to
     the focus window.

   * If you assign PointerRoot to the focus argument, the
     focus window is dynamically taken to be the root window
     of whatever screen the pointer is on at each input
     event. In this case, the revert-to argument is ignored.

   * If you assign FollowKeyboard to the focus argument, the
     focus window is dynamically taken to be the same as the
     focus of the X keyboard at each input event.

     The specified focus window must be viewable at the time
     of the request (else a Match error). If the focus window
     later becomes not viewable, the X server evaluates the
     revert-to argument to determine the new focus window.

   * If you assign RevertToParent to the revert-to argument,
     the focus reverts to the parent (or the closest viewable
     ancestor), and the new revert-to value is taken to be
     RevertToNone.

   * If you assign RevertToPointerRoot,
     RevertToFollowKeyboard, or RevertToNone to the revert-to
     argument, the focus reverts to that value.

   When the focus reverts, the X server generates DeviceFocusIn
   and DeviceFocusOut events, but the last-focus-change time is
   not affected.

   This request causes the X server to generate DeviceFocusIn and
   DeviceFocusOut events.

2.18 Controlling Device Feedback

   To get the settings of feedbacks on an extension device, use
   GetFeedbackControl. This request provides functionality
   equivalent to the core GetKeyboardControl and GetPointerControl
   functions. It also provides a way to control displays
   associated with an input device that are capable of displaying
   an integer or string.

                   GetFeedbackControl
                           device: DEVICE
                   =>
                           num_feedbacks_return: CARD16
                           return_value: LISTofFEEDBACKSTATE

   where

                       FEEDBACKSTATE: {KbdFeedbackState, PtrFeedbackState,
                                       IntegerFeedbackState, StringFeedbackState,
                                       BellFeedbackState, LedFeedbackState}

   Feedbacks are reported by class. Those feedbacks that are
   reported for the core keyboard device are in class KbdFeedback,
   and are returned in the KbdFeedbackState structure. The members
   of that structure are as follows:

                   CLASS Kbd:
                           [class: CARD8
                            length: CARD16
                            feedback id: CARD8
                            key_click_percent: CARD8
                            bell_percent: CARD8
                            bell_pitch: CARD16
                            bell_duration: CARD16
                            led_value: BITMASK
                            global_auto_repeat: {AutoRepeatModeOn, AutoRepeatModeOff}
                            auto_repeats: LISTofCARD8]

   Those feedbacks that are equivalent to those reported for the
   core pointer are in feedback class PtrFeedback and are reported
   in the PtrFeedbackState structure. The members of that
   structure are:

                   CLASS Ptr:
                           [class: CARD8
                            length: CARD16
                            feedback id: CARD8
                            accelNumerator: CARD16
                            accelDenominator: CARD16
                            threshold: CARD16]

   Some input devices provide a means of displaying an integer.
   Those devices will support feedback class IntegerFeedback,
   which is reported in the IntegerFeedbackState structure. The
   members of that structure are:

                     CLASS Integer:
                           [class: CARD8
                            length: CARD16
                            feedback id: CARD8
                            resolution: CARD32
                            min-val: INT32
                            max-val: INT32]

   Some input devices provide a means of displaying a string.
   Those devices will support feedback class StringFeedback, which
   is reported in the StringFeedbackState structure. The members
   of that structure are:

                     CLASS String:
                           [class: CARD8
                            length: CARD16
                            feedback id: CARD8
                            max_symbols: CARD16
                            num_keysyms_supported: CARD16
                            keysyms_supported: LISTofKEYSYM]

   Some input devices contain a bell. Those devices will support
   feedback class BellFeedback, which is reported in the
   BellFeedbackState structure. The members of that structure are:

                     CLASS String:
                           [class: CARD8
                            length: CARD16
                            feedback id: CARD8
                            percent: CARD8
                            pitch: CARD16
                            duration: CARD16]

   The percent sets the base volume for the bell between 0 (off)
   and 100 (loud) inclusive, if possible. Setting to -1 restores
   the default. Other negative values generate a Value error.

   The pitch sets the pitch (specified in Hz) of the bell, if
   possible. Setting to -1 restores the default. Other negative
   values generate a Value error.

   The duration sets the duration (specified in milliseconds) of
   the bell, if possible. Setting to -1 restores the default.
   Other negative values generate a Value error.

   A bell generator connected with the console but not directly on
   the device is treated as if it were part of the device. Some
   input devices contain LEDs. Those devices will support feedback
   class Led, which is reported in the LedFeedbackState structure.
   The members of that structure are:

                     CLASS String:
                           [class: CARD8
                            length: CARD16
                            feedback id: CARD8
                            led_mask: BITMASK
                            led_value: BITMASK]

   Each bit in led_mask indicates that the corresponding led is
   supported by the feedback. At most 32 LEDs per feedback are
   supported. No standard interpretation of LEDs is defined.

   This function will fail with a BadMatch error if the device
   specified in the request does not support feedbacks.

   Errors: Device, Match

   To change the settings of a feedback on an extension device,
   use ChangeFeedbackControl.

                   ChangeFeedbackControl
                           device: DEVICE
                           feedbackid: CARD8
                           value-mask: BITMASK
                           value: FEEDBACKCONTROL
                           FEEDBACKCONTROL: {KBDFEEDBACKCONTROL,
                                             PTRFEEDBACKCONTROL,
                                             INTEGERFEEDBACKCONTROL,
                                             STRINGFEEDBACKCONTROL,
                                             BELLFEEDBACKCONTROL,
                                             LEDFEEDBACKCONTROL}

   Errors: Device, Match, Value

   Feedback controls are grouped by class. Those feedbacks that
   are equivalent to those supported by the core keyboard are
   controlled by feedback class KbdFeedbackClass using the
   KbdFeedbackControl structure. The members of that structure
   are:

                   KBDFEEDBACKCTL
                           [class: CARD8
                            length: CARD16
                            feedback id: CARD8
                            key_click_percent: INT8
                            bell_percent: INT8
                            bell_pitch: INT16
                            bell_duration: INT16
                            led_mask: INT32
                            led_value: INT32
                            key: KEYCODE
                            auto_repeat_mode: {AutoRepeatModeOn, AutoRepeatModeOff,
                                               AutoRepeatModeDefault}]

   The key_click_percent sets the volume for key clicks between 0
   (off) and 100 (loud) inclusive, if possible. Setting to -1
   restores the default. Other negative values generate a Value
   error.

   If both auto_repeat_mode and key are specified, then the
   auto_repeat_mode of that key is changed, if possible. If only
   auto_repeat_mode is specified, then the global auto-repeat mode
   for the entire keyboard is changed, if possible, without
   affecting the per-key settings. It is a Match error if a key is
   specified without an auto_repeat_mode.

   The order in which controls are verified and altered is
   server-dependent. If an error is generated, a subset of the
   controls may have been altered.

   Those feedback controls equivalent to those of the core pointer
   are controlled by feedback class PtrFeedbackClass using the
   PtrFeedbackControl structure. The members of that structure are
   as follows:

                   PTRFEEDBACKCTL:
                           [class: CARD8
                            length: CARD16
                            feedback id: CARD8
                            accelNumerator: INT16
                            accelDenominator: INT16
                            threshold: INT16]

   The acceleration, expressed as a fraction, is a multiplier for
   movement. For example, specifying 3/1 means the device moves
   three times as fast as normal. The fraction may be rounded
   arbitrarily by the X server. Acceleration only takes effect if
   the device moves more than threshold pixels at once and only
   applies to the amount beyond the value in the threshold
   argument. Setting a value to -1 restores the default. The
   values of the do-accel and do-threshold arguments must be
   nonzero for the device values to be set. Otherwise, the
   parameters will be unchanged. Negative values generate a Value
   error, as does a zero value for the accel-denominator argument.

   Some devices are capable of displaying an integer. This is done
   using feedback class IntegerFeedbackClass using the
   IntegerFeedbackControl structure. The members of that structure
   are as follows:

                   INTEGERCTL:
                           [class: CARD8
                            length: CARD16
                            feedback id: CARD8
                            int_to_display: INT32]

   Some devices are capable of displaying an string. This is done
   using feedback class StringFeedbackClass using the
   StringFeedbackCtl structure. The members of that structure are
   as follows:

                   STRINGCTL:
                           [class: CARD8
                            length: CARD16
                            feedback id: CARD8
                            syms_to_display: LISTofKEYSYMS]

   Some devices contain a bell. This is done using feedback class
   BellFeedbackClass using the BellFeedbackControl structure. The
   members of that structure are as follows:

                   BELLCTL:
                           [class: CARD8
                            length: CARD16
                            feedback id: CARD8
                            percent: INT8
                            pitch: INT16
                            duration: INT16]

   Some devices contain leds. These can be turned on and off using
   the LedFeedbackControl structure. The members of that structure
   are as follows:

                   LEDCTL:
                           [class: CARD8
                            length: CARD16
                            feedback id: CARD8
                            led_mask: BITMASK
                            led_value: BITMASK]

   Errors: Device, Match, Value

2.20 Ringing a Bell on an Input Device

   To ring a bell on an extension input device, use DeviceBell.

                   DeviceBell:
                           device: DEVICE
                           feedbackclass: CARD8
                           feedbackid: CARD8
                           percent: INT8

   Errors: Device, Value

   This request is analogous to the core Bell request. It rings
   the specified bell on the specified input device feedback,
   using the specified volume. The specified volume is relative to
   the base volume for the feedback. If the value for the percent
   argument is not in the range -100 to 100 inclusive, a Value
   error results. The volume at which the bell rings when the
   percent argument is nonnegative is:

                   base - [(base * percent) / 100] + percent

   The volume at which the bell rings when the percent argument is
   negative is:

                   base + [(base * percent) / 100]

   To change the base volume of the bell, use
   ChangeFeedbackControl request.

Controlling Device Encoding

   To get the keyboard mapping of an extension device that has
   keys, use GetDeviceKeyMapping.

                   GetDeviceKeyMapping
                           device: DEVICE
                           first-keycode: KEYCODE
                           count: CARD8
                   =>
                           keysyms-per-keycode: CARD8
                           keysyms: LISTofKEYSYM

   Errors: Device, Match, Value

   This request returns the symbols for the specified number of
   keycodes for the specified extension device, starting with the
   specified keycode. The first-keycode must be greater than or
   equal to min-keycode as returned in the connection setup (else
   a Value error), and

                   first-keycode + count - 1

   must be less than or equal to max-keycode as returned in the
   connection setup (else a Value error). The number of elements
   in the keysyms list is

                   count * keysyms-per-keycode

   and KEYSYM number N (counting from zero) for keycode K has an
   index (counting from zero) of

                   (K - first-keycode) * keysyms-per-keycode + N

   in keysyms. The keysyms-per-keycode value is chosen arbitrarily
   by the server to be large enough to report all requested
   symbols. A special KEYSYM value of NoSymbol is used to fill in
   unused elements for individual keycodes.

   If the specified device has not first been opened by this
   client via OpenDevice, or if that device does not support input
   class Keys, this request will fail with a Device error.

   To change the keyboard mapping of an extension device that has
   keys, use ChangeDeviceKeyMapping.

                   ChangeDeviceKeyMapping
                           device: DEVICE
                           first-keycode: KEYCODE
                           keysyms-per-keycode: CARD8
                           keysyms: LISTofKEYSYM
                           num_codes: CARD8

   Errors: Device, Match, Value, Alloc

   This request is analogous to the core ChangeKeyMapping request.
   It defines the symbols for the specified number of keycodes for
   the specified extension device. If the specified device has not
   first been opened by this client via OpenDevice, or if that
   device does not support input class Keys, this request will
   fail with a Device error.

   The number of elements in the keysyms list must be a multiple
   of keysyms_per_keycode. Otherwise, ChangeDeviceKeyMapping
   generates a Length error. The specified first_keycode must be
   greater than or equal to the min_keycode value returned by the
   ListInputDevices request, or this request will fail with a
   Value error. In addition, if the following expression is not
   less than the max_keycode value returned by the
   ListInputDevices request, the request will fail with a Value
   error:

                   first_keycode + (num_codes / keysyms_per_keycode) - 1

   To obtain the keycodes that are used as modifiers on an
   extension device that has keys, use GetDeviceModifierMapping.

                   GetDeviceModifierMapping
                           device: DEVICE
                   =>
                           keycodes-per-modifier: CARD8
                           keycodes: LISTofKEYCODE

   Errors: Device, Match

   This request is analogous to the core GetModifierMapping
   request. This request returns the keycodes of the keys being
   used as modifiers. The number of keycodes in the list is
   8*keycodes-per-modifier. The keycodes are divided into eight
   sets, with each set containing keycodes-per-modifier elements.
   The sets are assigned in order to the modifiers Shift, Lock,
   Control, Mod1, Mod2, Mod3, Mod4, and Mod5. The
   keycodes-per-modifier value is chosen arbitrarily by the
   server; zeroes are used to fill in unused elements within each
   set. If only zero values are given in a set, the use of the
   corresponding modifier has been disabled. The order of keycodes
   within each set is chosen arbitrarily by the server.

   To set which keycodes that are to be used as modifiers for an
   extension device, use SetDeviceModifierMapping.

                   SetDeviceModifierMapping
                           device: DEVICE
                           keycodes-per-modifier: CARD8
                           keycodes: LISTofKEYCODE
                   =>
                           status: {Success, Busy, Failed}

   Errors: Device, Match, Value, Alloc

   This request is analogous to the core SetModifierMapping
   request. This request specifies the keycodes (if any) of the
   keys to be used as modifiers. The number of keycodes in the
   list must be 8*keycodes-per-modifier (else a Length error). The
   keycodes are divided into eight sets, with the sets, with each
   set containing keycodes-per-modifier elements. The sets are
   assigned in order to the modifiers Shift, Lock, Control, Mod1,
   Mod2, Mod3, Mod4, and Mod5. Only non-zero keycode values are
   used within each set; zero values are ignored. All of the
   non-zero keycodes must be in the range specified by min-keycode
   and max-keycode in the ListInputDevices request (else a Value
   error). The order of keycodes within a set does not matter. If
   no non-zero values are specified in a set, the use of the
   corresponding modifier is disabled, and the modifier bit will
   always be zero. Otherwise, the modifier bit will be one
   whenever at least one of the keys in the corresponding set is
   in the down position.

   A server can impose restrictions on how modifiers can be
   changed (for example, if certain keys do not generate up
   transitions in hardware or if multiple keys per modifier are
   not supported). The status reply is Failed if some such
   restriction is violated, and none of the modifiers are changed.

   If the new non-zero keycodes specified for a modifier differ
   from those currently defined, and any (current or new) keys for
   that modifier are logically in the down state, then the status
   reply is Busy, and none of the modifiers are changed.

   This request generates a DeviceMappingNotify event on a Success
   status. The DeviceMappingNotify event will be sent only to
   those clients that have expressed an interest in receiving that
   event via the XSelectExtensionEvent request.

   A X server can impose restrictions on how modifiers can be
   changed, for example, if certain keys do not generate up
   transitions in hardware or if multiple modifier keys are not
   supported. If some such restriction is violated, the status
   reply is MappingFailed , and none of the modifiers are changed.
   If the new keycodes specified for a modifier differ from those
   currently defined and any (current or new) keys for that
   modifier are in the logically down state, the status reply is
   MappingBusy, and none of the modifiers are changed.

2.20 Controlling Button Mapping

   These requests are analogous to the core GetPointerMapping and
   ChangePointerMapping requests. They allow a client to determine
   the current mapping of buttons on an extension device, and to
   change that mapping.

   To get the current button mapping for an extension device, use
   GetDeviceButtonMapping.

                   GetDeviceButtonMapping
                           device: DEVICE
                           nmap: CARD8
                   =>
                           map_return: LISTofCARD8

   Errors: Device, Match

   The GetDeviceButtonMapping function returns the current mapping
   of the buttons on the specified device. Elements of the list
   are indexed starting from one. The length of the list indicates
   the number of physical buttons. The nominal mapping is the
   identity mapping map[i]=i.

   nmap indicates the number of elements in the map_return array.
   Only the first nmap entries will be copied by the library into
   the map_return array.

   To set the button mapping for an extension device, use
   SetDeviceButtonMapping.

                   SetDeviceButtonMapping
                           device: DEVICE
                           map: LISTofCARD8
                           nmap: CARD8
                   =>
                           status: CARD8

   Errors: Device, Match, Value

   The SetDeviceButtonMapping function sets the mapping of the
   specified device and causes the X server to generate a
   DeviceMappingNotify event on a status of MappingSuccess.
   Elements of the list are indexed starting from one. The length
   of the list, specified in nmap, must be the same as
   GetDeviceButtonMapping would return. Otherwise,
   SetDeviceButtonMapping generates a Value error. A zero element
   disables a button, and elements are not restricted in value by
   the number of physical buttons. If any of the buttons to be
   altered are in the down state, the status reply is MappingBusy
   and the mapping is not changed.

   In servers supporting XI 1.x, no two elements can have the same
   nonzero value. Otherwise, this function generates a Value
   error.

2.21 Obtaining The State Of A Device

   To obtain vectors that describe the state of the keys, buttons
   and valuators of an extension device, use QueryDeviceState.

                   QueryDeviceState
                           device: DEVICE
                   =>
                           device-id: CARD8
                           data: LISTofINPUTCLASS

   where

                   INPUTCLASS: {VALUATOR, BUTTON, KEY}
                   CLASS VALUATOR:
                               [class: CARD8
                                num_valuators: CARD8
                                mode: CARD8
                                #x01 device mode (0 = Relative, 1 = Absolute)
                                #x02 proximity state (0 = InProximity, 1 = OutOfProximity)
                                valuators: LISTofINT32]
                   CLASS BUTTON:
                               [class: CARD8
                                num_buttons: CARD8
                                buttons: LISTofCARD8]
                   CLASS KEY:
                               [class: CARD8
                                num_keys: CARD8
                                keys: LISTofCARD8]

   Errors: Device

   The QueryDeviceState request returns the current logical state
   of the buttons, keys, and valuators on the specified input
   device. The buttons and keys arrays, byte N (from 0) contains
   the bits for key or button 8N to 8N+7 with the least
   significant bit in the byte representing key or button 8N.

   If the device has valuators, a bit in the mode field indicates
   whether the device is reporting Absolute or Relative data. If
   it is reporting Absolute data, the valuators array will contain
   the current value of the valuators. If it is reporting Relative
   data, the valuators array will contain undefined data.

   If the device reports proximity information, a bit in the mode
   field indicates whether the device is InProximity or
   OutOfProximity.

2.22 Listing Device Properties

   Introduced with XI 1.5

               ListDeviceProperties
                        deviceid: CARD8
               =>
                        nAtoms: CARD16
                        Atoms: LISTofATOM

   Errors: Device

   Each device can store an arbitrary number of properties. These
   properties can be allocated by either the client or the driver.
   The client can change device properties and the server
   guarantees that the device driver is notified about a change of
   the device's properties.

   ListDeviceProperties returns all properties of a device. The
   client is expected to retrieve details about the properties it
   is interested in separately.

2.23 Getting a Device Property

   Introduced with XI 1.5

               GetDeviceProperty:
                        property: ATOM
                        type: ATOM
                        longOffset: CARD32
                        longLength: CARD32
                        deviceid: CARD8
                        delete: BOOL
               =>
                        propertyType: ATOM
                        bytesAfter: CARD32
                        nItems: CARD32
                        format: CARD8
                        deviceid: CARD8
                        data: [LISTofCARD8]

   Errors: Atom, Device, Value, Access

   Retrieve the value for a property. If the property does not
   exist, propertyType is None and all other fields are undefined.

   If type is not AnyPropertyType and does not match the
   property's actual type, the propertyType, bytesAfter, and
   format are returned but not the actual data.

   longOffset and longLength specify the offset and length
   respectively in 32-bit multiples of the data to retrieve.

   If delete is True, the property is deleted after querying its
   data. If the property cannot be deleted, a BadAccess error is
   returned.

   propertyType returns the atom identifier that defines the
   actual type of the property.

   If bytesAfter is non-zero, it specifies the number of data
   4-byte units after the retrieved chunk of data.

   format specifies whether the data should be viewed as a list of
   8-bit, 16-bit, or 32-bit quantities. Possible values are 8, 16,
   and 32. This information allows the X server to correctly
   perform byte-swap operations as necessary.

   nItem specifies the number of 8-bit, 16-bit, or 32-bit items
   returned after the request.

2.24 Changing a Device Property

   Introduced with XI 1.5

               ChangeDeviceProperty:
                        property: ATOM
                        type: ATOM
                        deviceid: CARD8
                        format: CARD8
                        mode: CARD8
                        nUnits: CARD32

   Errors: Atom, Device, Value, Match, Access

   Changes the value of a specified property.

   The type specifies the atom identifier that defines the type of
   the property. If mode is not PropModeReplace, the type must
   match the current type of the property or a BadMatch error is
   returned.

   format specifies whether the data should be viewed as a list of
   8-bit, 16-bit, or 32-bit quantities. Possible values are 8, 16,
   and 32. This information allows the X server to correctly
   perform byte-swap operations as necessary.

   If mode is PropModeReplace, a preexising value for this
   property is replaced with the new value. If mode is
   PropModePrepend or PropModeAppend, the value is prepended or
   appended, respectively, to the current value of the property.

   nUnits specifies the number of 8-bit, 16-bit, or 32-bit items
   supplied after the reply.

   Changing a device property results in a
   DevicePropertyNotifyEvent being sent to all clients.

2.25 Deleting a Device Property

   Introduced with XI 1.5

               DeleteDeviceProperty:
                        property: ATOM
                        deviceid: CARD8

   Errors: Atom, Device, Match, Access.

   Deletes the specified property. If the property cannot be
   deleted by the client, a BadAccess error is returned.

3. Events

   The input extension creates input events analogous to the core
   input events. These extension input events are generated by
   manipulating one of the extension input devices.

3.1 Button, Key, and Motion Events

               DeviceKeyPress
               DeviceKeyRelease
               DeviceButtonPress,
               DeviceButtonRelease
               DeviceMotionNotify
                       device: CARD8
                       root, event: WINDOW
                       child: Window or None
                       same-screen: BOOL
                       root-x, root-y, event-x, event-y: INT16
                       detail: <see below>
                       state: SETofKEYBUTMASK
                       time: TIMESTAMP

   These events are generated when a key, button, or valuator
   logically changes state. The generation of these logical
   changes may lag the physical changes, if device event
   processing is frozen. Note that DeviceKeyPress and
   DeviceKeyRelease are generated for all keys, even those mapped
   to modifier bits. The “source” of the event is the window the
   pointer is in. The window with respect to which the event is
   normally reported is found by looking up the hierarchy
   (starting with the source window) for the first window on which
   any client has selected interest in the event. The actual
   window used for reporting can be modified by active grabs and
   by the focus window.The window the event is reported with
   respect to is called the “event” window.

   The root is the root window of the “source” window, and root-x
   and root-y are the pointer coordinates relative to root's
   origin at the time of the event. Event is the “event” window.
   If the event window is on the same screen as root, then event-x
   and event-y are the pointer coordinates relative to the event
   window's origin. Otherwise, event-x and event-y are zero. If
   the source window is an inferior of the event window, then
   child is set to the child of the event window that is an
   ancestor of (or is) the source window. Otherwise, it is set to
   None.

   The state component gives the logical state of the buttons on
   the X pointer and modifier keys on the core X keyboard just
   before the event.

   The detail component type varies with the event type:
   Event               Component
   DeviceKeyPress      KEYCODE
   DeviceKeyRelease    KEYCODE
   DeviceButtonPress   BUTTON
   DeviceButtonRelease BUTTON
   DeviceMotionNotify  { Normal , Hint }

   The granularity of motion events is not guaranteed, but a
   client selecting for motion events is guaranteed to get at
   least one event when a valuator changes. If DeviceMotionHint is
   selected, the server is free to send only one
   DeviceMotionNotify event (with detail Hint) to the client for
   the event window, until either a key or button changes state,
   the pointer leaves the event window, or the client issues a
   QueryDeviceState or GetDeviceMotionEvents request.

3.2 DeviceValuator Event

                   DeviceValuator
                           device: CARD8
                           device_state: SETofKEYBUTMASK
                           num_valuators: CARD8
                           first_valuator: CARD8
                           valuators: LISTofINT32

   DeviceValuator events are generated to contain valuator
   information for which there is insufficient space in DeviceKey,
   DeviceButton, DeviceMotion, and Proximity wire events. For
   events of these types, a second event of type DeviceValuator
   follows immediately. The library combines these events into a
   single event that a client can receive via XNextEvent.
   DeviceValuator events are not selected for by clients, they
   only exist to contain information that will not fit into some
   event selected by clients.

   The device_state component gives the state of the buttons and
   modifiers on the device generating the event.

   Extension motion devices may report motion data for a variable
   number of axes. The valuators array contains the values of all
   axes reported by the device. If more than 6 axes are reported,
   more than one DeviceValuator event will be sent by the server,
   and more than one DeviceKey, DeviceButton, DeviceMotion, or
   Proximity event will be reported by the library. Clients should
   examine the corresponding fields of the event reported by the
   library to determine the total number of axes reported, and the
   first axis reported in the current event. Axes are numbered
   beginning with zero.

   For Button, Key and Motion events on a device reporting
   absolute motion data the current value of the device's
   valuators is reported. For devices that report relative data,
   Button and Key events may be followed by a DeviceValuator event
   that contains 0s in the num_valuators field. In this case, only
   the device_state component will have meaning.

3.3 Device Focus Events

                   DeviceFocusIn
                   DeviceFocusOut
                           device: CARD8
                           time: TIMESTAMP
                           event: WINDOW
                           mode: { Normal, WhileGrabbed, Grab, Ungrab}
                           detail: { Ancestor, Virtual, Inferior, Nonlinear,
                                     NonlinearVirtual, Pointer, PointerRoot, None}

   These events are generated when the input focus changes and are
   reported to clients selecting DeviceFocusChange for the
   specified device and window. Events generated by SetDeviceFocus
   when the device is not grabbed have mode Normal. Events
   generated by SetDeviceFocus when the device is grabbed have
   mode WhileGrabbed. Events generated when a device grab actives
   have mode Grab, and events generated when a device grab
   deactivates have mode Ungrab.

   All DeviceFocusOut events caused by a window unmap are
   generated after any UnmapNotify event, but the ordering of
   DeviceFocusOut with respect to generated EnterNotify,
   LeaveNotify, VisibilityNotify and Expose events is not
   constrained.

   DeviceFocusIn and DeviceFocusOut events are generated for focus
   changes of extension devices in the same manner as focus events
   for the core devices are generated.

3.4 Device State Notify Event

                   DeviceStateNotify
                   time: TIMESTAMP
                   device: CARD8
                   num_keys: CARD8
                   num_buttons: CARD8
                   num_valuators: CARD8
                   classes_reported: CARD8 {SetOfDeviceMode | SetOfInputClass}
                       SetOfDeviceMode:
                           #x80 ProximityState 0 = InProxmity, 1 = OutOfProximity
                           #x40 Device Mode (0 = Relative, 1 = Absolute)
                       SetOfInputClass: #x04 reporting valuators
                           #x02 reporting buttons
                           #x01 reporting keys
                   buttons: LISTofCARD8
                   keys: LISTofCARD8
                   valuators: LISTofCARD32

   This event reports the state of the device just as in the
   QueryDeviceState request. This event is reported to clients
   selecting DeviceStateNotify for the device and window and is
   generated immediately after every EnterNotify and
   DeviceFocusIn. If the device has no more than 32 buttons, no
   more than 32 keys, and no more than 3 valuators, This event can
   report the state of the device. If the device has more than 32
   buttons, the event will be immediately followed by a
   DeviceButtonStateNotify event. If the device has more than 32
   keys, the event will be followed by a DeviceKeyStateNotify
   event. If the device has more than 3 valuators, the event will
   be followed by one or more DeviceValuator events.

3.5 Device KeyState and ButtonState Notify Events

                   DeviceKeyStateNotify
                           device: CARD8
                           keys: LISTofCARD8
                   DeviceButtonStateNotify
                           device: CARD8
                           buttons: LISTofCARD8

   These events contain information about the state of keys and
   buttons on a device that will not fit into the
   DeviceStateNotify wire event. These events are not selected by
   clients, rather they may immediately follow a DeviceStateNotify
   wire event and be combined with it into a single
   DeviceStateNotify client event that a client may receive via
   XNextEvent.

3.6 DeviceMappingNotify Event

                   DeviceMappingNotify
                           time: TIMESTAMP
                           device: CARD8
                           request: CARD8
                           first_keycode: CARD8
                           count: CARD8

   This event reports a change in the mapping of keys, modifiers,
   or buttons on an extension device. This event is reported to
   clients selecting DeviceMappingNotify for the device and window
   and is generated after every client SetDeviceButtonMapping,
   ChangeDeviceKeyMapping, or ChangeDeviceModifierMapping request.

3.7 ChangeDeviceNotify Event

                   ChangeDeviceNotify
                           device: CARD8
                           time: TIMESTAMP
                           request: CARD8

   This event reports a change in the physical device being used
   as the core X keyboard or X pointer device. ChangeDeviceNotify
   events are reported to clients selecting ChangeDeviceNotify for
   the device and window and is generated after every client
   ChangeKeyboardDevice or ChangePointerDevice request.

3.7 Proximity Events

                   ProximityIn
                   ProximityOut
                           device: CARD8
                           root, event: WINDOW
                           child: Window or None
                           same-screen: BOOL
                           root-x, root-y, event-x, event-y: INT16
                           state: SETofKEYBUTMASK
                           time: TIMESTAMP
                           device-state: SETofKEYBUTMASK
                           axis-count: CARD8
                           first-axis: CARD8
                           axis-data: LISTofINT32

   These events are generated by some devices (such as graphics
   tablets or touchscreens) to indicate that a stylus has moved
   into or out of contact with a positional sensing surface.

   The “source” of the event is the window the pointer is in. The
   window with respect to which the event is normally reported is
   found by looking up the hierarchy (starting with the source
   window) for the first window on which any client has selected
   interest in the event. The actual window used for reporting can
   be modified by active grabs and by the focus window.The window
   the event is reported with respect to is called the “event”
   window.

   The root is the root window of the “source” window, and root-x
   and root-y are the pointer coordinates relative to root's
   origin at the time of the event. Event is the “event” window.
   If the event window is on the same screen as root, then event-x
   and event-y are the pointer coordinates relative to the event
   window's origin. Otherwise, event-x and event-y are zero. If
   the source window is an inferior of the event window, then
   child is set to the child of the event window that is an
   ancestor of (or is) the source window. Otherwise, it is set to
   None. The state component gives the logical state of the
   buttons on the core X pointer and modifier keys on the core X
   keyboard just before the event. The device-state component
   gives the state of the buttons and modifiers on the device
   generating the event.

3.8 DevicePresenceEvents

   Introduced with XI 1.4.

                   DevicePresence
                           time: TIMESTAMP
                           devchange: BYTE
                               #x00: DeviceAdded
                               #x01: DeviceRemoved
                               #x02: DeviceEnabled
                               #x03: DeviceDisabled
                               #x04: DeviceUnrecoverable
                               #x05: DeviceControlChanged
                           deviceid: BYTE
                           control: CARD16

   DevicePresence events are sent when the server adds or removes,
   or enables or disables an input device. The client is expected
   to query the server for the list of input devices using the
   ListInputDevices request to obtain the updated list of input
   devices. DevicePresence events are also sent when a control on
   the device has been changed.

   The devchange field specifies the type of operation. In case of
   DeviceAdded, a new device has been added to the server, but
   this device does not yet send events. If devchange is set to
   DeviceEnabled, the device is enabled and will generate events.
   If the field is DeviceDisabled or DeviceRemoved, the given
   device is disabled and stops sending events or was removed from
   the server, respectively. If the field is DeviceUnrecoverable,
   an IO-error has occured on the device and the device is
   forcibly disabled and removed by the server. If devchange is
   DeviceControlChanged, control specifies the type of control
   that has been changed.

3.9 DevicePropertyNotifyEvent

   Introduced with XI 1.5.

                   DevicePropertyNotifyEvent
                           deviceid: CARD8
                           state: CARD8
                           time: TIMESTAMP
                           atom: ATOM

   A DevicePropertyNotifyEvent is sent to all clients when a
   property on the device is created, deleted, or changes value.

   The deviceid specifies the device which's property has been
   modified.

   The atom specifies the named identifier of the property that
   has been altered.

   If state is PropertyNewValue, the given property has a new
   value or has been newly created. If state is PropertyDeleted,
   the given property has been deleted.