summaryrefslogtreecommitdiffstats
path: root/tde-i18n-es/docs/tdevelop/kdearch/index.docbook
blob: c6273f08d38b0938cd546905b7b142fe551ef4c9 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
1287
1288
1289
1290
1291
1292
1293
1294
1295
1296
1297
1298
1299
1300
1301
1302
1303
1304
1305
1306
1307
1308
1309
1310
1311
1312
1313
1314
1315
1316
1317
1318
1319
1320
1321
1322
1323
1324
1325
1326
1327
1328
1329
1330
1331
1332
1333
1334
1335
1336
1337
1338
1339
1340
1341
1342
1343
1344
1345
1346
1347
1348
1349
1350
1351
1352
1353
1354
1355
1356
1357
1358
1359
1360
1361
1362
1363
1364
1365
1366
1367
1368
1369
1370
1371
1372
1373
1374
1375
1376
1377
1378
1379
1380
1381
1382
1383
1384
1385
1386
1387
1388
1389
1390
1391
1392
1393
1394
1395
1396
1397
1398
1399
1400
1401
1402
1403
1404
1405
1406
1407
1408
1409
1410
1411
1412
1413
1414
1415
1416
1417
1418
1419
1420
1421
1422
1423
1424
1425
1426
1427
1428
1429
1430
1431
1432
1433
1434
1435
1436
1437
1438
1439
1440
1441
1442
1443
1444
1445
1446
1447
1448
1449
1450
1451
1452
1453
1454
1455
1456
1457
1458
1459
1460
1461
1462
1463
1464
1465
1466
1467
1468
1469
1470
1471
1472
1473
1474
1475
1476
1477
1478
1479
1480
1481
1482
1483
1484
1485
1486
1487
1488
1489
1490
1491
1492
1493
1494
1495
1496
1497
1498
1499
1500
1501
1502
1503
1504
1505
1506
1507
1508
1509
1510
1511
1512
1513
1514
1515
1516
1517
1518
1519
1520
1521
1522
1523
1524
1525
1526
1527
1528
1529
1530
1531
1532
1533
1534
1535
1536
1537
1538
1539
1540
1541
1542
1543
1544
1545
1546
1547
1548
1549
1550
1551
1552
1553
1554
1555
1556
1557
1558
1559
1560
1561
1562
1563
1564
1565
1566
1567
1568
1569
1570
1571
1572
1573
1574
1575
1576
1577
1578
1579
1580
1581
1582
1583
1584
1585
1586
1587
1588
1589
1590
1591
1592
1593
1594
1595
1596
1597
1598
1599
1600
1601
1602
1603
1604
1605
1606
1607
1608
1609
1610
1611
1612
1613
1614
1615
1616
1617
1618
1619
1620
1621
1622
1623
1624
1625
1626
1627
1628
1629
1630
1631
1632
1633
1634
1635
1636
1637
1638
1639
1640
1641
1642
1643
1644
1645
1646
1647
1648
1649
1650
1651
1652
1653
1654
1655
1656
1657
1658
1659
1660
1661
1662
1663
1664
1665
1666
1667
1668
1669
1670
1671
1672
1673
1674
1675
1676
1677
1678
1679
1680
1681
1682
1683
1684
1685
1686
1687
1688
1689
1690
1691
1692
1693
1694
1695
1696
1697
1698
1699
1700
1701
1702
1703
1704
1705
1706
1707
1708
1709
1710
1711
1712
1713
1714
1715
1716
1717
1718
1719
1720
1721
1722
1723
1724
1725
1726
1727
1728
1729
1730
1731
1732
1733
1734
1735
1736
1737
1738
1739
1740
1741
1742
1743
1744
1745
1746
1747
1748
1749
1750
1751
1752
1753
1754
1755
1756
1757
1758
1759
1760
1761
1762
1763
1764
1765
1766
1767
1768
1769
1770
1771
1772
1773
1774
1775
1776
1777
1778
1779
1780
1781
1782
1783
1784
1785
1786
1787
1788
1789
1790
1791
1792
1793
1794
1795
1796
1797
1798
1799
1800
1801
1802
1803
1804
1805
1806
1807
1808
1809
1810
1811
1812
1813
1814
1815
1816
1817
1818
1819
1820
1821
1822
1823
1824
1825
1826
1827
1828
1829
1830
1831
1832
1833
1834
1835
1836
1837
1838
1839
1840
1841
1842
1843
1844
1845
1846
1847
1848
1849
1850
1851
1852
1853
1854
1855
1856
1857
1858
1859
1860
1861
1862
1863
1864
1865
1866
1867
1868
1869
1870
1871
1872
1873
1874
1875
1876
1877
1878
1879
1880
1881
1882
1883
1884
1885
1886
1887
1888
1889
1890
1891
1892
1893
1894
1895
1896
1897
1898
1899
1900
1901
1902
1903
1904
1905
1906
1907
1908
1909
1910
1911
1912
1913
1914
1915
1916
1917
1918
1919
<?xml version="1.0" ?>
<!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" "dtd/kdex.dtd" [
  <!ENTITY % addindex "INCLUDE">
  <!ENTITY % Spanish "INCLUDE"> <!-- change language only here -->
]>

<book lang="&language;">

<bookinfo>
<title>Introducción a la arquitectura de KDE</title>

<date></date>
<releaseinfo></releaseinfo>

<authorgroup>
<author><firstname>Bernd</firstname> <surname>Gehrmann</surname> <affiliation><address><email>bernd@kdevelop.org</email></address></affiliation>
</author>
</authorgroup>

<copyright>
<year>2001</year>
<year>2002</year>
<holder>Bernd Gehrmann</holder>
</copyright>

<legalnotice>&FDLNotice;</legalnotice>

<abstract>
<para>Esta documentación es una introducción a la plataforma de desarrollo de KDE</para>
</abstract>

<keywordset>
<keyword>KDE</keyword>
<keyword>arquitectura</keyword>
<keyword>desarrollo</keyword>
<keyword>programación</keyword>
</keywordset>

</bookinfo>

<chapter id="structure">
<title>Estructura de bibliotecas</title>

<simplesect id="structure-byname">
<title>Bibliotecas por nombre</title>

<variablelist>

<varlistentry>
<term><ulink url="kdeapi:tdecore/index.html">tdecore</ulink></term>
<listitem><para>La biblioteca tdecore es el marco de trabajo de aplicación básico para cualquier programa basado en KDE. Proporciona acceso al sistema de configuración, a la gestión de la línea de órdenes, a la carga y manipulación de iconos, a algunos tipos especiales de comunicación entre procesos, al manejo de archivos y a otras utilidades varias. </para></listitem>
</varlistentry>

<varlistentry>
<term><ulink url="kdeapi:tdeui/index.html">tdeui</ulink></term>
<listitem><para>La biblioteca <literal>tdeui</literal> proporciona muchos widgets y diálogos estándar que Qt no incluye o proporciona de forma menos completa. También incluye varios componentes que son subclases de otros de Qt y están mejor integrados en el entorno KDE al respetar las preferencias de los usuarios. </para></listitem>
</varlistentry>

<varlistentry>
<term><ulink url="kdeapi:tdeio/index.html">tdeio</ulink></term>
<listitem><para>La biblioteca <literal>tdeio</literal> contiene facilidades para la E/S transparente y asíncrona de red, así como acceso al manejo de tipos MIME. También proporciona el diálogo de archivos de KDE y sus clases auxiliares. </para></listitem>
</varlistentry>

<varlistentry>
<term><ulink url="kdeapi:kjs/index.html">kjs</ulink></term>
<listitem><para>La biblioteca <literal>kjs</literal> proporciona una implementación de JavaScript. </para></listitem>
</varlistentry>

<varlistentry>
<term><ulink url="kdeapi:tdehtml/index.html">tdehtml</ulink></term>
<listitem><para>La biblioteca <literal>tdehtml</literal> contiene el módulo TDEHTML, un widget de navegación HTML, el API y un procesador de DOM, incluyendo interfaces para Java y JavaScript. </para></listitem>
</varlistentry>

</variablelist>

</simplesect>


<simplesect id="structure-grouped">
<title>Clases agrupadas</title>

<para>Esquema principal de una aplicación - clases que son necesarias en casi cualquier aplicación. </para>

<itemizedlist>

<listitem><formalpara>
<title><ulink url="kdeapi:tdecore/TDEApplication">TDEApplication</ulink></title>
<para>Inicia y controla una aplicación de KDE. </para>
</formalpara></listitem>

<listitem><formalpara>
<title><ulink url="kdeapi:tdecore/KUniqueApplication">KUniqueApplication</ulink></title>
<para>Se asegura de que solo se ejecuta una sesión de la aplicación en cada momento. </para>
</formalpara></listitem>

<listitem><formalpara><title><ulink url="kdeapi:tdecore/TDEAboutData">TDEAboutData</ulink></title>
<para>Contiene la información de la ventana «Acerca de». </para>
</formalpara></listitem>

<listitem><formalpara><title><ulink url="kdeapi:tdecore/TDECmdLineArgs">TDECmdLineArgs</ulink></title>
<para>Procesamiento de argumentos de la línea de órdenes. </para>
</formalpara></listitem>

</itemizedlist>

<para>Preferencias de configuración - acceso a la base de datos de configuración jerárquica de KDE, a las preferencias globales y a los recursos de la aplicación. </para>

<itemizedlist>

<listitem><formalpara><title><ulink url="kdeapi:tdecore/TDEConfig">TDEConfig</ulink></title>
<para>Proporciona acceso a la base de datos de configuración de KDE. </para>
</formalpara></listitem>

<listitem><formalpara><title><ulink url="kdeapi:tdecore/KSimpleConfig">KSimpleConfig</ulink></title>
<para>Acceso a archivos de configuración simples y no jerárquicos. </para>
</formalpara></listitem>

<listitem><formalpara><title><ulink url="kdeapi:tdecore/KDesktopFile">KDesktopFile</ulink></title>
<para>Acceso a los archivo <literal>.desktop</literal>. </para>
</formalpara></listitem>

<listitem><formalpara><title><ulink url="kdeapi:tdecore/TDEGlobalSettings">TDEGlobalSettings</ulink></title>
<para>Acceso cómodo a las preferencias que no son específicas de la aplicación. </para>
</formalpara></listitem>

</itemizedlist>

<para>Manejo de archivos y URLs - descodificación de URLs, archivos temporales, etc. </para>

<itemizedlist>

<listitem><formalpara><title><ulink url="kdeapi:tdecore/KURL">KURL</ulink></title>
<para>Representa y procesa URLs. </para>
</formalpara></listitem>

<listitem><formalpara><title><ulink url="kdeapi:tdecore/KTempFile">KTempFile</ulink></title>
<para>Crea archivos de nombre único para almacenamiento temporal. </para>
</formalpara></listitem>

<listitem><formalpara><title><ulink url="kdeapi:tdecore/KSaveFile">KSaveFile</ulink></title>
<para>Permite guardar archivos en segmentos. </para>
</formalpara></listitem>

</itemizedlist>

<para>Comunicación entre procesos - clases auxiliares para DCOP e invocación de subprocesos. </para>

<itemizedlist>

<listitem><formalpara><title><ulink url="kdeapi:tdecore/TDEProcess">TDEProcess</ulink></title>
<para>Invoca y controla procesos hijo. </para>
</formalpara></listitem>

<listitem><formalpara><title><ulink url="kdeapi:tdecore/KShellProcess">KShellProcess</ulink></title>
<para>Invoca procesos hijo a través de un intérprete de comandos. </para>
</formalpara></listitem>

<listitem><formalpara><title><ulink url="kdeapi:tdesu/PtyProcess">PtyProcess</ulink></title>
<para>Comunicación con procesos hijo a través de una pseudo terminal. </para>
</formalpara></listitem>

<listitem><formalpara><title><ulink url="kdeapi:tdecore/KIPC">KIPC</ulink></title>
<para>Comunicación entre procesos simple utilizando ClientMessages de X11. </para>
</formalpara></listitem>

<listitem><formalpara><title><ulink url="kdeapi:dcop/DCOPClient">DCOPClient</ulink></title>
<para>Mensajería DCOP. </para>
</formalpara></listitem>

<listitem><formalpara><title><ulink url="kdeapi:tdecore/KDCOPPropertyProxy">KDCOPPropertyProxy</ulink></title>
<para>Una clase proxy que publica las propiedades de Qt a través de DCOP. </para>
</formalpara></listitem>

<listitem><formalpara><title><ulink url="kdeapi:tdeui/KDCOPActionProxy">KDCOPActionProxy</ulink></title>
<para>Una clase proxy que publica un interfaz DCOP para realizar acciones. </para>
</formalpara></listitem>

</itemizedlist>

<para>Clases de utilidades - gestión de memoria, expresiones regulares, manipulación de cadenas, números aleatorios </para>

<itemizedlist>

<listitem><formalpara><title><ulink url="kdeapi:tdecore/KRegExp">KRegExp</ulink></title>
<para>Tratamiento de expresiones regulares según POSIX. </para>
</formalpara></listitem>

<listitem><formalpara><title><ulink url="kdeapi:tdecore/KStringHandler">KStringHandler</ulink></title>
<para>Una extravagante interfaz para la manipulación de cadenas. </para>
</formalpara></listitem>

<listitem><formalpara><title><ulink url="kdeapi:tdecore/TDEZoneAllocator">TDEZoneAllocator</ulink></title>
<para>Localización eficiente de memoria para grandes grupos de pequeños objetos. </para>
</formalpara></listitem>

<listitem><formalpara><title><ulink url="kdeapi:tdecore/KRandomSequence">KRandomSequence</ulink></title>
<para>Generador de números pseudo aleatorios. </para>
</formalpara></listitem>

</itemizedlist>

<para>Aceleradores de teclado - clases de ayuda para el establecimiento de atajos de teclado consistentes con el escritorio. </para>

<itemizedlist>

<listitem><formalpara><title><ulink url="kdeapi:tdecore/TDEAccel">TDEAccel</ulink></title>
<para>Collección de atajos de teclado. </para>
</formalpara></listitem>

<listitem><formalpara><title><ulink url="kdeapi:tdecore/TDEStdAccel">TDEStdAccel</ulink></title>
<para>Acceso sencillo a los atajos de teclado más comunes. </para>
</formalpara></listitem>

<listitem><formalpara><title><ulink url="kdeapi:tdecore/TDEGlobalAccel"></ulink></title>
<para>Colección de atajos de teclado que afectan a todo el sistema. </para>
</formalpara></listitem>

</itemizedlist>

<para>Procesamiento de imágenes - carga y manipulación de iconos. </para>

<itemizedlist>

<listitem><formalpara><title><ulink url="kdeapi:tdecore/TDEIconLoader">TDEIconLoader</ulink></title>
<para>Carga iconos de una forma consistente con los temas de escritorio. </para>
</formalpara></listitem>

<listitem><formalpara><title><ulink url="kdeapi:tdecore/TDEIconTheme">TDEIconTheme</ulink></title>
<para>Clases de ayuda para TDEIconLoader. </para>
</formalpara></listitem>

<listitem><formalpara><title><ulink url="kdeapi:tdecore/KPixmap">KPixmap</ulink></title>
<para>Una clase de mapa de pixels con posibilidades extendidas de optimización de colores. </para>
</formalpara></listitem>

<listitem><formalpara><title><ulink url="kdeapi:tdeui/KPixmapEffect">KPixmapEffect</ulink></title>
<para>Efectos de mapas de píxels como gradientes y patrones. </para>
</formalpara></listitem>

<listitem><formalpara><title><ulink url="kdeapi:tdeui/KPixmapIO">KPixmapIO</ulink></title>
<para>Conversión rápida de <classname>TQImage</classname> a <classname>QPixmap</classname>. </para>
</formalpara></listitem>

</itemizedlist>

<para>Arrastrar y soltar - objetos de arrastre para colores y URLs. </para>

<itemizedlist>

<listitem><formalpara><title><ulink url="kdeapi:tdecore/KURLDrag">KURLDrag</ulink></title>
<para>Un objeto de arrastre para URLs. </para>
</formalpara></listitem>

<listitem><formalpara><title><ulink url="kdeapi:tdeui/KColorDrag">KColorDrag</ulink></title>
<para>Un objeto de arrastre para colores. </para>
</formalpara></listitem>

<listitem><formalpara><title><ulink url="kdeapi:tdecore/KMultipleDrag">KMultipleDrag</ulink></title>
<para>Permite construir objetos de arrastre a partir varios otros. </para>
</formalpara></listitem>

</itemizedlist>

<para>Autocompletado </para>

<itemizedlist>

<listitem><formalpara><title><ulink url="kdeapi:tdecore/TDECompletion">TDECompletion</ulink></title>
<para>Autocompletado de cadenas genérico. </para>
</formalpara></listitem>

<listitem><formalpara><title><ulink url="kdeapi:tdeio/KURLCompletion">KURLCompletion</ulink></title>
<para>Autocompletado de URLs. </para>
</formalpara></listitem>

<listitem><formalpara><title><ulink url="kdeapi:tdeio/KShellCompletion">KShellCompletion</ulink></title>
<para>Autocompletado de ejecutables. </para>
</formalpara></listitem>

</itemizedlist>

<para>Widgets - clases de widgets para vistas de lista, reglas, selección de colores, etc. </para>

<itemizedlist>

<listitem><formalpara><title><ulink url="kdeapi:tdeui/TDEListView">TDEListView</ulink></title>
<para>Una variante de <classname>QListView</classname> que se ajusta a las preferencias globales del sistema KDE. </para>
</formalpara></listitem>

<listitem><formalpara><title><ulink url="kdeapi:tdeui/TDEListView">TDEListBox</ulink></title>
<para>Una variante de <classname>QListBox</classname> que se ajusta a las preferencias globales del sistema KDE. </para>
</formalpara></listitem>

<listitem><formalpara><title><ulink url="kdeapi:tdeui/TDEListView">TDEIconView</ulink></title>
<para>Una variante de <classname>QIconView</classname> que se ajusta a las preferencias globales del sistema KDE. </para>
</formalpara></listitem>

<listitem><formalpara><title><ulink url="kdeapi:tdeui/TDEListView">KLineEdit</ulink></title>
<para>Una variante de <classname>QLineEdit</classname> con soporte para autocompletado. </para>
</formalpara></listitem>

<listitem><formalpara><title><ulink url="kdeapi:tdeui/KComboBox">KComboBox</ulink></title>
<para>Una variante de <classname>QComboBox</classname> con soporte para autocompletado. </para>
</formalpara></listitem>

<listitem><formalpara><title><ulink url="kdeapi:tdeui/TDEFontCombo">TDEFontCombo</ulink></title>
<para>Una lista desplegable para la selección de fuentes. </para>
</formalpara></listitem>

<listitem><formalpara><title><ulink url="kdeapi:tdeui/KColorCombo">KColorCombo</ulink></title>
<para>Una lista desplegable para la selección de colores. </para>
</formalpara></listitem>

<listitem><formalpara><title><ulink url="kdeapi:tdeui/KColorButton">KColorButton</ulink></title>
<para>Un botón para la selección de colores. </para>
</formalpara></listitem>

<listitem><formalpara><title><ulink url="kdeapi:tdeui/KURLCombo">KURLCombo</ulink></title>
<para>Una lista desplegable para la selección de nombres de archivos y URLs. </para>
</formalpara></listitem>

<listitem><formalpara><title><ulink url="kdeapi:tdefile/KURLRequester">KURLRequester</ulink></title>
<para>Una línea de edición para seleccionar nombres de archivos y URLs. </para>
</formalpara></listitem>

<listitem><formalpara><title><ulink url="kdeapi:tdeui/KRuler">KRuler</ulink></title>
<para>Un widget de una regla. </para>
</formalpara></listitem>

<listitem><formalpara><title><ulink
url="kdeapi:tdeui/KAnimWidget">KAnimWidget</ulink></title>
<para>animaciones. </para>
</formalpara></listitem>

<listitem><formalpara><title><ulink url="kdeapi:tdeui/KNumInput">KNumInput</ulink></title>
<para>Un widget para la entrada de números. </para>
</formalpara></listitem>

<listitem><formalpara><title><ulink url="kdeapi:tdeui/KPasswordEdit">KPasswordEdit</ulink></title>
<para>Un widget para la entrada de contraseñas. </para>
</formalpara></listitem>

</itemizedlist>

<para>Diálogos - díalogos completos para la selección de archivos, colores y fuentes. </para>

<itemizedlist>

<listitem><formalpara><title><ulink url="kdeapi:tdefile/KFileDialog">KFileDialog</ulink></title>
<para>Un diálogo de selección de archivos. </para>
</formalpara></listitem>

<listitem><formalpara><title><ulink url="kdeapi:tdeui/KColorDialog">KColorDialog</ulink></title>
<para>Un diálogo de selección de colores. </para>
</formalpara></listitem>

<listitem><formalpara><title><ulink url="kdeapi:tdeui/TDEFontDialog">TDEFontDialog</ulink></title>
<para>Un diálogo para la selección de fuentes. </para>
</formalpara></listitem>

<listitem><formalpara><title><ulink url="kdeapi:tdefile/TDEIconDialog">TDEIconDialog</ulink></title>
<para>Un diálogo para la selección de iconos. </para>
</formalpara></listitem>

<listitem><formalpara><title><ulink url="kdeapi:tdeui/KKeyDialog">KKeyDialog</ulink></title>
<para>Un diálogo para la edición de atajos de teclado. </para>
</formalpara></listitem>

<listitem><formalpara><title><ulink url="kdeapi:tdeui/KEditToolBar">KEditToolBar</ulink></title>
<para>Un diálogo para la edición de barras de herramientas. </para>
</formalpara></listitem>

<listitem><formalpara><title><ulink url="kdeapi:tdeui/KTipDialog">KTipDialog</ulink></title>
<para>Un diálogo para mostrar consejos. </para>
</formalpara></listitem>

<listitem><formalpara><title><ulink url="kdeapi:tdeui/TDEAboutDialog">TDEAboutDialog</ulink></title>
<para>Un diálogo de información de la aplicación. </para>
</formalpara></listitem>

<listitem><formalpara><title><ulink url="kdeapi:tdeui/KLineEditDlg">KLineEditDlg</ulink></title>
<para>Un diálogo simple para la entrada de texto. </para>
</formalpara></listitem>

<listitem><formalpara><title><ulink url="kdeapi:tdefile/KURLRequesterDlg">KURLRequesterDlg</ulink></title>
<para>Un diálogo simple para la entrada de URLs. </para>
</formalpara></listitem>

<listitem><formalpara><title><ulink url="kdeapi:tdeui/KMessageBox">KMessageBox</ulink></title>
<para>Un diálogo para indicar errores y advertencias. </para>
</formalpara></listitem>

<listitem><formalpara><title><ulink url="kdeapi:tdeui/KPasswordDialog">KPasswordDialog</ulink></title>
<para>Un diálogo para la entrada de contraseñas. </para>
</formalpara></listitem>

</itemizedlist>

<para>Acciones y entorno gráfico XML </para>

<itemizedlist>

<listitem><formalpara><title><ulink url="kdeapi:tdeui/TDEAction">TDEAction</ulink></title>
<para>Abstracción de una acción que puede ser conectada a barras de menús y barras de herramientas. </para>
</formalpara></listitem>

<listitem><formalpara><title><ulink url="kdeapi:tdeui/TDEActionCollection">TDEActionCollection</ulink></title>
<para>Un conjunto de acciones. </para>
</formalpara></listitem>

<listitem><formalpara><title><ulink url="kdeapi:tdeui/KXMLGUIClient">KXMLGUIClient</ulink></title>
<para>Un fragmento de entorno gráfico que contiene una colección de acciones y un árbol DOM que representa su ubicación en el entorno gráfico. </para>
</formalpara></listitem>

<listitem><formalpara><title><ulink url="kdeapi:tdeparts/KPartManager">KPartManager</ulink></title>
<para>Gestiona la activación de cliente de entorno gráfico XML. </para>
</formalpara></listitem>

</itemizedlist>

<para>Extensiones y componentes </para>

<itemizedlist>

<listitem><formalpara><title><ulink url="kdeapi:tdecore/KLibrary">KLibrary</ulink></title>
<para>Representa una biblioteca de carga dinámica. </para>
</formalpara></listitem>

<listitem><formalpara><title><ulink url="kdeapi:tdecore/KLibrary">KLibLoader</ulink></title>
<para>Carga de bibliotecas compartidas. </para>
</formalpara></listitem>

<listitem><formalpara><title><ulink url="kdeapi:tdecore/KLibFactory">KLibFactory</ulink></title>
<para>Factoría de objetos en las extensiones. </para>
</formalpara></listitem>

<listitem><formalpara><title><ulink url="kdeapi:tdeio/KServiceType">KServiceType</ulink></title>
<para>Representa un tipo de servicio. </para>
</formalpara></listitem>

<listitem><formalpara><title><ulink url="kdeapi:tdeio/KService">KService</ulink></title>
<para>Representa un servicio. </para>
</formalpara></listitem>

<listitem><formalpara><title><ulink url="kdeapi:tdeio/KMimeType">KMimeType</ulink></title>
<para>Representa un tipo MIME. </para>
</formalpara></listitem>

<listitem><formalpara><title><ulink url="kdeapi:tdeio/KServiceTypeProfile">KServiceTypeProfile</ulink></title>
<para>Preferencias del usuario para asignación de tipos MIME. </para>
</formalpara></listitem>

<listitem><formalpara><title><ulink url="kdeapi:tdeio/KServiceTypeProfile">TDETrader</ulink></title>
<para>Consultas para servicios. </para>
</formalpara></listitem>

</itemizedlist>

</simplesect>

</chapter>



<chapter id="graphics">
<title>Gráficos</title>

<sect1 id="graphics-qpainter">
<title>Gráficos de bajo nivel con QPainter</title>

<simplesect id="qpainter-rendering">
<title>Procesado con QPainter</title>

<para>El model de gráficos de bajo nivel de Qt se basa en las capacidades proporcionadas por X11 y otros sitemas de ventanas para los que existen versiones de Qt. Pero también extiende las opciones mencionadas implementando características adicionales como transformaciones de tamaño arbitrario para textos y mapas de pixels. </para>

<para>La clase central para la realización de gráficos 2D en Qt es <ulink url="kdeapi:qt/QPainter">QPainter</ulink>. Puede dibujar en un <ulink url="kdeapi:qt/QPaintDevice">QPaintDevice</ulink>. Hay implementados tres dispositivos de pintura posibles: uno es <ulink url="kdeapi:qt/TQWidget">TQWidget</ulink>, que representa un widget de la pantalla. El segundo es <ulink url="kdeapi:qt/QPrinter">QPrinter</ulink> que representa una impresora y produce salida PostScript. El tercero es la clase <ulink url="kdeapi:qt/QPicture">QPicture</ulink>, que almacena comandos de dibujo y puede guardarlos en el disco para reproducirlos posteriormente. Un formato de almacenamiento posible para los comandos de dibujo es el estándar de W3C denominado SVG. </para>

<para>Por lo tanto, es posible reutilizar el código de procesado que se utiliza para mostrar un widget en su impresión posterior, con las mismas características soportadas. Obviamente, en la práctica, el código se utiliza en un contexto ligeramente distinto. El dibujo en un widget se realiza casi exclusivamente en el método paintEvent() de la clase del widget. </para>

<programlisting>void FooWidget::paintEvent()
{
    QPainter p(esto);
    // Configurar sistema de dibujo
    // Utilizar sistema de dibujo
}
</programlisting>

<para>Al dibujar en la impresora, hay que asegurarse de utilizar QPrinter::newPage() para terminar una página y comenzar la siguiente - algo que, naturalmente, no resulta relevante al dibujar en los widgets. Además, al imprimir, puede ser interesante utilizar la <ulink url="kdeapi:qt/QPaintDeviceMetrics">métrica del dispositivo</ulink> para computar las coordenadas. </para>

</simplesect>


<simplesect id="qpainter-transformations">
<title>Transformaciones</title>

<para>De forma predeterminada, al utilizar QPainter, este dibuja en el sistema de coordenadas natural del dispositivo utilizado. Esto significa, si usted dibuja una línea a lo largo del eje horizontal con una longitud de 10 unidades, que aparecerá como una línea horizontal con una longitud de 10 píxeles en la pantalla. Sin embargo, QPainter puede aplicar transformaciones de tamaño arbitrario antes de dibujar físicamente las formas y las curvas. Una transformación de tamaño asigna las coordenadas x e y de forma lineal a x' e y' de acuerdo con </para>

<mediaobject>
<imageobject><imagedata fileref="affine-general.png"/></imageobject>
</mediaobject>

<para>La matriz 3x3 de esta ecuación se puede establecer con QPainter::setWorldMatrix() y es de tipo <ulink url="kdeapi:qt/QWMatrix">QWMatrix</ulink>. Normalmente, esta es la matriz de identidad, es decir, m11 y m22 son uno, y el resto de parámetros son cero. Básicamente hay tres grupos diferentes de transformaciones: </para>

<itemizedlist>

<listitem><formalpara>
<title>Desplazamientos</title>
<para>Mueven todos los puntos de un objeto una cantidad determinada en alguna dirección. Una matriz de desplazamiento se puede obtener invocando el método m.translate(dx, dy) de una QWMatrix. Esto corresponde a la matriz </para>
</formalpara>

<mediaobject>
<imageobject><imagedata fileref="affine-translate.png"/></imageobject>
</mediaobject>

</listitem>

<listitem><formalpara>
<title>Escalado</title>
<para>Amplian o reducen las coordenadas de un objeto para hacerlo mayor o menor evitando la distorsión. Una transformación de escalado se puede aplicar a una QWMatrix invocando m.scale(sx, sy). Esto corresponde a la matriz </para>
</formalpara>

<mediaobject>
<imageobject><imagedata fileref="affine-scale.png"/></imageobject>
</mediaobject>

<para>Si se establece uno de los parámetros a un valor negativo, se puede conseguir una visión simétrica del sistema de coordenadas. </para>

</listitem>

<listitem><formalpara>
<title>Corte</title>
<para>Una distorsión del sistema de coordenadas con dos parámetros. Una transformación de corte se puede aplicar invocanza m.shear(sh, sv), correspondiente a la matriz </para>
</formalpara>

<mediaobject>
    <imageobject><imagedata fileref="affine-shear.png"/></imageobject>
</mediaobject>

</listitem>

<listitem><formalpara>
<title>Giro</title>
<para>Gira un objeto. Una transformación de giro se puede aplicar invocando m.rotate(alpha). Tenga en cuenta que el ángulo debe ser expresado en grados, y no como un ángulo matemático. La matriz correspondiente es </para>
</formalpara>

<mediaobject>
<imageobject><imagedata fileref="affine-rotate.png"/></imageobject>
</mediaobject>

<para>Fíjese en que un giro es equivalente a una combinación de escalado y corte. </para>

</listitem>

</itemizedlist>

<para>Aquí se muestran algunas imágenes que muestran el efecto de transformaciones elementales sobre nuestra mascota: </para>

<informaltable frame="none">
<tgroup cols="3">
<tbody>
<row>
<entry><mediaobject>
    <imageobject><imagedata fileref="konqi-normal.png"/></imageobject>
</mediaobject></entry>
<entry><mediaobject>
    <imageobject><imagedata fileref="konqi-rotated.png"/></imageobject>
</mediaobject></entry>
<entry><mediaobject>
    <imageobject><imagedata fileref="konqi-sheared.png"/></imageobject>
</mediaobject></entry>
<entry><mediaobject>
   <imageobject><imagedata fileref="konqi-mirrored.png"/></imageobject>
</mediaobject></entry>
</row>
<row>
<entry>a) Normal</entry>
<entry>b) Girado 30 grados</entry>
<entry>c) Corte a 0.4</entry>
<entry>d) Simétrico</entry>
</row>
</tbody>
</tgroup>
</informaltable>

<para>Es posible combinar las transformaciones multiplicando matrices elementales. Tenga en cuenta que las operaciones entre matrices normalmente no son conmutables, y por lo tanto el efecto combinado de una concatenación depende del orden en el que las matrices hayan sido multiplicadas. </para>

</simplesect>


<simplesect id="qpainter-strokeattributes">
<title>Establecimiento de atributos de ajuste</title>

<para>Es posible modificar el procesado de líneas, curvas y bordes de polígonos estableciendo un pincel especial con QPainter::setPen(). El argumento de esta función es un objeto <ulink url="kdeapi:qt/QPen">QPen</ulink>. Las propiedades que almacena son estilo, color, estilo de unión y estilo de tope. </para>

<para>El estilo de pincel es un miembro de la enumeración <ulink url="kdeapi:qt/Qt#PenStyle-enum">TQt::PenStyle</ulink>. Puede tomar uno de los siguientes valores: </para>

<mediaobject>
    <imageobject><imagedata fileref="penstyles.png"/></imageobject>
</mediaobject>

<para>El estilo de unión es un miembro de la enumeración <ulink url="kdeapi:qt/Qt#PenJoinStyle-enum">TQt::PenJoinStyle</ulink>. Especifica cómo se debe dibujar la unión entre múltiples líneas que están conectadas unas con otras. Puede tomar uno de los siguientes valores: </para>

<informaltable frame="none">
<tgroup cols="3">
<tbody>
<row>
<entry><mediaobject>
    <imageobject><imagedata fileref="joinmiter.png"/></imageobject>
</mediaobject></entry>
<entry><mediaobject>
    <imageobject><imagedata fileref="joinbevel.png"/></imageobject>
</mediaobject></entry>
<entry><mediaobject>
    <imageobject><imagedata fileref="joinround.png"/></imageobject>
</mediaobject></entry>
</row>
<row>
<entry>a) MiterJoin</entry>
<entry>c) BevelJoin</entry>
<entry>b) RoundJoin</entry>
</row>
</tbody>
</tgroup>
</informaltable>

<para>El estilo de tope es un miembro de la enumeración <ulink url="kdeapi:qt/Qt#PenCapStyle-enum">TQt::PenCapStyle</ulink>, y especifica cómo se deben dibujar los puntos finales de las líneas. Toma uno de los valores de la siguiente tabla: </para>

<informaltable frame="none">
<tgroup cols="3">
<tbody>
<row>
<entry><mediaobject>
    <imageobject><imagedata fileref="capflat.png"/></imageobject>
</mediaobject></entry>
<entry><mediaobject>
    <imageobject><imagedata fileref="capsquare.png"/></imageobject>
</mediaobject></entry>
<entry><mediaobject>
    <imageobject><imagedata fileref="capround.png"/></imageobject>
</mediaobject></entry>
</row>
<row>
<entry>a) FlatCap</entry>
<entry>b) SquareCap</entry>
<entry>c) RoundCap</entry>
</row>
</tbody>
</tgroup>
</informaltable>

</simplesect>


<simplesect id="qpainter-fillattributes">
<title>Establecimiento de atributos de relleno</title>

<para>El estilo de relleno de los polígonos, círculos o rectángulos se puede modificar especificanto un tipo especial de brocha con QPainter::setBrush(). Esta función tiene un objeto <ulink url="kdeapi:qt/QBrush">QBrush</ulink> como argumento. Las brochas se pueden construir de cuatro maneras diferentes: </para>

<itemizedlist>
<listitem>
<para>QBrush::QBrush() - Crea una brocha que no rellena las figuras.</para>
</listitem>
<listitem>
<para>QBrush::QBrush(BrushStyle) - Crea una brocha negra con uno de los siguientes patrones mostrados a continuación.</para>
</listitem>
<listitem>
<para>QBrush::QBrush(const TQColor &amp;, BrushStyle) - Crea una brocha de color con uno de los patrones mostrados a continuación.</para>
</listitem>
<listitem>
<para>QBrush::QBrush(const TQColor &amp;, const QPixmap) - Crea una brocha de color con el patrón personalizado que se proporcione como segundo parámetro.</para>
</listitem>
</itemizedlist>

<para>Un estilo de brocha predeterminado se obtiene de la enumeración <ulink url="kdeapi:qt/Qt#BrushStyle-enum">TQt::BrushStyle</ulink>. Esta es una muestra de todos los patrones predefinidos: </para>

<mediaobject>
    <imageobject><imagedata fileref="brushstyles.png"/></imageobject>
</mediaobject>

<para>Una forma más avanzada de personalizar el comportamiento de la brocha es mediante la función QPainter::setBrushOrigin(). </para>

</simplesect>


<simplesect id="qpainter-color">
<title>Color</title>

<para>Los colores juegan un papel tanto al ajustar curvas como al rellenar figuras. En Qt, los colores están representados por la clase <ulink url="kdeapi:qt/TQColor">TQColor</ulink>. Qt no soporta características gráficas avanzadas como perfiles de color ICC y corrección de color. Los colores se construyen normalmente especificando sus componentes rojo, verde y azul, siguiendo el modelo RGB que utilizan los monitores para dibujar los pixels. </para>

<para>También es posible utilizar tono, saturación y valor. Esta representación (HSV) es la que se utiliza en el diálogo de color de Gtk, por ejemplo en GIMP. En este caso, el tono corresponde al ángulo en la rueda de color, mientras que la saturación corresponde a la distancia desde el centro de círuclo. El valor se puede elegir con un selector independiente. </para>

</simplesect>


<simplesect id="qpainter-paintsettings">
<title>Otros parámetros</title>

<para>Normalmente, al pintar en un dispositivo de pintura, los pixels que se dibujan reemplazan a los existentes anteriormente. Esto significa que si usted pinta ciertas regiones de uno color rojo y después pinta las mismas zonas con un color azul, únicamente será visible el color azul. El modelo de dibujo de Qt no soporta la transparencia, es decir, una forma de mezclar los colores principal y de fondo de un dibujo. Sin embargo, hay un método muy sencillo para combinar el primer plano y el fondo a través de operadores booleanos. El método QPainter::setRasterOp() establece el operador utilizado, que viene de la enumeración <ulink url="kdeapi:qt/Qt#RasterOp-enum">RasterOp</ulink>. </para>

<para>El predeterminado es CopyROP, que ignora el color de fondo. Otra elección popular es XorROP. Si dibuja una línea negra con este operador sobre una imagen en color, el área cubierta aparecerá invertida. Este efecto se utiliza, por ejemplo, para crear el borde de los cuadros de selección de los programas de manipulación de imágenes, y que se conoce como "ejército de hormigas". </para>

</simplesect>


<simplesect id="qpainter-primitives">
<title>Primitivas de dibujo</title>

<para>A continuación se muestra una lista de los elementos gráficos básicos soportados por QPainter. La mayoría van acompañados de versiones sobrecargadas que admiten un diferente número de argumentos. Por ejemplo, los métodos relacionados con rectácngulos normalmente admiten como argumentos un <ulink url="kdeapi:qt/QRect">QRect</ulink> o un conjunto de cuatro enteros. </para>

<itemizedlist>
<listitem>
<para>Dibujo de un único punto - drawPoint().</para>
</listitem>
<listitem>
<para>Dibujo de líneas - drawLine(), drawLineSegments() y drawPolyLine().</para>
</listitem>
<listitem>
<para>Dibujo y relleno de rectángulos - drawRect(), drawRoundRect(), fillRect() y eraseRect().</para>
</listitem>
<listitem>
<para>Dibujo y relleno de círculos, elipses o parte de ellos - drawEllipse(), drawArc(), drawPie y drawChord().</para>
</listitem>
<listitem>
<para>Dibujo y relleno de polígonos generales - drawPolygon().</para>
</listitem>
<listitem>
<para>Dibujo de curvas bezier - drawQuadBezier() [drawCubicBezier en Qt 3.0].</para>
</listitem>
</itemizedlist>

</simplesect>


<simplesect id="qpainter-pixmaps">
<title>Dibujo de mapas de pixels e imágenes</title>

<para>Qt proporciona dos clases muy diferentes para la representación de imágenes. </para>

<para><ulink url="kdeapi:qt/QPixmap">QPixmap</ulink> corresponde directamente a los objetos de mapas de pixels de X11. Los mapas de pixels son objetos del lado del servidor y pueden (en la mayoría de las tarjetas gráficas modernas) ser almacenadas directamente en la memoria de la tarjeta. Esto hace que sean <emphasis>muy</emphasis> eficientes para tranferir mapas de pixels a la pantalla. Los mapas de pixels también funcionan como los equivales de fuera de la pantalla de los widgets; la clase QPixmap es una subclase de QPaintDevice, por lo que es posible dibujarla con un QPainter. Las operaciones elementales de dibujo normalmente se ven aceleradas por los adaptadores gráficos modernos. Por lo tanto, una conducta muy habitual es la de utilizar mapas de pixels para trabajar con doble buffer. Esto significa, en vez de dibujar directamente sobre un widget, que sea crea un objeto de mapa de pixels temporal y se utiliza la función <ulink url="kdeapi:qt/QPaintDevice#bitBlt-1">bitBlt</ulink> para tranferir el mapa de pixels al widget. En casos de redibujados complejos, esto ayuda a evitar el efecto de parpadeo. </para>

<para>Por contra, el objeto <ulink url="kdeapi:qt/TQImage">TQImage</ulink> permanece en el lado del cliente. Su ventaja está en que proporciona acceso directo a los pixels de la imagen. Esto lo hace útil para la manipulación de imágenes, y operaciones como la carga y almacenamiento en disco (el método load() de QPixmap utiliza TQImage en un paso intermedio). Por otro lado, dibujar una imagen en un widget es una operación con un consumo de recursos relativamente alto, ya que implica una transferencia al servidor X, lo que puede llevar algún tiempo, especialmente en imágenes grandes y servidores remotos. Dependiendo de la profundidad de color, la conversión de TQImage a QPixmap puede requerir también un proceso de reducción del número de colores. </para>

</simplesect>


<simplesect id="qpainter-drawingtext">
<title>Dibujo de texto</title>

<para>Es posible dibujar texto con una de las variantes sobrecargadas del método QPainter::drawText(). De esta forma se dibuja una TQString en un punto o en un rectángulo dado, utilizando la fuente establecida por QPainter::setFont(). También hay un parámetro que admite una combinación OR de algunos parámetros obtenidos de las enumeraciones <ulink url="kdeapi:qt/Qt#AlignmentFlags-enum">TQt::AlignmentFlags</ulink> y <ulink url="kdeapi:qt/Qt#TextFlags-enum">TQt::TextFlags</ulink> </para>

<para>A partir de la versión 3.0, Qt se encarga completamente de la disposición del texto incluso en los idiomas escritos de derecha a izquierda. </para>

<para>Una forma más avanzada de mostrar texto con formato es la clase <ulink url="kdeapi:qt/QSimpleRichText">QSimpleRichText</ulink>. Los objetos de esta clase se pueden construir a partir de un texto que utilice un subconjunto de etiquetas HTML, lo cual mejora el aspecto y puede proporcionar incluso tablas. El estilo del texto se puede personalizar utilizando un <ulink url="kdeapi/qt/QStyleSheet">QStyleSheet</ulink> (también se puede encontrar aquí la documentación de las etiquetas). Una vez que se ha construido el objeto de texto enriquecido, se puede dibujar sobre un widget u otro dispositivo de dibujo utilizando el método QSimpleRichText::draw(). </para>

</simplesect>

</sect1>


<sect1 id="graphics-qcanvas">
<title>Gráficos estructurados con QCanvas</title>

<para>QPainter ofrece un potente modelo de dibujo para realizar representaciones sobre widgets y mapas de pixels. Sin embargo, puede ser complicado de utilizar. Cada vez que un widget recibe un evento de dibujo, tiene que analizar la QPaintEvent::region() o la QPaintEvent::rect() que debe ser redibujada. También tiene que configurar un QPainter y dibujar todos los objetos que se superponen con ese área. Por ejemplo, imagine un programa de gráficos vectoriales que permite arrastrar y mover objetos como polígonos, círculos o grupos de ellos. Cada vez que uno de esos objetos se mueve un poco, el evento de movimiento del ratón de widget dispara un evento de dibujo para toda la zona cubierta por los objetos de las posiciones antigua y nueva. Calcular las operaciones de redibujado necesarias y realizarlas de forma eficientes puede resultar difícil, y también podría entrar en conflicto con las estructura orientada a objetos del código fuente del programa. </para>

<para>Como alternativa, Qt contiene la clase <ulink url="kdeapi:qt/QCanvas">QCanvas</ulink> en la que es posible colocar objetos gráficos como polígonos, texto y mapas de pixels. También es posible incluir elementos adicionales a través de una subclase de <ulink url="kdeapi:qt/QCanvasItem">QCanvasItem</ulink> o de una de sus subclases más especializadas. Un espacio de dibujo puede ser mostrado en la pantalla por uno o más widgets de la clase <ulink url="kdeapi:qt/QCanvas">QCanvasView</ulink> de la que hay que derivar subclases para manejar la interacción con el usuario. Qt se encarga de todas las operaciones de redibujado de los objetos en la vista, ya sean estas causadas por el widget mostrado, por nuevos objetos creados o modificados u otras razones. Al utilizar un doble búfer, estas operaciones se realizan con eficiencia y evitando el efecto parpadeo. </para>

<para>Los espacios de dibujo se pueden superponer. Este este caso, el que resultará visible depende el orden en el eje z al que hayan sido asignados mediante QCanvasItem::setZ(). Los elementos también pueden ser visibles o invisibles. También puede proporcionar un fondo para que sea dibujado "detrás" de todos los demás elementos. Para asociar eventos del ratón a los objetos del espacio de dibujo, existe el método QCanvas::collisions(), de devuelve una lista de elementos superpuestos en un punto dado. Aquí mostramos una instantánea de una vista de espacio de dibujo en acción: </para>

<mediaobject>
<imageobject><imagedata fileref="canvas.png"/></imageobject>
</mediaobject>

<para>En este caso, la malla está dibujada en el fondo. Además hay un elemento QCanvasText y un QCanvasPolygon violeta. La mariposa es un QCanvasPixmap. Tiene zonas transparentes, por lo que se pueden ver los demás objetos a través de ella. </para>

<para>Se puede encontrar un tutorial para el uso de QCanvas en el desarrollo de juegos basados en sprites <ulink url="http://zez.org/article/articleview/2/1/">aquí</ulink>. </para>

</sect1>


<sect1 id="graphics-qglwidget">
<title>Gráficos 3D con OpenGL</title>

<simplesect id="qglwidget-lowlevel">
<title>Interfaz de bajo nivel</title>

<para>El estándar de facto actual para la realización de gráficos 3D es <ulink url="http://www.opengl.org">OpenGL</ulink>. Se encuentran implementaciones de esta especificación en Microsoft Windows, Mac OS X y XFree86 y normalmente también está soportado en la aceleración por hardware de las tarjetas gráficas modernas. OpenGL en sí únicamente se ocupa del procesado en un área de un framebuffer a través de un <emphasis>contexto GL</emphasis> y no tiene ningún tipo de interacción con el entorno de desarrollo. </para>

<para>Qt ofrece el widget <ulink url="kdeapi:qt/QGLWidget">QGL Widget</ulink> que encapsula una ventana con un contexto GL asociado. Básicamente se utiliza realizando subclases y reimplementando algunos métodos. </para>

<itemizedlist>

<listitem><para>En vez de reimplementar paintEvent() y utilizar QPainter para dibujar el contenido de un widget, es mejor utilizar paintGL() y emplear comandos GL para procesar una escena. QLWidget se encargará de hacer que su contexto GL sea el activo antes de que se llame a paintGL(), y posteriormente volcará toda la información. </para></listitem>

<listitem><para>El método virtual initializeGL() se llama una vez antes de las primera invocaciones de resizeGL() o paintGL(). Esto se utiliza para la construcción de listas visuales para objetos y para iniciar el entorno. </para></listitem>

<listitem><para>En ver se reimplementar resizeEvent(), se utiliza resizeGL(). Sirve para establacer el modo vista de forma correcta. </para></listitem>

<listitem><para>En vez de llamar a update() cuando el estado de la escena haya cambiado (por ejemplo, si se realiza animación con un temporizador), debería llamar a updateGL(). Esto provocará el redibujado. </para></listitem>

</itemizedlist>

<para>En general, QGLWidget se comporta como cualquier otro widget, es decir, los eventos del ratón se procesan normalmente, se puede redimensionar el widget y combinarlo con otros en una vista. </para>

<mediaobject>
<imageobject><imagedata fileref="opengl.png"/></imageobject>
</mediaobject>

<para>Qt contiene algunos ejemplos del uso de QGLWidget en su ejemplo <literal>demo</literal>. Se puede encontrar una colección de tutoriales <ulink url="http://www.libsdl.org/opengl/intro.html">aquí</ulink>, y más información junto a una referencia de OpenGL está disponible en la <ulink url="http://www.opengl.org">página web de OpenGL</ulink>. </para>

</simplesect>


<simplesect id="qglwidget-highlevel">
<title>Interfaces de alto nivel</title>

<para>OpenGL es un interfaz de relativo bajo nivel para el trazado de gráficos en 3D. De la misma forma que QCanvas proporciona al programador un interfaz de alto nivel para tratar con detalle los objetos y sus propiedades, también hay interfaces de alto nivel para los gráficos en 3D. Uno de los más populares es Open Inventor. Una tecnología desarrolladoa originalmente por SGI, que hoy en día tiene una implementación de código abierto llamada <ulink url="http://www.coin3d.org">Coin</ulink>, complementada por un entorno de desarrollo para Qt llamado SoQt. </para>

<para>El concepto básico de Open Inventor es la <emphasis>escena</emphasis>. Es posible cargar una escena del disco y guardarla en un formato especial muy unido a <ulink url="http://www.vrml.org">VRML</ulink>. Una escena consta de una colección de objetos llamados <emphasis>nodos</emphasis>. Inventor proporciona una interesante colección de nodos reutilizables, como cubos, cilindros y mallas, además de fuentes de luz, materiales, cámaras, etc. Los nodos están representados por clases de C++ y pueden ser combinados y tratados como subclases. </para>

<para>Puede encontrar una introducción a Inventor <ulink url="http://www.motifzone.com/tmd/articles/OpenInventor/OpenInventor.html">aquí</ulink> (por regla general, es posible sustituir los métodos de SoXt descritos en el artículo por los de SoQt). </para>

</simplesect>

</sect1>

</chapter>



<chapter id="userinterface">
<title>Interfaz de usuario</title>

<sect1 id="userinterface-actionpattern">
<title>El patrón de acción</title>

<para></para>

</sect1>


<sect1 id="userinterface-xmlgui">
<title>Definición de menús y barras de herramientas en XML</title>

<simplesect id="xmlgui-intro">
<title>Introducción</title>

<para>Mientras que el <link linkend="userinterface-actionpattern">patrón de acción</link> permite encapsular acciones disparadas por el usuario en un objeto que puede ser "conectado" en cualquier punto de las barrás de menú o de herramientas, no resuelve por sí mismo el problema de construir los propios menús. En particular, es necesario construir los menús desplegables en el código C++ e insertar explícitamente las acciones en un cierto orden, teniendo en consideración la guía de estilo de las acciones estándar. Esto hace muy difícil que es usuario pueda personalizar los menús o modificar los accesos directos a su gusto, ya que debería modificar el código fuente. </para>

<para>Este problema se resuelve por medio de un conjunto de clases llamado <literal>XMLGUI</literal>. Básicamente separa las acciones (programadas en C++) de su aspecto en las barras de menú y herramientas (programadas en XML). Sin tener que modificar el código fuente, es posible personalizar los menús ajustando un archivo XML. Además, esto ayuda a asegurar que las acciones estándar (como <menuchoice><guimenu>Archivo</guimenu><guimenuitem>Abrir</guimenuitem></menuchoice> o <menuchoice><guimenu>Ayuda</guimenu><guimenuitem>Acerca de...</guimenuitem></menuchoice>) aparezcan en las ubicaciones sugeridas por la guía de estilo. XMLGUI es especialmente importante en los programas modulares, donde los elementos que aparecen en las barras de menú pueden varias en función de las extensiones instaladas. </para>

<para>La clase de KDE para las ventanas de primer nivel, <ulink url="kdeapi:tdeui/TDEMainWindow.html">TDEMainWindow</ulink> es heredera de <ulink url="kdeapi:tdeui/KXMLGUIClient.html">KXMLGUIClient</ulink> y, por lo tanto, soporta XMLGUI directamente. Todas las acciones creadas dentro deben tener como superior jerárquico un <literal>actionCollection()</literal> del cliente. Una llamada a <literal>createGUI()</literal> construirá el conjunto completo de menús y barras de herramientas definidos en el archivo XML de la aplicación (normalmente con el sufijo <literal>ui.rc</literal>). </para>

</simplesect>


<simplesect id="xmlgui-kviewexample">
<title>Un ejemplo: el menú de KView</title>

<para>A continuación tomamos como ejemplo el visor de imágenes de KDE <application>KView</application>. Tiene un archivo <literal>ui.rc</literal> llamado <filename>kviewui.rc</filename> que es instalado por orden de <filename>Makefile.am</filename> </para>

<programlisting>rcdir = $(kde_datadir)/kview
rc_DATA = kviewui.rc
</programlisting>

<para>Esto es un extracto de <filename>kviewui.rc</filename>. Para simplificar el ejemplo, mostramos únicamente la definición del menú <guimenu>Ver</guimenu>. </para>

<programlisting>&lt;!DOCTYPE kpartgui&gt;
&lt;kpartgui name="kview"&gt;
  &lt;MenuBar&gt;
    &lt;Menu name="view" &gt;
      &lt;Action name="zoom50" /&gt;
      &lt;Action name="zoom100" /&gt;
      &lt;Action name="zoom200" /&gt;
      &lt;Action name="zoomMaxpect" /&gt;
      &lt;Separator/&gt;
      &lt;Action name="fullscreen" /&gt;
    &lt;/Menu&gt;
  &lt;/MenuBar&gt;
&lt;/kpartgui&gt;
</programlisting>

<para>La parte de código correspondiente en C++ es: </para>

<programlisting>KStdAction::zoomIn    ( this, SLOT(slotZoomIn()), actionCollection() );
  KStdAction::zoomOut   ( this, SLOT(slotZoomOut()), actionCollection() );
  KStdAction::zoom      ( this, SLOT(slotZoom()), actionCollection() );
  new TDEAction           ( i18n("&amp;Half size"), ALT+Key_0, 
                          this, SLOT(slotHalfSize()), 
                          actionCollection(), "zoom50" );
  new TDEAction           ( i18n("&amp;Normal size"), ALT+Key_1,
                          this, SLOT(slotDoubleSize()), 
                          actionCollection(), "zoom100" );
  new TDEAction           ( i18n("&amp;Double size"), ALT+Key_2, 
                          this, SLOT(slotDoubleSize()), 
                          actionCollection(), "zoom200" );
  new TDEAction           ( i18n("&amp;Fill Screen"), ALT+Key_3, 
                          this, SLOT(slotFillScreen()), 
                          actionCollection(), "zoomMaxpect" );
  new TDEAction           ( i18n("Fullscreen &amp;Mode"), CTRL+SHIFT+Key_F, 
                          this, SLOT(slotFullScreen()), 
                          actionCollection(), "fullscreen" );
</programlisting>

<para>El menú <guimenu>Ver</guimenu> que aparece en el entorno gráfico resultante tiene este aspecto: </para>

<mediaobject>
<imageobject><imagedata fileref="kview-menu.png"/></imageobject>
</mediaobject>

<para>El archivo XML comienza con una declaración del tipo de documento. La DTD para kpartgui se puede encontrar en el código fuente de kdelib, en el archivo <filename>tdeui/kpartgui.dtd</filename>. El elemento más externo del archivo contiene el nombre de la instancia de la aplicación como atributo. También puede contener un número de versión con el formato "version=2". Esto le puede resultar útil cuando crea nuevas versiones de una aplicación con una estructura de menú distinta (por ejemplo, con más características). Si incrementa el número de versión del archivo <literal>ui.rc</literal>, KDE se asegura de que cualquier versión personalizada del archivo sea desechada y se use en su lugar el nuevo archivo. </para>

<para>La siguiente línea, <literal>&lt;MenuBar&gt;</literal>, contiene una declaración de una barra de menú. También puede insertar cualquier número de declaraciones <literal>&lt;ToolBar&gt;</literal> para crear algunas barras de herramientas. El menú contiene un submenú con el nombre «view». Este nombre ya está predefinido, por lo que verá una versión traducida de la palabra «View» en la captura de pantalla. Si declara sus propios submenús, tendrá que añadir su título explícitamente. Por ejemplo, <application>KView</application> tiene un submenú con el título «Image», que está declarado del siguiente modo: </para>

<programlisting>&lt;Menu name="image" &gt;
   &lt;text&gt;&amp;amp;Image&lt;/text&gt;
   ...
&lt;/Menu&gt;
</programlisting>

<para>En la infraestructura automake de KDE, estos títulos se extraen automáticamente y se ponen en el archivo <ulink url="tde-i18n-howto.html"><literal>.po</literal></ulink>, de modo que puedan ser tenidos en cuenta por los traductores. Tenga en cuenta que deberá escribir la marca de acceso rápido «&amp;» en modo compatible con XML (en la forma «&amp;amp;»). </para>

<para>Volvamos al ejemplo. El menú <guimenu>View</guimenu> de <application>KView</application> contiene varias acciones personalizadas: <literal>zoom50</literal>, <literal>zoom100</literal>, <literal>zoom200</literal>, <literal>zoomMaxpect</literal> y <literal>fullscreen</literal>, declarados mediante un elemento <literal>&lt;Action&gt;</literal>. El separador de las capturas de pantalla corresponde al elemento <literal>&lt;Separator&gt;</literal>. </para>

<para>Notará que algunos elementos del menú no poseen su correspondiente entrada en el archivo XML. Se trata de las <emphasis>acciones estándar</emphasis>. Las acciones estándar son creadas por la clase <ulink url="kdeapi:tdeui/KStdAction.html">KStdAction</ulink>. Cuando cree estas acciones en su aplicación (como las del anterior ejemplo en C++ ), se insertarán de forma automática en una posición preestablecida, y posiblemente con un icono y un acceso rápido. Puede buscar estas posiciones en el archivo <filename>tdeui/ui_standards.rc</filename> en el código fuente de tdelibs. </para>

</simplesect>


<simplesect id="xmlgui-konqexample">
<title>Un ejemplo: las barras de herramientas de Konqueror</title>

<para>Para ilustrar la discusión sobre las barras de herramientas, veremos la definición de la interfaz gráfica de <application>Konqueror</application>. Este trozo de código define la barra de dirección, que contiene el campo de entrada para introducir una URL. </para>

<programlisting>&lt;ToolBar name="locationToolBar" fullWidth="true" newline="true" &gt;
  &lt;text&gt;Location Toolbar&lt;/text&gt;
  &lt;Action name="clear_location" /&gt;
  &lt;Action name="location_label" /&gt;
  &lt;Action name="toolbar_url_combo" /&gt;
  &lt;Action name="go_url" /&gt;
&lt;/ToolBar&gt;
</programlisting>

<para>Lo primero que notamos es que hay muchos más atributos que para las barras de menú, como: </para>

<itemizedlist>

<listitem><para><literal>fullWidth</literal>: Comunica a XMLGUI que la barra de herramientas tiene el mismo ancho que la ventana de nivel superior. Si tiene el valor «false», la barra de herramientas solo ocupará el espacio que necesite, y el resto de barras de herramientas se colocará en la misma fila. </para></listitem>

<listitem><para><literal>newline</literal>: Esto está relacionado con la opción anterior. Si «newline» es «true», la barra de herramientas se coloca al comienzo de una nueva fila. En caso contrario podrá ser colocada en la misma fila que la barra de herramientas previa. </para></listitem>

<listitem><para><literal>noEdit</literal>: Normalmente, el usuario puede personalizar las barras de herramientas, por ejemplo en <menuchoice><guimenu>Preferencias</guimenu><guimenuitem>Configurar barras de herramientas</guimenuitem></menuchoice> en <application>Konqueror</application>. Si se cambia el valor de esta opción a «true», la barra de herramientas será marcada como no editable. Esto es importante para las barras de herramientas que se rellenan con elementos en tiempo de ejecución, como la barra de marcadores de <application>Konqueror</application>. </para></listitem>

<listitem><para><literal>iconText</literal>: Hace que la interfaz gráfica XML muestre el texto de la acción junto al icono. Normalmente, el texto solo se muestra como ayuda emergente cuando el cursor del ratón permanece sobre el icono durante un corto espacio de tiempo. Los valores posibles para este atributo son «iconolny» (muestra solo el icono), «textonly» (muestra solo el texto), «icontextright» (muestra el texto a la derecha del icono) e «icontextbottom» (muestra el texto debajo del icono). </para></listitem>


<listitem><para><literal>hidden</literal>: Si vale «true», la barra de herramientas no será visible inicialmente y tendrá que ser activada mediante algún elemento del menú. </para></listitem>


<listitem><para><literal>position</literal>: El valor predeterminado para este atributo es «top», y significa que la barra de herramientas será posicionada bajo la barra de menú. Para los programas con muchas herramientas, como los programas de gráficos, puede ser interesante sustituir este valor por «left», «right» o «bottom». </para></listitem>

</itemizedlist>

</simplesect>


<simplesect id="xmlgui-dynamical">
<title>Menús dinámicos</title>

<para>Obviamente, un archivo XML solo puede contener una descripción estática de una interfaz de usuario. A menudo, existen menús que se modifican en tiempo real. Por ejemplo, el menú <guimenu>Dirección</guimenu> de <application>Konqueror</application> contiene un conjunto de elementos <guimenuitem>Abrir con X</guimenuitem> con las aplicaciones capaces de cargar un archivo con un tipo MIME concreto. Cada vez que cambia el documento mostrado, se modifica la lista de estos elementos del menú. XMLGUI está preparado para manejar estos casos mediante el uso de <emphasis>listas de acciones</emphasis>. Una lista de acciones se declara como un único elemento en el archivo XML, pero consta de varias acciones que se conectan al menú en tiempo de ejecución. El ejemplo anterior se implementa con la siguiente declaración en el archivo XML de <application>Konqueror</application>: </para>

<programlisting>&lt;Menu name="file"&gt;
  &lt;text&gt;&amp;amp;Location&lt;/text&gt;
  ...
  &lt;ActionList name="openwith"&gt;
  ...
&lt;/Menu&gt;
</programlisting>

<para>La función <function>KXMLGUIClient::plugActionList()</function> se usará para añadir acciones a ser mostradas, mientras que la función <function>KXMLGuiClient::unplugActionList()</function> eliminará todas las acciones conectadas. La rutina responsable de la actualización es semejante a la siguiente: </para>

<programlisting>void MainWindow::updateOpenWithActions()
{
    unplugActionList("openwith");
    openWithActions.clear();
    for ( /* repetir sobre los servicios importantes */ ) {
        TDEAction *action = new TDEAction( ...);
        openWithActions.append(action);
    }
    plugActionList("openwith", openWithActions);
}
</programlisting>

<para>Tenga en cuenta que, al contrario que las acciones estáticas, las que se crean aquí <emphasis>no</emphasis> están construidas con la colección de acciones como objeto padre, por lo que usted será el responsable de eliminarlas. El modo más sencillo de realizar esto consiste en usar <literal>openWithActions.setAutoDelete(true)</literal>, como en el ejemplo anterior. </para>

</simplesect>


<simplesect id="xmlgui-contextmenus">
<title>Menús de contexto</title>

<para>Los ejemplos anteriores solo trataban de casos en los que se creaba una barra de menú y barras de herramientas para la ventana principal. En estos casos, los procesos que construyen estos contenedores están completamente ocultos en la llamada a <function>createGUI()</function> (excepto cuando hay que crear contenedores personalizados). De todos modos, existen casos en los que se necesita construir otros contenedores y llenarlos con definiciones de interfaz gráfica procedentes de un archivo XML. Uno de estos ejemplos son los menús de contexto. Para obtener un puntero a un menú de contexto, necesitará pedírselo a la «fábrica» del cliente: </para>

<programlisting>void MainWindow::popupRequested()
{
    TQWidget *w = factory()->container("context_popup", this);
    QPopupMenu *popup = static_cast&lt;QPopupMenu *&gt;(w);
    popup->exec(QCursor::pos());
}
</programlisting>

<para>El método <function>KXMLGUIFactory::container()</function> usado arriba comprueba si puede encontrar un contenedor con un nombre dado en el archivo XML. De este modo, una posible definición podría ser: </para>

<programlisting>...
&lt;Menu name="context_popup"&gt;
  &lt;Action name="file_add"/&gt;
  &lt;Action name="file_remove"/&gt;
&lt;/Menu&gt;
...
</programlisting>

</simplesect>

</sect1>


<sect1 id="help">
<title>Proporcionando ayuda en línea</title>

<para>Hacer que un programa sea fácil e intuitivo de manejar requiere de un amplio abanico de utilidades que normalmente se denominan ayuda en línea. La ayuda en línea tiene varios objetivos (a veces conflictivos): por un lado, debe proporcionar al usuario respuestas a la pregunta «¿Cómo puedo hacer una determinada tarea?», y por otro, debe ayudar al usuario a explorar la aplicación y a encontrar características que aún no conocía. Es importante reconocer que esto solo se puede conseguir ofreciendo diversos niveles de ayuda: </para>

<itemizedlist>

<listitem><para>Las ayudas emergentes son pequeñas etiquetas que aparecen sobre los elementos de la interfaz de usuario cuando el cursor del ratón permanece sobre ellos durante un corto espacio de tiempo. Son especialmente importantes para las barras de herramientas, donde un icono no siempre resulta suficiente para explicar el propósito de un botón. </para></listitem>

<listitem><para>La ayuda «¿Qué es esto?» consiste normalmente en una larga y rica explicación sobre un «widget» o sobre un elemento del menú. También es algo más lenta de usar. En los diálogos, se puede invocar de dos formas: bien pulsando <keycombo><keycap>Mayúsculas</keycap><keycap>F1</keycap></keycombo>, o pulsando con el ratón sobre el símbolo de interrogación en la barra de título (aunque esto depende de la configuración del gestor de ventanas que esté usando). El puntero del ratón cambia entonces a una flecha con un signo de interrogación, y la ventana de ayuda aparecerá cuando el usuario pulse sobre algún elemento de la interfaz. En los elementos de los menús, la ayuda «¿Qué es esto?» se activa normalmente mediante un botón de la barra de herramientas que contiene una flecha y un signo de interrogación. </para></listitem>

<listitem><para>El problema de esta aproximación es que el usuario no puede ver cuándo un «widget» proporciona ayuda o no. Si un usuario activa el botón con el signo de interrogación y no obtiene ninguna ventana de ayuda al pulsar sobre un elemento de la interfaz de usuario, probablemente se sentirá frustrado. </para>

<para>La ventaja de las ventanas de ayuda «¿Qué es esto?» tal y como las proporcionan Qt y KDE consiste en que pueden contener <ulink url="kdeapi:qt/QStyleSheet">texto enriquecido</ulink>, es decir, que pueden contener diferentes tipos de letra, negrita, cursiva, e incluso imágenes y tablas. </para>

<para>Un ejemplo de la ayuda «¿Qué es esto?»: </para>

<mediaobject>
<imageobject><imagedata fileref="whatsthis.png"/></imageobject>
</mediaobject>

</listitem>

<listitem><para>Finalmente, cada programa debe tener un manual. El manual se visualiza normalmente en <application>KHelpCenter</application> tras activar la opción correspondiente del menú <guimenu>Ayuda</guimenu>. Esto significa que aparecerá una aplicación completa adicional que distraerá al usuario de su trabajo. Como consecuencia, consultar el manual solo debería ser necesario si otras facilidades, como las ayudas emergentes y las ayudas «¿Qué es esto?», no resultan suficientes. Por supuesto, un manual tiene la ventaja de que no explica aspectos aislados de la interfaz de usuario. En cambio, puede explicar aspectos de la aplicación en un contexto más amplio. Los manuales para KDE están escritos mediante el uso del lenguaje de etiquetas <ulink url="http://i18n.kde.org">DocBook</ulink>. </para></listitem>

</itemizedlist>

<para>Desde el punto de vista del programador, Qt proporciona una API para ayuda en línea fácil de usar. Para asignar una ayuda emergente a un widget, utilice la clase <ulink url="kdeapi:qt/QToolTip">QToolTip</ulink>. </para>

<programlisting>QToolTip::add(w, i18n("Este widget realiza alguna acción."))
</programlisting>

<para>Si las barras de menú y de herramientas han sido creadas usando el <ulink url="actionpattern.html">patrón de acciones</ulink>, la cadena usada como ayuda emergente procede el primer argumento del constructor de <ulink url="kdeapi:tdeui/TDEAction.html">TDEAction</ulink>: </para>

<programlisting>action = new TDEAction(i18n("&amp;Delete"), "editdelete", 
                     SHIFT+Key_Delete, actionCollection(), "del")
</programlisting>

<para>Aquí también es posible asignar un texto para que se muestre en la barra de estado cuando se seleccione el correspondiente elemento del menú. </para>

<programlisting>action->setStatusText(i18n("Deletes the marked file"))
</programlisting>

<para>La API para la ayuda «¿Qué es esto?» es muy similar. En los diálogos, utilice el siguiente código: </para>

<programlisting>QWhatsThis::add(w, i18n("&lt;qt&gt;This demonstrates &lt;b&gt;Qt&lt;/b&gt;'s"
                        " rich text engine.&lt;ul&gt;"
                        "&lt;li&gt;Foo&lt;/li&gt;"
                        "&lt;li&gt;Bar&lt;/li&gt;"
                        "&lt;/ul&gt;&lt;/qt&gt;"))
</programlisting>

<para>Para los elementos del menú, utilice </para>

<programlisting>action->setWhatsThis(i18n("Deletes the marked file"))
</programlisting>

<para>La invocación de <application>KHelpCenter</application> está encapsulada en la clase <ulink url="kdeapi:tdecore/TDEApplication">TDEApplication</ulink>. Para mostrar el manual de su aplicación, use </para>

<programlisting>kapp->invokeHelp()
</programlisting>

<para>Esto muestra la primera página con la tabla de contenidos. Cuando solo quiera mostrar cierta sección del manual, puede proporcionar un argumento adicional a la función <function>invokeHelp()</function> con la etiqueta a la que debe saltar el navegador. </para>

</sect1>

</chapter>



<chapter id="components">
<title>Componentes y servicios</title>

<sect1 id="components-services">
<title>Servicios de KDE</title>

<simplesect id="services-whatarekdeservices">
<title>¿Qué son los servicios de KDE?</title>

<para>La noción de <emphasis>servicio</emphasis> es un concepto central de la arquitectura modular de KDE. No existe una implementación técnica estricta conectada a este término (los servicios pueden ser extensiones en la forma de bibliotecas compartidas, o programas controlados mediante <ulink url="dcop.html">DCOP</ulink>. Al ser declarado de cierto <emphasis>tipo de servicio</emphasis>, promete implementar ciertos APi o características. En términos de C++, se puede pensar que un tipo de servicio es una clase abstracta, y que un servicio es una implementación de esta interfaz. </para>

<para>La ventaja de esta separación es clara. Una aplicación que utilice un tipo de servicio no tiene que conocer nada sobre sus posibles implementaciones. Solo tiene que usar el API asociado al tipo de servicio. De este modo, el servicio usado se puede cambiar sin afectar a la aplicación. Además, el usuario puede configurar qué servicios prefiere para ciertas características. </para>

<para>Algunos ejemplos: </para>

<itemizedlist>

<listitem><para>El motor de visualización HTML usado en <application>Konqueror</application> es un componente que se puede integrar y que implementa los tipos de servicio <literal>KParts/ReadOnlyPart</literal> y <literal>Browser/View</literal>. </para></listitem>
<listitem><para>En la rama HEAD de <application>KDevelop</application>, una gran parte de la funcionalidad está empaquetada en extensiones con el tipo de servicio <literal>KDevelop/Part</literal>. Durante el inicio se cargan todos los servicios de este tipo, de modo que pueda extender el IDE de una manera muy flexible. </para></listitem>
<listitem><para>En la vista de iconos, <application>Konqueror</application> muestra (si están activadas) miniaturas de los archivos de imágenes, páginas HTML, PDF y texto. Esta característica se puede extender. Si desea mostrar previsualizaciones de sus propios archivos de datos mediante algún tipo MIME, puede implementar un servicio con el tipo de servicio <classname>ThumbCreator</classname>. </para></listitem>

</itemizedlist>

<para>Obviamente, un servicio no se caracteriza únicamente por los tipos de servicio que implementa, sino también por algunas <emphasis>propiedades</emphasis>. Por ejemplo, ThumCreator no solo implementa la clase C++ con el tipo <classname>ThumbCreator</classname>, sino que también posee una lista de tipos MIME de los que es responsable. De modo similar, las partes de KDevelop tienen como propiedad el lenguaje de programación que soportan. Cuando una aplicación solicita un tipo de servicio, también puede listar restricciones de las propiedades del servicio. En el ejemplo anterior, cuando KDevelop carga las extensiones para un proyecto Java, solicita únicamente las extensiones que tienen Java como propiedad de lenguaje de programación. Para este propósito, KDE contiene un <emphasis>trader</emphasis> semejante a CORBA con un complejo lenguaje de consultas. </para>

</simplesect>


<simplesect id="services-definingservicetypes">
<title>Definición de tipos de servicios</title>

<para>Los nuevos tipos de servicio se añaden instalando una descripción en la carpeta <filename>TDEDIR/share/servicetypes</filename>. En un entorno automake, esto se puede realizar con el siguiente fragmento de <filename>Makefile.am</filename>: </para>

<programlisting>kde_servicetypesdir_DATA = tdeveloppart.desktop
EXTRA_DIST = $(kde_servicetypesdir_DATA)
</programlisting>

<para>La definición <filename>tdeveloppart.desktop</filename> de una parte <application>KDevelop</application> es similar a lo siguiente: </para>

<programlisting>[Desktop Entry]
Type=ServiceType
X-TDE-ServiceType=KDevelop/Part
Name=KDevelop Part

[PropertyDef::X-KDevelop-Scope]
Type=TQString

[PropertyDef::X-KDevelop-ProgrammingLanguages]
Type=QStringList

[PropertyDef::X-KDevelop-Args]
Type=TQString
</programlisting>

<para>Además de las entradas usuales, este ejemplo demuestra cómo declarar que un servicio posee algunas propiedades. Cada definición de propiedad corresponde a un grupo <literal>[PropertyDef::name]</literal> en el archivo de configuración. En este grupo, la entrada <literal>Type</literal> declara el tipo de la propiedad. Los tipos posibles son cualquier cosa que se pueda almacenar en un <ulink url="kdeapi:qt/QVariant">QVariant</ulink>. </para>

</simplesect>


<simplesect id="services-defininglibraryservices">
<title>Definición de servicios de bibliotecas compartidas</title>

<para>Las definiciones de servicios se guardan en la carpeta <filename>TDEDIR/share/services</filename>: </para>

<programlisting>kde_servicesdir_DATA = kdevdoxygen.desktop
EXTRA_DIST = $(kde_servicesdir_DATA)
</programlisting>

<para>El contenido del siguiente archivo de ejemplo <filename>kdevdoxygen.desktop</filename> define la extensión <literal>KDevDoxygen</literal> con el tipo de servicio <literal>KDevelop/Part</literal>: </para>

<programlisting>[Desktop Entry]
Type=Service
Comment=Doxygen
Name=KDevDoxygen
ServiceTypes=KDevelop/Part
X-TDE-Library=libkdevdoxygen
X-KDevelop-ProgrammingLanguages=C,C++,Java
X-KDevelop-Scope=Project
</programlisting>

<para>Aparte de las declaraciones usuales, una entrada importante es <literal>X-TDE-Library</literal>. Contiene el nombre de la biblioteca «libtool» (sin la extensión <literal>.la</literal>). También fija (mediante el prefijo <literal>init_</literal>) el nombre de los símbolos exportados en la biblioteca que devuelven una «fábrica de objetos». En el ejemplo anterior, la biblioteca debe contener la siguiente función: </para>

<programlisting>extern "C" {
    void *init_libkdevdoxygen()
    {
        return new DoxygenFactory;
    }
};
</programlisting>

<para>El tipo de la clase fábrica <classname>DoxygenFactory</classname> depende del tipo de servicio específico que implementa el servicio. En nuestro ejemplo de una extensión para KDevelop, la fábrica debe ser del tipo <classname>KDevFactory</classname> (que deriva de <classname>KLibFactory</classname>). Otros ejemplos más comunes son <ulink url="kdeapi:tdeparts/KParts::Factory">KParts::Factory</ulink> que debe producir objetos <ulink url="kdeapi:tdeparts/KParts::ReadOnlyPart">KParts::ReadOnlyPart</ulink>, o, en muchos casos, <ulink url="kdeapi:tdecore/KLibFactory">KLibFactory</ulink>. </para>

</simplesect>


<simplesect id="services-usinglibraryservices">
<title>Uso de servicios de bibliotecas compartidas</title>

<para>Para poder usar un servicio de biblioteca compartida en una aplicación, necesita obtener un objeto <ulink url="kdeapi:tdeio/KService.html">KService</ulink> que lo represente. Esto se discute en la <ulink url="mime.html">sección sobre tipos MIME</ulink> (y en una sección sobre el «trader» pendiente de escribir). </para>

<para>Una vez que disponga de un objeto <classname>KService</classname>, solo necesita cargar la biblioteca y obtener un puntero a su objeto fábrica: </para>

<programlisting>KService *service = ...
TQString libName = QFile::encodeName(service->library());
KLibFactory *factory = KLibLoader::self()->factory(libName);
if (!factory) {
    TQString name = service->name();
    TQString errorMessage = KLibLoader::self()->lastErrorMessage();
    KMessageBox::error(0, i18n("There was an error loading service %1.\n"
                               "The diagnostics from libtool is:\n%2")
                          .arg(name).arg(errorMessage);
}
</programlisting>

<para>A partir de este momento, el procedimiento a seguir depende de nuevo del tipo de servicio. Para las extensiones genéricas, puede crear objetos con el método <ulink url="kdeapi:tdecore/KLibFactory.html#ref3">KLibFactory::create()</ulink>. Para KParts, debe moldear el puntero de la fábrica al tipo más específico KParts::Factory y usar su método create(): </para>

<programlisting>if (factory->inherits("KParts::Factory")) {
    KParts::Factory *partFactory = static_cast&lt;KParts::Factory*&gt;(factory);
    TQObject *obj = partFactory->createPart(parentWidget, widgetName, 
                                           parent, name, "KParts::ReadOnlyPart");
    ...
} else {
    cout &lt;&lt; "El servicio no implementa la fábrica correcta" &lt;&lt; endl;
}
</programlisting>

</simplesect>


<simplesect id="services-definingdcopservices">
<title>Definición de servicios DCOP</title>

<para>Un servicio DCOP se implementa normalmente como un programa que se arranca cuando es necesario y que luego entra en un bucle para escuchar conexiones DCOP. El programa puede ser interactivo, pero también puede funcionar completa o parcialmente como un «demonio» en segundo plano sin que el usuario lo note. Un ejemplo de este tipo de «demonio» es <literal>tdeio_uiserver</literal>, que implementa la interacción del usuario como un diálogo de progreso en la biblioteca TDEIO. La ventaja de este tipo de «demonio» centralizado en este contexto radica en que, por ejemplo, los progresos de descarga de varios archivos distintos se pueden mostrar en una única ventana, incluso si todas las descargas se iniciaron desde aplicaciones diferentes. </para>

<para>Un servicio DCOP se define de un modo distinto a como se hace con un servicio de biblioteca compartida. Por supuesto, no especifica una biblioteca, sino un ejecutable. Además, los servicios DCOP no contienen una línea <literal>ServiceType</literal>, debido a que suelen ser iniciados por su nombre. También contienen las dos líneas siguientes como propiedades adicionales: </para>

<para><literal>X-DCOP-ServiceType</literal> especifica el modo en que se inicia el servicio. El valor <literal>Unique</literal> indica que el servicio no se debe iniciar más de una vez. Esto significa que si trata de iniciar este servicio, por ejemplo mediante <ulink url="kdeapi:tdecore/TDEApplication.html#startServiceByName">TDEApplication::startServiceByName()</ulink>, KDE comprueba si ya estaba registrado en DCOP. En caso afirmativo, usa el servicio que está en ejecución. Si todavía no estaba registrado, KDE lo iniciará y esperará hasta que esté registrado. De este modo puede enviar llamadas DCOP al servicio inmediatamente. En tal caso, el servicio debe implementarse como <ulink url="kdeapi:tdecore/KUniqueApplication.html">KUniqueApplication</ulink>. </para>

<para>El valor <literal>Multi</literal> para <literal>X-DCOP-ServiceType</literal> indica que pueden coexistir múltiples instancias del servicio, de modo que cada intento de iniciar el servicio creará un nuevo proceso. Como última posibilidad, también puede usar el valor <literal>None</literal>. En este caso, el inicio del servicio no esperará a estar registrado en DCOP. </para>

<para><literal>X-TDE-StartupNotify</literal> debe ser establecido normalmente como <literal>false</literal>. En caso contrario, cuando se inicie el programa, la barra de tareas mostrará una notificiación de lanzamiento o, dependiendo de las preferencias del usuario, se modificará el cursor. </para>

<para>Esta es la definición de <literal>tdeio_uiserver</literal>: </para>

<programlisting>[Desktop Entry]
Type=Service
Name=tdeio_uiserver
Exec=tdeio_uiserver
X-DCOP-ServiceType=Unique
X-TDE-StartupNotify=false
</programlisting>

</simplesect>


<simplesect id="services-usingdcopservices">
<title>Uso de servicios DCOP</title>

<para>Un servicio DCOP comienza con uno de entre varios métodos en la clase TDEApplication: </para>

<programlisting>DCOPClient *client = kapp->dcopClient();
client->attach();
if (!client->isApplicationRegistered("tdeio_uiserver")) {
    TQString error;
    if (TDEApplication::startServiceByName("tdeio_uiserver", QStringList(), &amp;error))
        cout &lt;&lt; "El inicio de kioserver ha fallado con el mensaje " &lt;&lt; error &lt;&lt; endl;
}
...
QByteArray data, replyData;
QCString replyType;
QDataStream arg(data, IO_WriteOnly);
arg &lt;&lt; true;
if (!client->call("tdeio_uiserver", "UIServer", "setListMode(bool)", 
                  data, replyType, replyData))
    cout &lt;&lt; "Ha fallado la llamada a tdeio_uiserver" &lt;&lt; endl;
...
</programlisting>

<para>Tenga en cuenta que el ejemplo de llamada DCOP que se proporciona aquí usa ordenación de argumentos. A menudo deseará usar una plantilla generada por «dcopidl2cpp» en su lugar, porque es mucho más simple y menos propensa a errores. </para>

<para>En el ejemplo propuesto, el servicio se inició «por nombre»; es decir, el primer argumento de <function>TDEApplication::startServiceByName()</function> es el nombre que aparece en la línea <literal>Name</literal> del archivo «desktop». Una alternativa consiste en usar <function>TDEApplication::startServiceByDesktopName()</function>, que toma el nombre del archivo «desktop» como argumento (en este caso, <literal>«tdeio_uiserver.desktop»</literal>). </para>

<para>Todas estas llamadas tienen una lista de URL como segundo parámetro, que se proporciona al servicio en la línea de comando. El tercer argumento es un puntero a una clase <classname>TQString</classname>. Si el inicio del servicio falla, este argumento contendrá un mensaje de error traducido. </para>

</simplesect>

</sect1>


<sect1 id="components-mime">
<title>Tipos MIME</title>

<simplesect id="mime-whataremimetypes">
<title>¿Qué son los tipos MIME?</title>

<para>Los tipos MIME se utilizan para describir el tipo de contenido de los archivos o de segmentos de datos. Al principio fueron introducidos para permitir el envío de archivos de imágenes, sonidos, etc., por correo electrónico (MIME significa «Multipurpose Internet Mail Extensions», «extensiones de correo Internet multipropósito» en español). Más tarde, este sistema también fue utilizado por los navegadores web para determinar cómo presentar los datos enviados al usuario por un servidor web. Por ejemplo, una página HTML posee el tipo MIME «text/html», y un archivo postscript, «application/postscript». En KDE, este concepto se usa en varios lugares: </para>

<itemizedlist>

<listitem><para>En la vista de iconos de <application>Konqueror</application>, los archivos se representan por iconos. Cada tipo MIME tiene asociado su propio icono. </para></listitem>

<listitem><para>Cuando pulse sobre un icono de archivo o sobre su nombre en <application>Konqueror</application>, el archivo será mostrado en una vista empotrada, o se abrirá una aplicación asociada con su tipo de archivo. </para></listitem>

<listitem><para>Cuando arrastra y suelta varios datos de una aplicación a otra (o dentro de la misma aplicación), el objetivo donde se sueltan puede decidir aceptar solo ciertos tipos de datos. Aún más, manejará datos de imágenes de un modo distinto a como maneja datos de texto. </para></listitem>

<listitem><para>Los datos del Portapapeles poseen un tipo MIME. Tradicionalmente, los programas de X solo manejan mapas de píxeles y textos, pero con Qt no existen restricciones sobre los tipos de datos. </para></listitem>

</itemizedlist>

<para>De los ejemplos anteriores se deduce que la manipulación de tipos MIME es algo complejo. En primer lugar, es necesario establecer una correspondencia entre los nombres de archivo y los tipos MIME. KDE va un paso más lejos al permitir correspondencias incluso entre contenido de archivos y tipos MIME para aquellos casos en los que no se dispone de un nombre de archivo. En segundo lugar, es necesario establecer una correspondencia entre tipos MIME y aplicaciones y bibliotecas que puedan visualizar o editar un archivo de cierto tipo, o crear una imagen en miniatura para él. </para>

<para>Existen diversas API para deducir el tipo MIME de datos o archivos. En general, existe una cierta compensación entre velocidad y fiabilidad que debe realizar. Puede encontrar el tipo de un archivo examinando solo su nombre de archivo (es decir, su extensión, en la mayoría de los casos). Por ejemplo, un archivo <filename>nombre.jpg</filename> es normalmente de tipo «image/jpeg». Pero no es fiable en los casos en los que se ha eliminado la extensión, donde tendrá que examinar el contenido del archivo. Por supuesto, se trata de un proceso más lento, especialmente para los archivos que tienen que ser descargados vía HTTP en primer lugar. Este método dependiente del contenido está basado en el archivo <filename>TDEDIR/share/mimelnk/magic</filename>, por lo que resulta difícil de extender. Pero, en general, la información de tipo MIME se puede facilitar al sistema de forma rápida instalando un archivo <literal>.desktop</literal>, con lo que estará disponible de forma eficiente y conveniente para todas las bibliotecas de KDE. </para>

</simplesect>


<simplesect id="mime-definingmimetypes">
<title>Definición de tipos MIME</title>

<para>Definamos un tipo MIME <literal>«application/x-foo»</literal> para nuestro programa <application>foobar</application>. Para este fin, deberá escribir un archivo <filename>foo.desktop</filename> e instalarlo en <filename>TDEDIR/share/mimelnk/application</filename> (que es su ubicación usual, aunque puede diferir entre distribuciones). Esto se consigue añadiendo lo siguiente al archivo <filename>Makefile.am</filename>: </para>

<programlisting>mimedir = $(kde_mimedir)/application
mime_DATA = foo.desktop
EXTRA_DIST = $(mime_DATA)
</programlisting>

<para>El archivo <filename>foo.desktop</filename> debería ser similar al siguiente: </para>

<programlisting>[Desktop Entry]
Type=MimeType
MimeType=application/x-foo
Icon=fooicon
Patterns=*.foo;
DefaultApp=foobar
Comment=Foo Data File
Comment[es]=Archivo de datos de ejemplo
</programlisting>

<para>La entrada <literal>Comment</literal> debe ser traducida. Como el archivo <filename>.desktop</filename> especifica un icono, también debe instalar un icono <filename>fooicon.png</filename> que represente al archivo, por ejemplo, en <application>Konqueror</application>. </para>

<para>En las bibliotecas de KDE, este tipo de definición se mapea a una instancia de la clase <ulink url="kdeapi:tdeio/KMimeType.html">KMimeType</ulink>. Use esto como en el siguiente ejemplo: </para>

<programlisting>KMimeType::Ptr type = KMimeType::mimeType("application/x-foo");
cout &lt;&lt; "Tipo:    " &lt;&lt; type->name() &lt; endl;
cout &lt;&lt; "Icono:    " &lt;&lt; type->icon() &lt; endl;
cout &lt;&lt; "Comentario: " &lt;&lt; type->icon() &lt; endl;
QStringList patterns = type->patterns();
QStringList::ConstIterator it;
for (it = patterns.begin(); it != patterns.end(); ++it)
  cout &lt;&lt; "Patrón: " &lt;&lt; (*it) &lt;&lt; endl;
</programlisting>

</simplesect>


<simplesect id="mime-determiningmimetypes">
<title>Determinación del tipo MIME de los datos</title>

<para>El método más rápido para determinar el tipo MIME de un archivo es usar la función <function>KMimeType::findByURL()</function>, que busca en la cadena de la URL y determina, en la mayoría de casos, el tipo MIME a partir de la extensión. Este mecanismo no se usa con ciertos protocolos (como http, man o info). Por ejemplo, los guiones CGI de un servidor web escritos en Perl suelen tener la extensión <literal>.pl</literal>, lo que indica un tipo MIME <literal>«text/x-perl»</literal>. No obstante, el archivo entregado por el servidor es la salida de este guión, que normalmente es de tipo HTML. En este caso, <function>KMimeType::findByURL()</function> devuelve el tipo MIME <literal>«application/octet-stream»</literal> (disponible mediante <function>KMimeType::defaultMimeType()</function>), que indica un fallo al encontrar el tipo MIME. </para>

<programlisting>KMimeType::Ptr type = KMimeType::findByURL("/home/bernd/foobar.jpg");
if (type->name() == KMimeType::defaultMimeType())
    cout &lt;&lt; "No se puede encontrar el tipo" &lt;&lt; endl;
else
    cout &lt;&lt; "Tipo: " &lt;&lt; type->name() &lt;&lt; endl;
</programlisting>

<para>(Este método posee algunos argumentos más, pero no están documentados, así que puede olvidarse de ellos sin más). </para>

<para>Es posible que quiera encontrar un tipo MIME a partir del contenido de un archivo en lugar de a partir de su nombre. Esto es mucho más eficaz, pero también más lento, ya que necesita leer una parte del archivo. Esto se hace con la clase <ulink url="kdeapi:tdeio/KMimeMagic.html">KMimeMagic</ulink>, que posee un manejo de errores distinto: </para>

<programlisting>KMimeMagicResult *result = KMimeMagic::self()->findFileType("/home/bernd/foobar.jpg");
if (!result || !result->isValid())
    cout &lt;&lt; "No se puede encontrar el tipo" &lt;&lt; endl;
else
    cout &lt;&lt; "Tipo: " &lt;&lt; result->mimeType() &lt;&lt; endl;
</programlisting>

<para>Como variante de esta función, también puede determinar el tipo de un segmento de memoria. Esto se usa, por ejemplo, en <application>Kate</application> para encontrar el modo de resaltado adecuado: </para>

<programlisting>QByteArray array;
...
KMimeMagicResult *result = KMimeMagic::self()->findBufferType(array);
if (!result || !result->isValid())
    cout &lt;&lt; "No se puede encontrar el tipo" &lt;&lt; endl;
else
    cout &lt;&lt; "Tipo: " &lt;&lt; result->mimeType() &lt;&lt; endl;
</programlisting>

<para>Por supuesto, incluso KMimeMagic sólo es capaz de determinar un tipo de archivo a partir del contenido de un archivo local. Para los archivos remotos existe otra posibilidad adicional: </para>

<programlisting>KURL url("http://developer.kde.org/favicon.ico");
TQString type = TDEIO::NetAccess::mimetype(url);
if (type == KMimeType::defaultMimeType())
    cout &lt;&lt; "No se puede encontrar el tipo" &lt;&lt; endl;
else
    cout &lt;&lt; "Tipo: " &lt;&lt; type &lt;&lt; endl;
</programlisting>

<para>Esto comienza una tarea TDEIO para descargar una parte del archivo y comprobar su tipo MIME. Tenga en cuenta que esta función puede resultar bastante lenta y bloquear el programa. Normalmente solo querrá usar esto si <function>KMimeType::findByURL()</function> ha devuelto <literal>«application/octect-stream»</literal>. </para>

<para>Por otra parte, si no desea bloquear su aplicación, también puede iniciar la tarea TDEIO explícitamente y conectarse a algunas de sus señales: </para>

<programlisting>void FooClass::findType()
{
    KURL url("http://developer.kde.org/favicon.ico");
    TDEIO::MimetypeJob *job = TDEIO::mimetype(url);
    connect( job, SIGNAL(result(TDEIO::Job*)),
             this, SLOT(mimeResult(TDEIO::Job*)) );
}

void FooClass::mimeResult(TDEIO::Job *job)
{
    if (job->error())
        job->showErrorDialog();
    else
        cout &lt;&lt; "Tipo MIME: " &lt;&lt; ((TDEIO::MimetypeJob *)job)->mimetype() &lt;&lt; endl;
}
</programlisting>

</simplesect>


<simplesect id="mime-mappingmimetypes">
<title>Mapear un tipo MIME a una aplicación o a un servicio</title>

<para>Cuando se instala una aplicación, se copia un archivo <literal>.desktop</literal> que contiene una lista de tipos MIME que esta aplicación puede cargar. De modo similar, los componentes como KParts hacen que esta información esté disponible por sus archivos <literal>.desktop</literal> de servicio. De modo que, en general, existen varios programas y componentes que pueden procesar un tipo MIME dado. Puede obtener una lista de ellos usando la clase <classname>KServiceTypeProfile</classname>: </para>

<programlisting>KService::OfferList offers = KServiceTypeProfile::offers("text/html", "Application");
KService::OfferList::ConstIterator it;
for (it = offers.begin(); it != offers.end(); ++it) {
    KService::Ptr service = (*it);
    cout &lt;&lt; "Nombre: " &lt;&lt; service->name() &lt;&lt; endl;
}
</programlisting>

<para>El valor devuelto por esta función es una lista de ofertas de servicio. Un objeto <classname>KServiceOffer</classname> empaqueta un KService::Ptr junto a un número de preferencia. La lista devuelta por <function>KServiceTypeProfile::offers()</function> está ordenada según la preferencia del usuario. El usuario puede cambiarla llamando a <command>keditfiletype text/html</command> o seleccionando <guimenuitem>Editar tipo de archivo</guimenuitem> en el menú de contexto de <application>Konqueror</application> sobre un archivo HTML. </para>

<para>En el ejemplo anterior, se solicitó una lista de las aplicaciones que ofrecen soporte para <literal>text/html</literal>. Entre otros, esta lista contendrá editores HTML, como <application>Quanta Plus</application>. También puede sustituir el segundo argumento <literal>"Application"</literal> por <literal>"KParts::ReadOnlyPart"</literal>. En este caso, obtendrá una lista de componentes integrables para visualizar HTML, como TDEHTML. </para>

<para>En la mayor parte de los casos no estará interesado en la lista de todos los servicios ofrecidos por una combinación de tipo MIME y tipo de servicio. Existe una función más conveniente que le proporciona solo el servicio ofrecido con la preferencia más alta: </para>

<programlisting>KService::Ptr offer = KServiceTypeProfile::preferredService("text/html", "Application");
if (offer)
    cout &lt;&lt; "Nombre: " &lt;&lt; service->name() &lt;&lt; endl;
else
    cout &lt;&lt; "No se ha encontrado un servicio apropiado" &lt;&lt; endl;
</programlisting>

<para>Para solicitudes aún más complejas existe un <ulink url="kdeapi:tdeio/TDETrader.html">«trader»</ulink> desarrollado de modo similar a CORBA. </para>

<para>Para ejecutar una aplicación de servicio con algunas URLs, use <ulink url="kdeapi:tdeio/KRun.html">KRun</ulink>: </para>

<programlisting>KURL::List urlList;
urlList &lt;&lt; "http://www.ietf.org/rfc/rfc1341.txt?number=1341";
urlList &lt;&lt; "http://www.ietf.org/rfc/rfc2046.txt?number=2046";
KRun::run(offer.service(), urlList);
</programlisting>

</simplesect>


<simplesect id="mime-misc">
<title>Otros</title>

<para>En esta sección listaremos algunas APIs directamente relacionadas con las de la sección anterior. </para>

<para>Obtener un icono para una URL. Esto busca el tipo de URL y devuelve el icono asociado. </para>

<programlisting>KURL url("ftp://ftp.kde.org/pub/incoming/wibble.c");
TQString icon = KMimeType::iconForURL(url);
</programlisting>

<para>Ejecutar una URL. Esto busca el tipo de URL y ejecuta el programa preferente del usuario que está asociado a este tipo. </para>

<programlisting>KURL url("http://dot.kde.org");
new KRun(url);
</programlisting>

</simplesect>

</sect1>


<sect1 id="nettransparency">
<title>Transparencia de red</title>

<simplesect id="nettransparency-intro">
<title>Introducción</title>

<para>En la era de la Web resulta de capital importancia que las aplicaciones de escritorio puedan acceder a recursos situados en Internet: deben ser capaces de descargar archivos de un servidor web, escribir archivos en un servidor ftp o leer mensajes de correo en un servidor web. Esta capacidad de acceder a archivos sin que importe su ubicación se suele denominar <emphasis>transparencia de red</emphasis>. </para>

<para>En el pasado se implementaron diferentes aproximaciones para conseguir este objetivo. El viejo sistema de archivos NFS es un intento de implementar transparencia de red en el nivel de la API POSIX. Aunque esta aproximación funciona bastante bien en redes locales, estrechamente unidas, no es adecuada para recursos cuyo acceso no es fiable o es posiblemente lento. En este caso, el <emphasis>asincronismo</emphasis> es importante. Mientras usted espera que su navegador web descargue una página, la interfaz de usuario no debería estar bloqueada. Además, la visualización de la página no debería comenzar cuando la página esté completamente disponible, sino que debe actualizarse a medida que los datos vayan llegando. </para>

<para>En las bibliotecas de KDE, la transparencia de red está implementada en la API TDEIO. El concepto central de esta arquitectura es una <emphasis>tarea</emphasis> de entrada/salida. Una tarea puede copiar o borrar archivos o cosas similares. Una vez que una tarea ha comenzado, funcionará en segundo plano y no bloqueará la aplicación. Cualquier comunicación de vuelta entre la tarea y la aplicación (como la entrega de datos o de información de progreso) se realiza de forma integrada en el bucle de eventos de Qt. </para>

<para>La operación en segundo plano se realiza mediante el inicio de <emphasis>ioslaves</emphasis> para realizar ciertas tareas. Los «ioslaves» se inician como procesos independientes y se comunica con ellos mediante «sockets» de dominio UNIX. De este modo no es necesaria la programación multihilo, y los esclavos inestables no pueden bloquear la aplicación que los usa. </para>

<para>Las ubicaciones de los archivos se expresan mediante las ampliamente usadas URL. Pero, en KDE, las URL no solo expanden el alcance de los archivos direccionables más allá del sistema de archivos local, sino que también van en el sentido contrario: por ejemplo, puede navegar por el interior de archivos «tar». Esto se consigue anidando URL. Por ejemplo, un archivo que resida dentro de un archivo comprimido «tar» en un servidor web, tendría la URL </para>

<programlisting>http://www-com.physik.hu-berlin.de/~bernd/article.tgz#tar:/paper.tex
</programlisting>

</simplesect>


<simplesect id="nettransparency-usingkio">
<title>Uso de TDEIO</title>

<para>En muchos casos, las tareas se crean llamando a funciones del nombre de espacios TDEIO. Estas funciones tienen una o dos URL como argumento, además de otros parámetros posiblemente necesarios. Cuando la tarea termina, emite la señal <literal>result(TDEIO::Job*)</literal>. Tras emitir esta señal, la tarea se borra a sí misma. De este modo, un caso de uso típico podría ser: </para>

<programlisting>void FooClass::makeDirectory()
{
    SimpleJob *job = TDEIO::mkdir(KURL("file:/home/bernd/kiodir"));
    connect( job, SIGNAL(result(TDEIO::Job*)), 
             this, SLOT(mkdirResult(TDEIO::Job*)) );
}

void FooClass::mkdirResult(TDEIO::Job *job)
{
    if (job->error())
        job->showErrorDialog();
    else
        cout &lt;&lt; "mkdir funcionó bien" &lt;&lt; endl;
}
</programlisting>

<para>Dependiendo del tipo de tarea, también podrá conectarla a otras señales. </para>

<para>Lo que sigue es una introducción a las posibles funciones: </para>

<variablelist>

<varlistentry><term>TDEIO::mkdir(const KURL &amp;url, int permission)</term>
<listitem><para>Crea un directorio, opcionalmente con ciertos permisos. </para></listitem>
</varlistentry>

<varlistentry><term>TDEIO::rmdir(const KURL &amp;url)</term>
<listitem><para>Elimina un directorio. </para></listitem>
</varlistentry>

<varlistentry><term>TDEIO::chmod(const KURL &amp;url, int permissions)</term>
<listitem><para>Cambia los permisos de un archivo. </para></listitem>
</varlistentry>

<varlistentry><term>TDEIO::rename(const KURL &amp;src, const KURL &amp;dest, bool overwrite)</term>
<listitem><para>Renombra un archivo. </para></listitem>
</varlistentry>

<varlistentry><term>TDEIO::symlink(const TQString &amp;target, const KURL &amp;dest, bool overwrite, bool showProgressInfo)</term>
<listitem><para>Crea un enlace simbólico. </para></listitem>
</varlistentry>

<varlistentry><term>TDEIO::stat(const KURL &amp;url, bool showProgressInfo)</term>
<listitem><para>Obtiene cierta información sobre el archivo, como su tamaño, hora de modificación y permisos. La información puede obtenerse de TDEIO::StatJob::statResult() una vez que el trabajo haya finalizado. </para></listitem>
</varlistentry>

<varlistentry><term>TDEIO::get(const KURL &amp;url, bool reload, bool showProgressInfo)</term>
<listitem><para>Transfiere datos desde un URL. </para></listitem>
</varlistentry>

<varlistentry><term>TDEIO::put(const KURL &amp;url, int permissions, bool overwrite, bool resume, bool showProgressInfo)</term>
<listitem><para>Transfiere datos a un URL. </para></listitem>
</varlistentry>

<varlistentry><term>TDEIO::http_post(const KURL &amp;url, const QByteArray &amp;data, bool showProgressInfo)</term>
<listitem><para>Envía datos. Específica de HTTP. </para></listitem>
</varlistentry>

<varlistentry><term>TDEIO::mimetype(const KURL &amp;url, bool showProgressInfo)</term>
<listitem><para>Intenta encontrar el tipo MIME de un URL. El tipo se puede obtener de TDEIO::MimetypeJob::mimetype() una vez que el trabajo haya finalizado. </para></listitem>
</varlistentry>

<varlistentry><term>TDEIO::file_copy(const KURL &amp;src, const KURL &amp;dest, int permissions, bool overwrite, bool resume, bool showProgressInfo)</term>
<listitem><para>Copia un único archivo. </para></listitem>
</varlistentry>

<varlistentry><term>TDEIO::file_move(const KURL &amp;src, const KURL &amp;dest, int permissions, bool overwrite, bool resume, bool showProgressInfo)</term>
<listitem><para>Renombra o mueve un único archivo. </para></listitem>
</varlistentry>

<varlistentry><term>TDEIO::file_delete(const KURL &amp;url, bool showProgressInfo)</term>
<listitem><para>Elimina un único archivo. </para></listitem>
</varlistentry>

<varlistentry><term>TDEIO::listDir(const KURL &amp;url, bool showProgressInfo)</term>
<listitem><para>Lista el contenido de un directorio. Cada vez que se conozcan nuevas entradas será emitida la señal TDEIO::ListJob::entries(). </para></listitem>
</varlistentry>

<varlistentry><term>TDEIO::listRecursive(const KURL &amp;url, bool showProgressInfo)</term>
<listitem><para>Similar a la función listDir(), aunque esta es recursiva. </para></listitem>
</varlistentry>

<varlistentry><term>TDEIO::copy(const KURL &amp;src, const KURL &amp;dest, bool showProgressInfo)</term>
<listitem><para>Copia un archivo o un directorio. Los directorios se copian recursivamente. </para></listitem>
</varlistentry>

<varlistentry><term>TDEIO::move(const KURL &amp;src, const KURL &amp;dest, bool showProgressInfo)</term>
<listitem><para>Mueve o renombra un archivo o un directorio. </para></listitem>
</varlistentry>

<varlistentry><term>TDEIO::del(const KURL &amp;src, bool shred, bool showProgressInfo)</term>
<listitem><para>Elimina un archivo o un directorio. </para></listitem>
</varlistentry>

</variablelist>

</simplesect>


<simplesect id="nettransparency-direntries">
<title>Entradas de directorio</title>

<para>La tarea TDEIO::stat() y la tarea TDEIO::listDir() devuelven un resultado de tipo UDSEntry y UDSEntryList, respectivamente. Esta última está definida como QValueList&lt;UDSEntry&gt;. El acrónimo de UDS significa «servicio de directorio universal», en inglés. El principio subyacente consiste en que una entrada de directorio solo contiene la información que puede proporcionar un «ioslave», pero no más. Por ejemplo, el esclavo http no proporciona ninguna información sobre permisos de acceso o propietarios del archivo. En lugar de ello, una USDEntry consiste en una lista de UDSAtoms, cada uno de los cuales proporciona una pieza de información específica (que consiste en un tipo almacenado en «m_uds», y en un valor entero en «m_long» o en una cadena de texto en «m_str», dependiendo del tipo). </para>

<para>Actualmente están definidos los siguientes tipos: </para>

<itemizedlist>

<listitem><para>UDS_SIZE (integer) - Tamaño del archivo. </para></listitem>

<listitem><para>UDS_USER (string) - Usuario al que pertenece el archivo. </para></listitem>

<listitem><para>UDS_GROUP (string) - Grupo al que pertenece el archivo. </para></listitem>

<listitem><para>UDS_NAME (string) - Nombre del archivo. </para></listitem>

<listitem><para>UDS_ACCESS (integer) - Permisos del archivo, tal y como se almacenan, por ejemplo, en el campo st_mode usando la función stat() de libc. </para></listitem>

<listitem><para>UDS_FILE_TYPE (integer) - El tipo de archivo, del mismo modo que se proporciona, por ejemplo, por stat() en el campo st_mode. Por lo tanto, puede usar las típicas macros de libc (como S_ISDIR) para comprobar este valor. Tenga en cuenta que los datos proporcionados por los «ioslaves» corresponden a los de stat(), no a los de lstat(). Es decir, en el caso de los enlaces simbólicos, el tipo de archivo será el tipo del archivo apuntado por el enlace, no el del enlace en sí mismo. </para></listitem>

<listitem><para>UDS_LINK_DEST (string) - En caso de un enlace simbólico, el nombre del archivo al que apunta. </para></listitem>

<listitem><para>UDS_MODIFICATION_TIME (integer) - La fecha y hora (del tipo time_t) de la última vez que se modificó el archivo, como se guarda, por ejemplo, en el campo st_mtime de stat(). </para></listitem>

<listitem><para>UDS_ACCESS_TIME (integer) - La fecha y hora de la última vez que se accedió al archivo, como se guarda, por ejemplo, en el campo st_atime de stat(). </para></listitem>

<listitem><para>UDS_CREATION_TIME (integer) - La fecha y hora de creación del archivo, como se guarda, por ejemplo, en el campo st_ctime de stat(). </para></listitem>

<listitem><para>UDS_URL (string) - Proporciona una URL de un archivo. No consiste simplemente en la suma de la URL del directorio y del nombre del archivo. </para></listitem>

<listitem><para>UDS_MIME_TYPE (string) - Tipo MIME del archivo. </para></listitem>

<listitem><para>UDS_GUESSED_MIME_TYPE (string) - El tipo MIME del archivo deducido por el esclavo. La diferencia con el tipo anterior reside en que este no se debe tomar como fiable (debido a que su determinación de una forma fiable resultaría muy costosa). Por ejemplo, la clase KRun comprueba explícitamente el tipo MIME si no posee información fiable sobre él. </para></listitem>

</itemizedlist>

<para>Aunque la forma de almacenar información sobre los archivos en una <classname>UDSEntry</classname> es flexible y práctica desde el punto de vista del «ioslave», resulta confusa para el programador de la aplicación. Por ejemplo, para encontrar el tipo MIME de un archivo, deberá recorrer todos los átomos y comprobar si <literal>m_uds</literal> contiene el valor <literal>UDS_MIME_TYPE</literal>. Afortunadamente, existe una API que es mucho más fácil de usar: la clase <classname>KFileItem</classname>. </para>

</simplesect>


<simplesect id="nettransparency-syncuse">
<title>Utilización síncrona</title>

<para>A menudo, la API asíncrona de TDEIO resulta demasiado compleja de usar, por lo que la implementación de asincronismo total no es una prioridad. Por ejemplo, en un programa que solo puede manejar un archivo de documento a la vez, realmente hay pocas cosas que se puedan hacer mientras el programa descarga el archivo. Para estos casos simples, existe una API mucho más simple bajo la forma de funciones estáticas en TDEIO::NetAccess. Por ejemplo, para copiar un archivo, utilice </para>

<programlisting>KURL origen, destino;
origen = ...;
destino = ...
TDEIO::NetAccess::copy(origen, destino);
</programlisting>

<para>La función retornará cuando haya finalizado el proceso de copia completamente. Además, este método proporciona un diálogo de proceso y se asegura de que la aplicación procesa los eventos de actualización gráfica. </para>

<para>Existe una combinación de funciones particularmente interesante: <function>download()</function> junto a <function>removeTempFile()</function>. La primera descarga un archivo de una determinada URL y lo almacena en un archivo temporal con un nombre único (este nombre se guarda en el segundo argumento). <emphasis>Si</emphasis> la URL es local, el archivo no se descarga, sino que se utiliza el segundo argumento como nombre para el archivo local. La función <function>removeTempFile()</function> borra el archivo proporcionado como argumento si este archivo fue el resultado de una descarga previa. En caso contrario, no hace nada. De este modo, el siguiente fragmento de código proporciona una manera muy fácil de descargar archivos independientemente de su ubicación: </para>

<programlisting>KURL url;
url = ...;
TQString tempFile;
if (TDEIO::NetAccess::download(url, tempFile) {
    // cargar el archivo de nombre tempFile
    TDEIO::NetAccess::removeTempFile(tempFile);
}
</programlisting>

</simplesect>


<simplesect id="nettransparency-metadata">
<title>Metadatos</title>

<para>Como se ha visto anteriormente, la interfaz para tareas de entrada/salida es bastante abstracta y no considera los intercambios de información entre la aplicación y el esclavo de entrada/salida que sean específicos del protocolo. Esto no siempre resulta apropiado. Por ejemplo, puede proporcionar ciertos parámetros al esclavo HTTP para controlar el comportamiento de su caché o para enviar varias «cookies» con la petición. Para esta necesidad se introdujo el concepto de metadatos. Cuando se crea una tarea, puede configurarla añadiéndole metadatos. Cada elemento de metadatos consiste en una pareja clave/valor. Por ejemplo, para evitar que el esclavo HTTP descargue una página web de su caché, puede usar: </para>
 
<programlisting>void FooClass::reloadPage()
{
    KURL url("http://www.kdevelop.org/index.html");
    TDEIO::TransferJob *job = TDEIO::get(url, true, false);
    job->addMetaData("cache", "reload");
    ...
}
</programlisting>

<para>La misma técnica se puede usar en el sentido contrario, o sea, para la comunicación del esclavo hacia la aplicación. El método <function>Job::queryMetaData()</function> pregunta por el valor de cierta clave entregada por el esclavo. Para el esclavo HTTP, un ejemplo sería la clave <literal>«modified»</literal>, que contiene la fecha (representada en forma de cadena de texto) de cuando la página web fue modificada por última vez. Por ejemplo: </para>
 
<programlisting>void FooClass::printModifiedDate()
{
    KURL url("http://developer.kde.org/documentation/kde2arch/index.html");
    TDEIO::TransferJob *job = TDEIO::get(url, true, false);
    connect( job, SIGNAL(result(TDEIO::Job*)),
             this, SLOT(transferResult(TDEIO::Job*)) );
}

void FooClass::transferResult(TDEIO::Job *job)
{
    TQString mimetype;
    if (job->error())
        job->showErrorDialog();
    else {
        TDEIO::TransferJob *transferJob = (TDEIO::TransferJob*) job;
        TQString modified = transferJob->queryMetaData("modified");
        cout &lt;&lt; "Última modificación: " &lt;&lt; modified &lt;&lt; endl;
}
</programlisting>

</simplesect>


<simplesect id="nettransparency-scheduling">
<title>Programación</title>

<para>Cuando use la API TDEIO no tendrá que preocuparse normalmente de los detalles de iniciar esclavos de entrada/salida y comunicarse con ellos. El uso normal consiste en comenzar una tarea con algunos parámetros y manejar las señales que emita esta tarea. </para>

<para>Pero detrás del telón, el escenario es bastante más complejo. Cuando crea una tarea, ésta va a parar a una cola. Cuando la aplicación retorna al bucle de eventos, TDEIO asigna procesos esclavos para las tareas que hay en esta cola. Para las primeras tareas iniciadas, resulta obvio: se inicia un esclavo de entrada/salida para el protocolo apropiado. No obstante, una vez que la tarea (por ejemplo, una descarga de un servidor web) haya terminado, no se elimina inmediatamente. En lugar de ello, se coloca en un almacén de tareas inactivas y se elimina tras cierto tiempo de inactividad (3 minutos en la actualidad). Si durante este tiempo se produce una nueva petición para el mismo protocolo y servidor, se vuelve a reutilizar el esclavo. La ventaja obvia consiste en que, para una serie de tareas con el mismo servidor, se ahorra el costo de tener que crear nuevos procesos y posiblemente de repetir acciones de autenticación. </para>

<para>Por supuesto, esta reutilización solo es posible cuando el esclavo existente ya ha terminado su anterior tarea. Si llega una nueva petición mientras un proceso esclavo existente todavía está en funcionamiento, se debe iniciar y usar un nuevo proceso. En el uso de la API de los ejemplos anteriores no existe ninguna limitación para la creación de nuevos procesos esclavos: si inicia una serie de descargas consecutivas para 20 archivos distintos, TDEIO iniciará 20 procesos esclavos. Este esquema de asignación de esclavos a las tareas se denomina <emphasis>directo</emphasis>. No siempre es el esquema más adecuado, ya que puede necesitar mucha memoria y sobrecargar tanto a la máquina cliente como a la servidora. </para>

<para>Por lo tanto, existe una manera diferente: puede <emphasis>programar</emphasis> tareas. Si hace esto, solo podrá crear un limitado número (actualmente 3) de procesos esclavos para un protocolo determinado. Si crea más tareas, se colocarán en una cola y serán procesadas cuando un proceso esclavo quede inactivo. Esto se hace como sigue: </para>

<programlisting>KURL url("http://developer.kde.org/documentation/kde2arch/index.html");
TDEIO::TransferJob *job = TDEIO::get(url, true, false);
TDEIO::Scheduler::scheduleJob(job);
</programlisting>

<para>Existe una tercera posibilidad <emphasis>orientada a conexiones</emphasis>. Por ejemplo, para el esclavo IMAP, no tiene sentido iniciar múltiples procesos para el mismo servidor: solo se debe forzar una conexión IMAP a la vez. En este caso, la aplicación debe tratar explícitamente con la noción de esclavo. Debe desasignar un esclavo de cierta conexión y luego asignar todas las tareas que pueda realizar la misma conexión con el mismo esclavo. De nuevo, esto se puede conseguir fácilmente usando TDEIO::Scheduler: </para>

<programlisting>KURL baseUrl("imap://bernd@albert.physik.hu-berlin.de");
TDEIO::Slave *slave = TDEIO::Scheduler::getConnectedSlave(baseUrl);

TDEIO::TransferJob *job1 = TDEIO::get(KURL(baseUrl, "/INBOX;UID=79374"));
TDEIO::Scheduler::assignJobToSlave(slave, job1);

TDEIO::TransferJob *job2 = TDEIO::get(KURL(baseUrl, "/INBOX;UID=86793"));
TDEIO::Scheduler::assignJobToSlave(slave, job2);

...

TDEIO::Scheduler::disconnectSlave(slave);
</programlisting>

<para>Solo debe desconectar el esclavo una vez que se garantice que han finalizado todos los trabajos que le hayan sido asignados. </para>

</simplesect>


<simplesect id="nettransparency-definingslaves">
<title>Definición de un ioslave</title>

<para>A continuación discutiremos cómo añadir un nuevo «ioslave» al sistema. Del mismo modo que ocurre con los servicios, los nuevos «ioslaves» se notifican al sistema mediante la instalación de un pequeño archivo de configuración. El siguiente fragmento de archivo «Makefile.am» instala el protocolo ftp: </para>

<programlisting>protocoldir = $(kde_servicesdir)
protocol_DATA = ftp.protocol
EXTRA_DIST = $(mime_DATA)
</programlisting>

<para>El contenido del archivo ftp.protocol sería el siguiente: </para>

<programlisting>[Protocol]
exec=tdeio_ftp
protocol=ftp
input=none
output=filesystem
listing=Name,Type,Size,Date,Access,Owner,Group,Link,
reading=true
writing=true
makedir=true
deleting=true
Icon=ftp
</programlisting>

<para>La entrada <literal>«protocol»</literal> define de qué protocolo se hace responsable este esclavo. La entrada <literal>«exec»</literal> es (al contrario de lo que hubiera esperado) el nombre de la biblioteca que implementa el esclavo. Cuando deba iniciarse el esclavo, se ejecuta el comando <command>«tdeinit»</command>, que es el encargado de cargar la biblioteca en su espacio de direcciones. Así que, en la práctica, puede pensar que un esclavo en funcionamiento es un proceso independiente, aunque esté implementado en una biblioteca. La ventaja de este mecanismo reside en que así se ahorra gran cantidad de memoria y se reduce el tiempo que necesita el enlazador en tiempo de ejecución. </para>

<para>Las líneas «input» y «output» no se usan actualmente. </para>

<para>Las restantes líneas del archivo <literal>.protocol</literal> definen qué propiedades tiene el esclavo. En general, las características que debe implementar un esclavo son más simples que las que proporciona la API TDEIO para la aplicación. La razón para esto reside en que las tareas complejas se programan en un conjunto de subtareas. Por ejemplo, para listar un directorio recursivamente se iniciará una tarea para el directorio de nivel superior, y luego una adicional para cada subdirectorio que contenga. Un programador interno de TDEIO se asegura de que no estén activas demasiadas tareas al mismo tiempo. De forma similar, para copiar un archivo con un protocolo que no proporciona copias directamente (como el protocolo <literal>ftp:</literal>), TDEIO puede leer el archivo de origen y luego escribir los datos en el archivo de destino. Para que esto funcione, el archivo <literal>.protocol</literal> debe notificar las acciones que proporciona su esclavo. </para>

<para>Debido a que los esclavos se cargan como bibliotecas compartidas, aunque constituyen programas independientes, su infraestructura de código parece algo distinta a la de las extensiones para bibliotecas compartidas normales. La función que se llama para iniciar el esclavo se denomina <function>kdemain()</function>. Esta función realiza algún tipo de inicialización y luego entra en un bucle de eventos a la espera de peticiones por parte de la aplicación que la usa. El siguiente fragmento ilustra el proceso: </para>

<programlisting>extern "C" { int kdemain(int argc, char **argv); }

int kdemain(int argc, char **argv)
{
    TDELocale::setMainCatalogue("tdelibs");
    TDEInstance instance("tdeio_ftp");
    (void) TDEGlobal::locale();

    if (argc != 4) {
        fprintf(stderr, "Uso: tdeio_ftp protocol "
                        "domain-socket1 domain-socket2\n");
        exit(-1);
    }

    FtpSlave slave(argv[2], argv[3]);
    slave.dispatchLoop();
    return 0;
}
</programlisting>

</simplesect>


<simplesect id="nettransparency-implementingslaves">
<title>Implementación de un ioslave</title>

<para>Los esclavos se implementan como subclases de <classname>TDEIO::SlaveBase</classname> (FtpSlave en el ejemplo anterior). De este modo, las acciones que se listan en el archivo <literal>.protocol</literal> corresponden a ciertas funciones virtuales de <classname>TDEIO::SlaveBase</classname> que la implementación del esclavo debe reimplementar. Estas son algunas de las posibles acciones y sus correspondientes funciones virtuales: </para>

<variablelist>

<varlistentry><term>reading - Lee datos desde una URL</term>
<listitem><para>void get(const KURL &amp;url)</para></listitem></varlistentry>

<varlistentry><term>writing - Escribe datos en una URL y crea el archivo de destino si no existe.</term>
<listitem><para>void put(const KURL &amp;url, int permissions, bool overwrite, bool resume)</para></listitem></varlistentry>

<varlistentry><term>moving - Renombra un archivo.</term>
<listitem><para>void rename(const KURL &amp;src, const KURL &amp;dest, bool overwrite)</para></listitem></varlistentry>

<varlistentry><term>deleting - Borra un archivo o directorio.</term>
<listitem><para>void del(const KURL &amp;url, bool isFile)</para></listitem></varlistentry>

<varlistentry><term>listing - Lista el contenido de un directorio.</term>
<listitem><para>void listDir(const KURL &amp;url)</para></listitem></varlistentry>

<varlistentry><term>makedir - Crea un directorio.</term>
<listitem><para>void mkdir(const KURL &amp;url, int permissions)</para></listitem></varlistentry>

</variablelist>

<para>Adicionalmente, existen funciones reimplementables que no están listadas en el archivo <literal>.protocol</literal>. Para estas operaciones, TDEIO determina automáticamente si están soportadas o no (es decir, la implementación por defecto devuelve un error). </para>

<variablelist>

<varlistentry><term>Entrega información sobre el archivo, similar a la función stat() de C.</term>
<listitem><para>void stat(const KURL &amp;url)</para></listitem></varlistentry>

<varlistentry><term>Cambia los permisos de acceso de un archivo.</term>
<listitem><para>void chmod(const KURL &amp;url, int permissions)</para></listitem></varlistentry>

<varlistentry><term>Determina el tipo MIME de un archivo.</term>
<listitem><para>void mimetype(const KURL &amp;url)</para></listitem></varlistentry>

<varlistentry><term>Copia un archivo.</term>
<listitem><para>copy(const KURL &amp;url, const KURL &amp;dest, int permissions, bool overwrite)</para></listitem></varlistentry>

<varlistentry><term>Crea un enlace simbólico.</term>
<listitem><para>void symlink(const TQString &amp;target, const KURL &amp;dest, bool overwrite)</para></listitem></varlistentry>

</variablelist>

<para>Todas estas implementaciones deben finalizar con una de estas dos llamadas: si la operación fue exitosa, se debería llamar a <literal>finished()</literal>; si ocurrió un error, <literal>error()</literal> debería ser llamada con un código de error como primer argumento y una cadena de texto como segundo. Los códigos de error posibles se listan como enumeraciones de tipo <type>TDEIO::Error</type>. El segundo argumento suele ser la URL en cuestión. Se usa, por ejemplo, en la función <function>TDEIO::Kob::showErrorDialgog()</function> para parametizar el mensaje de error legible por el usuario. </para>

<para>En el caso de los esclavos que se corresponden con protocolos de red, resulta interesante reimplementar el método <function>SlaveBase::setHost()</function>. Este método se llama para comunicar al proceso esclavo información sobre el servidor, el puerto a usar, el nombre de usuario y su contraseña para iniciar la sesión. En general, los metadatos ajustados por la aplicación se pueden solicitar mediante <function>SlaveBase::metaData()</function>. Puede comprobar la existencia de metadatos para cualquier clave con la función <function>SlaveBase::hasMetaData()</function>. </para>

</simplesect>


<simplesect id="nettransparency-communication">
<title>Devolviendo datos a la aplicación</title>

<para>Varias acciones implementadas en un proceso esclavo necesitan algún modo de devolver datos a la aplicación que está usando dicho proceso esclavo: </para>

<itemizedlist>

<listitem><para><function>get()</function> envía bloques de datos. Esto se lleva a cabo con <function>data()</function>, que tiene como argumento un <classname>QByteArray</classname>. Por supuesto, no es necesario que envíe todos los datos al mismo tiempo. Si tiene que enviar un archivo grande, llame a <function>data()</function> con bloques más pequeños de datos, de modo que la aplicación pueda procesarlos. Llame a <function>finished()</function> cuando la transferencia haya terminado. </para></listitem>
    
<listitem><para><function>listDir()</function> devuelve información sobre las entradas de un directorio. Para este propósito, llame a <function>listEntries()</function> con una <classname>TDEIO::UDSEntryList</classname> como argumento. Del mismo modo que ocurría con <function>data()</function>, puede llamar a esta función varias veces. Cuando haya terminado, llame a <function>listEntry()</function> con «true» como segundo parámetro. También puede llamar a <function>totalSize()</function> para devolver el número total de entradas de directorio, si es conocido. </para></listitem>

<listitem><para><function>stat()</function> devuelve información sobre el archivo, como su tamaño, tipo MIME, etc. Esta información está empaquetada en una <classname>TDEIO::UDSEntry</classname>, que se describirá más adelante. Use <function>statEntry()</function> para enviar este tipo de elementos a la aplicación. </para></listitem>

<listitem><para><function>mimetype()</function> llama a <function>mimeType()</function> con un argumento de cadena. </para></listitem>

<listitem><para><function>get()</function> y <function>copy()</function> pueden necesitar proporcionar información de progreso. Esto se lleva a cabo con los métodos <function>totalSize()</function>, <function>processedSize()</function> y <function>speed()</function>. El tamaño total y el procesado se devuelven en bytes, y la velocidad en bytes por segundo. </para></listitem>

<listitem><para>Puede enviar pares clave/valor de metadatos arbitrarios con <function>setMetaData()</function>. </para></listitem>

</itemizedlist>

</simplesect>


<simplesect id="nettransparency-interacting">
<title>Interacción con el usuario</title>

<para>A veces, un proceso esclavo debe interacturar con el usuario. Como ejemplos se pueden incluir los mensajes de información, los diálogos de autenticación y los de confirmación cuando se va a sobrescribir un archivo. </para>

<itemizedlist>

<listitem><para><function>infoMessage()</function> - Se usa para propósitos informativos, tales como el mensaje «Obteniendo datos de &lt;host&gt;» del esclavo http, que se muestra a menudo en la barra de estado del programa. En el lado de la aplicación, este método se corresponde a la señal <function>TDEIO::Job::infoMessage()</function>. </para></listitem>

<listitem><para><function>warning()</function> - Muestra un aviso en una caja de mensaje con <function>KMessageBox::information()</function>. No ocurre nada si ya hubiera otra caja de mensaje abierta como consecuencia de una llamada anterior a warning() desde el mismo proceso esclavo. </para></listitem>

<listitem><para><function>messageBox()</function> - Este método es más rico que el anterior, ya que permite abrir una caja de mensaje con texto, título y algunos botones. Vea el tipo enum <type>SlaveBase::MessageBoxType</type> como referencia. </para></listitem>

<listitem><para><function>openPassDlg()</function> - Abre un diálogo para introducir el nombre de usuario y la contraseña. </para></listitem>

</itemizedlist>

</simplesect>

</sect1>

</chapter>



<appendix id="misc">
<title>Licencias</title>

&underFDL;
&underGPL;

</appendix>

</book>