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
2545
2546
2547
2548
2549
2550
2551
2552
2553
2554
2555
2556
2557
2558
2559
2560
2561
2562
2563
2564
2565
2566
2567
2568
2569
2570
2571
2572
2573
2574
2575
2576
2577
2578
2579
2580
2581
2582
2583
2584
2585
2586
2587
2588
2589
2590
2591
2592
2593
2594
2595
2596
2597
2598
2599
2600
2601
2602
2603
2604
2605
2606
2607
2608
2609
2610
2611
2612
2613
2614
2615
2616
2617
2618
2619
2620
2621
2622
2623
2624
2625
2626
2627
2628
2629
2630
2631
2632
2633
2634
2635
2636
2637
2638
2639
2640
2641
2642
2643
2644
2645
2646
2647
2648
2649
2650
2651
2652
2653
2654
2655
2656
2657
2658
2659
2660
2661
2662
2663
2664
2665
2666
2667
2668
2669
2670
2671
2672
2673
2674
2675
2676
2677
2678
2679
2680
2681
2682
2683
2684
2685
2686
2687
2688
2689
2690
2691
2692
2693
2694
2695
2696
2697
2698
2699
2700
2701
2702
2703
2704
2705
2706
2707
2708
2709
2710
2711
2712
2713
2714
2715
2716
2717
2718
2719
2720
2721
2722
2723
2724
2725
2726
2727
2728
2729
2730
2731
2732
2733
2734
2735
2736
2737
2738
2739
2740
2741
2742
2743
2744
2745
2746
2747
2748
2749
2750
2751
2752
2753
2754
2755
2756
2757
2758
2759
2760
2761
2762
2763
2764
2765
2766
2767
2768
2769
2770
2771
2772
2773
2774
2775
2776
2777
2778
2779
2780
2781
2782
2783
2784
2785
2786
2787
2788
2789
2790
2791
2792
2793
2794
2795
2796
2797
2798
2799
2800
2801
2802
2803
2804
2805
2806
2807
2808
2809
2810
2811
2812
2813
2814
2815
2816
2817
2818
2819
2820
2821
2822
2823
2824
2825
2826
2827
2828
2829
2830
2831
2832
2833
2834
2835
2836
2837
2838
2839
2840
2841
2842
2843
2844
2845
2846
2847
2848
2849
2850
2851
2852
2853
2854
2855
2856
2857
2858
2859
2860
2861
2862
2863
2864
2865
2866
2867
2868
2869
2870
2871
2872
2873
2874
2875
2876
2877
2878
2879
2880
2881
2882
2883
2884
2885
2886
2887
2888
2889
2890
2891
2892
2893
2894
2895
2896
2897
2898
2899
2900
2901
2902
2903
2904
2905
2906
2907
2908
2909
2910
2911
2912
2913
2914
2915
2916
2917
2918
2919
2920
2921
2922
2923
2924
2925
2926
2927
2928
2929
2930
2931
2932
2933
2934
2935
2936
2937
2938
2939
2940
2941
2942
2943
2944
2945
2946
2947
2948
2949
2950
2951
2952
2953
2954
2955
2956
2957
2958
2959
2960
2961
2962
2963
2964
2965
2966
2967
2968
2969
2970
2971
2972
2973
2974
2975
2976
2977
2978
2979
2980
2981
2982
2983
2984
2985
2986
2987
2988
2989
2990
2991
2992
2993
2994
2995
2996
2997
2998
2999
3000
3001
3002
3003
3004
3005
3006
3007
3008
3009
3010
3011
3012
3013
3014
3015
3016
3017
3018
3019
3020
3021
3022
3023
3024
3025
3026
3027
3028
3029
3030
3031
3032
3033
3034
3035
3036
3037
3038
3039
3040
3041
3042
3043
3044
3045
3046
3047
3048
3049
3050
3051
3052
3053
3054
3055
3056
3057
3058
3059
3060
3061
3062
3063
3064
3065
3066
3067
3068
3069
3070
3071
3072
3073
3074
3075
3076
3077
3078
3079
3080
3081
3082
3083
3084
3085
3086
3087
3088
3089
3090
3091
3092
3093
3094
3095
3096
3097
3098
3099
3100
3101
3102
3103
3104
3105
3106
3107
3108
3109
3110
3111
3112
3113
3114
3115
3116
3117
3118
3119
3120
3121
3122
3123
3124
3125
3126
3127
3128
3129
3130
3131
3132
3133
3134
3135
3136
3137
3138
3139
3140
3141
3142
3143
3144
3145
3146
3147
3148
3149
3150
3151
3152
3153
3154
3155
3156
3157
3158
3159
3160
3161
3162
3163
3164
3165
3166
3167
3168
3169
3170
3171
3172
3173
3174
3175
3176
3177
3178
3179
3180
3181
3182
3183
3184
3185
3186
3187
3188
3189
3190
3191
3192
3193
3194
3195
3196
3197
3198
3199
3200
3201
3202
3203
3204
3205
3206
3207
3208
3209
3210
3211
3212
3213
3214
3215
3216
3217
3218
3219
3220
3221
3222
3223
3224
3225
3226
3227
3228
3229
3230
3231
3232
3233
3234
3235
3236
3237
3238
3239
3240
3241
3242
3243
3244
3245
3246
3247
3248
3249
3250
3251
3252
3253
3254
3255
3256
3257
3258
3259
3260
3261
3262
3263
3264
3265
3266
3267
3268
3269
3270
3271
3272
3273
3274
3275
3276
3277
3278
3279
3280
3281
3282
3283
3284
3285
3286
3287
3288
3289
3290
3291
3292
3293
3294
3295
3296
3297
3298
3299
3300
3301
3302
3303
3304
3305
3306
3307
3308
3309
3310
3311
3312
3313
3314
3315
3316
3317
3318
3319
3320
3321
3322
3323
3324
3325
3326
3327
3328
3329
3330
3331
3332
3333
3334
3335
3336
3337
3338
3339
3340
3341
3342
3343
3344
3345
3346
3347
3348
3349
3350
3351
3352
3353
3354
3355
3356
3357
3358
3359
3360
3361
3362
3363
3364
3365
3366
3367
3368
3369
3370
3371
3372
3373
3374
3375
3376
3377
3378
3379
3380
3381
3382
3383
3384
3385
3386
3387
3388
3389
3390
3391
3392
3393
3394
3395
3396
3397
3398
3399
3400
3401
3402
3403
3404
3405
3406
3407
3408
3409
3410
3411
3412
3413
3414
3415
3416
3417
3418
3419
3420
3421
3422
3423
3424
3425
3426
3427
3428
3429
3430
3431
3432
3433
3434
3435
3436
3437
3438
3439
3440
3441
3442
3443
3444
3445
3446
3447
3448
3449
3450
3451
3452
3453
3454
3455
3456
3457
3458
3459
3460
3461
3462
3463
3464
3465
3466
3467
3468
3469
3470
3471
3472
3473
3474
3475
3476
3477
3478
3479
3480
3481
3482
3483
3484
3485
3486
3487
3488
3489
3490
3491
3492
3493
3494
3495
3496
3497
3498
3499
3500
3501
3502
3503
3504
3505
3506
3507
3508
3509
3510
3511
3512
3513
3514
3515
3516
3517
3518
3519
3520
3521
3522
3523
3524
3525
3526
3527
3528
3529
3530
3531
3532
3533
3534
3535
3536
3537
3538
3539
3540
3541
3542
3543
3544
3545
3546
3547
3548
3549
3550
3551
3552
3553
3554
3555
3556
3557
3558
3559
3560
3561
3562
3563
3564
3565
3566
3567
3568
3569
3570
3571
3572
3573
3574
3575
3576
3577
3578
3579
3580
3581
3582
3583
3584
3585
3586
3587
3588
3589
3590
3591
3592
3593
3594
3595
3596
3597
3598
3599
3600
3601
3602
3603
3604
3605
3606
3607
3608
3609
3610
3611
3612
3613
3614
3615
3616
3617
3618
3619
3620
3621
3622
3623
3624
3625
3626
3627
3628
3629
3630
3631
3632
3633
3634
3635
3636
3637
3638
3639
3640
3641
3642
3643
3644
3645
3646
3647
3648
3649
3650
3651
3652
3653
3654
3655
3656
3657
3658
3659
3660
3661
3662
3663
3664
3665
3666
3667
3668
3669
3670
3671
3672
3673
3674
3675
3676
3677
3678
3679
3680
3681
3682
3683
3684
3685
3686
3687
3688
3689
3690
3691
3692
3693
3694
3695
3696
3697
3698
3699
3700
3701
3702
3703
3704
3705
3706
3707
3708
3709
3710
3711
3712
3713
3714
3715
3716
3717
3718
3719
3720
3721
3722
3723
3724
3725
3726
3727
3728
3729
3730
3731
3732
3733
3734
3735
3736
3737
3738
3739
3740
3741
3742
3743
3744
3745
3746
3747
3748
3749
3750
3751
3752
3753
3754
3755
3756
3757
3758
3759
3760
3761
3762
3763
3764
3765
3766
3767
3768
3769
3770
3771
3772
3773
3774
3775
|
<!DOCTYPE html public "-//W3C//DTD HTML 4.01 Transitional//EN"
"http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<title>Basic Graphics Programming With The XCB Library</title>
<link href="xcb.css" rel="stylesheet" type="text/css" />
</head>
<body>
<div class="title">
Basic Graphics Programming With The XCB Library
</div>
<div class="toc">
<ol>
<li><a class="section" href="#intro">Introduction</a></li>
<li><a class="section" href="#Xmodel">The client and server model of the X window system</a></li>
<li><a class="section" href="#asynch">GUI programming: the asynchronous model</a></li>
<li><a class="section" href="#notions">Basic XCB notions</a></li>
<ol>
<li><a class="subsection" href="#conn">The X Connection</a></li>
<li><a class="subsection" href="#requestsreplies">Requests and replies: the Xlib killers</a></li>
<li><a class="subsection" href="#gc">The Graphics Context</a></li>
<li>Object handles</li>
<li>Memory allocation for XCB structures</li>
<li><a class="subsection" href="#events">Events</a></li>
</ol>
<li><a class="section" href="#use">Using XCB-based programs</a></li>
<ol>
<li><a class="subsection" href="#inst">Installation of XCB</a></li>
<li><a class="subsection" href="#comp">Compiling XCB-based programs</a></li>
</ol>
<li><a class="section" href="#openconn">Opening and closing the connection to an X server</a></li>
<li><a class="section" href="#screen">Checking basic information about a connection</a></li>
<li><a class="section" href="#helloworld">Creating a basic window - the "hello world" program</a></li>
<li><a class="section" href="#drawing">Drawing in a window</a></li>
<ol>
<li><a class="subsection" href="#allocgc">Allocating a Graphics Context</a></li>
<li><a class="subsection" href="#changegc">Changing the attributes of a Graphics Context</a></li>
<li><a class="subsection" href="#drawingprim">Drawing primitives: point, line, box, circle,...</a></li>
</ol>
<li><a class="section" href="#xevents">X Events</a></li>
<ol>
<li><a class="subsection" href="#register">Registering for event types using event masks</a></li>
<li><a class="subsection" href="#loop">Receiving events: writing the events loop</a></li>
<li><a class="subsection" href="#expose">Expose events</a></li>
<li><a class="subsection" href="#userinput">Getting user input</a></li>
<ol>
<li><a class="subsubsection" href="#mousepressrelease">Mouse button press and release events</a></li>
<li><a class="subsubsection" href="#mousemvnt">Mouse movement events</a></li>
<li><a class="subsubsection" href="#mouseenter">Mouse pointer enter and leave events</a></li>
<li><a class="subsubsection" href="#focus">The keyboard focus</a></li>
<li><a class="subsubsection" href="#keypress">Keyboard press and release events</a></li>
</ol>
<li><a class="subsection" href="#eventex">X events: a complete example</a></li>
</ol>
<li><a class="section" href="#font">Handling text and fonts</a></li>
<ol>
<li><a class="subsection" href="#fontstruct">The Font structure</a></li>
<li>Loading a Font</li>
<li>Assigning a Font to a Graphic Context</li>
<li>Drawing text in a window</li>
</ol>
<li>Windows hierarchy</li>
<ol>
<li>Root, parent and child windows</li>
<li>Events propagation</li>
</ol>
<li><a class="section" href="#wm">Interacting with the window manager</a></li>
<ol>
<li><a class="subsection" href="#wmprop">Window properties</a></li>
<li><a class="subsection" href="#wmname">Setting the window name and icon name</a></li>
<li>Setting preferred window size(s)</li>
<li>Setting miscellaneous window manager hints</li>
<li>Setting an application's icon</li>
</ol>
<li><a class="section" href="#winop">Simple window operations</a></li>
<ol>
<li><a class="subsection" href="#winmap">Mapping and un-mapping a window</a></li>
<li><a class="subsection" href="#winconf">Configuring a window</a></li>
<li><a class="subsection" href="#winmove">Moving a window around the screen</a></li>
<li><a class="subsection" href="#winsize">Resizing a window</a></li>
<li><a class="subsection" href="#winstack">Changing windows stacking order: raise and lower</a></li>
<li>Iconifying and de-iconifying a window</li>
<li><a class="subsection" href="#wingetinfo">Getting informations about a window</a></li>
</ol>
<li><a class="section" href="#usecolor">Using colors to paint the rainbow</a></li>
<ol>
<li><a class="subsection" href="#colormap">Color maps</a></li>
<li><a class="subsection" href="#colormapalloc">Allocating and freeing Color Maps</a></li>
<li><a class="subsection" href="#alloccolor">Allocating and freeing a color entry</a></li>
<li>Drawing with a color</li>
</ol>
<li><a class="section" href="#pixmaps">X Bitmaps and Pixmaps</a></li>
<ol>
<li><a class="subsection" href="#pixmapswhat">What is a X Bitmap ? An X Pixmap ?</a></li>
<li>Loading a bitmap from a file</li>
<li>Drawing a bitmap in a window</li>
<li><a class="subsection" href="#pixmapscreate">Creating a pixmap</a></li>
<li><a class="subsection" href="#pixmapsdraw">Drawing a pixmap in a window</a></li>
<li><a class="subsection" href="#pixmapsfree">Freeing a pixmap</a></li>
</ol>
<li>Messing with the mouse cursor</li>
<ol>
<li>Creating and destroying a mouse cursor</li>
<li>Setting a window's mouse cursor</li>
</ol>
<li><a class="subsection" href="#translation">Translation of basic Xlib functions and macros</a></li>
<ol>
<li><a class="subsection" href="#displaystructure">Members of the Display structure</a></li>
<ol>
<li><a class="subsection" href="#ConnectionNumber">ConnectionNumber</a></li>
<li><a class="subsection" href="#DefaultScreen">DefaultScreen</a></li>
<li><a class="subsection" href="#QLength">QLength</a></li>
<li><a class="subsection" href="#ScreenCount">ScreenCount</a></li>
<li><a class="subsection" href="#ServerVendor">ServerVendor</a></li>
<li><a class="subsection" href="#ProtocolVersion">ProtocolVersion</a></li>
<li><a class="subsection" href="#ProtocolRevision">ProtocolRevision</a></li>
<li><a class="subsection" href="#VendorRelease">VendorRelease</a></li>
<li><a class="subsection" href="#DisplayString">DisplayString</a></li>
<li><a class="subsection" href="#BitmapUnit">BitmapUnit</a></li>
<li><a class="subsection" href="#BitmapBitOrder">BitmapBitOrder</a></li>
<li><a class="subsection" href="#BitmapPad">BitmapPad</a></li>
<li><a class="subsection" href="#ImageByteOrder">ImageByteOrder</a></li>
</ol>
<li><a class="subsection" href="#screenofdisplay">ScreenOfDisplay related functions</a></li>
<ol>
<li><a class="subsection" href="#ScreenOfDisplay">ScreenOfDisplay</a></li>
<li><a class="subsection" href="#DefaultScreenOfDisplay">DefaultScreenOfDisplay</a></li>
<li><a class="subsection" href="#RootWindow">RootWindow / RootWindowOfScreen</a></li>
<li><a class="subsection" href="#DefaultRootWindow">DefaultRootWindow</a></li>
<li><a class="subsection" href="#DefaultVisual">DefaultVisual / DefaultVisualOfScreen</a></li>
<li><a class="subsection" href="#DefaultGC">DefaultGC / DefaultGCOfScreen</a></li>
<li><a class="subsection" href="#BlackPixel">BlackPixel / BlackPixelOfScreen</a></li>
<li><a class="subsection" href="#WhitePixel">WhitePixel / WhitePixelOfScreen</a></li>
<li><a class="subsection" href="#DisplayWidth">DisplayWidth / WidthOfScreen</a></li>
<li><a class="subsection" href="#DisplayHeight">DisplayHeight / HeightOfScreen</a></li>
<li><a class="subsection" href="#DisplayWidthMM">DisplayWidthMM / WidthMMOfScreen</a></li>
<li><a class="subsection" href="#DisplayHeightMM">DisplayHeightMM / HeightMMOfScreen</a></li>
<li><a class="subsection" href="#DisplayPlanes">DisplayPlanes / DefaultDepth / DefaultDepthOfScreen / PlanesOfScreen</a></li>
<li><a class="subsection" href="#DefaultColormap">DefaultColormap / DefaultColormapOfScreen</a></li>
<li><a class="subsection" href="#MinCmapsOfScreen">MinCmapsOfScreen</a></li>
<li><a class="subsection" href="#MaxCmapsOfScreen">MaxCmapsOfScreen</a></li>
<li><a class="subsection" href="#DoesSaveUnders">DoesSaveUnders</a></li>
<li><a class="subsection" href="#DoesBackingStore">DoesBackingStore</a></li>
<li><a class="subsection" href="#EventMaskOfScreen">EventMaskOfScreen</a></li>
</ol>
<li><a class="subsection" href="#misc">Miscellaneaous macros</a></li>
<ol>
<li><a class="subsection" href="#DisplayOfScreen">DisplayOfScreen</a></li>
<li><a class="subsection" href="#DisplayCells">DisplayCells / CellsOfScreen</a></li>
</ol>
</ol>
</ol>
</div>
<div class="section">
<ol>
<li class="title"><a name="intro">Introduction</a></li>
<p>
This tutorial is based on the
<a href="http://users.actcom.co.il/~choo/lupg/tutorials/xlib-programming/xlib-programming.html">Xlib Tutorial</a>
written by <a href="mailto:choor@atcom.co.il">Guy Keren</a>. The
author allowed me to take some parts of his text, mainly the text which
deals with the X Windows generality.
</p>
<p>
This tutorial is intended to people who want to start to program
with the <a href="http://xcb.freedesktop.org">XCB</a>
library. keep in mind that XCB, like the
<a href="http://tronche.com/gui/x/xlib/introduction">Xlib</a>
library, isn't what post programmers wanting to write X
applications are looking for. They should use a much higher
level GUI toolkit like Motif,
<a href="http://www.lesstif.org">LessTiff</a>,
<a href="http://www.gtk.org">GTK</a>,
<a href="http://www.trolltech.com">QT</a> or
<a href="http://www.enlightenment.org">EWL</a>, or use
<a href="http://cairographics.org">Cairo</a>.
However,
we need to start somewhere. More than this, knowing how things
work down below is never a bad idea.
</p>
<p>
After reading this tutorial, one should be able to write very
simple graphical programs, but not programs with descent user
interfaces. For such programs, one of the previously mentioned
library should be used.
</p>
<p>
But what is XCB? Xlib has been
the standard C binding for the <a href="http://www.xfree86.org">X
Window System</a> protocol for many years now. It is an
excellent piece of work, but there are applications for which it
is not ideal, for example
<ul>
<li><b>Small platforms</b>: Xlib is a large piece of code, and
it's difficult to make it smaller</li>
<li><b>Latency hiding</b>: Xlib requests requiring a reply are
effectively synchronous: they block until the reply appears,
whether the result is needed immediately or not.</li>
<li><b>Direct access to the protocol</b>: Xlib does quite a
bit of caching, layering, and similar optimizations. While this
is normally a feature, it makes it difficult to simply emit
specified X protocol requests and process specific
responses.</li>
<li><b>Threaded applications</b>: While Xlib does attempt to
support multithreading, the API makes this difficult and
error-prone.</li>
<li><b>New extensions</b>: The Xlib infrastructure provides
limited support for the new creation of X extension client side
code.</li>
</ul>
</p>
<p>
For these reasons, among others, XCB, an X C binding, has been
designed to solve the above problems and thus provide a base for
<ul>
<li>Toolkit implementation.</li>
<li>Direct protocol-level programming.</li>
<li>Lightweight emulation of commonly used portions of the
Xlib API (in progress)</li>
</ul>
</p>
<p></p>
<li class="title"><a name="Xmodel">The client and server model of the X window system</a></li>
<p>
The X Window System was developed with one major goal:
flexibility. The idea was that the way things look is one thing,
but the way things work is another matter. Thus, the lower
levels provide the tools required to draw windows, handle user
input, allow drawing graphics using colors (or black and white
screens), etc. To this point, a decision was made to separate
the system into two parts. A client that decides what to do, and
a server that actually draws on the screen and reads user input
in order to send it to the client for processing.
</p>
<p>
This model is the complete opposite of what is used to when
dealing with clients and servers. In our case, the user seats
near the machine controlled by the server, while the client
might be running on a remote machine. The server controls the
screens, mouse and keyboard. A client may connect to the server,
request that it draws a window (or several windows), and ask the
server to send it any input the user sends to these
windows. Thus, several clients may connect to a single X server
(one might be running an mail software, one running a WWW
browser, etc). When input is sent by the user to some window,
the server sends a message to the client controlling this window
for processing. The client decides what to do with this input,
and sends the server requests for drawing in the window.
</p>
<p>
The whole session is carried out using the X message
protocol. This protocol was originally carried over the TCP/IP
protocol suite, allowing the client to run on any machine
connected to the same network that the server is. Later on, the
X servers were extended to allow clients running on the local
machine with more optimized access to the server (note that an X
protocol message may be several hundreds of KB in size), such as
using shared memory, or using Unix domain sockets (a method for
creating a logical channel on a Unix system between two processes).
</p>
<li class="title"><a name="asynch">GUI programming: the asynchronous model</a></li>
<p>
Unlike conventional computer programs, that carry some serial
nature, a GUI program usually uses an asynchronous programming
model, also known as "event-driven programming". This means that
that program mostly sits idle, waiting for events sent by the X
server, and then acts upon these events. An event may say "The
user pressed the 1st button mouse in spot (x,y)", or "The window
you control needs to be redrawn". In order for the program to be
responsive to the user input, as well as to refresh requests, it
needs to handle each event in a rather short period of time
(e.g. less that 200 milliseconds, as a rule of thumb).
</p>
<p>
This also implies that the program may not perform operations
that might take a long time while handling an event (such as
opening a network connection to some remote server, or
connecting to a database server, or even performing a long file
copy operation). Instead, it needs to perform all these
operations in an asynchronous manner. This may be done by using
various asynchronous models to perform the longish operations,
or by performing them in a different process or thread.
</p>
<p>
So the way a GUI program looks is something like that:
<ol>
<li>Perform initialization routines.</li>
<li>Connect to the X server.</li>
<li>Perform X-related initialization.</li>
<li>While not finished:</li>
<ol>
<li>Receive the next event from the X server.</li>
<li>Handle the event, possibly sending various drawing
requests to the X server.</li>
<li>If the event was a quit message, exit the loop.</li>
</ol>
<li>Close down the connection to the X server. </li>
<li>Perform cleanup operations.</li>
</ol>
</p>
<p></p>
<li class="title"><a name="notions">Basic XCB notions</a></li>
<p>
XCB has been created to eliminate the needs of
programs to actually implement the X protocol layer. This
library gives a program a very low-level access to any X
server. Since the protocol is standardized, a client using any
implementation of XCB may talk with any X server (the same
occurs for Xlib, of course). We now give a brief description of
the basic XCB notions. They will be detailed later.
</p>
<ol>
<li class="subtitle"><a name="conn">The X Connection</a></li>
<p>
The major notion of using XCB is the X Connection. This is a
structure representing the connection we have open with a
given X server. It hides a queue of messages coming from the
server, and a queue of pending requests that our client
intends to send to the server. In XCB, this structure is named
'XCBConnection'. When we open a connection to an X server, the
library returns a pointer to such a structure. Later, we
supply this pointer to any XCB function that should send
messages to the X server or receive messages from this server.
</p>
<li class="subtitle"><a name="requestsreplies">Requests and
replies: the Xlib killers</a></li>
<p>
To ask informations to the X server, we have to make a request
and ask for a reply. With Xlib, these two tasks are
automatically done: Xlib locks the system, sends a request,
waits for a reply from the X server and unlocks. This is
annoying, especially if one makes a lot of requests to the X
server. Indeed, Xlib has to wait for the end of a reply
before asking for the next request (because of the locks that
Xlib sends). For example, here is a time-line of N=4
requests/replies with Xlib, with a round-trip latency
<b>T_round_trip</b> that is 5 times long as the time required
to write or read a request/reply (<b>T_write/T_read</b>):
</p>
<pre class="text">
W-----RW-----RW-----RW-----R
</pre>
<ul>
<li>W: Writing request</li>
<li>-: Stalled, waiting for data</li>
<li>R: Reading reply</li>
</ul>
<p>
The total time is N * (T_write + T_round_trip + T_read).
</p>
<p>
With XCB, we can suppress most of the round-trips as the
requests and the replies are not locked. We usually send a
request, then XCB returns to us a <b>cookie</b>, which is an
identifier. Then, later, we ask for a reply using this
<b>cookie</b> and XCB returns a
pointer to that reply. Hence, with XCB, we can send a lot of
requests, and later in the program, ask for all the replies
when we need them. Here is the time-line for 4
requests/replies when we use this property of XCB:
</p>
<pre class="text">
WWWW--RRRR
</pre>
<p>
The total time is N * T_write + max (0, T_round_trip - (N-1) *
T_write) + N * T_read. Which can be considerably faster than
all those Xlib round-trips.
</p>
<p>
Here is a program that computes the time to create 500 atoms
with Xlib and XCB. It shows the Xlib way, the bad XCB way
(which is similar to Xlib) and the good XCB way. On my
computer, XCB is 25 times faster than Xlib.
</p>
<pre class="code">
#include <stdlib.h>
#include <stdio.h>
#include <string.h>
#include <sys/time.h>
#include <X11/XCB/xcb.h>
#include <X11/Xlib.h>
double
get_time(void)
{
struct timeval timev;
gettimeofday(&timev, NULL);
return (double)timev.tv_sec + (((double)timev.tv_usec) / 1000000);
}
int
main ()
{
XCBConnection *c;
XCBATOM *atoms;
XCBInternAtomCookie *cs;
char **names;
int count;
int i;
double start;
double end;
double diff;
/* Xlib */
Display *disp;
Atom *atoms_x;
double diff_x;
c = XCBConnectBasic ();
count = 500;
atoms = (XCBATOM *)malloc (count * sizeof (atoms));
names = (char **)malloc (count * sizeof (char *));
/* init names */
for (i = 0; i < count; ++i)
{
char buf[100];
sprintf (buf, "NAME%d", i);
names[i] = strdup (buf);
}
/* bad use */
start = get_time ();
for (i = 0; i < count; ++i)
atoms[i] = XCBInternAtomReply (c,
XCBInternAtom (c,
0,
strlen(names[i]),
names[i]),
NULL)->atom;
end = get_time ();
diff = end - start;
printf ("bad use time : %f\n", diff);
/* good use */
start = get_time ();
cs = (XCBInternAtomCookie *) malloc (count * sizeof(XCBInternAtomCookie));
for(i = 0; i < count; ++i)
cs[i] = XCBInternAtom (c, 0, strlen(names[i]), names[i]);
for(i = 0; i < count; ++i)
{
XCBInternAtomRep *r;
r = XCBInternAtomReply(c, cs[i], 0);
if(r)
atoms[i] = r->atom;
free(r);
}
end = get_time ();
printf ("good use time : %f\n", end - start);
printf ("ratio : %f\n", diff / (end - start));
diff = end - start;
/* free var */
for (i = 0; i < count; ++i)
{
free (names[i]);
}
free (atoms);
free (cs);
XCBDisconnect (c);
/* Xlib */
disp = XOpenDisplay (getenv("DISPLAY"));
atoms_x = (Atom *)malloc (count * sizeof (atoms_x));
start = get_time ();
for (i = 0; i < count; ++i)
atoms_x[i] = XInternAtom(disp, names[i], 0);
end = get_time ();
diff_x = end - start;
printf ("Xlib use time : %f\n", diff_x);
printf ("ratio : %f\n", diff_x / diff);
free (atoms_x);
free (names);
XCloseDisplay (disp);
return 1;
}
</pre>
<li class="subtitle"><a name="gc">The Graphic Context</a></li>
<p>
When we perform various drawing operations (graphics, text,
etc), we may specify various options for controlling how the
data will be drawn (what foreground and background colors to
use, how line edges will be connected, what font to use when
drawing some text, etc). In order to avoid the need to supply
hundreds of parameters to each drawing function, a graphical
context structure is used. We set the various drawing options
in this structure, and then we pass a pointer to this
structure to any drawing routines. This is rather handy, as we
often need to perform several drawing requests with the same
options. Thus, we would initialize a graphical context, set
the desired options, and pass this structure to all drawing
functions.
</p>
<p>
Note that graphic contexts have no client-side structure in
XCB, they're just XIDs. Xlib has a client-side structure
because it caches the GC contents so it can avoid making
redundant requests, but of course XCB doesn't do that.
</p>
<li class="subtitle"><a name="events">Events</a></li>
<p>
A structure is used to pass events received from the X
server. XCB supports exactly the events specified in the
protocol (33 events). This structure contains the type
of event received, as well as the data associated with the
event (e.g. position on the screen where the event was
generated, mouse button associated with the event, region of
the screen associated with a "redraw" event, etc). The way to
read the event's data epends on the event type.
</p>
</ol>
<p></p>
<li class="title"><a name="use">Using XCB-based programs</a></li>
<p></p>
<ol>
<li class="subtitle"><a name="inst">Installation of XCB</a></li>
<p>
To build XCB from source, you need to have installed at
least:
</p>
<ul>
<li>pkgconfig 0.15.0</li>
<li>automake 1.7</li>
<li>autoconf 2.50</li>
<li><a href="http://www.check.org">check</a></li>
<li><a href="http://xmlsoft.org/XSLT/">xsltproc</a></li>
</ul>
<p>
You have to checkout in CVS the following modules:
</p>
<ul>
<li>Xproto from xlibs</li>
<li>Xau from xlibs</li>
<li>xcb-proto</li>
<li>xcb</li>
</ul>
<p>
Note that Xproto and xcb-proto exist only to install header
files, so typing 'make' or 'make all' will produce the message
"Nothing to be done for 'all'". That's normal.
</p>
<li class="subtitle"><a name="comp">Compiling XCB-based programs</a></li>
<p>
Compiling XCB-based programs requires linking them with the XCB
library. This is easily done thanks to pkgconfig:
</p>
<pre class="text">
gcc -Wall prog.c -o prog `pkg-config --cflags --libs xcb`
</pre>
</ol>
<li class="title"><a name="openconn">Opening and closing the connection to an X server</a></li>
<p>
An X program first needs to open the connection to the X
server. There is a function that opens a connection. It requires
the display name, or NULL. In the latter case, the display name
will be the one in the environment variable DISPLAY.
</p>
<pre class="code">
XCBConnection *XCBConnect (const char *displayname,
int *screenp);
</pre>
<p>
The second parameter returns the screen number used for the
connection. The returned structure describes an XCB connection
and is opaque. Here is how the connection can be opened:
</p>
<pre class="code">
#include <X11/XCB/xcb.h>
int
main (int argc, char *argv[])
{
XCBConnection *c;
/* Open the connection to the X server. use the DISPLAY environment variable as the default display name */
c = XCBConnect (NULL, NULL);
return 1;
}
</pre>
<p>
To close a connection, it suffices to use:
</p>
<pre class="code">
void XCBDisconnect (XCBConnection *c);
</pre>
<div class="comp">
<div class="title">
Comparison Xlib/XCB
</div>
<div class="xlib">
<ul>
<li>XOpenDisplay ()</li>
</ul>
</div>
<div class="xcb">
<ul>
<li>XCBConnect ()</li>
</ul>
</div>
<div class="xlib">
<ul>
<li>XCloseDisplay ()</li>
</ul>
</div>
<div class="xcb">
<ul>
<li>XCBDisconnect ()</li>
</ul>
</div>
</div>
<p>
</p>
<li class="title"><a name="screen">Checking basic information about a connection</a></li>
<p>
Once we opened a connection to an X server, we should check some
basic informations about it: what screens it has, what is the
size (width and height) of the screen, how many colors it
supports (black and white ? grey scale ?, 256 colors ? more ?),
and so on. We get such informations from the XCBSCREEN
structure:
</p>
<pre class="code">
typedef struct {
XCBWINDOW root;
XCBCOLORMAP default_colormap;
CARD32 white_pixel;
CARD32 black_pixel;
CARD32 current_input_masks;
CARD16 width_in_pixels;
CARD16 height_in_pixels;
CARD16 width_in_millimeters;
CARD16 height_in_millimeters;
CARD16 min_installed_maps;
CARD16 max_installed_maps;
XCBVISUALID root_visual;
BYTE backing_stores;
BOOL save_unders;
CARD8 root_depth;
CARD8 allowed_depths_len;
} XCBSCREEN;
</pre>
<p>
We could retrieve the first screen of the connection by using the
following function:
</p>
<pre class="code">
XCBSCREENIter XCBConnSetupSuccessRepRootsIter (XCBConnSetupSuccessRep *R);
</pre>
<p>
Here is a small program that shows how to use this function:
</p>
<pre class="code">
#include <stdio.h>
#include <X11/XCB/xcb.h>
int
main (int argc, char *argv[])
{
XCBConnection *c;
XCBSCREEN *screen;
int screen_nbr;
XCBSCREENIter iter;
/* Open the connection to the X server. Use the DISPLAY environment variable */
c = XCBConnect (NULL, &screen_nbr);
/* Get the screen #screen_nbr */
iter = XCBConnSetupSuccessRepRootsIter (XCBGetSetup (c));
for (; iter.rem; --screen_nbr, XCBSCREENNext (&iter))
if (screen_nbr == 0)
{
screen = iter.data;
break;
}
printf ("\n");
printf ("Informations of screen %ld:\n", screen->root.xid);
printf (" width.........: %d\n", screen->width_in_pixels);
printf (" height........: %d\n", screen->height_in_pixels);
printf (" white pixel...: %ld\n", screen->white_pixel);
printf (" black pixel...: %ld\n", screen->black_pixel);
printf ("\n");
return 1;
}
</pre>
<li class="title"><a name="helloworld">Creating a basic window - the "hello world" program</a></li>
<p>
After we got some basic informations about our screen, we can
create our first window. In the X Window System, a window is
characterized by an Id. So, in XCB, a window is of type:
</p>
<pre class="code">
typedef struct {
CARD32 xid;
} XCBWINDOW;
</pre>
<p>
We first ask for a new Id for our window, with this function:
</p>
<pre class="code">
XCBWINDOW XCBWINDOWNew(XCBConnection *c);
</pre>
<p>
Then, XCB supplies the following function to create new windows:
</p>
<pre class="code">
XCBVoidCookie XCBCreateWindow (XCBConnection *c, /* Pointer to the XCBConnection structure */
CARD8 depth, /* Depth of the screen */
XCBWINDOW wid, /* Id of the window */
XCBWINDOW parent, /* Id of an existing window that should be the parent of the new window */
INT16 x, /* X position of the top-left corner of the window (in pixels) */
INT16 y, /* Y position of the top-left corner of the window (in pixels) */
CARD16 width, /* Width of the window (in pixels) */
CARD16 height, /* Height of the window (in pixels) */
CARD16 border_width, /* Width of the window's border (in pixels) */
CARD16 _class,
XCBVISUALID visual,
CARD32 value_mask,
const CARD32 *value_list);
</pre>
<p>
The fact that we created the window does not mean that it will
be drawn on screen. By default, newly created windows are not
mapped on the screen (they are invisible). In order to make our
window visible, we use the function <span class="code">XCBMapWindow()</span>, whose
prototype is
</p>
<pre class="code">
XCBVoidCookie XCBMapWindow (XCBConnection *c, XCBWINDOW window);
</pre>
<p>
Finally, here is a small program to create a window of size
150x150 pixels, positioned at the top-left corner of the screen:
</p>
<pre class="code">
#include <unistd.h>
#include <X11/XCB/xcb.h>
int
main (int argc, char *argv[])
{
XCBConnection *c;
XCBSCREEN *screen;
XCBDRAWABLE win;
/* Open the connection to the X server */
c = XCBConnect (NULL, NULL);
/* Get the first screen */
screen = XCBConnSetupSuccessRepRootsIter (XCBGetSetup (c)).data;
/* Ask for our window's Id */
win.window = XCBWINDOWNew(c);
/* Create the window */
XCBCreateWindow (c, /* Connection */
0, /* depth */
win.window, /* window Id */
screen->root, /* parent window */
0, 0, /* x, y */
150, 150, /* width, height */
10, /* border_width */
InputOutput, /* class */
screen->root_visual, /* visual */
0, NULL); /* masks, not used yet */
/* Map the window on the screen */
XCBMapWindow (c, win.window);
XCBSync (c, 0);
pause ();
return 1;
}
</pre>
<p>
In this code, you see one more function - <span class="code">XCBSync()</span>, not explained
yet. It is used to flush all the pending requests. More
precisely, there are 2 functions that do such things. The first
one is <span class="code">XCBFlush()</span>:
</p>
<pre class="code">
int XCBFlush (XCBConnection *c);
</pre>
<p>
This function flushes all pending requests to the X server (much
like the <span class="code">fflush()</span> function is used to
flush standard output). The second function is
<span class="code">XCBSync()</span>:
</p>
<pre class="code">
int XCBSync(XCBConnection *c, XCBGenericError **e);
</pre>
<p>
This functions also flushes all pending requests to the X
server, and then waits until the X server finishing processing
these requests. In a normal program, this will not be necessary
(we'll see why when we get to write a normal X program), but for
now, we put it there.
</p>
<p>
The window that is created by the above code has a default
background (gray). This one can be set to a specific color,
thanks to the two last parameters of
<span class="code">XCBCreateWindow()</span>, which are not
described yet. See the subsections
<a href="#winconf">Configuring a window</a> or
<a href="#winconf">Registering for event types using event masks</a>
for exemples on how to use these parameters. In addition, as no
events are handled, you have to make a Ctrl-C to interrupt the
program.
</p>
<p>
<b>TODO</b>: one should tell what these functions return and
about the generic error
</p>
<div class="comp">
<div class="title">
Comparison Xlib/XCB
</div>
<div class="xlib">
<ul>
<li>XCreateWindow ()</li>
</ul>
</div>
<div class="xcb">
<ul>
<li>XCBWINDOWNew ()</li>
<li>XCBCreateWindow ()</li>
</ul>
</div>
</div>
<p></p>
<li class="title"><a name="drawing">Drawing in a window</a></li>
<p>
Drawing in a window can be done using various graphical
functions (drawing pixels, lines, rectangles, etc). In order to
draw in a window, we first need to define various general
drawing parameters (what line width to use, which color to draw
with, etc). This is done using a graphical context.
</p>
<ol>
<li class="subtitle"><a name="allocgc">Allocating a Graphics Context</a></li>
<p>
As we said, a graphical context defines several attributes to
be used with the various drawing functions. For this, we
define a graphical context. We can use more than one graphical
context with a single window, in order to draw in multiple
styles (different colors, different line widths, etc). In XCB,
a Graphics Context is, as a window, characterized by an Id:
</p>
<pre class="code">
typedef struct {
CARD32 xid;
} XCBGCONTEXT;
</pre>
<p>
We first ask the X server to attribute an Id to our graphic
context with this function:
</p>
<pre class="code">
XCBGCONTEXT XCBGCONTEXTNew (XCBConnection *c);
</pre>
<p>
Then, we set the attributes of the graphic context with this function:
</p>
<pre class="code">
XCBVoidCookie XCBCreateGC (XCBConnection *c,
XCBGCONTEXT cid,
XCBDRAWABLE drawable,
CARD32 value_mask,
const CARD32 *value_list);
</pre>
<p>
We give now an example on how to allocate a graphic context
that specifies that each drawing functions that use it will
draw in foreground with a black color.
</p>
<pre class="code">
#include <X11/XCB/xcb.h>
int
main (int argc, char *argv[])
{
XCBConnection *c;
XCBSCREEN *screen;
XCBDRAWABLE win;
XCBGCONTEXT black;
CARD32 mask;
CARD32 value[1];
/* Open the connection to the X server and get the first screen */
c = XCBConnect (NULL, NULL);
screen = XCBConnSetupSuccessRepRootsIter (XCBGetSetup (c)).data;
/* Create a black graphic context for drawing in the foreground */
win.window = screen->root;
black = XCBGCONTEXTNew (c);
mask = GCForeground;
value[0] = screen->black_pixel;
XCBCreateGC (c, black, win, mask, value);
return 1;
}
</pre>
<p>
Note should be taken regarding the role of "value_mask" and
"value_list" in the prototype of <span class="code">XCBCreateGC()</span>. Since a
graphic context has many attributes, and since we often just
want to define a few of them, we need to be able to tell the
<span class="code">XCBCreateGC()</span> which attributes we
want to set. This is what the "value_mask" parameter is
for. We then use the "value_list" parameter to specify actual
values for the attribute we defined in "value_mask". Thus, for
each constant used in "value_list", we will use the matching
constant in "value_mask". In this case, we define a graphic
context with one attribute: when drawing (a point, a line,
etc), the foreground color will be black. The rest of the
attributes of this graphic context will be set to their
default values.
</p>
<p>
See the next Subsection for more details.
</p>
<div class="comp">
<div class="title">
Comparison Xlib/XCB
</div>
<div class="xlib">
<ul>
<li>XCreateGC ()</li>
</ul>
</div>
<div class="xcb">
<ul>
<li>XCBGCONTEXTNew ()</li>
<li>XCBCreateGC ()</li>
</ul>
</div>
</div>
<p></p>
<li class="subtitle"><a name="changegc">Changing the attributes of a Graphics Context</a></li>
<p>
Once we have allocated a Graphic Context, we may need to
change its attributes (for example, changing the foreground
color we use to draw a line, or changing the attributes of the
font we use to display strings. See Subsections Drawing with a
color and Assigning a Font to a Graphic Context). This is done
by using this function:
</p>
<pre class="code">
XCBVoidCookie XCBChangeGC (XCBConnection *c, /* The XCB Connection */
XCBGCONTEXT gc, /* The Graphic Context */
CARD32 value_mask, /* Components of the Graphic Context that have to be set */
const CARD32 *value_list); /* Value as specified by value_mask */
</pre>
<p>
The <span class="code">value_mask</span> parameter could take
these values:
</p>
<ul>
<li>GCFunction</li>
<li>GCPlaneMask</li>
<li>GCForeground</li>
<li>GCBackground</li>
<li>GCLineWidth</li>
<li>GCLineStyle</li>
<li>GCCapStyle</li>
<li>GCJoinStyle</li>
<li>GCFillStyle</li>
<li>GCFillRule</li>
<li>GCTile</li>
<li>GCStipple</li>
<li>GCTileStipXOrigin</li>
<li>GCTileStipYOrigin</li>
<li>GCFont</li>
<li>GCSubwindowMode</li>
<li>GCGraphicsExposures</li>
<li>GCClipXOrigin</li>
<li>GCClipYOrigin</li>
<li>GCClipMask</li>
<li>GCDashOffset</li>
<li>GCDashList</li>
<li>GCArcMode</li>
</ul>
<p>
It is possible to set several attributes at the same
time (for example setting the attributes of a font and the
color which will be used to display a string), by OR'ing these
values in <span class="code">value_mask</span>. Then
<span class="code">value_list</span> has to be an array which
lists the value for the respective attributes. See Subsection
Drawing with a color to have an example.
</p>
<p>
<b>TODO</b>: set the links of the 3 subsections, once they will
be written :)
</p>
<p>
<b>TODO</b>: give an example which sets several attributes.
</p>
<li class="subtitle"><a name="drawingprim">Drawing primitives: point, line, box, circle,...</a></li>
<p>
After we have created a Graphic Context, we can draw on a
window using this Graphic Context, with a set of XCB
functions, collectively called "drawing primitive". Let see
how they are used.
</p>
<p>
To draw a point, or several points, we use
</p>
<pre class="code">
XCBVoidCookie XCBPolyPoint (XCBConnection *c, /* The connection to the X server */
BYTE coordinate_mode, /* Coordinate mode, usually set to CoordModeOrigin */
XCBDRAWABLE drawable, /* The drawable on which we want to draw the point(s) */
XCBGCONTEXT gc, /* The Graphic Context we use to draw the point(s) */
CARD32 points_len, /* The number of points */
const XCBPOINT *points); /* An array of points */
</pre>
<p>
The <span class="code">coordinate_mode</span> parameter
specifies the coordinate mode. Available values are
</p>
<ul>
<li><span class="code">CoordModeOrigin</span></li>
<li><span class="code">CoordModePrevious</span></li>
</ul>
<p>
The <span class="code">XCBPOINT</span> type is just a
structure with two fields (the coordinates of the point):
</p>
<pre class="code">
typedef struct {
INT16 x;
INT16 y;
} XCBPOINT;
</pre>
<p>
You could see an example in xpoints.c. <b>TODO</b> Set the link.
</p>
<p>
To draw a line, or a polygonal line, we use
</p>
<pre class="code">
XCBVoidCookie XCBPolyLine (XCBConnection *c, /* The connection to the X server */
BYTE coordinate_mode, /* Coordinate mode, usually set to CoordModeOrigin */
XCBDRAWABLE drawable, /* The drawable on which we want to draw the line(s) */
XCBGCONTEXT gc, /* The Graphic Context we use to draw the line(s) */
CARD32 points_len, /* The number of points in the polygonal line */
const XCBPOINT *points); /* An array of points */
</pre>
<p>
This function will draw the line between the first and the
second points, then the line between the second and the third
points, and so on.
</p>
<p>
To draw a segment, or several segments, we use
</p>
<pre class="code">
XCBVoidCookie XCBPolySegment (XCBConnection *c, /* The connection to the X server */
XCBDRAWABLE drawable, /* The drawable on which we want to draw the segment(s) */
XCBGCONTEXT gc, /* The Graphic Context we use to draw the segment(s) */
CARD32 segments_len, /* The number of segments */
const XCBSEGMENT *segments); /* An array of segments */
</pre>
<p>
The <span class="code">XCBSEGMENT</span> type is just a
structure with four fields (the coordinates of the two points
that define the segment):
</p>
<pre class="code">
typedef struct {
INT16 x1;
INT16 y1;
INT16 x2;
INT16 y2;
} XCBSEGMENT;
</pre>
<p>
To draw a rectangle, or several rectangles, we use
</p>
<pre class="code">
XCBVoidCookie XCBPolyRectangle (XCBConnection *c, /* The connection to the X server */
XCBDRAWABLE drawable, /* The drawable on which we want to draw the rectangle(s) */
XCBGCONTEXT gc, /* The Graphic Context we use to draw the rectangle(s) */
CARD32 rectangles_len, /* The number of rectangles */
const XCBRECTANGLE *rectangles); /* An array of rectangles */
</pre>
<p>
The <span class="code">XCBRECTANGLE</span> type is just a
structure with four fields (the coordinates of the top-left
corner of the rectangle, and its width and height):
</p>
<pre class="code">
typedef struct {
INT16 x;
INT16 y;
CARD16 width;
CARD16 height;
} XCBRECTANGLE;
</pre>
<p>
<b>TODO</b>: there's no coordinate_mode. Is it normal ?
</p>
<p>
To draw an elliptical arc, or several elliptical arcs, we use
</p>
<pre class="code">
XCBVoidCookie XCBPolyArc (XCBConnection *c, /* The connection to the X server */
XCBDRAWABLE drawable, /* The drawable on which we want to draw the arc(s) */
XCBGCONTEXT gc, /* The Graphic Context we use to draw the arc(s) */
CARD32 arcs_len, /* The number of arcs */
const XCBARC *arcs); /* An array of arcs */
</pre>
<p>
The <span class="code">XCBARC</span> type is a structure with
six fields:
</p>
<pre class="code">
typedef struct {
INT16 x; /* Top left x coordinate of the rectangle surrounding the ellipse */
INT16 y; /* Top left y coordinate of the rectangle surrounding the ellipse */
CARD16 width; /* Width of the rectangle surrounding the ellipse */
CARD16 height; /* Height of the rectangle surrounding the ellipse */
INT16 angle1; /* Angle at which the arc begins */
INT16 angle2; /* Angle at which the arc ends */
} XCBARC;
</pre>
<div class="emph">
<p>
Note: the angles are expressed in units of 1/64 of a degree,
so to have an angle of 90 degrees, starting at 0,
<span class="code">angle1 = 0</span> and
<span class="code">angle2 = 90 << 6</span>. Positive angles
indicate counterclockwise motion, while negative angles
indicate clockwise motion.
</p>
</div>
<p>
<b>TODO</b>: there's no coordinate_mode. Is it normal ?
</p>
<p>
<b>TODO</b>: I think that (x,y) should be the center of the
ellipse, and (width, height) the radius. It's more logical.
</p>
<p>
The corresponding function which fill inside the geometrical
object are listed below, without further explanation, as they
are used as the above functions.
</p>
<p>
To Fill a polygon defined by the points given as arguments ,
we use
</p>
<pre class="code">
XCBVoidCookie XCBFillPoly (XCBConnection *c,
XCBDRAWABLE drawable,
XCBGCONTEXT gc,
CARD8 shape,
CARD8 coordinate_mode,
CARD32 points_len,
const XCBPOINT *points);
</pre>
<p>
The <span class="code">shape</span> parameter specifies a
shape that helps the server to improve performance. Available
values are
</p>
<ul>
<li><span class="code">Complex</span></li>
<li><span class="code">Convex</span></li>
<li><span class="code">Nonconvex</span></li>
</ul>
<p>
To fill one or several rectangles, we use
</p>
<pre class="code">
XCBVoidCookie XCBPolyFillRectangle (XCBConnection *c,
XCBDRAWABLE drawable,
XCBGCONTEXT gc,
CARD32 rectangles_len,
const XCBRECTANGLE *rectangles);
</pre>
<p>
To fill one or several arcs, we use
</p>
<pre class="code">
XCBVoidCookie XCBPolyFillArc (XCBConnection *c,
XCBDRAWABLE drawable,
XCBGCONTEXT gc,
CARD32 arcs_len,
const XCBARC *arcs);
</pre>
<p></p>
<p>
To illustrate these functions, here is an example that draws
four points, a polygonal line, two segments, two rectangles
and two arcs. Remark that we use events for the first time, as
an introduction to the next section.
</p>
<pre class="code">
#include <stdlib.h>
#include <stdio.h>
#include <X11/XCB/xcb.h>
/* Get the depth of the screen. Needed in order to draw something */
int
get_depth(XCBConnection *c,
XCBSCREEN *root)
{
XCBDRAWABLE drawable;
XCBGetGeometryRep *geom;
int depth;
drawable.window = root->root;
geom = XCBGetGeometryReply (c, XCBGetGeometry(c, drawable), 0);
if(!geom)
{
perror ("GetGeometry(root) failed");
exit (0);
}
depth = geom->depth;
free (geom);
return depth;
}
int
main (int argc, char *argv[])
{
XCBConnection *c;
XCBSCREEN *screen;
XCBDRAWABLE win;
XCBGCONTEXT foreground;
XCBGenericEvent *e;
CARD32 mask = 0;
CARD32 values[2];
/* geometric objects */
XCBPOINT points[] = {
{10, 10},
{10, 20},
{20, 10},
{20, 20}};
XCBPOINT polyline[] = {
{50, 10},
{55, 30},
{80, 10},
{90, 20}};
XCBSEGMENT segments[] = {
{100, 10, 140, 30},
{110, 25, 130, 60}};
XCBRECTANGLE rectangles[] = {
{ 10, 50, 40, 20},
{ 80, 50, 10, 40}};
XCBARC arcs[] = {
{10, 100, 60, 40, 0, 90 << 6},
{90, 100, 55, 40, 0, 270 << 6}};
/* Open the connection to the X server */
c = XCBConnect (NULL, NULL);
/* Get the first screen */
screen = XCBConnSetupSuccessRepRootsIter (XCBGetSetup (c)).data;
/* Create black (foregroung) graphic context */
win.window = screen->root;
foreground = XCBGCONTEXTNew (c);
mask = GCForeground | GCGraphicsExposures;
values[0] = screen->black_pixel;
values[1] = 0;
XCBCreateGC (c, foreground, win, mask, values);
/* Ask for our window's Id */
win.window = XCBWINDOWNew(c);
/* Create the window */
mask = XCBCWBackPixel | XCBCWEventMask;
values[0] = screen->white_pixel;
values[1] = ExposureMask;
XCBCreateWindow (c, /* Connection */
0, /* depth */
win.window, /* window Id */
screen->root, /* parent window */
0, 0, /* x, y */
150, 150, /* width, height */
10, /* border_width */
InputOutput, /* class */
screen->root_visual, /* visual */
mask, values); /* masks */
/* Map the window on the screen */
XCBMapWindow (c, win.window);
/* We flush the request */
XCBSync (c, 0);
while ((e = XCBWaitEvent (c)))
{
switch (e->response_type)
{
case XCBExpose:
{
/* We draw the points */
XCBPolyPoint (c, CoordModeOrigin, win, foreground, 4, points);
/* We draw the polygonal line */
XCBPolyLine (c, CoordModeOrigin, win, foreground, 4, polyline);
/* We draw the segements */
XCBPolySegment (c, win, foreground, 2, segments);
/* We draw the rectangles */
XCBPolyRectangle (c, win, foreground, 2, rectangles);
/* We draw the arcs */
XCBPolyArc (c, win, foreground, 2, arcs);
/* We flush the request */
XCBSync (c, 0);
break;
}
default:
{
/* Unknown event type, ignore it */
break;
}
}
/* Free the Generic Event */
free (e);
}
return 1;
}
</pre>
</ol>
<li class="title"><a name="xevents">X Events</a></li>
<p>
In an X program, everything is driven by events. Event painting
on the screen is sometimes done as a response to an event (an
<span class="code">Expose</span> event). If part of a program's
window that was hidden, gets exposed (e.g. the window was raised
above other widows), the X server will send an "expose" event to
let the program know it should repaint that part of the
window. User input (key presses, mouse movement, etc) is also
received as a set of events.
</p>
<ol>
<li class="subtitle"><a name="register">Registering for event types using event masks</a></li>
<p>
During the creation of a window, you should give it what kind
of events it wishes to receive. Thus, you may register for
various mouse (also called pointer) events, keyboard events,
expose events, and so on. This is done for optimizing the
server-to-client connection (i.e. why send a program (that
might even be running at the other side of the globe) an event
it is not interested in ?)
</p>
<p>
In XCB, you use the "value_mask" and "value_list" data in the
<span class="code">XCBCreateWindow()</span> function to
register for events. Here is how we register for
<span class="code">Expose</span> event when creating a window:
</p>
<pre class="code">
mask = XCBCWEventMask;
valwin[0] = ExposureMask;
win.window = XCBWINDOWNew (c);
XCBCreateWindow (c, depth, win.window, root->root,
0, 0, 150, 150, 10,
InputOutput, root->root_visual,
mask, valwin);
</pre>
<p>
<span class="code">ExposureMask</span> is a constant defined
in the "X.h" header file. If we wanted to register to several
event types, we can logically "or" them, as follows:
</p>
<pre class="code">
mask = XCBCWEventMask;
valwin[0] = ExposureMask | ButtonPressMask;
win.window = XCBWINDOWNew (c);
XCBCreateWindow (c, depth, win.window, root->root,
0, 0, 150, 150, 10,
InputOutput, root->root_visual,
mask, valwin);
</pre>
<p>
This registers for <span class="code">Expose</span> events as
well as for mouse button presses insode the created
window. You should note that a mask may represent several
event sub-types.
</p>
<p>
The values that a mask could take are given
by the <span class="code">XCBCW</span> enumeration:
</p>
<pre class="code">
typedef enum {
XCBCWBackPixmap = 1L<<0,
XCBCWBackPixel = 1L<<1,
XCBCWBorderPixmap = 1L<<2,
XCBCWBorderPixel = 1L<<3,
XCBCWBitGravity = 1L<<4,
XCBCWWinGravity = 1L<<5,
XCBCWBackingStore = 1L<<6,
XCBCWBackingPlanes = 1L<<7,
XCBCWBackingPixel = 1L<<8,
XCBCWOverrideRedirect = 1L<<9,
XCBCWSaveUnder = 1L<<10,
XCBCWEventMask = 1L<<11,
XCBCWDontPropagate = 1L<<12,
XCBCWColormap = 1L<<13,
XCBCWCursor = 1L<<14
} XCBCW;
</pre>
<div class="emph">
<p>Note: we must be careful when setting the values of the valwin
parameter, as they have to follow the order the
<span class="code">XCBCW</span> enumeration. Here is an
example:
</p>
</div>
<pre class="code">
mask = XCBCWEventMask | XCBCWBackPixmap;
valwin[0] = None; /* for XCBCWBackPixmap (whose value is 1) */
valwin[1] = ExposureMask | ButtonPressMask; /* for XCBCWEventMask, whose value (2048) */
/* is superior to the one of XCBCWBackPixmap */
</pre>
<p>
If the window has already been created, we can use the
<span class="code">XCBConfigureWindow()</span> function to set
the events that the window will receive. The subsection
<a href="#winconf">Configuring a window</a> shows its
prototype. As an example, here is a piece of code that
configures the window to receive the
<span class="code">Expose</span> and
<span class="code">ButtonPressMask</span> events:
</p>
<pre class="code">
const static CARD32 values[] = { ExposureMask | ButtonPressMask };
/* The connection c and the window win are supposed to be defined */
XCBConfigureWindow (c, win, XCBCWEventMask, values);
</pre>
<div class="emph">
<p>
Note: A common bug programmers do is adding code to handle new
event types in their program, while forgetting to add the
masks for these events in the creation of the window. Such a
programmer then should sit down for hours debugging his
program, wondering "Why doesn't my program notice that I
released the button?", only to find that they registered for
button press events but not for button release events.
</p>
</div>
<li class="subtitle"><a name="loop">Receiving events: writing the events loop</a></li>
<p>
After we have registered for the event types we are interested
in, we need to enter a loop of receiving events and handling
them. There are two ways to receive events: a blocking way and
a non blocking way:
</p>
<ul>
<li>
<span class="code">XCBWaitEvent (XCBConnection *c)</span>
is the blocking way. It waits (so blocks...) until an event is
queued in the X server. Then it retrieves it into a newly
allocated structure (it dequeues it from the queue) and returns
it. This structure has to be freed. The function returns
<span class="code">NULL</span> if an error occurs.
</li>
<br />
<li>
<span class="code">XCBPollForEvent (XCBConnection *c, int
*error)</span> is the non blocking way. It looks at the event
queue and returns (and dequeues too) an existing event into
a newly allocated structure. This structure has to be
freed. It returns <span class="code">NULL</span> if there is
no event. If an error occurs, the parameter <span
class="code">error</span> will be filled with the error
status.
</li>
</ul>
<p>
There are various ways to write such a loop. We present two
ways to write such a loop, with the two functions above. The
first one uses <span class="code">XCBWaitEvent</span>, which
is similar to an event Xlib loop using only <span
class="code">XNextEvent</span>:
</p>
<pre class="code">
XCBGenericEvent *e;
while ((e = XCBWaitEvent (c)))
{
switch (e->response_type)
{
case XCBExpose:
{
/* Handle the Expose event type */
XCBExposeEvent *ev = (XCBExposeEvent *)e;
/* ... */
break;
}
case XCBButtonPress:
{
/* Handle the ButtonPress event type */
XCBButtonPressEvent *ev = (XCBButtonPressEvent *)e;
/* ... */
break;
}
default:
{
/* Unknown event type, ignore it */
break;
}
}
/* Free the Generic Event */
free (e);
}
</pre>
<p>
You will certainly want to use <span
class="code">XCBPollForEvent(XCBConnection *c, int
*error)</span> if, in Xlib, you use <span
class="code">XPending</span>:
</p>
<pre class="code">
while (XPending (display))
{
XEvent ev;
XNextEvent(d, &ev);
/* Manage your event */
}
</pre>
<p>
Such a loop in XCB looks like:
</p>
<pre class="code">
XCBGenericEvent *ev;
while ((ev = XCBPollForEvent (conn, 0)))
{
/* Manage your event */
}
</pre>
<p>
The events are managed in the same way as with <span
class="code">XCBWaitEvent</span>.
Obviously, we will need to give the user some way of
terminating the program. This is usually done by handling a
special "quit" event, as we will soon see.
</p>
<div class="comp">
<div class="title">
Comparison Xlib/XCB
</div>
<div class="xlib">
<ul>
<li>XNextEvent ()</li>
</ul>
</div>
<div class="xcb">
<ul>
<li>XCBWaitEvent ()</li>
</ul>
</div>
<div class="xlib">
<ul>
<li>XPending ()</li>
<li>XNextEvent ()</li>
</ul>
</div>
<div class="xcb">
<ul>
<li>XCBPollForEvent ()</li>
<br />
</ul>
</div>
</div>
<p />
<li class="subtitle"><a name="expose">Expose events</a></li>
<p>
The <span class="code">Expose</span> event is one of the most
basic (and most used) events an application may receive. It
will be sent to us in one of several cases:
<ul>
<li>A window that covered part of our window has moved
away, exposing part (or all) of our window.</li>
<li>Our window was raised above other windows.</li>
<li>Our window mapped for the first time.</li>
<li>Our window was de-iconified.</li>
</ul>
</p>
<p>
You should note the implicit assumption hidden here: the
contents of our window is lost when it is being obscured
(covered) by either windows. One may wonder why the X server
does not save this contents. The answer is: to save
memory. After all, the number of windows on a display at a
given time may be very large, and storing the contents of all
of them might require a lot of memory. Actually, there is a
way to tell the X server to store the contents of a window in
special cases, as we will see later.
</p>
<p>
When we get an <span class="code">Expose</span> event, we
should take the event's data from the members of the following
structure:
</p>
<pre class="code">
typedef struct {
BYTE response_type; /* The type of the event, here it is XCBExpose */
CARD8 pad0;
CARD16 sequence;
XCBWINDOW window; /* The Id of the window that receives the event (in case */
/* our application registered for events on several windows */
CARD16 x; /* The x coordinate of the top-left part of the window that needs to be redrawn */
CARD16 y; /* The y coordinate of the top-left part of the window that needs to be redrawn */
CARD16 width; /* The width of the part of the window that needs to be redrawn */
CARD16 height; /* The height of the part of the window that needs to be redrawn */
CARD16 count;
} XCBExposeEvent;
</pre>
<li class="subtitle"><a name="userinput">Getting user input</a></li>
<p>
User input traditionally comes from two sources: the mouse
and the keyboard. Various event types exist to notify us of
user input (a key being presses on the keyboard, a key being
released on the keyboard, the mouse moving over our window,
the mouse entering (or leaving) our window, and so on.
</p>
<ol>
<li class="subsubtitle"><a name="mousepressrelease">Mouse button press and release events</a></li>
<p>
The first event type we will deal with is a mouse
button-press (or button-release) event in our window. In
order to register to such an event type, we should add one
(or more) of the following masks when we create our window:
</p>
<ul>
<li><span class="code">ButtonPressMask</span>: notify us
of any button that was pressed in one of our windows.</li>
<li><span class="code">ButtonReleaseMask</span>: notify us
of any button that was released in one of our windows.</li>
</ul>
<p>
The structure to be checked for in our events loop is the
same for these two events, and is the following:
</p>
<pre class="code">
typedef struct {
BYTE response_type; /* The type of the event, here it is XCBButtonPressEvent or XCBButtonReleaseEvent */
XCBBUTTON detail;
CARD16 sequence;
XCBTIMESTAMP time; /* Time, in milliseconds the event took place in */
XCBWINDOW root;
XCBWINDOW event;
XCBWINDOW child;
INT16 root_x;
INT16 root_y;
INT16 event_x; /* The x coordinate where the mouse has been pressed in the window */
INT16 event_y; /* The y coordinate where the mouse has been pressed in the window */
CARD16 state; /* A mask of the buttons (or keys) during the event */
BOOL same_screen;
} XCBButtonPressEvent;
typedef XCBButtonPressEvent XCBButtonReleaseEvent;
</pre>
<p>
The <span class="code">time</span> field may be used to calculate "double-click"
situations by an application (e.g. if the mouse button was
clicked two times in a duration shorter than a given amount
of time, assume this was a double click).
</p>
<p>
The <span class="code">state</span> field is a mask of the buttons held down during
the event. It is a bitwise OR of any of the following:
</p>
<ul>
<li><span class="code">Button1Mask</span></li>
<li><span class="code">Button2Mask</span></li>
<li><span class="code">Button3Mask</span></li>
<li><span class="code">Button4Mask</span></li>
<li><span class="code">Button5Mask</span></li>
<li><span class="code">ShiftMask</span></li>
<li><span class="code">LockMask</span></li>
<li><span class="code">ControlMask</span></li>
<li><span class="code">Mod1Mask</span></li>
<li><span class="code">Mod2Mask</span></li>
<li><span class="code">Mod3Mask</span></li>
<li><span class="code">Mod4Mask</span></li>
<li><span class="code">Mod5Mask</span></li>
</ul>
<p>
Their names are self explanatory, where the first 5 refer to
the mouse buttons that are being pressed, while the rest
refer to various "special keys" that are being pressed (Mod1
is usually the 'Alt' key or the 'Meta' key).
</p>
<p>
<b>TODO:</b> Problem: it seems that the state does not
change when clicking with various buttons.
</p>
<li class="subsubtitle"><a name="mousemvnt">Mouse movement events</a></li>
<p>
Similar to mouse button press and release events, we also
can be notified of various mouse movement events. These can
be split into two families. One is of mouse pointer
movement while no buttons are pressed, and the second is a
mouse pointer motion while one (or more) of the buttons are
pressed (this is sometimes called "a mouse drag operation",
or just "dragging"). The following event masks may be added
during the creation of our window:
</p>
<ul>
<li><span class="code">PointerMotionMask</span>: events of
the pointer moving in one of the windows controlled by our
application, while no mouse button is held pressed.</li>
<li><span class="code">ButtonMotionMask</span>: Events of
the pointer moving while one or more of the mouse buttons
is held pressed.</li>
<li><span class="code">Button1MotionMask</span>: same as
<span class="code">ButtonMotionMask</span>, but only when
the 1st mouse button is held pressed.</li>
<li><span class="code">Button2MotionMask</span>,
<span class="code">Button3MotionMask</span>,
<span class="code">Button4MotionMask</span>,
<span class="code">Button5MotionMask</span>: same as
<span class="code">Button1MotionMask</span>, but
respectively for 2nd, 3rd, 4th and 5th mouse button.</li>
</ul>
<p>
The structure to be checked for in our events loop is the
same for these events, and is the following:
</p>
<pre class="code">
typedef struct {
BYTE response_type; /* The type of the event */
BYTE detail;
CARD16 sequence;
XCBTIMESTAMP time; /* Time, in milliseconds the event took place in */
XCBWINDOW root;
XCBWINDOW event;
XCBWINDOW child;
INT16 root_x;
INT16 root_y;
INT16 event_x; /* The x coordinate of the mouse when the event was generated */
INT16 event_y; /* The y coordinate of the mouse when the event was generated */
CARD16 state; /* A mask of the buttons (or keys) during the event */
BOOL same_screen;
} XCBMotionNotifyEvent;
</pre>
<li class="subsubtitle"><a name="mouseenter">Mouse pointer enter and leave events</a></li>
<p>
Another type of event that applications might be interested
at, is a mouse pointer entering a window the program
controls, or leaving such a window. Some programs use these
events to show the user tht the applications is now in
focus. In order to register for such an event type, we
should add one (or more) of the following masks when we
create our window:
</p>
<ul>
<li><span class="code">EnterWindowMask</span>: notify us
when the mouse pointer enters any of our controlled
windows.</li>
<li><span class="code">LeaveWindowMask</span>: notify us
when the mouse pointer leaves any of our controlled
windows.</li>
</ul>
<p>
The structure to be checked for in our events loop is the
same for these two events, and is the following:
</p>
<pre class="code">
typedef struct {
BYTE response_type; /* The type of the event */
BYTE detail;
CARD16 sequence;
XCBTIMESTAMP time; /* Time, in milliseconds the event took place in */
XCBWINDOW root;
XCBWINDOW event;
XCBWINDOW child;
INT16 root_x;
INT16 root_y;
INT16 event_x; /* The x coordinate of the mouse when the event was generated */
INT16 event_y; /* The y coordinate of the mouse when the event was generated */
CARD16 state; /* A mask of the buttons (or keys) during the event */
BYTE mode; /* The number of mouse button that was clicked */
BYTE same_screen_focus;
} XCBEnterNotifyEvent;
typedef XCBEnterNotifyEvent XCBLeaveNotifyEvent;
</pre>
<li class="subsubtitle"><a name="focus">The keyboard focus</a></li>
<p>
There may be many windows on a screen, but only a single
keyboard attached to them. How does the X server then know
which window should be sent a given keyboard input ? This is
done using the keyboard focus. Only a single window on the
screen may have the keyboard focus at a given time. There
is a XCB function that allow a program to set the keyboard
focus to a given window. The user can usually set the
keyboard ficus using the window manager (often by clicking
on the title bar of the desired window). Once our window
has the keyboard focus, every key press or key release will
cause an event to be sent to our program (if it regsitered
for these event types...).
</p>
<li class="subsubtitle"><a name="keypress">Keyboard press and release events</a></li>
<p>
If a window controlled by our program currently holds the
keyboard focus, it can receive key press and key release
events. So, we should add one (or more) of the following
masks when we create our window:
</p>
<ul>
<li><span class="code">KeyPressMask</span>: notify us when
a key was pressed while any of our controlled windows had
the keyboard focus.</li>
<li><span class="code">KeyReleaseMask</span>: notify us
when a key was released while any of our controlled
windows had the keyboard focus.</li>
</ul>
<p>
The structure to be checked for in our events loop is the
same for these two events, and is the following:
</p>
<pre class="code">
typedef struct {
BYTE response_type; /* The type of the event */
XCBKEYCODE detail;
CARD16 sequence;
XCBTIMESTAMP time; /* Time, in milliseconds the event took place in */
XCBWINDOW root;
XCBWINDOW event;
XCBWINDOW child;
INT16 root_x;
INT16 root_y;
INT16 event_x;
INT16 event_y;
CARD16 state;
BOOL same_screen;
} XCBKeyPressEvent;
typedef XCBKeyPressEvent XCBKeyReleaseEvent;
</pre>
<p>
The <span class="code">detail</span> field refer to the
physical key on the keyboard.
</p>
<p>
<b>TODO:</b> Talk about getting the ASCII code from the key code.
</p>
</ol>
<li class="subtitle"><a name="eventex">X events: a complete example</a></li>
<p>
As an example for handling events, we show a program that
creates a window, enter an events loop and check for all the
events described above, and write on the terminal the relevant
characteristics of the event. With this code, it should be
easy to add drawing operations, like those which have been
described above.
</p>
<pre class="code">
#include <malloc.h>
#include <stdio.h>
#include <X11/XCB/xcb.h>
int
main (int argc, char *argv[])
{
XCBConnection *c;
XCBSCREEN *screen;
XCBDRAWABLE win;
XCBGenericEvent *e;
CARD32 mask = 0;
CARD32 values[2];
/* Open the connection to the X server */
c = XCBConnect (NULL, NULL);
/* Get the first screen */
screen = XCBConnSetupSuccessRepRootsIter (XCBGetSetup (c)).data;
/* Ask for our window's Id */
win.window = XCBWINDOWNew(c);
/* Create the window */
mask = XCBCWBackPixel | XCBCWEventMask;
values[0] = screen->white_pixel;
values[1] = ExposureMask | ButtonPressMask | ButtonReleaseMask |
PointerMotionMask | EnterWindowMask | LeaveWindowMask |
KeyPressMask | KeyReleaseMask;
XCBCreateWindow (c, /* Connection */
0, /* depth */
win.window, /* window Id */
screen->root, /* parent window */
0, 0, /* x, y */
150, 150, /* width, height */
10, /* border_width */
InputOutput, /* class */
screen->root_visual, /* visual */
mask, values); /* masks */
/* Map the window on the screen */
XCBMapWindow (c, win.window);
XCBSync (c, 0);
while ((e = XCBWaitEvent (c)))
{
switch (e->response_type)
{
case XCBExpose:
{
XCBExposeEvent *ev = (XCBExposeEvent *)e;
printf ("Window %ld exposed. Region to be redrawn at location (%d,%d), with dimension (%d,%d)\n",
ev->window.xid, ev->x, ev->y, ev->width, ev->height);
break;
}
case XCBButtonPress:
{
XCBButtonPressEvent *ev = (XCBButtonPressEvent *)e;
int button_num = 0;
if ((ev->state | Button1Mask) == Button1Mask)
button_num = 1;
if ((ev->state | Button2Mask) == Button2Mask)
button_num = 2;
if ((ev->state | Button3Mask) == Button3Mask)
button_num = 3;
if ((ev->state | Button4Mask) == Button4Mask)
button_num = 4;
if ((ev->state | Button5Mask) == Button5Mask)
button_num = 5;
switch (ev->detail.id)
{
case 4:
{
printf ("Wheel Button up in window %ld, at coordinates (%d,%d)\n",
ev->event.xid, ev->event_x, ev->event_y);
break;
}
case 5:
{
printf ("Wheel Button down in window %ld, at coordinates (%d,%d)\n",
ev->event.xid, ev->event_x, ev->event_y);
break;
}
default:
printf ("Button %d pressed in window %ld, at coordinates (%d,%d)\n",
ev->detail.id, ev->event.xid, ev->event_x, ev->event_y);
}
break;
}
case XCBButtonRelease:
{
XCBButtonReleaseEvent *ev = (XCBButtonReleaseEvent *)e;
int button_num = 0;
if ((ev->state | Button1Mask) == Button1Mask)
button_num = 1;
if ((ev->state | Button2Mask) == Button2Mask)
button_num = 2;
if ((ev->state | Button3Mask) == Button3Mask)
button_num = 3;
if ((ev->state | Button4Mask) == Button4Mask)
button_num = 4;
if ((ev->state | Button5Mask) == Button5Mask)
button_num = 5;
printf ("Button %d released in window %ld, at coordinates (%d,%d)\n",
ev->detail.id, ev->event.xid, ev->event_x, ev->event_y);
break;
}
case XCBMotionNotify:
{
XCBMotionNotifyEvent *ev = (XCBMotionNotifyEvent *)e;
printf ("Mouse moved in window %ld, at coordinates (%d,%d)\n",
ev->event.xid, ev->event_x, ev->event_y);
break;
}
case XCBEnterNotify:
{
XCBEnterNotifyEvent *ev = (XCBEnterNotifyEvent *)e;
printf ("Mouse entered window %ld, at coordinates (%d,%d)\n",
ev->event.xid, ev->event_x, ev->event_y);
break;
}
case XCBLeaveNotify:
{
XCBLeaveNotifyEvent *ev = (XCBLeaveNotifyEvent *)e;
printf ("Mouse leaved window %ld, at coordinates (%d,%d)\n",
ev->event.xid, ev->event_x, ev->event_y);
break;
}
case XCBKeyPress:
{
XCBKeyPressEvent *ev = (XCBKeyPressEvent *)e;
printf ("Key pressed in window %ld\n",
ev->event.xid);
break;
}
case XCBKeyRelease:
{
XCBKeyReleaseEvent *ev = (XCBKeyReleaseEvent *)e;
printf ("Key releaseed in window %ld\n",
ev->event.xid);
break;
}
default:
{
/* Unknown event type, ignore it */
break;
}
}
/* Free the Generic Event */
free (e);
}
return 1;
}
</pre>
</ol>
<li class="title"><a name="font">Handling text and fonts</a></li>
<p>
Besides drawing graphics on a window, we often want to draw
text. Text strings have two major properties: the characters to
be drawn and the font with which they are drawn. In order to
draw text, we need to first request the X server to load a
font. We then assign a font to a Graphic Context, and finally, we
draw the text in a window, using the Graphic Context.
</p>
<ol>
<li class="subtitle"><a name="fontstruct">The Font structure</a></li>
<p>
In order to support flexible fonts, a font structure is
defined. You know what ? Its an Id:
</p>
<pre class="code">
typedef struct {
CARD32 xid;
} XCBFONT;
</pre>
<p>
It is used to contain information about a font, and is passed
to several functions that handle fonts selection and text drawing.
</p>
</ol>
<li class="title"><a name="wm">Interacting with the window manager</a></li>
<p>
After we have seen how to create windows and draw on them, we
take one step back, and look at how our windows are interacting
with their environment (the full screen and the other
windows). First of all, our application needs to interact with
the window manager. The window manager is responsible to
decorating drawn windows (i.e. adding a frame, an iconify
button, a system menu, a title bar, etc), as well as handling
icons shown when windows are being iconified. It also handles
ordering of windows on the screen, and other administrative
tasks. We need to give it various hints as to how we want it to
treat our application's windows.
</p>
<ol>
<li class="subtitle"><a name="wmprop">Window properties</a></li>
<p>
Many of the parameters communicated to the window manager are
passed using data called "properties". These properties are
attached by the X server to different windows, and are stores
in a format that makes it possible to read them from different
machines that may use different architectures (remember that
an X client program may run on a remote machine).
</p>
<p>
The property and its type (a string, an integer, etc) are
Id. Their type are <span class="code">XCBATOM</span>:
</p>
<pre class="code">
typedef struct {
CARD32 xid;
} XCBATOM;
</pre>
<p>
To change the property of a window, we use the following
function:
</p>
<pre class="code">
XCBVoidCookie XCBChangeProperty (XCBConnection *c, /* Connection to the X server */
CARD8 mode, /* Property mode */
XCBWINDOW window, /* Window */
XCBATOM property, /* Property to change */
XCBATOM type, /* Type of the property */
CARD8 format, /* Format of the property (8, 16, 32) */
CARD32 data_len, /* Length of the data parameter */
const void *data); /* Data */
</pre>
<p>
The <span class="code">mode</span> parameter coud be one of
the following value (defined in the X.h header file):
</p>
<ul>
<li>PropModeReplace</li>
<li>PropModePrepend</li>
<li>PropModeAppend</li>
</ul>
<p></p>
<li class="subtitle"><a name="wmname">Setting the window name and icon name</a></li>
<p>
The firt thing we want to do would be to set the name for our
window. This is done using the
<span class="code">XCBChangeProperty()</span> function. This
name may be used by the window manager as the title of the
window (in the title bar), in a task list, etc. The property
atom to use to set the name of a window is
<span class="code">WM_NAME</span> (and
<span class="code">WM_ICON_NAME</span> for the iconified
window) and its type is <span class="code">STRING</span>. Here
is an example of utilization:
</p>
<pre class="code">
#include <string.h>
#include <X11/XCB/xcb.h>
#include <X11/XCB/xcb_atom.h>
int
main (int argc, char *argv[])
{
XCBConnection *c;
XCBSCREEN *screen;
XCBDRAWABLE win;
char *title = "Hello World !";
char *title_icon = "Hello World ! (iconified)";
/* Open the connection to the X server */
c = XCBConnect (NULL, NULL);
/* Get the first screen */
screen = XCBConnSetupSuccessRepRootsIter (XCBGetSetup (c)).data;
/* Ask for our window's Id */
win.window = XCBWINDOWNew(c);
/* Create the window */
XCBCreateWindow (c, /* Connection */
0, /* depth */
win.window, /* window Id */
screen->root, /* parent window */
0, 0, /* x, y */
250, 150, /* width, height */
10, /* border_width */
InputOutput, /* class */
screen->root_visual, /* visual */
0, NULL); /* masks, not used */
/* Set the title of the window */
XCBChangeProperty(c, PropModeReplace, win.window,
WM_NAME, STRING, 8,
strlen(title), title);
/* Set the title of the window icon */
XCBChangeProperty(c, PropModeReplace, win.window,
WM_ICON_NAME, STRING, 8,
strlen(title_icon), title_icon);
/* Map the window on the screen */
XCBMapWindow (c, win.window);
XCBSync (c, 0);
while (1) {}
return 1;
}
</pre>
<div class="emph">
<p>Note: the use of the atoms needs our program to be compiled
and linked against xcb_atom, so that we have to use
</p>
</div>
<pre class="text">
gcc prog.c -o prog `pkg-config --cflags --libs xcb_atom`
</pre>
<div class="emph">
<p>
for the program to compile fine.
</p>
</div>
</ol>
<li class="title"><a name="winop">Simple window operations</a></li>
<p>
One more thing we can do to our window is manipulate them on the
screen (resize them, move them, raise or lower them, iconify
them, and so on). Some window operations functions are supplied
by XCB for this purpose.
</p>
<ol>
<li class="subtitle"><a name="winmap">Mapping and un-mapping a window</a></li>
<p>
The first pair of operations we can apply on a window is
mapping it, or un-mapping it. Mapping a window causes the
window to appear on the screen, as we have seen in our simple
window program example. Un-mapping it causes it to be removed
from the screen (although the window as a logical entity still
exists). This gives the effect of making a window hidden
(unmapped) and shown again (mapped). For example, if we have a
dialog box window in our program, instead of creating it every
time the user asks to open it, we can create the window once,
in an un-mapped mode, and when the user asks to open it, we
simply map the window on the screen. When the user clicked the
'OK' or 'Cancel' button, we simply un-map the window. This is
much faster than creating and destroying the window, however,
the cost is wasted resources, both on the client side, and on
the X server side.
</p>
<p>
To map a window, you use the following function:
</p>
<pre class="code">
XCBVoidCookie XCBMapWindow(XCBConnection *c, XCBWINDOW window);
</pre>
<p>
To have a simple example, see the <a href="#helloworld">example</a>
above. The mapping operation will cause an
<span class="code">Expose</span> event to be sent to our
application, unless the window is completely covered by other
windows.
</p>
<p>
Un-mapping a window is also simple. You use the function
</p>
<pre class="code">
XCBVoidCookie XCBUnmapWindow(XCBConnection *c, XCBWINDOW window);
</pre>
<p>
The utilization of this function is the same as
<span class="code">XCBMapWindow()</span>.
</p>
<li class="subtitle"><a name="winconf">Configuring a window</a></li>
<p>
As we have seen when we have created our first window, in the
X Events subsection, we can set some attributes to the window
(that is, the position, the size, the events the window will
receive, etc). If we want to modify them, but the window is
already created, we can change them by using the following
function:
</p>
<pre class="code">
XCBVoidCookie XCBConfigureWindow (XCBConnection *c, /* The connection to the X server*/
XCBWINDOW window, /* The window to configure */
CARD16 value_mask, /* The mask */
const CARD32 *value_list); /* The values to set */
</pre>
<p>
We set the <span class="code">value_mask</span> to one or
several mask values that are in the X.h header:
<ul>
<li><span class="code">CWX</span>: new x coordinate of the window's top left corner</li>
<li><span class="code">CWY</span>: new y coordinate of the window's top left corner</li>
<li><span class="code">CWWidth</span>: new width of the window</li>
<li><span class="code">CWHeight</span>: new height of the window</li>
<li><span class="code">CWBorderWidth</span>: new width of the border of the window</li>
<li><span class="code">CWSibling</span></li>
<li><span class="code">CWStackMode</span>: the new stacking order</li>
</ul>
</p>
<p>
We then give to <span class="code">value_mask</span> the new
value. We now describe how to use
<span class="code">XCBConfigureWindow</span> in some useful
situations.
</p>
<li class="subtitle"><a name="winmove">Moving a window around the screen</a></li>
<p>
An operation we might want to do with windows is to move them
to a different location. This can be done like this:
</p>
<pre class="code">
const static CARD32 values[] = { 10, 20 };
/* The connection c and the window win are supposed to be defined */
/* Move the window to coordinates x = 10 and y = 20 */
XCBConfigureWindow (c, win, CWX | CWY, values);
</pre>
<p>
Note that when the window is moved, it might get partially
exposed or partially hidden by other windows, and thus we
might get <span class="code">Expose</span> events due to this
operation.
</p>
<li class="subtitle"><a name="winsize">Resizing a window</a></li>
<p>
Yet another operation we can do is to change the size of a
window. This is done using the following code:
</p>
<pre class="code">
const static CARD32 values[] = { 200, 300 };
/* The connection c and the window win are supposed to be defined */
/* Resize the window to width = 10 and height = 20 */
XCBConfigureWindow (c, win, CWWidth | CWHeight, values);
</pre>
<p>
We can also combine the move and resize operations using one
single call to <span class="code">XCBConfigureWindow</span>:
</p>
<pre class="code">
const static CARD32 values[] = { 10, 20, 200, 300 };
/* The connection c and the window win are supposed to be defined */
/* Move the window to coordinates x = 10 and y = 20 */
/* and resize the window to width = 10 and height = 20 */
XCBConfigureWindow (c, win, CWX | CWY | CWWidth | CWHeight, values);
</pre>
<li class="subtitle"><a name="winstack">Changing windows stacking order: raise and lower</a></li>
<p>
Until now, we changed properties of a single window. We'll see
that there are properties that relate to the window and other
windows. One of hem is the stacking order. That is, the order
in which the windows are layered on top of each other. The
front-most window is said to be on the top of the stack, while
the back-most window is at the bottom of the stack. Here is
how to manipulate our windows stack order:
</p>
<pre class="code">
const static CARD32 values[] = { Above };
/* The connection c and the window win are supposed to be defined */
/* Move the window on the top of the stack */
XCBConfigureWindow (c, win, CWStackMode, values);
</pre>
<pre class="code">
const static CARD32 values[] = { Below };
/* The connection c and the window win are supposed to be defined */
/* Move the window on the bottom of the stack */
XCBConfigureWindow (c, win, CWStackMode, values);
</pre>
<li class="subtitle"><a name="wingetinfo">Getting information about a window</a></li>
<p>
Just like we can set various attributes of our windows, we can
also ask the X server supply the current values of these
attributes. For example, we can check where a window is
located on the screen, what is its current size, whether it is
mapped or not, etc. The structure that contains some of this
information is
</p>
<pre class="code">
typedef struct {
BYTE response_type;
CARD8 depth; /* depth of the window */
CARD16 sequence;
CARD32 length;
XCBWINDOW root; /* Id of the root window *>
INT16 x; /* X coordinate of the window's location */
INT16 y; /* Y coordinate of the window's location */
CARD16 width; /* Width of the window */
CARD16 height; /* Height of the window */
CARD16 border_width; /* Width of the window's border */
} XCBGetGeometryRep;
</pre>
<p>
XCB fill this structure with two functions:
</p>
<pre class="code">
XCBGetGeometryCookie XCBGetGeometry (XCBConnection *c,
XCBDRAWABLE drawable);
XCBGetGeometryRep *XCBGetGeometryReply (XCBConnection *c,
XCBGetGeometryCookie cookie,
XCBGenericError **e);
</pre>
<p>
You use them as follows:
</p>
<pre class="code">
XCBConnection *c;
XCBDRAWABLE win;
XCBGetGeometryRep *geom;
/* You initialize c and win */
geom = XCBGetGeometryReply (c, XCBGetGeometry (c, win), 0);
/* Do something with the fields of geom */
free (geom);
</pre>
<p>
Remark that you have to free the structure, as
<span class="code">XCBGetGeometryReply</span> allocates a
newly one.
</p>
<p>
One problem is that the returned location of the window is
relative to its parent window. This makes these coordinates
rather useless for any window manipulation functions, like
moving it on the screen. In order to overcome this problem, we
need to take a two-step operation. First, we find out the Id
of the parent window of our window. We then translate the
above relative coordinates to the screen coordinates.
</p>
<p>
To get the Id of the parent window, we need this structure:
</p>
<pre class="code">
typedef struct {
BYTE response_type;
CARD8 pad0;
CARD16 sequence;
CARD32 length;
XCBWINDOW root;
XCBWINDOW parent; /* Id of the parent window */
CARD16 children_len;
CARD8 pad1[14];
} XCBQueryTreeRep;
</pre>
<p>
To fill this structure, we use these two functions:
</p>
<pre class="code">
XCBQueryTreeCookie XCBQueryTree (XCBConnection *c,
XCBWINDOW window);
XCBQueryTreeRep *XCBQueryTreeReply (XCBConnection *c,
XCBQueryTreeCookie cookie,
XCBGenericError **e);
</pre>
<p>
The translated coordinates will be found in this structure:
</p>
<pre class="code">
typedef struct {
BYTE response_type;
BOOL same_screen;
CARD16 sequence;
CARD32 length;
XCBWINDOW child;
CARD16 dst_x; /* Translated x coordinate */
CARD16 dst_y; /* Translated y coordinate */
} XCBTranslateCoordinatesRep;
</pre>
<p>
As usual, we need two functions to fill this structure:
</p>
<pre class="code">
XCBTranslateCoordinatesCookie XCBTranslateCoordinates (XCBConnection *c,
XCBWINDOW src_window,
XCBWINDOW dst_window,
INT16 src_x,
INT16 src_y);
XCBTranslateCoordinatesRep *XCBTranslateCoordinatesReply (XCBConnection *c,
XCBTranslateCoordinatesCookie cookie,
XCBGenericError **e);
</pre>
<p>
We use them as follows:
</p>
<pre class="code">
XCBConnection *c;
XCBDRAWABLE win;
XCBGetGeometryRep *geom;
XCBQueryTreeRep *tree;
XCBTranslateCoordinatesRep *trans;
/* You initialize c and win */
geom = XCBGetGeometryReply (c, XCBGetGeometry (c, win), 0);
if (!geom)
return 0;
tree = XCBQueryTreeReply (c, XCBQueryTree (c, win), 0);
if (!tree)
return 0;
trans = XCBTranslateCoordinatesReply (c,
XCBTranslateCoordinates (c,
win,
tree->parent,
geom->x, geom->y),
0);
if (!trans)
return 0;
/* the translated coordinates are in trans->dst_x and trans->dst_y */
free (trans);
free (tree);
free (geom);
</pre>
<p>
Of course, as for <span class="code">geom</span>,
<span class="code">tree</span> and
<span class="code">trans</span> have to be freed.
</p>
<p>
The work is a bit hard, but XCB is a very low-level library.
</p>
<p>
<b>TODO:</b> the utilization of these functions should be a
prog, which displays the coordinates of the window.
</p>
<p>
There is another structure that gives informations about our window:
</p>
<pre class="code">
typedef struct {
BYTE response_type;
CARD8 backing_store;
CARD16 sequence;
CARD32 length;
XCBVISUALID visual; /* Visual of the window */
CARD16 _class;
CARD8 bit_gravity;
CARD8 win_gravity;
CARD32 backing_planes;
CARD32 backing_pixel;
BOOL save_under;
BOOL map_is_installed;
CARD8 map_state; /* Map state of the window */
BOOL override_redirect;
XCBCOLORMAP colormap; /* Colormap of the window */
CARD32 all_event_masks;
CARD32 your_event_mask;
CARD16 do_not_propagate_mask;
} XCBGetWindowAttributesRep;
</pre>
<p>
XCB supplies these two functions to fill it:
</p>
<pre class="code">
XCBGetWindowAttributesCookie XCBGetWindowAttributes (XCBConnection *c,
XCBWINDOW window);
XCBGetWindowAttributesRep *XCBGetWindowAttributesReply (XCBConnection *c,
XCBGetWindowAttributesCookie cookie,
XCBGenericError **e);
</pre>
<p>
You use them as follows:
</p>
<pre class="code">
XCBConnection *c;
XCBDRAWABLE win;
XCBGetWindowAttributesRep *attr;
/* You initialize c and win */
attr = XCBGetWindowAttributesReply (c, XCBGetWindowAttributes (c, win), 0);
if (!attr)
return 0;
/* Do something with the fields of attr */
free (attr);
</pre>
<p>
As for <span class="code">geom</span>,
<span class="code">attr</span> has to be freed.
</p>
</ol>
<li class="title"><a name="usecolor">Using colors to paint the rainbow</a></li>
<p>
Up until now, all our painting operation were done using black
and white. We will (finally) see now how to draw using colors.
</p>
<ol>
<li class="subtitle"><a name="colormap">Color maps</a></li>
<p>
In the beginning, there were not enough colors. Screen
controllers could only support a limited number of colors
simultaneously (initially 2, then 4, 16 and 256). Because of
this, an application could not just ask to draw in a "light
purple-red" color, and expect that color to be available. Each
application allocated the colors it needed, and when all the
color entries (4, 16, 256 colors) were in use, the next color
allocation would fail.
</p>
<p>
Thus, the notion of "a color map" was introduced. A color map
is a table whose size is the same as the number of
simultaneous colors a given screen controller. Each entry
contained the RGB (Red, Green and Blue) values of a different
color (all colors can be drawn using some combination of red,
green and blue). When an application wants to draw on the
screen, it does not specify which color to use. Rather, it
specifies which color entry of some color map to be used
during this drawing. Change the value in this color map entry
and the drawing will use a different color.
</p>
<p>
In order to be able to draw using colors that got something to
do with what the programmer intended, color map allocation
functions are supplied. You could ask to allocate entry for a
color with a set of RGB values. If one already existed, you
would get its index in the table. If none existed, and the
table was not full, a new cell would be allocated to contain
the given RGB values, and its index returned. If the table was
full, the procedure would fail. You could then ask to get a
color map entry with a color that is closest to the one you
were asking for. This would mean that the actual drawing on
the screen would be done using colors similar to what you
wanted, but not the same.
</p>
<p>
On today's more modern screens where one runs an X server with
support for 16 million colors, this limitation looks a little
silly, but remember that there are still older computers with
older graphics cards out there. Using color map, support for
these screen becomes transparent to you. On a display
supporting 16 million colors, any color entry allocation
request would succeed. On a display supporting a limited
number of colors, some color allocation requests would return
similar colors. It won't look as good, but your application
would still work.
</p>
<li class="subtitle"><a name="colormapalloc">Allocating and freeing Color Maps</a></li>
<p>
When you draw using XCB, you can choose to use the standard
color map of the screen your window is displayed on, or you
can allocate a new color map and apply it to a window. In the
latter case, each time the mouse moves onto your window, the
screen color map will be replaced by your window's color map,
and you'll see all the other windows on screen change their
colors into something quite bizzare. In fact, this is the
effect you get with X applications that use the "-install"
command line option.
</p>
<p>
In XCB, a color map is (as often in X) an Id:
</p>
<pre class="code">
typedef struct {
CARD32 xid;
} XCBCOLORMAP;
</pre>
<p>
In order to access the screen's default color map, you just
have to retrieve the <span class="code">default_colormap</span>
field of the <span class="code">XCBSCREEN</span> structure
(see Section
<a href="#screen">Checking basic information about a connection</a>):
</p>
<pre class="code">
#include <stdio.h>
#include <X11/XCB/xcb.h>
int
main (int argc, char *argv[])
{
XCBConnection *c;
XCBSCREEN *screen;
XCBCOLORMAP colormap;
/* Open the connection to the X server and get the first screen */
c = XCBConnect (NULL, NULL);
screen = XCBConnSetupSuccessRepRootsIter (XCBGetSetup (c)).data;
colormap = screen->default_colormap;
return 1;
}
</pre>
<p>
This will return the color map used by default on the first
screen (again, remember that an X server may support several
different screens, each of which might have its own resources).
</p>
<p>
The other option, that of allocating a new colormap, works as
follows. We first ask the X server to give an Id to our color
map, with this function:
</p>
<pre class="code">
XCBCOLORMAP XCBCOLORMAPNew (XCBConnection *c);
</pre>
<p>
Then, we create the color map with
</p>
<pre class="code">
XCBVoidCookie XCBCreateColormap (XCBConnection *c, /* Pointer to the XCBConnection structure */
BYTE alloc, /* Colormap entries to be allocated (AllocNone or AllocAll) */
XCBCOLORMAP mid, /* Id of the color map */
XCBWINDOW window, /* Window on whose screen the colormap will be created */
XCBVISUALID visual); /* Id of the visual supported by the screen */
</pre>
<p>
Here is an example of creation of a new color map:
</p>
<pre class="code">
#include <X11/XCB/xcb.h>
int
main (int argc, char *argv[])
{
XCBConnection *c;
XCBSCREEN *screen;
XCBWINDOW win;
XCBCOLORMAP cmap
/* Open the connection to the X server and get the first screen */
c = XCBConnect (NULL, NULL);
screen = XCBConnSetupSuccessRepRootsIter (XCBGetSetup (c)).data;
/* We create the window win here*/
cmap = XCBCOLORMAPNew (c);
XCBCreateColormap (c, AllocNone, cmap, win, screen->root_visual);
return 1;
}
</pre>
<p>
Note that the window parameter is only used to allow the X
server to create the color map for the given screen. We can
then use this color map for any window drawn on the same screen.
</p>
<p>
To free a color map, it suffices to use this function:
</p>
<pre class="code">
XCBVoidCookie XCBFreeColormap (XCBConnection *c, /* The connection */
XCBCOLORMAP cmap); /* The color map */
</pre>
<div class="comp">
<div class="title">
Comparison Xlib/XCB
</div>
<div class="xlib">
<ul>
<li>XCreateColormap ()</li>
</ul>
</div>
<div class="xcb">
<ul>
<li>XCBCOLORMAPNew ()</li>
<li>XCBCreateColormap ()</li>
</ul>
</div>
<div class="xlib">
<ul>
<li>XFreeColormap ()</li>
</ul>
</div>
<div class="xcb">
<ul>
<li>XCBFreeColormap ()</li>
</ul>
</div>
</div>
<p></p>
<li class="subtitle"><a name="alloccolor">Allocating and freeing a color entry</a></li>
<p>
Once we got access to some color map, we can start allocating
colors. The informations related to a color are stored in the
following structure:
</p>
<pre class="code">
typedef struct {
BYTE response_type;
CARD8 pad0;
CARD16 sequence;
CARD32 length;
CARD16 red; /* The red component */
CARD16 green; /* The green component */
CARD16 blue; /* The blue component */
CARD8 pad1[2];
CARD32 pixel; /* The entry in the color map, supplied by the X server */
} XCBAllocColorRep;
</pre>
<p>
XCB supplies these two functions to fill it:
</p>
<pre class="code">
XCBAllocColorCookie XCBAllocColor (XCBConnection *c,
XCBCOLORMAP cmap,
CARD16 red,
CARD16 green,
CARD16 blue);
XCBAllocColorRep *XCBAllocColorReply (XCBConnection *c,
XCBAllocColorCookie cookie,
XCBGenericError **e);
</pre>
<p>
The fuction <span class="code">XCBAllocColor()</span> takes the
3 RGB components as parameters (red, green and blue). Here is an
example of using these functions:
</p>
<pre class="code">
#include <malloc.h>
#include <X11/XCB/xcb.h>
int
main (int argc, char *argv[])
{
XCBConnection *c;
XCBSCREEN *screen;
XCBWINDOW win;
XCBCOLORMAP cmap;
XCBAllocColorRep *rep;
/* Open the connection to the X server and get the first screen */
c = XCBConnect (NULL, NULL);
screen = XCBConnSetupSuccessRepRootsIter (XCBGetSetup (c)).data;
/* We create the window win here*/
cmap = XCBCOLORMAPNew (c);
XCBCreateColormap (c, AllocNone, cmap, win, screen->root_visual);
rep = XCBAllocColorReply (c, XCBAllocColor (c, cmap, 65535, 0, 0), 0);
if (!rep)
return 0;
/* Do something with r->pixel or the components */
free (rep);
return 1;
}
</pre>
<p>
As <span class="code">XCBAllocColorReply()</span> allocates
memory, you have to free <span class="code">rep</span>.
</p>
<p>
<b>TODO</b>: Talk about freeing colors.
</p>
</ol>
<li class="title"><a name="pixmaps">X Bitmaps and Pixmaps</a></li>
<p>
One thing many so-called "Multi-Media" applications need to do,
is display images. In the X world, this is done using bitmaps
and pixmaps. We have already seen some usage of them when
setting an icon for our application. Lets study them further,
and see how to draw these images inside a window, along side the
simple graphics and text we have seen so far.
</p>
<p>
One thing to note before delving further, is that XCB (nor Xlib)
supplies no means of manipulating popular image formats, such as
gif, png, jpeg or tiff. It is up to the programmer (or to higher
level graphics libraries) to translate these image formats into
formats that the X server is familiar with (x bitmaps and x
pixmaps).
</p>
<ol>
<li class="subtitle"><a name="pixmapswhat">What is a X Bitmap? An X Pixmap?</a></li>
<p>
An X bitmap is a two-color image stored in a format specific
to the X window system. When stored in a file, the bitmap data
looks like a C source file. It contains variables defining the
width and the height of the bitmap, an array containing the
bit values of the bitmap (the size of the array is
weight*height), and an optional hot-spot location (that will
be explained later, when discussing mouse cursors).
</p>
<p>
An X pixmap is a format used to stored images in the memory of
an X server. This format can store both black and white images
(such as x bitmaps) as well as color images. It is the only
image format supported by the X protocol, and any image to be
drawn on screen, should be first translated into this format.
</p>
<p>
In actuality, an X pixmap can be thought of as a window that
does not appear on the screen. Many graphics operations that
work on windows, will also work on pixmaps. Indeed, the type
of X pixmap in XCB is an Id like a window:
</p>
<pre class="code">
typedef struct {
CARD32 xid;
} XCBPIXMAP;
</pre>
<p>
In order to make the difference between a window and a pixmap,
XCB introduces a drawable type, which is a <b>union</b>
</p>
<pre class="code">
typedef union {
XCBWINDOW window;
XCBPIXMAP pixmap;
} XCBDRAWABLE;
</pre>
<p>
in order to avoid confusion between a window and a pixmap. The
operations that will work indifferently on a window or a pixmap
will require a <span class="code">XCBDRAWABLE</span>
</p>
<div class="emph">
<p>
Remark: In Xlib, there is no specific difference between a
<span class="code">Drawable</span>, a
<span class="code">Pixmap</span> or a
<span class="code">Window</span>: all are 32 bit long
integer.
</p>
</div>
<li class="subtitle"><a name="pixmapscreate">Creating a pixmap</a></li>
<p>
Sometimes we want to create an un-initialized pixmap, so we
can later draw into it. This is useful for image drawing
programs (creating a new empty canvas will cause the creation
of a new pixmap on which the drawing can be stored). It is
also useful when reading various image formats: we load the
image data into memory, create a pixmap on the server, and
then draw the decoded image data onto that pixmap.
</p>
<p>
To create a new pixmap, we first ask the X server to give an
Id to our pixmap, with this function:
</p>
<pre class="code">
XCBPIXMAP XCBPIXMAPNew (XCBConnection *c);
</pre>
<p>
Then, XCB supplies the following function to create new pixmaps:
</p>
<pre class="code">
XCBVoidCookie XCBCreatePixmap (XCBConnection *c, /* Pointer to the XCBConnection structure */
CARD8 depth, /* Depth of the screen */
XCBPIXMAP pid, /* Id of the pixmap */
XCBDRAWABLE drawable,
CARD16 width, /* Width of the window (in pixels) */
CARD16 height); /* Height of the window (in pixels) */
</pre>
<p>
<b>TODO</b>: Explain the drawable parameter, and give an
example (like xpoints.c)
</p>
<li class="subtitle"><a name="pixmapsdraw"></a>Drawing a pixmap in a window</li>
<p>
Once we got a handle to a pixmap, we can draw it on some
window, using the following function:
</p>
<pre class="code">
XCBVoidCookie XCBCopyArea (XCBConnection *c, /* Pointer to the XCBConnection structure */
XCBDRAWABLE src_drawable, /* The Drawable we want to paste */
XCBDRAWABLE dst_drawable, /* The Drawable on which we copy the previous Drawable */
XCBGCONTEXT gc, /* A Graphic Context */
INT16 src_x, /* Top left x coordinate of the region we want to copy */
INT16 src_y, /* Top left y coordinate of the region we want to copy */
INT16 dst_x, /* Top left x coordinate of the region where we want to copy */
INT16 dst_y, /* Top left y coordinate of the region where we want to copy */
CARD16 width, /* Width of the region we want to copy */
CARD16 height); /* Height of the region we want to copy */
</pre>
<p>
As you can see, we could copy the whole pixmap, as well as
only a given rectangle of the pixmap. This is useful to
optimize the drawing speed: we could copy only what we have
modified in the pixmap.
</p>
<p>
<b>One important note should be made</b>: it is possible to
create pixmaps with different depths on the same screen. When
we perform copy operations (a pixmap onto a window, etc), we
should make sure that both source and target have the same
depth. If they have a different depth, the operation would
fail. The exception to this is if we copy a specific bit plane
of the source pixmap using the
<span class="code">XCBCopyPlane</span> function. In such an
event, we can copy a specific plain to the target window (in
actuality, setting a specific bit in the color of each pixel
copied). This can be used to generate strange graphic effects
in widow, but that is beyond the scope of this tutorial.
</p>
<li class="subtitle"><a name="pixmapsfree"></a>Freeing a pixmap</li>
<p>
Finally, when we are done using a given pixmap, we should free
it, in order to free resources of the X server. This is done
using this function:
</p>
<pre class="code">
XCBVoidCookie XCBFreePixmap (XCBConnection *c, /* Pointer to the XCBConnection structure */
XCBPIXMAP pixmap); /* A given pixmap */
</pre>
<p>
Of course, after having freed it, we must not try accessing
the pixmap again.
</p>
<p>
<b>TODO</b>: Give an example, or a link to xpoints.c
</p>
</ol>
<li class="title"><a name="translation">Translation of basic Xlib functions and macros</a></li>
<p>
The problem when you want to port an Xlib program to XCB is that
you don't know if the Xlib function that you want to "translate"
is a X Window one or an Xlib macro. In that section, we describe
a way to translate the usual functions or macros that Xlib
provides. It's usually just a member of a structure.
</p>
<ol>
<li class="subtitle"><a name="displaystructure">Members of the Display structure</a></li>
In this section, we look at how to translate the macros that
return some members of the <span class="code">Display</span>
structure. They are obtained by using a function that requires a
<span class="code">XCBConnection *</span> or a member of the
<span class="code">XCBConnSetupSuccessRep</span> structure
(via the function <span class="code">XCBGetSetup</span>), or
a function that requires that structure.
<ol>
<li class="subtitle"><a name="ConnectionNumber">ConnectionNumber</a></li>
<p>
This number is the file descriptor that connects the client
to the server. You just have to use that function:
</p>
<pre class="code">
int XCBGetFileDescriptor(XCBConnection *c);
</pre>
<li class="subtitle"><a name="DefaultScreen"></a>DefaultScreen</li>
<p>
That number is not stored by XCB. It is returned in the
second parameter of the function <span class="code"><a href="#openconn">XCBConnect</a></span>.
Hence, you have to store it yourself if you want to use
it. Then, to get the <span class="code">XCBSCREEN</span>
structure, you have to iterate on the screens.
The equivalent function of the Xlib's
<span class="code">ScreenOfDisplay</span> function can be
found <a href="#ScreenOfDisplay">below</a>. OK, here is the
small piece of code to get that number:
</p>
<pre class="code">
XCBConnection *c;
int screen_default_nbr;
/* you pass the name of the display you want to XCBConnect */
c = XCBConnect (display_name, &screen_default_nbr);
/* screen_default_nbr contains now the number of the default screen */
</pre>
<li class="subtitle"><a name="QLength"></a>QLength</li>
<p>
Not documented yet.
</p>
<li class="subtitle"><a name="ScreenCount"></a>ScreenCount</li>
<p>
You get the count of screens with the functions
<span class="code">XCBGetSetup</span>
and
<span class="code">XCBConnSetupSuccessRepRootsIter</span>
(if you need to iterate):
</p>
<pre class="code">
XCBConnection *c;
int screen_count;
/* you init the connection */
screen_count = XCBConnSetupSuccessRepRootsIter (XCBGetSetup (c)).rem;
/* screen_count contains now the count of screens */
</pre>
<p>
If you don't want to iterate over the screens, a better way
to get that number is to use
<span class="code">XCBConnSetupSuccessRepRootsLength</span>:
</p>
<pre class="code">
XCBConnection *c;
int screen_count;
/* you init the connection */
screen_count = XCBConnSetupSuccessRepRootsLength (XCBGetSetup (c));
/* screen_count contains now the count of screens */
</pre>
<li class="subtitle"><a name="ServerVendor"></a>ServerVendor</li>
<p>
You get the name of the vendor of the server hardware with
the functions <span class="code">XCBGetSetup</span>
and
<span
class="code">XCBConnSetupSuccessRepVendor</span>. Beware
that, unlike Xlib, the string returned by XCB is not
necessarily null-terminaled:
</p>
<pre class="code">
XCBConnection *c;
char *vendor = NULL;
int length;
/* you init the connection */
length = XCBConnSetupSuccessRepVendorLength (XCBGetSetup (c));
vendor = (char *)malloc (length + 1);
if (vendor)
memcpy (vendor, XCBConnSetupSuccessRepVendor (XCBGetSetup (c)), length);
vendor[length] = '\0';
/* vendor contains now the name of the vendor. Must be freed when not used anymore */
</pre>
<li class="subtitle"><a name="ProtocolVersion"></a>ProtocolVersion</li>
<p>
You get the major version of the protocol in the
<span class="code">XCBConnSetupSuccessRep</span>
structure, with the function <span class="code">XCBGetSetup</span>:
</p>
<pre class="code">
XCBConnection *c;
CARD16 protocol_major_version;
/* you init the connection */
protocol_major_version = XCBGetSetup (c)->protocol_major_version;
/* protocol_major_version contains now the major version of the protocol */
</pre>
<li class="subtitle"><a name="ProtocolRevision"></a>ProtocolRevision</li>
<p>
You get the minor version of the protocol in the
<span class="code">XCBConnSetupSuccessRep</span>
structure, with the function <span class="code">XCBGetSetup</span>:
</p>
<pre class="code">
XCBConnection *c;
CARD16 protocol_minor_version;
/* you init the connection */
protocol_minor_version = XCBGetSetup (c)->protocol_minor_version;
/* protocol_minor_version contains now the minor version of the protocol */
</pre>
<li class="subtitle"><a name="VendorRelease"></a>VendorRelease</li>
<p>
You get the number of the release of the server hardware in the
<span class="code">XCBConnSetupSuccessRep</span>
structure, with the function <span class="code">XCBGetSetup</span>:
</p>
<pre class="code">
XCBConnection *c;
CARD32 release_number;
/* you init the connection */
release_number = XCBGetSetup (c)->release_number;
/* release_number contains now the number of the release of the server hardware */
</pre>
<li class="subtitle"><a name="DisplayString"></a>DisplayString</li>
<p>
The name of the display is not stored in XCB. You have to
store it by yourself.
</p>
<li class="subtitle"><a name="BitmapUnit"></a>BitmapUnit</li>
<p>
You get the bitmap scanline unit in the
<span class="code">XCBConnSetupSuccessRep</span>
structure, with the function <span class="code">XCBGetSetup</span>:
</p>
<pre class="code">
XCBConnection *c;
CARD8 bitmap_format_scanline_unit;
/* you init the connection */
bitmap_format_scanline_unit = XCBGetSetup (c)->bitmap_format_scanline_unit;
/* bitmap_format_scanline_unit contains now the bitmap scanline unit */
</pre>
<li class="subtitle"><a name="BitmapBitOrder"></a>BitmapBitOrder</li>
<p>
You get the bitmap bit order in the
<span class="code">XCBConnSetupSuccessRep</span>
structure, with the function <span class="code">XCBGetSetup</span>:
</p>
<pre class="code">
XCBConnection *c;
CARD8 bitmap_format_bit_order;
/* you init the connection */
bitmap_format_bit_order = XCBGetSetup (c)->bitmap_format_bit_order;
/* bitmap_format_bit_order contains now the bitmap bit order */
</pre>
<li class="subtitle"><a name="BitmapPad"></a>BitmapPad</li>
<p>
You get the bitmap scanline pad in the
<span class="code">XCBConnSetupSuccessRep</span>
structure, with the function <span class="code">XCBGetSetup</span>:
</p>
<pre class="code">
XCBConnection *c;
CARD8 bitmap_format_scanline_pad;
/* you init the connection */
bitmap_format_scanline_pad = XCBGetSetup (c)->bitmap_format_scanline_pad;
/* bitmap_format_scanline_pad contains now the bitmap scanline pad */
</pre>
<li class="subtitle"><a name="ImageByteOrder"></a>ImageByteOrder</li>
<p>
You get the image byte order in the
<span class="code">XCBConnSetupSuccessRep</span>
structure, with the function <span class="code">XCBGetSetup</span>:
</p>
<pre class="code">
XCBConnection *c;
CARD8 image_byte_order;
/* you init the connection */
image_byte_order = XCBGetSetup (c)->image_byte_order;
/* image_byte_order contains now the image byte order */
</pre>
</ol>
<li class="subtitle"><a name="screenofdisplay">ScreenOfDisplay related functions</a></li>
<p>
in Xlib, <span class="code">ScreenOfDisplay</span> returns a
<span class="code">Screen</span> structure that contains
several characteristics of your screen. XCB has a similar
structure (<span class="code">XCBSCREEN</span>),
but the way to obtain it is a bit different. With
Xlib, you just provide the number of the screen and you grab it
from an array. With XCB, you iterate over all the screens to
obtain the one you want. The complexity of this operation is
O(n). So the best is to store this structure if you use
it often. See <a href="#ScreenOfDisplay">ScreenOfDisplay</a> just below.
</p>
<p>
Xlib provides generally two functions to obtain the characteristics
related to the screen. One with the display and the number of
the screen, which calls <span class="code">ScreenOfDisplay</span>,
and the other that uses the <span class="code">Screen</span> structure.
This might be a bit confusing. As mentioned above, with XCB, it
is better to store the <span class="code">XCBSCREEN</span>
structure. Then, you have to read the members of this
structure. That's why the Xlib functions are put by pairs (or
more) as, with XCB, you will use the same code.
</p>
<ol>
<li class="subtitle"><a name="ScreenOfDisplay">ScreenOfDisplay</a></li>
<p>
This function returns the Xlib <span class="code">Screen</span>
structure. With XCB, you iterate over all the screens and
once you get the one you want, you return it:
</p>
<pre class="code"><a name="ScreenOfDisplay"></a>
XCBSCREEN *ScreenOfDisplay (XCBConnection *c,
int screen)
{
XCBSCREENIter iter;
iter = XCBConnSetupSuccessRepRootsIter (XCBGetSetup (c));
for (; iter.rem; --screen, XCBSCREENNext (&iter))
if (screen == 0)
return iter.data;
return NULL;
}
</pre>
<p>
As mentioned above, you might want to store the value
returned by this function.
</p>
<p>
All the functions below will use the result of that
function, as they just grab a specific member of the
<span class="code">XCBSCREEN</span> structure.
</p>
<li class="subtitle"><a name="DefaultScreenOfDisplay"></a>DefaultScreenOfDisplay</li>
<p>
It is the default screen that you obtain when you connect to
the X server. It suffices to call the <a href="#ScreenOfDisplay">ScreenOfDisplay</a>
function above with the connection and the number of the
default screen.
</p>
<pre class="code">
XCBConnection *c;
int screen_default_nbr;
XCBSCREEN *default_screen; /* the returned default screen */
/* you pass the name of the display you want to XCBConnect */
c = XCBConnect (display_name, &screen_default_nbr);
default_screen = ScreenOfDisplay (c, screen_default_nbr);
/* default_screen contains now the default root window, or a NULL window if no screen is found */
</pre>
<li class="subtitle"><a name="RootWindow">RootWindow / RootWindowOfScreen</a></li>
<p>
</p>
<pre class="code">
XCBConnection *c;
XCBSCREEN *screen;
int screen_nbr;
XCBWINDOW root_window = { 0 }; /* the returned window */
/* you init the connection and screen_nbr */
screen = ScreenOfDisplay (c, screen_nbr);
if (screen)
root_window = screen->root;
/* root_window contains now the root window, or a NULL window if no screen is found */
</pre>
<li class="subtitle"><a name="DefaultRootWindow">DefaultRootWindow</a></li>
<p>
It is the root window of the default screen. So, you call
<a name="ScreenOfDisplay">ScreenOfDisplay</a> with the
default screen number and you get the
<a href="#RootWindow">root window</a> as above:
</p>
<pre class="code">
XCBConnection *c;
XCBSCREEN *screen;
int screen_default_nbr;
XCBWINDOW root_window = { 0 }; /* the returned root window */
/* you pass the name of the display you want to XCBConnect */
c = XCBConnect (display_name, &screen_default_nbr);
screen = ScreenOfDisplay (c, screen_default_nbr);
if (screen)
root_window = screen->root;
/* root_window contains now the default root window, or a NULL window if no screen is found */
</pre>
<li class="subtitle"><a name="DefaultVisual">DefaultVisual / DefaultVisualOfScreen</a></li>
<p>
While a Visual is, in Xlib, a structure, in XCB, there are
two types: <span class="code">XCBVISUALID</span>, which is
the Id of the visual, and <span class="code">XCBVISUALTYPE</span>,
which corresponds to the Xlib Visual. To get the Id of the
visual of a screen, just get the
<span class="code">root_visual</span>
member of a <span class="code">XCBSCREEN</span>:
</p>
<pre class="code">
XCBConnection *c;
XCBSCREEN *screen;
int screen_nbr;
XCBVISUALID root_visual = { 0 }; /* the returned visual Id */
/* you init the connection and screen_nbr */
screen = ScreenOfDisplay (c, screen_nbr);
if (screen)
root_visual = screen->root_visual;
/* root_visual contains now the value of the Id of the visual, or a NULL visual if no screen is found */
</pre>
<p>
To get the <span class="code">XCBVISUALTYPE</span>
structure, it's a bit less easy. You have to get the
<span class="code">XCBSCREEN</span> structure that you want,
get its <span class="code">root_visual</span> member,
then iterate over the <span class="code">XCBDEPTH</span>s
and the <span class="code">XCBVISUALTYPE</span>s, and compare
the <span class="code">XCBVISUALID</span> of these <span class="code">XCBVISUALTYPE</span>s:
with <span class="code">root_visual</span>:
</p>
<pre class="code">
XCBConnection *c;
XCBSCREEN *screen;
int screen_nbr;
XCBVISUALID root_visual = { 0 };
XCBVISUATYPE *visual_type = NULL; /* the returned visual type */
/* you init the connection and screen_nbr */
screen = ScreenOfDisplay (c, screen_nbr);
if (screen)
{
XCBDEPTHIter depth_iter;
depth_iter = XCBSCREENAllowedDepthsIter (screen);
for (; depth_iter.rem; XCBDEPTHNext (&depth_iter))
{
XCBVISUALTYPEIter visual_iter;
visual_iter = XCBDEPTHVisualsIter (depth_iter.data);
for (; visual_iter.rem; XCBVISUALTYPENext (&visual_iter))
{
if (screen->root_visual.id == visual_iter.data->visual_id.id)
{
visual_type = visual_iter.data;
break;
}
}
}
}
/* visual_type contains now the visual structure, or a NULL visual structure if no screen is found */
</pre>
<li class="subtitle"><a name="DefaultGC">DefaultGC / DefaultGCOfScreen</a></li>
<p>
This default Graphic Context is just a newly created Graphic
Context, associated to the root window of a
<span class="code">XCBSCREEN</span>,
using the black white pixels of that screen:
</p>
<pre class="code">
XCBConnection *c;
XCBSCREEN *screen;
int screen_nbr;
XCBGCONTEXT gc = { 0 }; /* the returned default graphic context */
/* you init the connection and screen_nbr */
screen = ScreenOfDisplay (c, screen_nbr);
if (screen)
{
XCBDRAWABLE draw;
CARD32 mask;
CARD32 values[2];
gc = XCBGCONTEXTNew (c);
draw.window = screen->root;
mask = GCForeground | GCBackground;
values[0] = screen->black_pixel;
values[1] = screen->white_pixel;
XCBCreateGC (c, gc, draw, mask, values);
}
/* gc contains now the default graphic context */
</pre>
<li class="subtitle"><a name="BlackPixel">BlackPixel / BlackPixelOfScreen</a></li>
<p>
It is the Id of the black pixel, which is in the structure
of an <span class="code">XCBSCREEN</span>.
</p>
<pre class="code">
XCBConnection *c;
XCBSCREEN *screen;
int screen_nbr;
CARD32 black_pixel = 0; /* the returned black pixel */
/* you init the connection and screen_nbr */
screen = ScreenOfDisplay (c, screen_nbr);
if (screen)
black_pixel = screen->black_pixel;
/* black_pixel contains now the value of the black pixel, or 0 if no screen is found */
</pre>
<li class="subtitle"><a name="WhitePixel">WhitePixel / WhitePixelOfScreen</a></li>
<p>
It is the Id of the white pixel, which is in the structure
of an <span class="code">XCBSCREEN</span>.
</p>
<pre class="code">
XCBConnection *c;
XCBSCREEN *screen;
int screen_nbr;
CARD32 white_pixel = 0; /* the returned white pixel */
/* you init the connection and screen_nbr */
screen = ScreenOfDisplay (c, screen_nbr);
if (screen)
white_pixel = screen->white_pixel;
/* white_pixel contains now the value of the white pixel, or 0 if no screen is found */
</pre>
<li class="subtitle"><a name="DisplayWidth">DisplayWidth / WidthOfScreen</a></li>
<p>
It is the width in pixels of the screen that you want, and
which is in the structure of the corresponding
<span class="code">XCBSCREEN</span>.
</p>
<pre class="code">
XCBConnection *c;
XCBSCREEN *screen;
int screen_nbr;
CARD32 width_in_pixels = 0; /* the returned width in pixels */
/* you init the connection and screen_nbr */
screen = ScreenOfDisplay (c, screen_nbr);
if (screen)
width_in_pixels = screen->width_in_pixels;
/* width_in_pixels contains now the width in pixels, or 0 if no screen is found */
</pre>
<li class="subtitle"><a name="DisplayHeight">DisplayHeight / HeightOfScreen</a></li>
<p>
It is the height in pixels of the screen that you want, and
which is in the structure of the corresponding
<span class="code">XCBSCREEN</span>.
</p>
<pre class="code">
XCBConnection *c;
XCBSCREEN *screen;
int screen_nbr;
CARD32 height_in_pixels = 0; /* the returned height in pixels */
/* you init the connection and screen_nbr */
screen = ScreenOfDisplay (c, screen_nbr);
if (screen)
height_in_pixels = screen->height_in_pixels;
/* height_in_pixels contains now the height in pixels, or 0 if no screen is found */
</pre>
<li class="subtitle"><a name="DisplayWidthMM">DisplayWidthMM / WidthMMOfScreen</a></li>
<p>
It is the width in millimeters of the screen that you want, and
which is in the structure of the corresponding
<span class="code">XCBSCREEN</span>.
</p>
<pre class="code">
XCBConnection *c;
XCBSCREEN *screen;
int screen_nbr;
CARD32 width_in_millimeters = 0; /* the returned width in millimeters */
/* you init the connection and screen_nbr */
screen = ScreenOfDisplay (c, screen_nbr);
if (screen)
width_in_millimeters = screen->width_in_millimeters;
/* width_in_millimeters contains now the width in millimeters, or 0 if no screen is found */
</pre>
<li class="subtitle"><a name="DisplayHeightMM">DisplayHeightMM / HeightMMOfScreen</a></li>
<p>
It is the height in millimeters of the screen that you want, and
which is in the structure of the corresponding
<span class="code">XCBSCREEN</span>.
</p>
<pre class="code">
XCBConnection *c;
XCBSCREEN *screen;
int screen_nbr;
CARD32 height_in_millimeters = 0; /* the returned height in millimeters */
/* you init the connection and screen_nbr */
screen = ScreenOfDisplay (c, screen_nbr);
if (screen)
height_in_millimeters = screen->height_in_millimeters;
/* height_in_millimeters contains now the height in millimeters, or 0 if no screen is found */
</pre>
<li class="subtitle"><a name="DisplayPlanes">DisplayPlanes / DefaultDepth / DefaultDepthOfScreen / PlanesOfScreen</a></li>
<p>
It is the depth (in bits) of the root window of the
screen. You get it from the <span class="code">XCBSCREEN</span> structure.
</p>
<pre class="code">
XCBConnection *c;
XCBSCREEN *screen;
int screen_nbr;
CARD8 root_depth = 0; /* the returned depth of the root window */
/* you init the connection and screen_nbr */
screen = ScreenOfDisplay (c, screen_nbr);
if (screen)
root_depth = screen->root_depth;
/* root_depth contains now the depth of the root window, or 0 if no screen is found */
</pre>
<li class="subtitle"><a name="DefaultColormap">DefaultColormap / DefaultColormapOfScreen</a></li>
<p>
This is the default colormap of the screen (and not the
(default) colormap of the default screen !). As usual, you
get it from the <span class="code">XCBSCREEN</span> structure:
</p>
<pre class="code">
XCBConnection *c;
XCBSCREEN *screen;
int screen_nbr;
XCBCOLORMAP default_colormap = { 0 }; /* the returned default colormap */
/* you init the connection and screen_nbr */
screen = ScreenOfDisplay (c, screen_nbr);
if (screen)
default_colormap = screen->default_colormap;
/* default_colormap contains now the default colormap, or a NULL colormap if no screen is found */
</pre>
<li class="subtitle"><a name="MinCmapsOfScreen"></a>MinCmapsOfScreen</li>
<p>
You get the minimum installed colormaps in the <span class="code">XCBSCREEN</span> structure:
</p>
<pre class="code">
XCBConnection *c;
XCBSCREEN *screen;
int screen_nbr;
CARD16 min_installed_maps = 0; /* the returned minimum installed colormaps */
/* you init the connection and screen_nbr */
screen = ScreenOfDisplay (c, screen_nbr);
if (screen)
min_installed_maps = screen->min_installed_maps;
/* min_installed_maps contains now the minimum installed colormaps, or 0 if no screen is found */
</pre>
<li class="subtitle"><a name="MaxCmapsOfScreen"></a>MaxCmapsOfScreen</li>
<p>
You get the maximum installed colormaps in the <span class="code">XCBSCREEN</span> structure:
</p>
<pre class="code">
XCBConnection *c;
XCBSCREEN *screen;
int screen_nbr;
CARD16 max_installed_maps = 0; /* the returned maximum installed colormaps */
/* you init the connection and screen_nbr */
screen = ScreenOfDisplay (c, screen_nbr);
if (screen)
max_installed_maps = screen->max_installed_maps;
/* max_installed_maps contains now the maximum installed colormaps, or 0 if no screen is found */
</pre>
<li class="subtitle"><a name="DoesSaveUnders"></a>DoesSaveUnders</li>
<p>
You know if <span class="code">save_unders</span> is set,
by looking in the <span class="code">XCBSCREEN</span> structure:
</p>
<pre class="code">
XCBConnection *c;
XCBSCREEN *screen;
int screen_nbr;
BOOL save_unders = 0; /* the returned value of save_unders */
/* you init the connection and screen_nbr */
screen = ScreenOfDisplay (c, screen_nbr);
if (screen)
save_unders = screen->save_unders;
/* save_unders contains now the value of save_unders, or FALSE if no screen is found */
</pre>
<li class="subtitle"><a name="DoesBackingStore"></a>DoesBackingStore</li>
<p>
You know the value of <span class="code">backing_stores</span>,
by looking in the <span class="code">XCBSCREEN</span> structure:
</p>
<pre class="code">
XCBConnection *c;
XCBSCREEN *screen;
int screen_nbr;
BYTE backing_stores = 0; /* the returned value of backing_stores */
/* you init the connection and screen_nbr */
screen = ScreenOfDisplay (c, screen_nbr);
if (screen)
backing_stores = screen->backing_stores;
/* backing_stores contains now the value of backing_stores, or FALSE if no screen is found */
</pre>
<li class="subtitle"><a name="EventMaskOfScreen"></a>EventMaskOfScreen</li>
<p>
To get the current input masks,
you look in the <span class="code">XCBSCREEN</span> structure:
</p>
<pre class="code">
XCBConnection *c;
XCBSCREEN *screen;
int screen_nbr;
CARD32 current_input_masks = 0; /* the returned value of current input masks */
/* you init the connection and screen_nbr */
screen = ScreenOfDisplay (c, screen_nbr);
if (screen)
current_input_masks = screen->current_input_masks;
/* current_input_masks contains now the value of the current input masks, or FALSE if no screen is found */
</pre>
</ol>
<li class="subtitle"><a name="misc">Miscellaneous macros</a></li>
<ol>
<li class="subtitle"><a name="DisplayOfScreen"></a>DisplayOfScreen</li>
<p>
in Xlib, the <span class="code">Screen</span> structure
stores its associated <span class="code">Display</span>
structure. This is not the case in the X Window protocol,
hence, it's also not the case in XCB. So you have to store
it by yourself.
</p>
<li class="subtitle"><a name="DisplayCells"></a>DisplayCells / CellsOfScreen</li>
<p>
To get the colormap entries,
you look in the <span class="code">XCBVISUALTYPE</span>
structure, that you grab like <a class="subsection" href="#DefaultVisual">here</a>:
</p>
<pre class="code">
XCBConnection *c;
XCBVISUALTYPE *visual_type;
CARD16 colormap_entries = 0; /* the returned value of the colormap entries */
/* you init the connection and visual_type */
if (visual_type)
colormap_entries = visual_type->colormap_entries;
/* colormap_entries contains now the value of the colormap entries, or FALSE if no screen is found */
</pre>
</ol>
</ol>
</ol>
</div>
</body>
</html>
|
