1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517 518 519 520 521 522 523 524 525 526 527 528 529 530 531 532 533 534 535 536 537 538 539 540 541 542 543 544 545 546 547 548 549 550 551 552 553 554 555 556 557 558 559 560 561 562 563 564 565 566 567 568 569 570 571 572 573 574 575 576 577 578 579 580 581 582 583 584 585 586 587 588 589 590 591 592 593 594 595 596 597 598 599 600 601 602 603 604 605 606 607 608 609 610 611 612 613 614 615 616 617 618 619 620 621 622 623 624 625 626 627 628 629 630 631 632 633 634 635 636 637 638 639 640 641 642 643 644 645 646 647 648 649 650 651 652 653 654 655 656 657 658 659 660 661 662 663 664 665 666 667 668 669 670 671 672 673 674 675 676 677 678 679 680 681 682 683 684 685 686 687 688 689 690 691 692 693 694 695 696 697 698 699 700 701 702 703 704 705 706 707 708 709 710 711 712 713 714 715 716 717 718 719 720 721 722 723 724 725 726 727 728 729 730 731 732 733 734 735 736 737 738 739 740 741 742 743 744 745 746 747 748 749 750 751 752 753 754 755 756 757 758 759 760 761 762 763 764 765 766 767 768 769 770 771 772 773 774 775 776 777 778 779 780 781 782 783 784 785 786 787 788 789 790 791 792 793 794 795 796 797 798 799 800 801 802 803 804 805 806 807 808 809 810 811 812 813 814 815 816 817 818 819 820 821 822 823 824 825 826 827 828 829 830 831 832 833 834 835 836 837 838 839 840 841 842 843 844 845 846 847 848 849 850 851 852 853 854 855 856 857 858 859 860 861 862 863 864 865 866 867 868 869 870 871 872 873 874 875 876 877 878 879 880 881 882 883 884 885 886 887 888 889 890 891 892 893 894 895 896 897 898 899 900 901 902 903 904 905 906 907 908 909 910 911 912 913 914 915 916 917 918 919 920 921 922 923 924 925 926 927 928 929 930 931 932 933 934 935 936 937 938 939 940 941 942 943 944 945 946 947 948 949 950 951 952 953 954 955 956 957 958 959 960 961 962 963 964 965 966 967 968 969 970 971 972 973 974 975 976 977 978 979 980 981 982 983 984 985 986 987 988 989 990 991 992 993 994 995 996 997 998 999 1000 1001 1002 1003 1004 1005 1006 1007 1008 1009 1010 1011 1012 1013 1014 1015 1016 1017 1018 1019 1020 1021 1022 1023 1024 1025 1026 1027 1028 1029 1030 1031 1032 1033 1034 1035 1036 1037 1038 1039 1040 1041 1042 1043 1044 1045 1046 1047 1048 1049 1050 1051 1052 1053 1054 1055 1056 1057 1058 1059 1060 1061 1062 1063 1064 1065 1066 1067 1068 1069 1070 1071 1072 1073 1074 1075 1076 1077 1078 1079 1080 1081 1082 1083 1084 1085 1086 1087 1088 1089 1090 1091 1092 1093 1094 1095 1096 1097 1098 1099 1100 1101 1102 1103 1104 1105 1106 1107 1108 1109 1110 1111 1112 1113 1114 1115 1116 1117 1118 1119 1120 1121 1122 1123 1124 1125 1126 1127 1128 1129 1130 1131 1132 1133 1134 1135 1136 1137 1138 1139 1140 1141 1142 1143 1144 1145 1146 1147 1148 1149 1150 1151 1152 1153 1154 1155 1156 1157 1158 1159 1160 1161 1162 1163 1164 1165 1166 1167 1168 1169 1170 1171 1172 1173 1174 1175 1176 1177 1178 1179 1180 1181 1182 1183 1184 1185 1186 1187 1188 1189 1190 1191 1192 1193 1194 1195 1196 1197 1198 1199 1200 1201 1202 1203 1204 1205 1206 1207 1208 1209 1210 1211 1212 1213 1214 1215 1216 1217 1218 1219 1220 1221 1222 1223 1224 1225 1226 1227 1228 1229 1230 1231 1232 1233 1234 1235 1236 1237 1238 1239 1240 1241 1242 1243 1244 1245 1246 1247 1248 1249 1250 1251 1252 1253 1254 1255 1256 1257 1258 1259 1260 1261 1262 1263 1264 1265 1266 1267 1268 1269 1270 1271 1272 1273 1274 1275 1276 1277 1278 1279 1280 1281 1282 1283 1284 1285 1286 1287 1288 1289 1290 1291 1292 1293 1294 1295 1296 1297 1298 1299 1300 1301 1302 1303 1304 1305 1306 1307 1308 1309 1310 1311 1312 1313 1314 1315 1316 1317 1318 1319 1320 1321 1322 1323 1324 1325 1326 1327 1328 1329 1330 1331 1332 1333 1334 1335 1336 1337 1338 1339 1340 1341 1342 1343 1344 1345 1346 1347 1348 1349 1350 1351 1352 1353 1354 1355 1356 1357 1358 1359 1360 1361 1362 1363 1364 1365 1366 1367 1368 1369 1370 1371 1372 1373 1374 1375 1376 1377 1378 1379 1380 1381 1382 1383 1384 1385 1386 1387 1388 1389 1390 1391 1392 1393 1394 1395 1396 1397 1398 1399 1400 1401 1402 1403 1404 1405 1406 1407 1408 1409 1410 1411 1412 1413 1414 1415 1416 1417 1418 1419 1420 1421 1422 1423 1424 1425 1426 1427 1428 1429 1430 1431 1432 1433 1434 1435 1436 1437 1438 1439 1440 1441 1442 1443 1444 1445 1446 1447 1448 1449 1450 1451 1452 1453 1454 1455 1456 1457 1458 1459 1460 1461 1462 1463 1464 1465 1466 1467 1468 1469 1470 1471 1472 1473 1474 1475 1476 1477 1478 1479 1480 1481 1482 1483 1484 1485 1486 1487 1488 1489 1490 1491 1492 1493 1494 1495 1496 1497 1498 1499 1500 1501 1502 1503 1504 1505 1506 1507 1508 1509 1510 1511 1512 1513 1514 1515 1516 1517 1518 1519 1520 1521 1522 1523 1524 1525 1526 1527 1528 1529 1530 1531 1532 1533 1534 1535 1536 1537 1538 1539 1540 1541 1542 1543 1544 1545 1546 1547 1548 1549 1550 1551 1552 1553 1554 1555 1556 1557 1558 1559 1560 1561 1562 1563 1564 1565 1566 1567 1568 1569 1570 1571 1572 1573 1574 1575 1576 1577 1578 1579 1580 1581 1582 1583 1584 1585 1586 1587 1588 1589 1590 1591 1592 1593 1594 1595 1596 1597 1598 1599 1600 1601 1602 1603 1604 1605 1606 1607 1608 1609 1610 1611 1612 1613 1614 1615 1616 1617 1618 1619 1620 1621 1622 1623 1624 1625 1626 1627 1628 1629 1630 1631 1632 1633 1634 1635 1636 1637 1638 1639 1640 1641 1642 1643 1644 1645 1646 1647 1648 1649 1650 1651 1652 1653 1654 1655 1656 1657 1658 1659 1660 1661 1662 1663 1664 1665 1666 1667 1668 1669 1670 1671 1672 1673 1674 1675 1676 1677 1678 1679 1680 1681 1682 1683 1684 1685 1686 1687 1688 1689 1690 1691 1692 1693 1694 1695 1696 1697 1698 1699 1700 1701 1702 1703 1704 1705 1706 1707 1708 1709 1710 1711 1712 1713 1714 1715 1716 1717 1718 1719 1720 1721 1722 1723 1724 1725 1726 1727 1728 1729 1730 1731 1732 1733 1734 1735 1736 1737 1738 1739 1740 1741 1742 1743 1744 1745 1746 1747 1748 1749 1750 1751 1752 1753 1754 1755 1756 1757 1758 1759 1760 1761 1762 1763 1764 1765 1766 1767 1768 1769 1770 1771 1772 1773 1774 1775 1776 1777 1778 1779 1780 1781 1782 1783 1784 1785 1786 1787 1788 1789 1790 1791 1792 1793 1794 1795 1796 1797 1798 1799 1800 1801 1802 1803 1804 1805 1806 1807 1808 1809 1810 1811 1812 1813 1814 1815 1816 1817 1818 1819 1820 1821 1822 1823 1824 1825 1826 1827 1828 1829 1830 1831 1832 1833 1834 1835 1836 1837 1838 1839 1840 1841 1842 1843 1844 1845 1846 1847 1848 1849 1850 1851 1852 1853 1854 1855 1856 1857 1858 1859 1860 1861 1862 1863 1864 1865 1866 1867 1868 1869 1870 1871 1872 1873 1874 1875 1876 1877 1878 1879 1880 1881 1882 1883 1884 1885 1886 1887 1888 1889 1890 1891 1892 1893 1894 1895 1896 1897 1898 1899 1900 1901 1902 1903 1904 1905 1906 1907 1908 1909 1910 1911 1912 1913 1914 1915 1916 1917 1918 1919 1920 1921 1922 1923 1924 1925 1926 1927 1928 1929 1930 1931 1932 1933 1934 1935 1936 1937 1938 1939 1940 1941 1942 1943 1944 1945 1946 1947 1948 1949 1950 1951 1952 1953 1954 1955 1956 1957 1958 1959 1960 1961 1962 1963 1964 1965 1966 1967 1968 1969 1970 1971 1972 1973 1974 1975 1976 1977 1978 1979 1980 1981 1982 1983 1984 1985 1986 1987 1988 1989 1990 1991 1992 1993 1994 1995 1996 1997 1998 1999 2000 2001 2002 2003 2004 2005 2006 2007 2008 2009 2010 2011 2012 2013 2014 2015 2016 2017 2018 2019 2020 2021 2022 2023 2024 2025 2026 2027 2028 2029 2030 2031 2032 2033 2034 2035 2036 2037 2038 2039 2040 2041 2042 2043 2044 2045 2046 2047 2048 2049 2050 2051 2052 2053 2054 2055 2056 2057 2058 2059 2060 2061 2062 2063 2064 2065 2066 2067 2068 2069 2070 2071 2072 2073 2074 2075 2076 2077 2078 2079 2080 2081 2082 2083 2084 2085 2086 2087 2088 2089 2090 2091 2092 2093 2094 2095 2096 2097 2098 2099 2100 2101 2102 2103 2104 2105 2106 2107 2108 2109 2110 2111 2112 2113 2114 2115 2116 2117 2118 2119 2120 2121 2122 2123 2124 2125 2126 2127 2128 2129 2130 2131 2132 2133 2134 2135 2136 2137 2138 2139 2140 2141 2142 2143 2144 2145 2146 2147 2148 2149 2150 2151 2152 2153 2154 2155 2156 2157 2158 2159 2160 2161 2162 2163 2164 2165 2166 2167 2168 2169 2170 2171 2172 2173 2174 2175 2176 2177 2178 2179 2180 2181 2182 2183 2184 2185 2186 2187 2188 2189 2190 2191 2192 2193 2194 2195 2196 2197 2198 2199 2200 2201 2202 2203 2204 2205 2206 2207 2208 2209 2210 2211 2212 2213 2214 2215 2216 2217 2218 2219 2220 2221 2222 2223 2224 2225 2226 2227 2228 2229 2230 2231 2232 2233 2234 2235 2236 2237 2238 2239 2240 2241 2242 2243 2244 2245 2246 2247 2248 2249 2250 2251 2252 2253 2254 2255 2256 2257 2258 2259 2260 2261 2262 2263 2264 2265 2266 2267 2268 2269 2270 2271 2272 2273 2274 2275 2276 2277 2278 2279 2280 2281 2282 2283 2284 2285 2286 2287 2288 2289 2290 2291 2292 2293 2294 2295 2296 2297 2298 2299 2300 2301 2302 2303 2304 2305 2306 2307 2308 2309 2310 2311 2312 2313 2314 2315 2316 2317 2318 2319 2320 2321 2322 2323 2324 2325 2326 2327 2328 2329 2330 2331 2332 2333 2334 2335 2336 2337 2338 2339 2340 2341 2342 2343 2344 2345 2346 2347 2348 2349 2350 2351 2352 2353 2354 2355 2356 2357 2358 2359 2360 2361 2362 2363 2364 2365 2366 2367 2368 2369 2370 2371 2372 2373 2374 2375 2376 2377 2378 2379 2380 2381 2382 2383 2384 2385 2386 2387 2388 2389 2390 2391 2392 2393 2394 2395 2396 2397 2398 2399 2400 2401 2402 2403 2404 2405 2406 2407 2408 2409 2410 2411 2412 2413 2414 2415 2416 2417 2418 2419 2420 2421 2422 2423 2424 2425 2426 2427 2428 2429 2430 2431 2432 2433 2434 2435 2436 2437 2438 2439 2440 2441 2442 2443 2444 2445 2446 2447 2448 2449 2450 2451 2452 2453 2454 2455 2456 2457 2458 2459 2460 2461 2462 2463 2464 2465 2466 2467 2468 2469 2470 2471 2472 2473 2474 2475 2476 2477 2478 2479 2480 2481 2482 2483 2484 2485 2486 2487 2488 2489 2490 2491 2492 2493 2494 2495 2496 2497 2498 2499 2500 2501 2502 2503 2504 2505 2506 2507 2508 2509 2510 2511 2512 2513 2514 2515 2516 2517 2518 2519 2520 2521 2522 2523 2524 2525 2526 2527 2528 2529 2530 2531 2532 2533 2534 2535 2536 2537 2538 2539 2540 2541 2542 2543 2544 2545 2546 2547 2548 2549 2550 2551 2552 2553 2554 2555 2556 2557 2558 2559 2560 2561 2562 2563 2564 2565 2566 2567 2568 2569 2570 2571 2572 2573 2574 2575 2576 2577 2578 2579 2580 2581 2582 2583 2584 2585 2586 2587 2588 2589 2590 2591 2592 2593 2594 2595 2596 2597 2598 2599 2600 2601 2602 2603 2604 2605 2606 2607 2608 2609 2610 2611 2612 2613 2614 2615 2616 2617 2618 2619 2620 2621 2622 2623 2624 2625 2626 2627 2628 2629 2630 2631 2632 2633 2634 2635 2636 2637 2638 2639 2640 2641 2642 2643 2644 2645 2646 2647 2648 2649 2650 2651 2652 2653 2654 2655 2656 2657 2658 2659 2660 2661 2662 2663 2664 2665 2666 2667 2668 2669 2670 2671 2672 2673 2674 2675 2676 2677 2678 2679 2680 2681 2682 2683 2684 2685 2686 2687 2688 2689 2690 2691 2692 2693 2694 2695 2696 2697 2698 2699 2700 2701 2702 2703 2704 2705 2706 2707 2708 2709 2710 2711 2712 2713 2714 2715 2716 2717 2718 2719 2720 2721 2722 2723 2724 2725 2726 2727 2728 2729 2730 2731 2732 2733 2734 2735 2736 2737 2738 2739 2740 2741 2742 2743 2744 2745 2746 2747 2748 2749 2750 2751 2752 2753 2754 2755 2756 2757 2758 2759 2760 2761 2762 2763 2764 2765 2766 2767 2768 2769 2770 2771 2772 2773 2774 2775 2776 2777 2778 2779 2780 2781 2782 2783 2784 2785 2786 2787 2788 2789 2790 2791 2792 2793 2794 2795 2796 2797 2798 2799 2800 2801 2802 2803 2804 2805 2806 2807 2808 2809 2810 2811 2812 2813 2814 2815 2816 2817 2818 2819 2820 2821 2822 2823 2824 2825 2826 2827 2828 2829 2830 2831 2832 2833 2834 2835 2836 2837 2838 2839 2840 2841 2842 2843 2844 2845 2846 2847 2848 2849 2850 2851 2852 2853 2854 2855 2856 2857 2858 2859 2860 2861 2862 2863 2864 2865 2866 2867 2868 2869 2870 2871 2872 2873 2874 2875 2876 2877 2878 2879 2880 2881 2882 2883 2884 2885 2886 2887 2888 2889 2890 2891 2892 2893 2894 2895 2896 2897 2898 2899 2900 2901 2902 2903 2904 2905 2906 2907 2908 2909 2910 2911 2912 2913 2914 2915 2916 2917 2918 2919 2920 2921 2922 2923 2924 2925 2926 2927 2928 2929 2930 2931 2932 2933 2934 2935 2936 2937 2938 2939 2940 2941 2942 2943 2944 2945 2946 2947 2948 2949 2950 2951 2952 2953 2954 2955 2956 2957 2958 2959 2960 2961 2962 2963 2964 2965 2966 2967 2968 2969 2970 2971 2972 2973 2974 2975 2976 2977 2978 2979 2980 2981 2982 2983 2984 2985 2986 2987 2988 2989 2990 2991 2992 2993 2994 2995 2996 2997 2998 2999 3000 3001 3002 3003 3004 3005 3006 3007 3008 3009 3010 3011 3012 3013 3014 3015 3016 3017 3018 3019 3020 3021 3022 3023 3024 3025 3026 3027 3028 3029 3030 3031 3032 3033 3034 3035 3036 3037 3038 3039 3040 3041 3042 3043 3044 3045 3046 3047 3048 3049 3050 3051 3052 3053 3054 3055 3056 3057 3058 3059 3060 3061 3062 3063 3064 3065 3066 3067 3068 3069 3070 3071 3072 3073 3074 3075 3076 3077 3078 3079 3080 3081 3082 3083 3084 3085 3086 3087 3088 3089 3090 3091 3092 3093 3094 3095 3096 3097 3098 3099 3100 3101 3102 3103 3104 3105 3106 3107 3108 3109 3110 3111 3112 3113 3114 3115 3116 3117 3118 3119 3120 3121 3122 3123 3124 3125 3126 3127 3128 3129 3130 3131 3132 3133 3134 3135 3136 3137 3138 3139 3140 3141 3142 3143 3144 3145 3146 3147 3148 3149 3150 3151 3152 3153 3154 3155 3156 3157 3158 3159 3160 3161 3162 3163 3164 3165 3166 3167 3168 3169 3170 3171 3172 3173 3174 3175 3176 3177 3178 3179 3180 3181 3182 3183 3184 3185 3186 3187 3188 3189 3190 3191 3192 3193 3194 3195 3196 3197 3198 3199 3200 3201 3202 3203 3204 3205 3206 3207 3208 3209 3210 3211 3212 3213 3214 3215 3216 3217 3218 3219 3220 3221 3222 3223 3224 3225 3226 3227 3228 3229 3230 3231 3232 3233 3234 3235 3236 3237 3238 3239 3240 3241 3242 3243 3244 3245 3246 3247 3248 3249 3250 3251 3252 3253 3254 3255 3256 3257 3258 3259 3260 3261 3262 3263 3264 3265 3266 3267 3268 3269 3270 3271 3272 3273 3274 3275 3276 3277 3278 3279 3280 3281 3282 3283 3284 3285 3286 3287 3288 3289 3290 3291 3292 3293 3294 3295 3296 3297 3298 3299 3300 3301 3302 3303 3304 3305 3306 3307 3308 3309 3310 3311 3312 3313 3314 3315 3316 3317 3318 3319 3320 3321 3322 3323 3324 3325 3326 3327 3328 3329 3330 3331 3332 3333 3334 3335 3336 3337 3338 3339 3340 3341 3342 3343 3344 3345 3346 3347 3348 3349 3350 3351 3352 3353 3354 3355 3356 3357 3358 3359 3360 3361 3362 3363 3364 3365 3366 3367 3368 3369 3370 3371 3372 3373 3374 3375 3376 3377 3378 3379 3380 3381 3382 3383 3384 3385 3386 3387 3388 3389 3390 3391 3392 3393 3394 3395 3396 3397 3398 3399 3400 3401 3402 3403 3404 3405 3406 3407 3408 3409 3410 3411 3412 3413 3414 3415 3416 3417 3418 3419 3420 3421 3422 3423 3424 3425 3426 3427 3428 3429 3430 3431 3432 3433 3434 3435 3436 3437 3438 3439 3440 3441 3442 3443 3444 3445 3446 3447 3448 3449 3450 3451 3452 3453 3454 3455 3456 3457 3458 3459 3460 3461 3462 3463 3464 3465 3466 3467 3468 3469 3470 3471 3472 3473 3474 3475 3476 3477 3478 3479 3480 3481 3482 3483 3484 3485 3486 3487 3488 3489 3490 3491 3492 3493 3494 3495 3496 3497 3498 3499 3500 3501 3502 3503 3504 3505 3506 3507 3508 3509 3510 3511 3512 3513 3514 3515 3516 3517 3518 3519 3520 3521 3522 3523 3524 3525 3526 3527 3528 3529 3530 3531 3532 3533 3534 3535 3536 3537 3538 3539 3540 3541 3542 3543 3544 3545 3546 3547 3548 3549 3550 3551 3552 3553 3554 3555 3556 3557 3558 3559 3560 3561 3562 3563 3564 3565 3566 3567 3568 3569 3570 3571 3572 3573 3574 3575 3576 3577 3578 3579 3580 3581 3582 3583 3584 3585 3586 3587 3588 3589 3590 3591 3592 3593 3594 3595 3596 3597 3598 3599 3600 3601 3602 3603 3604 3605 3606 3607 3608 3609 3610 3611 3612 3613 3614 3615 3616 3617 3618 3619 3620 3621 3622 3623 3624 3625 3626 3627 3628 3629 3630 3631 3632 3633 3634 3635 3636 3637 3638 3639 3640 3641 3642 3643 3644 3645 3646 3647 3648 3649 3650 3651 3652 3653 3654 3655 3656 3657 3658 3659 3660 3661 3662 3663 3664 3665 3666 3667 3668 3669 3670 3671 3672 3673 3674 3675 3676 3677 3678 3679 3680 3681 3682 3683 3684 3685 3686 3687 3688 3689 3690 3691 3692 3693 3694 3695 3696 3697 3698 3699 3700 3701 3702 3703 3704 3705 3706 3707 3708 3709 3710 3711 3712 3713 3714 3715 3716 3717 3718 3719 3720 3721 3722 3723 3724 3725 3726 3727 3728 3729 3730 3731 3732 3733 3734 3735 3736 3737 3738 3739 3740 3741 3742 3743 3744 3745 3746 3747 3748 3749 3750 3751 3752 3753 3754 3755 3756 3757 3758 3759 3760 3761 3762 3763 3764 3765 3766 3767 3768 3769 3770 3771 3772 3773 3774 3775 3776 3777 3778 3779 3780 3781 3782 3783 3784 3785 3786 3787 3788 3789 3790 3791 3792 3793 3794 3795 3796 3797 3798 3799 3800 3801 3802 3803 3804 3805 3806 3807 3808 3809 3810 3811 3812 3813 3814 3815 3816 3817 3818 3819 3820 3821 3822 3823 3824 3825 3826 3827 3828 3829 3830 3831 3832 3833 3834 3835 3836 3837 3838 3839 3840 3841 3842 3843 3844 3845 3846 3847 3848 3849 3850 3851 3852 3853 3854 3855 3856 3857 3858 3859 3860 3861 3862 3863 3864 3865 3866 3867 3868 3869 3870 3871 3872 3873 3874 3875 3876 3877 3878 3879 3880 3881 3882 3883 3884 3885 3886 3887 3888 3889 3890 3891 3892 3893 3894 3895 3896 3897 3898 3899 3900 3901 3902 3903 3904 3905 3906 3907 3908 3909 3910 3911 3912 3913 3914 3915 3916 3917 3918 3919 3920 3921 3922 3923 3924 3925 3926 3927 3928 3929 3930 3931 3932 3933 3934 3935 3936 3937 3938 3939 3940 3941 3942 3943 3944 3945 3946 3947 3948 3949 3950 3951 3952 3953 3954 3955 3956 3957 3958 3959 3960 3961 3962 3963 3964 3965 3966 3967 3968 3969 3970 3971 3972 3973 3974 3975 3976 3977 3978 3979 3980 3981 3982 3983 3984 3985 3986 3987 3988 3989 3990 3991 3992 3993 3994 3995 3996 3997 3998 3999 4000 4001 4002 4003 4004 4005 4006 4007 4008 4009 4010 4011 4012 4013 4014 4015 4016 4017 4018 4019 4020 4021 4022 4023 4024 4025 4026 4027 4028 4029 4030 4031 4032 4033 4034 4035 4036 4037 4038 4039 4040 4041 4042 4043 4044 4045 4046 4047 4048 4049 4050 4051 4052 4053 4054 4055 4056 4057 4058 4059 4060 4061 4062 4063 4064 4065 4066 4067 4068 4069 4070 4071 4072 4073 4074 4075 4076 4077 4078 4079 4080 4081 4082 4083 4084 4085 4086 4087 4088 4089 4090 4091 4092 4093 4094 4095 4096 4097 4098 4099 4100 4101 4102 4103 4104 4105 4106 4107 4108 4109 4110 4111 4112 4113 4114 4115 4116 4117 4118 4119 4120 4121 4122 4123 4124 4125 4126 4127 4128 4129 4130 4131 4132 4133 4134 4135 4136 4137 4138 4139 4140 4141 4142 4143 4144 4145 4146 4147 4148 4149 4150 4151 4152 4153 4154 4155 4156 4157 4158 4159 4160 4161 4162 4163 4164 4165 4166 4167 4168 4169 4170 4171 4172 4173 4174 4175 4176 4177 4178 4179 4180 4181 4182 4183 4184 4185 4186 4187 4188 4189 4190 4191 4192 4193 4194 4195 4196 4197 4198 4199 4200 4201 4202 4203 4204 4205 4206 4207 4208 4209 4210 4211 4212 4213 4214 4215 4216 4217 4218 4219 4220 4221 4222 4223 4224 4225 4226 4227 4228 4229 4230 4231 4232 4233 4234 4235 4236 4237 4238 4239 4240 4241 4242 4243 4244 4245 4246 4247 4248 4249 4250 4251 4252 4253 4254 4255 4256 4257 4258 4259 4260 4261 4262 4263 4264 4265 4266 4267 4268 4269 4270 4271 4272 4273 4274 4275 4276 4277 4278 4279 4280 4281 4282 4283 4284 4285 4286 4287 4288 4289 4290 4291 4292 4293 4294 4295 4296 4297 4298 4299 4300 4301 4302 4303 4304 4305 4306 4307 4308 4309 4310 4311 4312 4313 4314 4315 4316 4317 4318 4319 4320 4321 4322 4323 4324 4325 4326 4327 4328 4329 4330 4331 4332 4333 4334 4335 4336 4337 4338 4339 4340 4341 4342 4343 4344 4345 4346 4347 4348 4349 4350 4351 4352 4353 4354 4355 4356 4357 4358 4359 4360 4361 4362 4363 4364 4365 4366 4367 4368 4369 4370 4371 4372 4373 4374 4375 4376 4377 4378 4379 4380 4381 4382 4383 4384 4385 4386 4387 4388 4389 4390 4391 4392 4393 4394 4395 4396 4397 4398 4399 4400 4401 4402 4403 4404 4405 4406 4407 4408 4409 4410 4411 4412 4413 4414 4415 4416 4417 4418 4419 4420 4421 4422 4423 4424 4425 4426 4427 4428 4429 4430 4431 4432 4433 4434 4435 4436 4437 4438 4439 4440 4441 4442 4443 4444 4445 4446 4447 4448 4449 4450 4451 4452 4453 4454 4455 4456 4457 4458 4459 4460 4461 4462 4463 4464 4465 4466 4467 4468 4469 4470 4471 4472 4473 4474 4475 4476 4477 4478 4479 4480 4481 4482 4483 4484 4485 4486 4487 4488 4489 4490 4491 4492 4493 4494 4495 4496 4497 4498 4499 4500 4501 4502 4503 4504 4505 4506 4507 4508 4509 4510 4511 4512 4513 4514 4515 4516 4517 4518 4519 4520 4521 4522 4523 4524 4525 4526 4527 4528 4529 4530 4531 4532 4533 4534
|
<?xml version="1.0" ?>
<!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.5-Based Variant V1.1//EN" "dtd/kdedbx45.dtd" [
<!ENTITY rkward '<application>RKWard</application>'>
<!ENTITY R '<application>R</application>'>
<!ENTITY javascript 'JavaScript'>
<!ENTITY pluginmap '<literal role="extension">.pluginmap</literal>'>
<!ENTITY % addindex "IGNORE">
<!ENTITY % English "INCLUDE"><!-- change language only here -->
<!-- Do not define any other entities; instead, use the entities
from kde-genent.entities and $LANG/user.entities. -->
]>
<book lang="&language;">
<!-- This header contains all of the meta-information for the document such
as Authors, publish date, the abstract, and Keywords -->
<bookinfo>
<title>Introduction to Writing Plugins for &rkward;</title>
<authorgroup>
<author>
<firstname>Thomas</firstname>
<surname>Friedrichsmeier</surname>
<affiliation>
<address><email>rkward-devel AT kde DOT org</email></address>
</affiliation>
</author>
<author>
<firstname>Meik</firstname>
<surname>Michalke</surname>
<affiliation>
<address><email>rkward-devel AT kde DOT org</email></address>
</affiliation>
</author>
<!-- Additional authors go here -->
<!-- TRANS:ROLES_OF_TRANSLATORS -->
</authorgroup>
<copyright>
<year>2006-2020</year>
<holder>Thomas Friedrichsmeier</holder>
</copyright>
<!-- Translators: put here the copyright notice of the translation -->
<!-- Put here the FDL notice. Read the explanation in fdl-notice.docbook
and in the FDL itself on how to use it. -->
<legalnotice>&FDLNotice;</legalnotice>
<date>2020-09-26</date>
<releaseinfo>0.7.2</releaseinfo>
<abstract>
<para>
This is a guide to writing plugins for &rkward;.
</para>
</abstract>
<keywordset>
<keyword>KDE</keyword>
<keyword>R</keyword>
<keyword>rkward</keyword>
<keyword>plugins</keyword>
</keywordset>
</bookinfo>
<chapter id="introduction">
<title>Introduction</title>
<note>
<para>
Documentation as of &rkward; release 0.6.4.
</para>
</note>
<para>
This document describes how to write your own plugins. Note, that at the time of this writing, some of the concepts are not yet set in stone. Therefore, this document should be regarded as an introduction to the current approach, and as a basis for discussion. All sorts of comments are welcome.
The documentation has grown quite large over time. Do not let that scare you. We recommend reading through the four basic steps (as
outlined, below), to get a basic idea of how things work. After that you may want to skim the table of contents to see which advanced
topics could be of relevance to you.
</para>
<para>
For questions and comments, please write to the &rkward; development mailing list.
</para>
<para>
<emphasis>You do not need to read this in order to use &rkward;.</emphasis> This document is about extending &rkward;. It is targeted at advanced users, or people willing to help improve &rkward;.
</para>
<para>
Writing a standard plugin is basically a four-step process:
</para>
<itemizedlist>
<listitem><para><link linkend="pluginmap">Placing a new Action in the menu hierarchy</link></para></listitem>
<listitem><para><link linkend="mainxml">Describing the looks and behavior of the plugin &GUI;</link></para></listitem>
<listitem><para><link linkend="jstemplate">Defining, how R-code is to be generated from the settings, the user makes in the &GUI;</link></para></listitem>
<listitem><para><link linkend="pluginhelp">Adding a help page to your plugin</link></para></listitem>
</itemizedlist>
<para>
Those will be dealt with in turn.
</para>
<para>
Some advanced concepts may be used in those four steps, but are dealt with in separate chapters, to keep things simple:
<itemizedlist>
<listitem><para><link linkend="logic">&GUI; logic</link></para></listitem>
<listitem><para><link linkend="embedding">Embedding Plugins into Plugins</link></para></listitem>
<listitem><para><link linkend="plugin_series">Useful concepts for creating many series of similar plugins</link></para></listitem>
</itemizedlist>
</para>
<para>
Also, none of the chapters shows all options, but rather only the basic concepts. A complete <link linkend="reference">reference</link> of options is provided separately.
</para>
</chapter>
<chapter id="whatareplugins">
<title>Preliminaries: What are plugins in &rkward;? How do they work?</title>
<para>
Of course the first question you might have is: what portions of &rkward; functionality is realized using plugins? Or: what can plugins do?
</para>
<para>
One way to answer this is: deselect all &pluginmap; files under <menuchoice><guimenu>Settings</guimenu><guimenuitem>Configure &rkward;</guimenuitem><guimenuitem>Plugins</guimenuitem></menuchoice>, and see what is missing. A slightly more helpful answer: most actual statistics functions accessible via the &GUI; are realized using plugins. Also, you can create fairly flexible &GUI;s for all kinds of operations using plugins.
</para>
<para>
The basic paradigm behind &rkward; plugins is the one we will walk you through in this document: an &XML; file describes what the &GUI; looks like. An additional &javascript; file is used to generate &R; syntax from the &GUI; settings. That is, plugins do not really have to perform any statistical calculations. Rather plugins generate the &R; syntax needed to run those calculations. The &R; syntax is then sent to the &R; backend for evaluation, and typically a result is shown in the output window.
</para>
<para>
Read on in the next chapters to see how this is done.
</para>
</chapter>
<chapter id="pluginmap">
<title>Creating menu entries</title>
<para>
When you create a new plugin, you need to tell &rkward; about it. So the first thing to do, is to write a &pluginmap; file (or modify an existing one). The format of &pluginmap; is &XML;. I will walk you through an example (also of course, be sure you have &rkward; configured to load your &pluginmap; -- <menuchoice><guimenu>Settings</guimenu><guimenuitem>Configure &rkward;</guimenuitem><guimenuitem>Plugins</guimenuitem></menuchoice>):
</para>
<tip>
<para>
After reading this chapter, have a look at the <link linkend="rkwarddev"><application>rkwarddev</application> package</link> as well. It provides some &R; functions to create most of &rkward;'s &XML; tags for you.
</para>
</tip>
<programlisting>
<!DOCTYPE rkpluginmap>
</programlisting>
<para>
The doctype is not really interpreted, but set it to <replaceable>"rkpluginmap"</replaceable> anyway.
</para>
<programlisting>
<document base_prefix="" namespace="myplugins" id="mypluginmap">
</programlisting>
<para>
The <parameter>base_prefix</parameter> attribute can be used, if all your plugins reside in a common directory. Basically, then you can omit that directory from the filenames specified below. It safe to leave this at <replaceable>""</replaceable>.
</para><para>
As you will see below, all plugins get a unique identifier, <parameter>id</parameter>. The <parameter>namespace</parameter> is a way to organize those IDs, and make it less likely to create a duplicate identifier accidentally. Internally, basically the namespace and then a <quote>::</quote> gets prepended to all the identifiers you specify in this &pluginmap;. In general, if you intend to <link linkend="sect_external_plugins">distribute your plugins in an &R; package</link>, it is a good idea to use the package name as <parameter>namespace</parameter> parameter. Plugins shipped with the official &rkward; distribution have <replaceable>namespace="rkward"</replaceable>.
</para>
<para>
The <parameter>id</parameter> attribute is optional, but specifying an id for your &pluginmap; makes it possible for other people to make their &pluginmap;s load your &pluginmap;, automatically (see <link linkend="chapter_dependencies">the section on dependencies</link>).
</para>
<programlisting>
<components>
</programlisting>
<para>
Components? Are not we talking about plugins? Yes, but in the future, plugins will be no more than a special class of components. What we do here, then, is to register all components/plugins with &rkward;. Let's look at an example entry:
</para>
<programlisting>
<component type="standard" id="t_test_two_vars" file="t_test_two_vars.xml" label="Two Variable t-Test" />
</programlisting>
<para>
First the <parameter>type</parameter> attribute: Leave this to <replaceable>"standard"</replaceable> for now. Further types are not yet implemented. The <parameter>id</parameter> we have already hinted at. Each component has to be given a unique (in its namespace) identifier. Pick one that is easily recognizable. Avoid spaces and any special characters. Those are not banned, so far, but might have special meanings. With the <parameter>file</parameter> attribute, you specify where the <link linkend="mainxml">description of the actual plugin itself</link> is located. This is relative to the directory the &pluginmap; file is in, and the <parameter>base_prefix</parameter> above. Finally, give the component a label. This label will be shown wherever the plugin is placed in the menu (or in the future perhaps in other places as well).
</para>
<para>
Typically a &pluginmap; file will contain several components, so here are a few more:
</para>
<programlisting>
<component type="standard" id="unimplemented_test" file="means/unimplemented.xml" />
<component type="standard" id="fictional_t_test" file="means/ttests/fictional.xml" label="This is a fictional t-test" />
<component type="standard" id="descriptive" file="descriptive.xml" label="Descriptive Statistics" />
<component type="standard" id="corr_matrix" file="corr_matrix.xml" label="Correlation Matrix" />
<component type="standard" id="simple_anova" file="simple_anova.xml" label="Simple Anova" />
</components>
</programlisting>
<para>
OK, this was the first step. &rkward; now knows those plugins exist. But how to invoke them? They need to be placed in a menu hierarchy:
</para>
<programlisting>
<hierarchy>
<menu id="analysis" label="Analysis">
</programlisting>
<para>
Right below the <command><hierarchy></command> tag, you start describing, in which <command><menu></command> your plugins should go. With the above line, you basically say, that your plugin should be in the <menuchoice><guimenu>Analysis</guimenu></menuchoice> menu (not necessarily directly there, but in a submenu). The <menuchoice><guimenu>Analysis</guimenu></menuchoice> menu is standard in &rkward;, so it does not actually have to be created from scratch. However, if it did not exist yet, using the <parameter>label</parameter> attribute you would give it its name.
Finally, the <parameter>id</parameter> once again identifies this <command><menu></command>. This is needed, so several &pluginmap; files can place their plugins in the same menus. They do this by looking for a <command><menu></command> with the given <parameter>id</parameter>. If the ID does not yet exist, a new menu will be created. Otherwise the entries will be added to the existing menu.
</para>
<programlisting>
<menu id="means" label="Means">
</programlisting>
<para>
Basically the same thing here: Now we define a submenu to the <menuchoice><guimenu>Analysis</guimenu></menuchoice> menu. It is to be called <menuchoice><guimenuitem>Means</guimenuitem></menuchoice>.
</para>
<programlisting>
<menu id="ttests" label="t-Tests">
</programlisting>
<para>
And a final level in the menu hierarchy: A submenu of the submenu <menuchoice><guimenuitem>Means</guimenuitem></menuchoice>.
</para>
<programlisting>
<entry component="t_test_two_vars" />
</programlisting>
<para>
Now, finally, this is the menu we want to place the plugin in. The <command><entry></command> tag signals, this actually is the real thing, instead of another submenu. The <parameter>component</parameter> attribute refers to the <parameter>id</parameter> you gave the plugin/component above.
</para>
<programlisting>
<entry component="fictional_t_test" />
</menu>
<entry component="fictional_t_test" />
</menu>
<menu id="frequency" label="Frequency" index="2"/>
</programlisting>
<para>
In case you have lost track: This is another submenu to the <menuchoice><guimenu>Analysis</guimenu></menuchoice> menu. See the screenshot below. We will skip some of what is not visible, marked with [...].
</para>
<programlisting>
[...]
</menu>
<entry component="corr_matrix"/>
<entry component="descriptive"/>
<entry component="simple_anova"/>
</menu>
</programlisting>
<para>
These are the final entries visible in the screenshots below.
</para>
<programlisting>
<menu id="plots" label="Plots">
[...]
</menu>
</programlisting>
<para>
Of course you can also place your plugins in menus other than <menuchoice><guimenu>Analysis</guimenu></menuchoice>.
</para>
<programlisting>
<menu id="file" label="File">
[...]
</menu>
</programlisting>
<para>
Even in standard-menus such as <menuchoice><guimenu>File</guimenu></menuchoice>. All you need is the correct <parameter>id</parameter>.
</para>
<programlisting>
</hierarchy>
</document>
</programlisting>
<para>
That is how to do it. And this screenshot shows the result:
</para>
<screenshot>
<screeninfo>Menu hierarchy created by the code shown above</screeninfo>
<mediaobject>
<imageobject>
<imagedata fileref="menu_hierarchy_example.png" format="PNG"/>
</imageobject>
<textobject>
<phrase>Menu hierarchy created by the code shown above</phrase>
</textobject>
</mediaobject>
</screenshot>
<para>
Confused? The easiest way to get started is probably taking some of the existing &pluginmap; files shipped with the distribution, and modifying them to your needs. Also, if you need help, do not hesitate to write to the development mailing list.
</para>
<sect1 id="pluginmap_grouping"><title>Controlling the order of menu entries</title>
<para>By default, all items (entries / submenus) inside a menu will be sorted alphabetically, automatically. In <emphasis>some</emphasis> cases you may want more control. In this case you can group elements as follows:</para>
<itemizedlist>
<listitem>
<para>You can define groups inside any menu like this. All elements belonging to the same group will be grouped together:</para>
<programlisting>
<group id="somegroup"/>
</programlisting>
</listitem><listitem>
<para>If you want the group to be visually separated from other entries, use:</para>
<programlisting>
<group id="somegroup" separated="true"/>
</programlisting>
</listitem><listitem>
<para>Entries, menus, and groups can be appended to a specified group, using:</para>
<programlisting>
<entry component="..." group="somegroup"/>
</programlisting>
</listitem><listitem>
<para>In fact, it is also possible to define groups (without separator lines) implicitly:</para>
<programlisting>
<entry component="first" group="a"/>
<entry component="third"/>
<entry component="second" group="a"/>
</programlisting>
</listitem><listitem>
<para>Group names are specific to each menu. Group "a" in menu "Data" does not conflict with group "a" in menu "Analysis", for example.</para>
</listitem><listitem>
<para>The most common use case is defining groups at the top, or at the bottom of a menu. For this, there are pre-defined groups "top" and "bottom" in each menu.</para>
</listitem><listitem>
<para>Entries within each group are sorted, alphabetically. Groups appear in the order of declaration (unless appended to another group, of course).</para>
</listitem><listitem>
<para>Menus and entries without group specification logically form a group (""), too.</para>
</listitem>
</itemizedlist>
</sect1>
</chapter>
<chapter id="mainxml">
<title>Defining the &GUI;</title>
<sect1 id="sect_defining_the_GUI"><title>Defining a dialog</title>
<para>
In the <link linkend="pluginmap">previous chapter</link> you have seen how to register a plugin with &rkward;. The most important ingredient was specifying the path to an &XML; file with a description of what the plugin actually looks like. In this chapter you will learn how to create this &XML; file.
</para>
<tip>
<para>
After reading this chapter, have a look at the <link linkend="rkwarddev"><application>rkwarddev</application> package</link> as well. It provides some &R; functions to create most of &rkward;'s &XML; tags for you.
</para>
</tip>
<para>
Once again we will walk you through an example. The example is a (slightly simplified) version of the two variable t-Test.
</para>
<programlisting>
<!DOCTYPE rkplugin>
</programlisting>
<para>
The doctype is not really interpreted, yet. Set it to <replaceable>rkplugin</replaceable>, anyway.
</para>
<programlisting>
<document>
<code file="t_test_two_vars.js"/>
</programlisting>
<para>
All plugins generate some code. Currently the only way to do so is using JS, as detailed in <link linkend="jstemplate">the next chapter</link>. This defines, where to look for the JS code. The filename is relative to the directory the plugin &XML; is in.
</para>
<programlisting>
<help file="t_test_two_vars.rkh"/>
</programlisting>
<para>
It is usually a good idea to also provide a help page for your plugin. The filename of that help page is given, here, relative to the directory, the plugin &XML; is in. Writing help pages is documented <link linkend="pluginhelp">here</link>. If you do not provide a help file, omit this line.
</para>
<programlisting>
<dialog label="Two Variable t-Test">
</programlisting>
<para>
As you know, plugins may have either a dialog or a wizard interface or both. Here we start defining a dialog interface. The <parameter>label</parameter> attribute specifies the caption of the dialog.
</para>
<programlisting>
<tabbook>
<tab label="Basic settings">
</programlisting>
<para>
&GUI; elements can be organized using a tabbook. Here we define a tabbook as the first element in the dialog. Use <command><tabbook></command>[...]<command></tabbook></command> to define the tabbook and then for each page in the tabbook use <command><tab></command>[...]<command></tab></command>. The <parameter>label</parameter> attribute in the <command><tab></command> element allows you to specify a caption for that page of the tabbook.
</para>
<programlisting>
<row id="main_settings_row">
</programlisting>
<para>
The <command><row></command> and <command><column></command> tags specify the layout of the &GUI; elements. Here you say, that you would like to place some elements side-by-side (left to right). The <parameter>id</parameter> attribute is not strictly necessary, but we will use it later on, when adding a wizard interface to our plugin. The first element to place in the row, is:
</para>
<programlisting>
<varselector id="vars"/>
</programlisting>
<para>
Using this simple tag you create a list from which the user can select variables. You have to specify an <parameter>id</parameter> for this element, so &rkward; knows how to find it.
</para>
<warning>
<para>
You may NOT use a dot (.) in the <parameter>id</parameter> string.
</para>
</warning>
<programlisting>
<column>
</programlisting>
<para>
Next, we nest a <command><column></command> inside the row. That is the following elements will be placed above each other (top-to-bottom), and all will be to the right of the <command><varselector></command>.
</para>
<programlisting>
<varslot types="number" id="x" source="vars" required="true" label="compare"/>
<varslot types="number" id="y" source="vars" required="true" label="against" i18n_context="compare against"/>
</programlisting>
<para>
These elements are the counterpart to the <command><varselector></command>. They represent <quote>slots</quote> into which the user can put variables. You will note that the <parameter>source</parameter> is set to the same value as the <parameter>id</parameter> of the <command><varselector></command>. This means, the <command><varslot></command>s will each take their variables from the varselector. The <command><varslot></command>s also have to be given an <parameter>id</parameter>. They may have a <parameter>label</parameter>, and they may be set to <parameter>required</parameter>. This means that the <guibutton>Submit</guibutton> button will not be enabled until the <command><varslot></command> holds a valid value. Finally the <parameter>type</parameter> attribute is not interpreted yet, but it will be used to take care that only the correct types of variables will be allowed in the <command><varslot></command>.
</para>
<para>
In case you are wondering about the <parameter>i18n_context</parameter>-attribute: This is to provide context to help the correct translation of the word "against", used as the
<command><varslot></command>'s label, but does not affect the functionality of the plugin, directly. More on this in <link linkend="i18n_general">a separate chapter</link>.
</para>
<programlisting>
<radio id="hypothesis" label="using test hypothesis">
<option value="two.sided" label="Two-sided"/>
<option value="greater" label="First is greater"/>
<option value="less" label="Second is greater"/>
</radio>
</programlisting>
<para>
Here, you define a group of <command><radio></command> exclusive buttons. The group has a <parameter>label</parameter> and an <parameter>id</parameter>. Each <command><option></command> (button) has a <parameter>label</parameter> and is assigned a <parameter>value</parameter>. This is the value the <command><radio></command> element will return when the option is selected.
</para>
<programlisting>
</column>
</row>
</tab>
</programlisting>
<para>
Each tag has to be closed. We have put all the elements we wanted (the two <command><varslots></command> and the <command><radio></command>) in the <command><column></command>. We put all elements we wanted (the <command><varselector></command> and the <command><column></command> with those elements) in the <command><row></command>. And we have put all the elements we wanted into the first page in the <command><tabbook></command>. We are not yet done defining the <command><tabbook></command> (more pages to come), and of course there is more to come in the <command><dialog></command>, too. But this screenshot is basically what we have done so far:
</para>
<screenshot>
<screeninfo>t-Test plugin</screeninfo>
<mediaobject>
<imageobject>
<imagedata fileref="t_test_plugin_example.png" format="PNG"/>
</imageobject>
<textobject>
<phrase>t-Test plugin</phrase>
</textobject>
</mediaobject>
</screenshot>
<para>
Note that we have not specified the <guibutton>Submit</guibutton>, <guibutton>Close</guibutton>, &etc; buttons or the code view. Those elements get generated automatically. But of course we still have to define the second page of the <command><tabbook></command>:
</para>
<programlisting>
<tab label="Options">
<checkbox id="varequal" label="assume equal variances" value=", var.equal=TRUE"/>
</programlisting>
<para>
By default elements will be placed top-to-bottom like in a <command><column></command>. Since that is what we want here, we do not have to explicitly state a <command><row></command> or <command><column></command> layout. The first element we define is a checkbox. Just like the <command><radio></command><command><option></command>s, the checkbox has a <parameter>label</parameter> and a <parameter>value</parameter>. The <parameter>value</parameter> is what gets returned, if the check box is checked. Of course the checkbox also needs an <parameter>id</parameter>.
</para>
<programlisting>
<frame label="Confidence Interval" id="frame_conf_int">
</programlisting>
<para>
Here is yet another layout element: In order to signal that the two elements below belong together, we draw a <command><frame></command> (box). That frame may have a <parameter>label</parameter> (caption). Since the frame is just a passive layout element, it does not need an <parameter>id</parameter>, we still define one here, as we will refer to it later, when defining an additional wizard interface.
</para>
<programlisting>
<checkbox id="confint" label="print confidence interval" value="1" checked="true"/>
<spinbox type="real" id="conflevel" label="confidence level" min="0" max="1" initial="0.95"/>
</frame>
</programlisting>
<para>
Inside the <command><frame></command> we place another <command><checkbox></command> (using <parameter>checked=</parameter><replaceable>"true"</replaceable>, we signal that check box should be checked by default), and a <command><spinbox></command>. The spinbox allows the user to select a value between <replaceable>"min"</replaceable> and <replaceable>"max"</replaceable> with the default/initial value <replaceable>"0.95"</replaceable>. Setting the <parameter>type</parameter> to <replaceable>"real"</replaceable> signals that real numbers are accepted as opposed to <parameter>type=</parameter><replaceable>"integer"</replaceable> which would accept integers only.
</para>
<note><para>
It is also possible, and often preferable, to make the <command><frame></command> itself checkable, instead of adding a <command><checkbox></command> inside. See the reference for details. This is not done here, for illustrational purposes.
</para></note>
<programlisting>
</tab>
</tabbook>
</dialog>
</programlisting>
<para>
That is all for the second page of the <command><tabbook></command>, all pages in the <command><tabbook></command> and all elements in the <command><dialog></command>. We are finished defining what the dialog looks like.
</para>
<programlisting>
</document>
</programlisting>
<para>
Finally we close the <command><document></command> tag, and that is it. The &GUI; is defined. You can save the file now. But how does &R; syntax get generated from the &GUI; settings? We will deal with that in the <link linkend="jstemplate">next chapter</link>. First, however, we will look into adding a wizard interface, and some general considerations.
</para>
</sect1>
<sect1 id="wizard_interface">
<title>Adding a wizard interface</title>
<para>
Actually we do not have to define an additional <command><wizard></command> interface, but here is how that would be done. To add a wizard interface, you will add a <command><wizard></command> tag at the same level as the <command><dialog></command> tag:
</para>
<programlisting>
<wizard label="Two Variable t-Test">
<page id="firstpage">
<text>As a first step, select the two variables you want to compare against
each other. And specify, which one you theorize to be greater. Select two-sided,
if your theory does not tell you, which variable is greater.</text>
<copy id="main_settings_row"/>
</page>
</programlisting>
<para>
Some of this is pretty self explanatory: We add a <command><wizard></command> tag with a <parameter>label</parameter> for the wizard. Since a wizard can hold several pages that are shown one after another, we next define the first <command><page></command>, and put an explanatory <command><text></command> note in there. Then we use a <command><copy></command> tag. What this does, is really it saves us having to define yet again, what we already wrote for the <command><dialog></command>: The copy tag looks for another tag with the same <parameter>id</parameter> earlier in the &XML;. This happens to be defined in the <command><dialog></command> section, and is a <command><row></command> in which there are the <command><varselector></command>, <command><varslots></command> and the <quote>hypothesis</quote> <command><radio></command> control. All of this is copied 1:1 and inserted right at the <command><copy></command> element.
</para>
<para>
Now to the second page:
</para>
<programlisting>
<page id="secondpage">
<text>Below are some advanced options. It is generally safe not to assume the
variables have equal variances. An appropriate correction will be applied then.
Choosing "assume equal variances" may increase test-strength, however.</text>
<copy id="varequal"/>
<text>Sometimes it is helpful to get an estimate of the confidence interval of
the difference in means. Below you can specify whether one should be shown, and
which confidence-level should be applied (95% corresponds to a 5% level of
significance).</text>
<copy id="frame_conf_int"/>
</page>
</wizard>
</programlisting>
<para>
Much of the same thing here. We add some texts, and in between that <command><copy></command> further sections from the dialog interface.
</para>
<para>
You may of course make the wizard interface look very different to the plain dialog, and not use the <command><copy></command> tag at all. Be sure, however, to assign corresponding elements the same <parameter>id</parameter> in both interfaces. This is not only used to transfer settings from the dialog interface to the wizard interface and back, when the user switches interfaces (which does not yet happen in the current version of &rkward;), but also simplifies writing your code template (see below).
</para>
</sect1>
<sect1 id="mainxmltips">
<title>Some considerations on &GUI; design</title>
<para>
This section contains some general considerations on which &GUI; elements to use where. If this is your first attempt of creating a plugin, feel free to skip over this section, as it is not relevant to getting a basic &GUI; working. Come back here, later, to see, whether you can refine your plugin's &GUI; in some way or another.
</para>
<sect2 id="radio_vs_checkbox_vs_dropdown">
<title><radio> vs. <checkbox> vs. <dropdown></title>
<para>
The three elements <command><radio></command>, <command><checkbox></command>, <command><dropdown></command>, all serve a similar function: To select one out of several options. Obviously, a check box only allows to choose between two options: checked or not checked, so you cannot use it, if there are more than two options to choose from. But when to use which of the elements? Some rules of thumb:
</para>
<para>
If you find yourself creating a <command><radio></command> or <command><dropdown></command> with only two options, ask yourself, whether the question is essentially a yes / no type of question. E.g. a choice between <quote>adjust results</quote> and <quote>do not adjust results</quote>, or between <quote>remove missing values</quote> and <quote>keep missing values</quote>. In this case a <command><checkbox></command> is the best choice: It uses little space, will have the least words of labels, and is easiest to read for the user. There are very few situations where you should choose a <command><radio></command> over a <command><checkbox></command>, when there are only two options. An example of that might be: <quote>Method of calculation: 'pearson'/'spearman'</quote>. Here, more methods might be thinkable, and they do not really form a pair of opposites.
</para>
<para>
Choosing between a <command><radio></command> and a <command><dropdown></command> is mostly a question of space. The <command><dropdown></command> has the advantage of using little space, even if there are a lot of options to choose from. On the other hand, a <command><radio></command> has the advantage of making all possible choices visible to the user at once, without clicking on the dropdown arrow. Generally, if there are six or more options to choose from, a <command><dropdown></command> is preferable. If there are five or less options, a <command><radio></command> is the better choice.
</para>
</sect2>
</sect1>
</chapter>
<chapter id="jstemplate">
<title>Generating &R; code from &GUI; settings</title>
<sect1 id="sect_generating_R_code"><title>Using &javascript; in &rkward; plugins</title>
<para>
Now we have a &GUI; defined, but we still need to generate some &R; code from that. For that, we need another text file, <filename>code.js</filename>, located in the same directory as the <link linkend="mainxml"><filename>description.xml</filename></link>. You may or may not be familiar with &javascript; (or, to be technically precise: ECMA-script). Documentation on JS can be found in abundance, both in printed form, and on the Internet (⪚: <ulink url="https://developer.mozilla.org/en/Core_JavaScript_1.5_Guide">https://developer.mozilla.org/en/Core_JavaScript_1.5_Guide</ulink>). But for most purposes you will not need to know much about JS at all, as we will only use some very basic features.
</para>
<tip>
<para>
After reading this chapter, have a look at the <link linkend="rkwarddev"><application>rkwarddev</application> package</link> as well. It provides some &R; functions to create &javascript; code commonly used in &rkward;. It can also autodetect variables used in a plugin &XML; file and create basic &javascript; code from that for you to start with.
</para>
</tip>
<note>
<para>
Plugin <literal role="extension">.js</literal> files are assumed to be UTF-8 encoded. Be sure to check you editor's encoding, if using any non-ascii characters.
</para>
</note>
<para>
For the two variable t-test, the <filename>code.js</filename> file looks as follows (with comments in between):
</para>
<sect2 id="sect_JS_preprocess"><title>preprocess()</title>
<programlisting>
function preprocess () {
}
</programlisting>
<para>
The JS file is organized into three separate functions: <function>preprocess()</function>, <function>calculate()</function>, and <function>printout()</function>. This is because not all code is needed at all stages. Currently the preprocess-function is not really used in many places (typically you will omit it altogether).
</para>
</sect2>
<sect2 id="sect_JS_calculate"><title>calculate()</title>
<programlisting>
function calculate () {
echo ('res <- t.test (x=' + getString ("x") + ', y=' + getString ("y") + ', hypothesis="' + getString ("hypothesis") + '"' + getString ("varequal"));
var conflevel = getString ("conflevel");
if (conflevel != "0.95") echo (', conf.level=' + conflevel);
echo (')\n');
}
</programlisting>
<para>
This function generates the actual &R; syntax to be run from the &GUI; settings. Let's look at this in detail: The code to be used is generated using <function>echo()</function> statement. Looking at the <function>echo()</function> statement step by step, the first part of it is
</para>
<screen>
res <- t.test (
</screen>
<para>
as plain text. Next we need to fill in the value, the user selected as the first variable. We fetch this using <function>getString ("x")</function>, and append it to the string to be <quote>echoed</quote>. This prints out the value of the &GUI;-element with <parameter>id=</parameter><replaceable>"x"</replaceable>: our first <command><checkbox></command>. Next, we append a ', ', and do the same to fetch the value of the element <replaceable>"y"</replaceable> - the second <command><checkbox></command>. For the hypothesis (the <command><radio></command> group), and the equal variances <command><checkbox></command>, the procedure is very similar.
</para>
<para>
Note that instead of concatenating the output snippets with <quote>+</quote>, you can also use several <function>echo()</function> statements. Everything is printed on a single line. To produce a line break in the generated code, insert a <replaceable>"\n"</replaceable> in the echoed string. In theory, you can even produce many lines with a single echo-statement, but please keep it to one line (or less) of generated code per <function>echo()</function>.
</para>
<note>
<para>Besides <function>getString()</function>, there are also functions <function>getBoolean()</function>, which will try to return the value as a logical (suitable for using in an <function>if()</function>-statement), and <function>getList()</function>, which will try to return list-like data in a JS <function>Array()</function>. We will show examples of those, later.</para>
<para>When looking at existing plugins, you will also find plenty of plugins using <function>getValue()</function>, instead of <function>getString()</function>, and in fact the two are <emphasis>almost</emphasis> identical. However using <function>getString()</function>, <function>getBoolean()</function> and <function>getList()</function> is the recommended practice since version 0.6.1.
</para>
</note>
<para>
It gets a little more tricky for the confidence level. For reasons of aesthetics, we do not want to explicitly specify the confidence level to use, if it corresponds to the default value. Hence, instead of printing the value unconditionally, we first fetch into a variable. Then we check, whether that variable differs from <replaceable>"0.95"</replaceable> and if so print out an additional argument. Finally, we echo a closing bracket and a line break: <replaceable>")\n"</replaceable>. That is all for the calculate function.
</para>
</sect2>
<sect2 id="sect_JS_printout"><title>printout()</title>
<programlisting>
function printout () {
echo ('rk.header (' + i18n ("Two Variable t-Test") + ')\n');
echo ('rk.print (res)\n');
}
</programlisting>
<para>
And this was all there is to the printout function in most cases. <function>rk.header()</function> prints a standard headline for the results. Note that in the <literal role="extension">.js</literal> files, you have to
mark up all translatable strings by hand, using <command>i18n()</command>, or some alternative commands. More on this in the <link linkend="i18n_js">chapter on internationalization</link>.
You can also add some more information to this, if you like, ⪚:
</para>
<programlisting>
function printout () {
new Header (i18n ("Two Variable t-Test"))
.addFromUI ("varequal")
.add (i18n ("Confidence level"), getString ("conflevel")) // Note: written like this for illustration purposes. More automatic:
// .addFromUI ("conflevel")
.print ();
echo ('rk.print (res)\n');
}
</programlisting>
<para>
<function>rk.print()</function> utilizes the R2HTML package to provide &HTML; formatted output. Another helpful function is <function>rk.results()</function>, which can also output different kinds of result tables. If in doubt, however, just use <function>rk.print()</function>, and be done with. The JS class <function>Header</function> is a JS level helper to generate a call to <function>rk.header()</function> (just take a look at the generated &R; code). In some cases you may want to call <function>echo ('rk.header (...)')</function> directly to print a header for your output.
</para>
<para>
Note that internally, the output is just a plain &HTML; document at this point of time. Therefore you might be tempted to add custom &HTML; using <function>rk.cat.output()</function>. While this will work, please do not do this. The output format may change (⪚ to ODF) in the future, so it is best not to introduce &HTML; specific code. Rather keep things simple with <function>rk.header()</function>, <function>rk.print()</function>, <function>rk.results()</function>, and -- if needed -- <function>rk.print.literal()</function>. If those do not seem to satisfy your formatting needs, contact us on the mailing list for help.
</para>
<para>
Congratulations! You created your first plugin. Read on in the next chapters for more advanced concepts.
</para>
</sect2>
</sect1>
<sect1 id="jsconventions">
<title>Conventions, policies, and background</title>
<para>
There are many ways to write &R; code for a certain task, and there are even more ways to generate this &R; code from JS. How exactly you do it, is left up to you. Still there are a number of considerations that you should follow, and background information you should understand.
</para>
<sect2 id="policylocal">
<title>Understanding the <function>local()</function> environment</title>
<para>
More often than not you will have to create one or more temporary &R; objects in the code generated by your plugin. Normally, you do not want those to be placed in the user's workspace, potentially even overwriting user variables. Hence, all plugin generated code is run in a <function>local()</function> environment (see &R; help page on function <function>local()</function>). This means, all variables you create are temporary and will not be saved permanently.
</para>
<para>
If the user explicitly asks for a variable to be saved, you will need to assign to that object using <function>.GlobalEnv$objectname <- value</function>. In general, do not use the <function><<-</function> operator. It will not necessarily assign in .GlobalEnv.
</para>
<para>
One important pitfall is using <function>eval()</function>. Here, you need to note that eval will by default use the current environment for evaluation, &ie; the local one. This will work well most of the times, but not always. Thus, if you need to use <function>eval()</function>, you will probably want to specify the <parameter>envir</parameter> parameter: <function>eval(..., envir=globalenv()</function>).
</para>
</sect2>
<sect2 id="policyformatting">
<title>Code formatting</title>
<para>
The most important thing is for your generated &R; code to work, but it should be also easy to read. Therefore, please also keep an eye on formatting. Some considerations:
</para>
<para>
Normal top-level &R; statements should be left aligned.
</para>
<para>
Statements in a lower block should be indented with one tab (see example below).
</para>
<para>
If you do very complex calculations, add a comment here and there, esp. to mark up logical sections. Note that there is a dedicated function <command>comment()</command> for inserting
translatable comments in the generated code.
</para>
<para>
For example, generated code might look like this. The same code without indentation or comments would be pretty hard to read, despite its modest complexity:
</para>
<programlisting>
# first determine the wobble and rotation
my.wobble <- wobble (x, y)
my.rotation <- wobble.rotation (my.wobble, z)
# boggling method needs to be chosen according to rotation
if (my.rotation > wobble.rotation.limit (x)) {
method <- "foo"
result <- boggle.foo (my.wobble, my.rotation)
} else {
method <- "bar"
result <- boggle.bar (my.wobble, my.rotation)
}
</programlisting>
</sect2>
<sect2 id="policysimplicity">
<title>Dealing with complex options</title>
<para>
Many plugins can do more than one thing. For instance, the <quote>Descriptive Statistics</quote> plugin can compute mean, range, sum, product, median, length, &etc; However, typically the user will only choose to have some of those calculations performed. In this case, please try to keep the generated code as simple as possible. It should only contain portions relevant to the options that are actually selected. To achieve this, here is an example of a common design patterns as you would use it (in JS; here, "domean", "domedian", and "dosd" would be <checkbox> elements):
</para>
<programlisting>
function calculate () {
echo ('x <- <' + getString ("x") + ')\n');
echo ('results <- list ()\n');
if (getBoolean ("domean.state")) echo ("results$" + i18n ("Mean value") + " <- mean (x)\n");
if (getBoolean ("domedian.state")) echo ("results$" + i18n ("Median") + " <- median (x)\n");
if (getBoolean ("dosd.state")) echo ("results$" + i18n ("Standard deviation") + " <- sd (x)\n");
//...
}
</programlisting>
</sect2>
</sect1>
<sect1 id="jstips">
<title>Tips and tricks</title>
<para>
Here are a few assorted tricks which may make writing plugins less tedious:
</para>
<para>
If you need the value of a &GUI; setting at several places in you plugin's code, consider assigning it to a variable in JS, and using that instead of fetching it again and again with <function>getString()/getBoolean()/getList()</function>. This is faster, more readable, and less typing all at the same time:
</para>
<programlisting>
function calculate () {
var narm = ""; // na.rm=FALSE is the default in all functions below
if (getBoolean ("remove_nas")) {
$narm = ", na.rm=TRUE";
}
// ...
echo ("results$foo <- foo (x" + narm + ")\n");
echo ("results$bar <- bar (x" + narm + ")\n");
echo ("results$foobar <- foobar (x" + narm "\n");
// ...
}
</programlisting>
<para>
The simple helper function <function>makeOption()</function> can make it easier to omit parameters that are at their default value, in many cases:
</para>
<programlisting>
function calculate () {
var options
//...
// This will do nothing, if VALUE is 0.95 (the default). Otherwise it will append ', conf.int=VALUE' to options.
options += makeOption ("conf.int", getString ("confint"), "0.95");
//...
}
</programlisting>
</sect1>
</chapter>
<chapter id="pluginhelp">
<title>Writing a help page</title>
<para>
When your plugin basically works, the time has come to provide a help page. While typically you will not want to explain all the underlying concepts in depth, you may want to add some more explanation for some of the options, and link to related plugins and &R; functions.
</para>
<tip>
<para>
After reading this chapter, have a look at the <link linkend="rkwarddev"><application>rkwarddev</application> package</link> as well. It provides some &R; functions to create most of &rkward;'s &XML; tags for you. It is also capable of creating basic help file skeletons from existing plugin &XML; files for you to start with.
</para>
</tip>
<para>
You may recall putting this inside your plugin &XML; (if you have not put this in, do so now):
</para>
<programlisting>
<document>
[...]
<help file="filename.rkh" />
[...]
</document>
</programlisting>
<para>
Where, obviously, you would replace <filename>filename</filename> with a more appropriate name. Now it is time to create this <literal role="extension">.rkh</literal> file. Here is a self-descriptive example:
</para>
<programlisting>
<!DOCTYPE rkhelp>
<document>
<summary>
In this section, you will put some short, very basic information about what the plugin does.
This section will always show up on the very top of the help page.
</summary>
<usage>
The usage section may contain a little more practical information. It does not explain all
the settings in detail (that is done in the "settings" section), however.
To start a new paragraph, insert an empty line, as shown above.
This line, in contrast, will be in the same paragraph.
In all sections you can insert some simple HTML code, such as <b>bold</b> or
<i>italic</i> text. Please keep formatting to the minimum needed, however.
The usage section is always the second section shown in a help page.
</usage>
<section id="sectionid" title="Generic section" short_title="Generic">
If you need to, you can add additional sections between the usage and settings sections.
However, usually, you will not need this while documenting plugins. The "id"-attribute
provides an anchor point to jump to this section from the navigation menu. The "short_title"
attribute provides a short title to use in the navigation bar. This is optional, by default
the main "title" will be used both as a heading to the section, and as the link name in the
navigation bar.
In any section you may want to insert links to further information. You do this by adding
<link href="URL">link name</link>
Where URL could be an external link such as https://rkward.kde.org .
Several special URLs are supported in the help pages:
<link href="rkward://page/path/page_id"/>
This links to a top level rkward help page (not for a plugin).
<link href="rkward://component/[namespace/]component_id"/>
This links to the help page of another plugin. The [namespace/] part may be omitted
(in this case, rkward is assumed as the standard namespace, e.g.:
<link href="rkward://component/import_spss"/> or
<link href="rkward://component/rkward/import_spss"/> are equivalent).
The component_id is the same that you specified in the <link linkend="pluginmap">&pluginmap;</link>.
<link href="rkward://rhelp/rfunction"/>
Links to the &R; help page on "rfunction".
Note that the link names will be generated automatically for these types of links.
</section>
<settings>
<caption id="id_of_tab_or_frame"/>
<setting id="id_of_element">
Description of the GUI element identified by the given id
</setting>
<setting id="id_of_elementb" title="description">
Usually the title of the GUI element will be extracted from the
<link linkend="mainxml">&XML; definition of the plugin</link>, automatically. However,
for some GUI elements, this description may not be enough to identify them, reliably.
In this case, you can add an explicit title using the "title" attribute.
</setting>
<setting id="id_of_elementc">
Description of the GUI element identified by "id_of_elementc"
</setting>
[...]
</settings>
<related>
The related section typically just contains some links, such as:
<ul>
<li><link href="rkward://rhelp/mean"/></li>
<li><link href="rkward://rhelp/median"/></li>
<li><link href="rkward://component/related_component"/></li>
</ul>
</related>
<technical>
The technical section (optional, always last) may contain some technical details of the plugin
implementation, which are of interest only to RKWard developers. This is particularly relevant
for plugins that are designed to be embedded in many other plugins, and could detail, which
options are available to customize the embedded plugin, and which code sections contain which
R code.
</technical>
</document>
</programlisting>
</chapter>
<chapter id="logic">
<title>Logic interactions between &GUI; elements</title>
<sect1 id="sect_GUI_logic"><title>&GUI; logic</title>
<para>
All the basic concepts of creating a plugin for &rkward; have been described in the previous chapters. Those basic concepts should be sufficient for many -- if not most -- cases. However, sometimes you want more control over how your plugin's &GUI; behaves.
</para>
<para>
For instance, suppose you want to extend the t-test example used in this documentation to allow both: comparing a variable against another variable (as shown), and comparing a variable against a constant value. Now, one way of doing this would be to add a radio-control that switches between the two modes, and adding a spinbox to enter the constant value to compare against. Consider this simplified example:
</para>
<programlisting>
<!DOCTYPE rkplugin>
<document>
<code file="code.js"/>
<dialog label="T-Test">
<row>
<varselector id="vars"/>
<column>
<varslot id="x" types="number" source="vars" required="true" label="compare"/>
<radio id="mode" label="Compare against">
<option value="variable" checked="true" label="another variable (select below)"/>
<option value="constant" label="a constant value (set below)"/>
</radio>
<varslot id="y" types="number" source="vars" required="true" label="variable" i18n_context="Noun; a variable"/>
<spinbox id="constant" initial="0" label="constant" i18n_context="Noun; a constant"/>
</column>
</row>
</dialog>
</document>
</programlisting>
<para>
So far so good, but there are a number of problems with this &GUI;. First, both the varslot and the spinbox are always shown, whereas only one of the two is really used. Worse, the varslot always requires a valid selection, even if you compare against a constant. Obviously, if we create a multi-purpose &GUI; like this, we want more flexibility. Enter: the <command><logic></command> section (inserted at the same level as <command><code></command>, <command><dialog></command>, or <command><wizard></command>).
</para>
<programlisting>
[...]
<code file="code.js"/>
<logic>
<convert id="varmode" mode="equals" sources="mode.string" standard="variable" />
<connect client="y.visible" governor="varmode" />
<connect client="constant.visible" governor="varmode.not" />
</logic>
<dialog label="T-Test">
[...]
</programlisting>
<para>
The first line inside the logic section is a <command><convert></command> tag. Basically, this provides a new boolean (on or off, true or false) property, which can be used later on. This property (<replaceable>"varmode"</replaceable>) is true, whenever the upper radio button is selected and false whenever the lower radio button is selected. How is this done?
</para>
<para>
First, under <parameter>sources</parameter>, the source properties to work on are listed (in this case only one each; you could list several as <parameter>sources=</parameter><replaceable>"mode.string;somethingelse"</replaceable>, then <replaceable>"varmode"</replaceable> would only be true, if both <replaceable>"mode.string"</replaceable> and <replaceable>"somethingelse"</replaceable> are equal to the string <replaceable>"variable"</replaceable>). Note that in this case we do not just write <replaceable>"mode"</replaceable> (as we would in <function>getString("mode")</function>), but <replaceable>"mode.string"</replaceable>. This is actually the internal way a radio control works: It has a property <quote>string</quote>, which holds its string value. <function>getString("mode")</function> is just a shorthand, and equivalent to <function>getString("mode.string")</function>. See the reference for all properties of the different &GUI; elements.
</para>
<para>
Second, we set the mode of conversion to <parameter>mode=</parameter><replaceable>"equals"</replaceable>. This means, we want to check, whether the source(s) is (are) equal to a certain value. Finally standard is the value to compare against, so with <parameter>standard=</parameter><replaceable>"variable"</replaceable>, we check whether the property <replaceable>"mode.string"</replaceable> is equal to the string <replaceable>"variable"</replaceable> (the value of the upper radio option). If it is equal, then the property varmode is true, else it is false.
</para>
<para>
Now to the real stuff: We <command><connect></command> the <replaceable>"varmode"</replaceable> property to y.visible, which controls whether the varslot <replaceable>"y"</replaceable> is shown or not. Note that any element which is made invisible is implicitly non-required. Thus, if the upper radio-option is selected, the varslot <replaceable>"y"</replaceable> is required, and visible. Else it is not required and hidden.
</para>
<para>
For the spinbox, we want the exact reverse. Fortunately, we do not need another <command><convert></command> for this: Boolean
properties can be negated very easily by appending the modifier <replaceable>"not"</replaceable>, so we <command><connect></command> <replaceable>"varmode.not"</replaceable> to the spinbox's visibility property. In effect, either
the varslot is shown and required, <emphasis>or</emphasis> the spinbox is shown and required - depending on which option is selected in the radio control. The &GUI; is changing itself according to the radio option. Try the example, if you like.
</para>
<para>
For a complete list of properties, refer to the <link linkend="reference">reference</link>. One more property, however, is special in that all &GUI; elements have it: <quote>enabled</quote>. This is slightly less drastic than <quote>visible</quote>. It does not show/hide the &GUI; element, but only enables/disables it. Disabled elements are typically shown grayed out, and do not react to user input.
</para>
<note>
<para>Besides <command><convert></command> and <command><connect></command>, there are several further elements for use in the <command><logic></command> section. E.g. conditional constructs can also be implemented using the <command><switch></command>-element. Refer to the <link linkend="logicelements">reference on logic elements</link> for details.</para>
</note>
</sect1>
<sect1 id="logic_scripted">
<title>Scripted &GUI; logic</title>
<para>
While connecting properties as described above is often enough, sometimes it is more flexible or more convenient to use JS to script the &GUI; logic. In this way, the above example could be re-written as:
</para>
<programlisting>
[...]
<code file="code.js"/>
'
<logic>
<script><![CDATA[
// ECMAScript code in this block
// the top-level statement is only called once
gui.addChangeCommand ("mode.string", "modeChanged ()");
// this function is called whenever the "mode" was changed
modeChanged = function () {
var varmode = (gui.getString ("mode.string") == "variable");
gui.setValue ("y.enabled", varmode);
gui.setValue ("constant.enabled", !varmode);
}
]]></script>
</logic>
<dialog label="T-Test">
[...]
</programlisting>
<para>
The first line of code tells &rkward; to call the function <function>modeChanged()</function> whenever the value of the <parameter>id=</parameter><replaceable>"mode"</replaceable> radio box changes. Inside this function, we define a helper-variable <replaceable>"varmode"</replaceable> which is true when the mode is <replaceable>"variable"</replaceable>, false as it is <replaceable>"constant"</replaceable>. Then we use <function>gui.setValue()</function> to set the <quote>enabled</quote> properties of <replaceable>"y"</replaceable> and <replaceable>"constant"</replaceable>, in just the same way as we did using <command><connect></command> statements, before.
</para>
<para>
The scripted approach to &GUI; logic becomes particularly useful when you want to change the available option according to the type of object that the user has selected. See <link linkend="guilogic_functions">the reference</link> for available functions.
</para>
<para>
Note that the scripted approach to &GUI; logic can be mixed with <command><connect></command> and <command><convert></command>-statements if you like. Also note that the <command><script></command> tag allows to specify a script file name in addition to or as an alternative to inlining the script code. Typically, inlining the script code as shown above is most convenient, however.
</para>
</sect1>
</chapter>
<chapter id="embedding">
<title>Embedding Plugins into Plugins</title>
<sect1 id="sect_embedding"><title>Use cases for embedding</title>
<para>
When writing plugins, you will often find that you are creating a number of plugins that only differ in some respects, but have a lot more in common. For instance, for plotting, there are a number of generic &R; options that can be used with mostly all types of plots. Should you create a &GUI; and JS-template for those over and over again?
</para>
<para>
Obviously that would be quite a hassle. Fortunately, you do not have to do that. Rather you create the common functionality once, and later you can embed it into several plugins. In fact it is possible to embed any plugin into any other plugin, even if the original author of the embedded plugin never thought, somebody would want to embed their plugin into another one.
</para>
</sect1>
<sect1 id="embedding_dialog">
<title>Embedding inside a dialog</title>
<para>
OK, enough said. How does it work? Simple: Just use the <command><embed></command> tag. Here is a stripped down example:
</para>
<programlisting>
<dialog>
<tabbook>
<tab [...]>
[...]
</tab>
<tab label="Plot Options" i18n_context="Options concerning the plot">
<embed id="plotoptions" component="rkward::plot_options"/>
</tab>
<tab [...]>
[...]
</tab>
</tabbook>
</dialog>
</programlisting>
<para>
What happens here, is that the entire &GUI; or the plot options plugin (except of course for the standard elements like <guibutton>Submit</guibutton> button, &etc;) is embedded right into your plugin (try it!).
</para>
<para>
As you can see the syntax of the <command><embed></command>-tag is fairly simple. It takes an <parameter>id</parameter> as most elements. The parameter component specifies which plugin to embed, as defined in the &pluginmap; file (<replaceable>"rkward::plot_options"</replaceable> is the result of concatenating the namespace <quote>rkward</quote>, a separator <quote>::</quote>, and the name of the component <quote>plot_options</quote>).
</para>
</sect1>
<sect1 id="embedding_code">
<title>Code generation when embedding</title>
<para>
So far so good, but what about the generated code? How are the code for the embedding and embedded plugin merged? In the embedding plugin's JS code, simply write something like this:
</para>
<programlisting>
function printout () {
// ...
echo ("myplotfunction ([...]" + getString ("plotoptions.code.printout"); + ")\n");
// ...
}
</programlisting>
<para>
So essentially, we are fetching the code generated by the embedded plugin just like we are fetching any other &GUI; setting. Here the string <replaceable>"plotoptions.code.printout"</replaceable> can be deparsed to: <quote>The printout section of the generated code of the element with the <parameter>id</parameter> plotoptions</quote> (plotoptions is the ID we gave for the <command><embed></command> tag above). And yes, if you want advanced control, you can even fetch the values of individual &GUI; elements inside the embedded plugin (but not the other way around, as the embedded plugin does not know anything about its surroundings).
</para>
</sect1>
<sect1 id="embedding_wizard">
<title>Embedding inside a wizard</title>
<para>
If your plugin provides a wizard &GUI;, embedding works basically in the same way. You will generally use:
</para>
<programlisting>
<wizard [...]>
[...]
<page id="page12">
[...]
</page>
<embed id="plotoptions" component="rkward::plot_options"/>
<page id="page13">
[...]
</page>
[...]
</wizard>
</programlisting>
<para>
If the embedded plugin provides a wizard interface, its pages will be inserted right between <replaceable>"page12"</replaceable> and <replaceable>"page13"</replaceable> of your plugin. If the embedded plugin provides a dialog interface only, a single new page will be added between your pages <replaceable>"page12"</replaceable> and <replaceable>"page13"</replaceable>. The user will never notice.
</para>
</sect1>
<sect1 id="embedding_as_button">
<title>Less embedded embedding: Further Options button</title>
<para>
While embedding is cool, you should be careful not to overdo it. Too many functions inside a &GUI; just make it hard to find the relevant options. Of course, sometimes you may want to embed a great deal of options (like all the options to <function>plot()</function>), but as those are really optional, you do not want them prominently in your &GUI;.
</para>
<para>
An alternative is to embed those options <quote>as a button</quote>:
</para>
<programlisting>
<dialog>
<tabbook>
[...]
<tab label="Options">
[...]
<embed id="plotoptions" component="rkward::plot_options" as_button="true" label="Specify plotting options"/>
</tab>
[...]
</tabbook>
</dialog>
</programlisting>
<para>
In this case, a single push button will be added to your plugin, labeled <guibutton>Specify plotting options</guibutton>. When you press that button, a separate dialog will come up, with all the options of the embedded plugin. Even while this embedded &GUI; is not visible most of the time, you can fetch its settings just as described <link linkend="embedding_code">above</link>.
</para>
<para>
<caution>
<para>
Probably the <quote>button</quote> approach should only ever be used for plugins that can never be invalid (for missing/bad settings). Otherwise the user would not be able to submit the code, but might have a hard time finding out, the reason for that is hidden behind some button.
</para>
</caution>
</para>
</sect1>
<sect1 id="embedding_incomplete">
<title>Embedding/defining incomplete plugins</title>
<para>
Some plugins -- and as a matter of fact, the plot_options used as an example above, is one of them -- are not complete by themselves. They simply do not have the &GUI; elements to select some important values. They are meant to be used only embedded into other plugins.
</para>
<para>
In how far is the plot_options plugin incomplete? Well, for some option settings, it needs to know the name of the objects/expressions for the x and y axes (actually it will do fine if it only has either, but it needs at least one to function properly). However, it does not have a mechanism of selecting those objects, or entering them any other way. So how does it know about them?
</para>
<para>
In the logic section of the plot_options plugin there are two additional lines, not covered, yet:
</para>
<programlisting>
<logic>
<external id="xvar" />
<external id="yvar" />
[...]
</logic>
</programlisting>
<para>
This defines two additional properties in the plot_options plugin, whose sole purpose is to be connected to some (yet unknown) properties of the embedding plugin. In the plot_options plugin those two properties are simply used like any other, and for instance there are calls to <function>getString("xvar")</function> in the plot_options JS template.
</para>
<para>
Now, for the incomplete plugin there is no way of knowing, where it will be embedded, and what the relevant settings in the embedding plugin will be called. So we need to add two additional lines in the embedding plugin's logic section as well:
</para>
<programlisting>
<logic>
[...]
<connect client="plotoptions.xvar" governor="xvarslot.available" />
<connect client="plotoptions.yvar" governor="yvarslot.available" />
</logic>
</programlisting>
<para>
This is nothing new in principle, we have covered <command><connect></command> statements in the <link linkend="logic">chapter of &GUI; logic</link>. You simply connect the values in two varlots (called <replaceable>"xvarslot"</replaceable> and <replaceable>"yvarslot"</replaceable> in this example) to the receiving <quote>external</quote> properties of the embedded plugin. That is it. Everything else is taken care of automatically.
</para>
</sect1>
</chapter>
<chapter id="plugin_series">
<title>Dealing with many similar plugins</title>
<sect1 id="sect_similar_plugins"><title>Overview on different approaches</title>
<para>
Sometimes, you may wish to develop plugins for a series of similar functions. As an example, consider the distribution plots. These generate fairly similar code, and of course it is desirable to make the graphical interfaces look similar to each other. Finally large sections of the help files can be identical. Only a few parameters are different for each plugin.
</para>
<para>
The naive approach to this is to develop one plugin, then basically copy and paste the entire contents of the <literal role="extension">.js</literal>, <literal role="extension">.xml</literal>, and <literal role="extension">.rkh</literal> files, then changing the few portions that are different. However, what if sometime later you find a spelling mistake that has been copied and pasted to all plugins? What if you want to add support for a new feature? You would have to visit all plugins again, and change each single one. A tiresome and tedious process.
</para>
<para>
A second approach would be to use <link linkend="embedding">embedding</link>. However, in some cases this does not lend itself well to the problem at hand, mostly because the <quote>chunks</quote> you can embed are sometimes too large to be useful, and it places some constraints on the layout. For these cases, the concepts <link linkend="include_js">including <literal role="extension">.js</literal> files</link>, <link linkend="include_xml">including <literal role="extension">.xml</literal> files</link> and <link linkend="snippets">snippets</link> can be very useful (but see the <link linkend="include_snippets_vs_embedding">thoughts on when it is preferable to use embedding</link>).
</para>
<para>
One word of caution, before you begin reading, though: These concepts can help making it simpler to deal with many similar plugins, and can improve maintainability and readability of those plugins. However, overdoing it can easily lead to the reverse effect. Use with some caution.
</para>
</sect1>
<sect1 id="include_js">
<title>Using the JS include statement</title>
<para>
You can easily include one script file into another in &rkward; plugins. The value of this becomes immediately obvious, if some sections of your JS code are similar across plugins. You can simply define those sections in a separate <literal role="extension">.js</literal> file, and include this in all the plugin <literal role="extension">.js</literal> files. For example, as in:
</para>
<programlisting>
// this is a file called "common_functions.js"
function doCommonStuff () {
// perhaps fetch some options, etc.
// ...
comment ("This is R code you want in several different plugins\n");
// ...
}
</programlisting>
<programlisting>
// this is one of your regular plugin <literal role="extension">.js</literal> files
// include the common functions
include ("common_functions.js");
function calculate () {
// do something
// ...
// insert the common code
doCommonStuff ();
}
</programlisting>
<para>
Note that sometimes it is even more useful to reverse this, and define the <quote>skeleton</quote> of <function>preprocess()</function>, <function>calculate()</function>, and <function>printout()</function> functions is a common file, and make these call back for those part which are different across plugins. E.g.:
</para>
<programlisting>
// this is a file called "common_functions.js"
function calculate () {
// do some things which are the same in all plugins
// ...
// add in something that is different across plugins
getSpecifics ();
// ...
}
</programlisting>
<programlisting>
// this is one of your regular plugin <literal role="extension">.js</literal> files
// include the common functions
include ("common_functions.js");
// note: no calculate() function is defined in here.
// it in the common_functions.js, instead.
function getSpecifics () {
// print some R code
}
</programlisting>
<para>
One issue you should be aware of when using this technique is variable scoping. See the JS manual on variable scopes.
</para>
<para>
This technique is heavily used in the distribution plot and distribution CLT plot plugins, so you may want to look there for examples.
</para>
</sect1>
<sect1 id="include_xml">
<title>Including <literal role="extension">.xml</literal> files</title>
<para>
Basically the same feature of including files is also available for use in the <literal role="extension">.xml</literal>, &pluginmap; and <literal role="extension">.rkh</literal> files. At any place in these files you can place an <command><include></command> tag as shown below. The effect is that the entire contents of that &XML; file (to be precise: everything within the <command><document></command> tag of that file) is included verbatim at this point in the file. Note that you can only include another &XML; file.
</para>
<programlisting>
<document>
[...]
<include file="another_xml_file.xml"/>
[...]
</document>
</programlisting>
<para>
The attribute <parameter>file</parameter> is the filename relative to the directory the current file is located in.
</para>
</sect1>
<sect1 id="snippets">
<title>Using <snippets></title>
<para>
While including files as shown in the <link linkend="include_xml">previous section</link> is fairly powerful, it become most useful when used in combination with <command><snippets></command>. Snippets are really smaller sections which you can insert at another point in the file. An example illustrates this best:
</para>
<programlisting>
<document>
<snippets>
<snippet id="note">
<frame>
<text>
This will be inserted at two places in the GUI
</text>
</frame>
</snippet>
</snippets>
<dialog label="test">
<column>
<insert snippet="note"/>
[...]
<insert snippet="note"/>
</column>
</dialog>
</document>
</programlisting>
<para>
Hence, you define the snippet at one place at the top of the &XML; file, and then you <command><insert></command> it at any place(s) you wish.
</para>
<para>
While this example is not too useful in itself, think about combining this with an <command><include></command>d <literal role="extension">.xml</literal> file. Note that you can also place snippets for the <literal role="extension">.rkh</literal> file in the same file. You would simply <command><include></command> the file there as well, and <command><insert></command> the relevant snippet:
</para>
<programlisting>
<!-- This is a file called "common_snippets.xml" -->
<document>
<snippet id="common_options">
<spinbox id="something" [...]/>
[...]
</snippet>
<snippet id="common_note">
<text>An important note for this type of plugin</text>
</snippet>
<snippet id="common_help">
<setting id="something">This does something</setting>
[...]
</snippet>
</document>
</programlisting>
<programlisting>
<!-- This is the .xml file of the plugin -->
<document>
<snippets>
<!-- Import the common snippets -->
<include file="common_snippets.xml"/>
</snippets>
<dialog label="test2">
<insert snippet="common_note"/>
<spinbox id="something_plugin_specific" [...] />
<insert snippet="common_options"/>
</dialog>
</document>
</programlisting>
<para>
Similar to <link linkend="include_js">inclusion in JS</link>, the reverse approach is often even more useful:
</para>
<programlisting>
<!-- This is a file called "common_layout.xml" -->
<document>
<column>
<insert snippet="note">
[...]
<insert snippet="plugin_parameters">
</column>
[...]
</document>
</programlisting>
<programlisting>
<!-- This is the .xml file of the plugin -->
<document>
<snippets>
<snippet id="note">
<text>The note used for this specific plugin</text>
</snippet>
<snippet id="plugin_parameters">
<frame label="Parameters specific to this plugin">
[...]
</frame>
</snippet>
</snippets>
<dialog label="test3">
<include file="common_layout.xml"/>
</dialog>
</document>
</programlisting>
<para>
Finally, it is also possible to <command><insert></command> snippets into other snippets, provided that: a) there is only one level of nesting, and b) the <command><snippets></command> section is placed at the top of the file (before a nested snippet is inserted); this is because <command><insert></command> statements are resolved from top to bottom.
</para>
</sect1>
<sect1 id="include_snippets_vs_embedding">
<title><include> and <snippets> vs. <embed></title>
<para>
At first glance, <command><include></command> and <command><snippets></command> provides functionality rather similar to <link linkend="embedding">embedding</link>: It allows to reuse some portions of code across plugins. So what is the difference between these approaches, and when should you use which?
</para>
<para>
The key difference between these concepts is that embeddable plugins are a more tight bundle. They combine a complete &GUI;, code to generate &R; code from this, and a help page. In contrast, include and insert allow much more fine grained control, but at the price of less modularity.
</para>
<para>
That is, a plugin embedding another plugin will typically not need to know much about the internal details of the embedded plugin. A prime example is the plot_options plugin. Plugins wishing to embed this do not necessarily need to know about all the options provided, or how they are provided. This is a good thing, as otherwise a change in the plot_options plugin might make it necessary to adjust all plugins embedding this (a lot). In contrast, include and insert really exposes all the internal details, and plugins using this will -- for example -- need to know the exact ids and perhaps even the type of the elements used.
</para>
<para>
Hence the rule of thumb is this: include and insert are great if the relevant options are only needed for a clearly limited group of plugins. Embedded plugins are better, if the group of plugins it may be useful to is not clearly defined, and if the functionality can easily be modularized. Another rule of thumb: If you can put the common portions into a single <quote>chunk</quote>, then do so, and use embedding. If you need lots of small snippets to define the common portions -- well, use <command><snippets></command>. A final way to look at it: If all plugins provide <emphasis>highly</emphasis> similar functionality, includes and inserts are probably a good idea. If they merely share one or two common <quote>modules</quote>, embedding is likely better.
</para>
</sect1>
</chapter>
<chapter id="specialized_plugins">
<title>Concepts for use in specialized plugins</title>
<para>
This chapter contains information on some topics that are useful only to certain classes of plugins.
</para>
<sect1 id="specialized_plugins_plots">
<title>Plugins that produce a plot</title>
<para>
Creating a plot from a plugin is easy to do. However, there are a few subtle gotchas to avoid, and also some great generic functionality that you should be aware of. This section shows you the basic concepts, and concludes with a canonical example that you should follow whenever creating plot plugins.
</para>
<sect2 id="rk_graph_on">
<title>Drawing a plot to the output window</title>
<para>
In order to draw a plot to the output window, use <function>rk.graph.on()</function> directly before creating the plot, and
<function>rk.graph.off()</function>, directly afterwards. This is similar to ⪚ calling <function>postscript()</function> and
<function>dev.off()</function> in a regular &R; session.
</para>
<para>
Importantly, however, you must <emphasis>always</emphasis> call <function>rk.graph.off()</function> after calling <function>rk.graph.on()</function>. Otherwise the output file will be left in a broken state. To ensure <function>rk.graph.off()</function> really gets called, you should wrap <emphasis>all</emphasis> &R; commands between the two calls in
<function>try()</function> statement. Never heard of that? Do not worry, it is easy. All you need to do is follow the pattern shown in
<link linkend="plot_plugin_example">example</link>, below.
</para>
</sect2>
<sect2 id="preview_plots">
<title>Adding preview functionality</title>
<note><para>This section discusses adding preview functionality to plugins producing plots. There are separate sections on <link linkend="preview_output">previews of (&HTML;) output</link>, <link linkend="preview_data">previews of (imported) data</link>, and <link linkend="preview_custom">custom previews</link>. However, it is recommended that you read this section first, as the approach is similar in each case.</para></note>
<para>
A very useful feature for all plugins generating a plot/graph is to provide an automatically updating preview. To do so, you will need two things: Adding a <command><preview></command> check box to your <link linkend="mainxml">&GUI; definition</link>, and adjusting the <link linkend="jstemplate">generated code</link> for the preview.
</para>
<para>
Adding a <command><preview></command> check box is simple. Just place the following somewhere in your &GUI;. It will take care of all the behind-the-scenes magic of creating a preview device, updating the preview whenever the setting have changed, &etc; Example:
</para>
<note><para>Starting with version 0.6.5 of &rkward; <command><preview></command> preview elements are special-cased in plugin dialogs (not wizards): They will be placed in the button-column, irrespective of where exactly they are defined in the UI. It is still a good idea to define them at a sensible place in the layout, for backwards compatibility.
</para></note>
<programlisting>
<document>
[...]
<dialog [...]>
[...]
<preview id="preview"/>
[...]
</dialog>
[...]
</document>
</programlisting>
<para>
And that is it for the &GUI; definition.
</para>
<para>
Adjusting the JS template is a little more work. You will have to create a new function called <function>preview()</function> in addition to the <function>preprocess()</function>, <function>calculate()</function>, &etc; functions. This function should generate the code needed to produce the plot, and only that. Esp. no printing of headers, <function>rk.graphics.on()</function>, or similar calls. See the <link linkend="plot_plugin_example">example</link>, below for the typical pattern that you will use.
</para>
</sect2>
<sect2 id="plot_options">
<title>Generic plot options</title>
<para>
You will have noticed that most plotting plugins in &rkward; provide a wide range of generic options ⪚ for customizing axis titles or figure margins. Adding these options to your plugin is easy. They are provided by an <link linkend="embedding">embeddable</link> plugin called <command>rkward::plot_options</command>. Embed this in your plugin UI like this:
</para>
<programlisting>
<document>
[...]
<logic [...]>
<connect client="plotoptions.xvar" governor="x.available"/>
<set id="plotoptions.allow_type" to="true"/>
<set id="plotoptions.allow_ylim" to="true"/>
<set id="plotoptions.allow_xlim" to="false"/>
<set id="plotoptions.allow_log" to="false"/>
<set id="plotoptions.allow_grid" to="true"/>
</logic>
<dialog [...]>
[...]
<embed id="plotoptions" component="rkward::plot_options" as_button="true" label="Plot Options"/>
[...]
</dialog>
[...]
</document>
</programlisting>
<para>
This will add a button to your UI to bring up a window with plot options. The logic section is just an example. It allows you some control over the plot options plugin. Read more in the plot_options plugin's help page (linked from the help page of any plugin providing the generic options).
</para>
<para>
Next you need to make sure that the code corresponding to your plot options is added to the generated code for your plot. To do so,
fetch the properties <command>code.preprocess</command>, <command>code.printout</command>, and <command>code.calculate</command> from the embedded plot options plugin, and insert them into your code as shown in the <link linkend="plot_plugin_example">example</link>, below.
</para>
</sect2>
<sect2 id="plot_plugin_example">
<title>A canonical example</title>
<para>
Here is an example .JS file that you should use as a template, whenever you create a plotting plugin:
</para>
<programlisting>
function preprocess () {
// the "somepackage" is needed to create the plot
echo ("require (somepackage)\n");
}
function preview () {
// we call all stages of the general code. Only the printout () function needs to be called slightly different for the plot preview
preprocess ();
// calculate (); // in this example, the plugin has no calculate () function.
printout (true); // in this case, 'true' means: Create the plot, but not any headers or other output.
}
function printout (is_preview) {
// If "is_preview" is set to false, it generates the full code, including headers.
// If "is_preview" is set to true, only the essentials will be generated.
if (!is_preview) {
echo ('rk.header (' + i18n ("An example plot") + ')\n\n');
echo ('rk.graph.on ()\n');
}
// only the following section will be generated for is_preview==true
// remember: everything between rk.graph.on() and rk.graph.off() should be wrapped inside a try() statement:
echo ('try ({\n');
// insert any option-setting code that should be run before the actual plotting commands.
// The code itself is provided by the embedded plot options plugin. printIndentedUnlessEmpty() takes care of pretty formatting.
printIndentedUnlessEmpty ('\t', getString ("plotoptions.code.preprocess"), '', '\n');
// create the actual plot. plotoptions.code.printout provides the part of the generic plot options
// that have to be added to the plotting call, itself.
echo ('plot (5, 5' + getString ("plotoptions.code.printout") + ')\n');
// insert any option-setting code that should be run after the actual plot.
printIndentedUnlessEmpty ('\t', getString ("plotoptions.code.calculate"), '\n');
echo ('})'\n); // the closure of the try() statement
if (!is_preview) {
echo ('rk.graph.off ()\n');
}
}
</programlisting>
</sect2>
</sect1>
<sect1>
<title>Previews for data, output and other results</title>
<sect2 id="preview_output">
<title>Previews of (HTML) output</title>
<note><para>This section discusses adding preview functionality to plugins creating output / HTML printouts. It is recommended that you read the separate section on <link linkend="preview_plots">plot previews</link>, before this section.</para></note>
<para>
Creating a preview of HTML output is almost the same procedure as creating a plot preview. In this case, simply make sure that the <command>preview()</command> generates the relevant
<command>rk.print()/rk.results()</command> commands. It is generally a good idea to omit the header statements in the preview, however. Here is a stripped-down example:
</para>
<programlisting>
<!-- In the plugin's XML file -->>
<dialog label="Import CSV data" >
<browser id="file" type="file" label="File name"/>
<!-- [...] -->>
<preview id="preview" mode="output"/>
</dialog>>
</programlisting>
<para>
Note the specification of <parameter>mode="output"</parameter> in the <command><preview></command> element.
</para>
<programlisting>
// In the plugin's JS file
function preview () {
// generates the code used for preview
printout (true);
}
function printout (is_preview) {
// only generates a header if is_preview==false
if (!is_preview) {
new Header ("This is a caption").print ();
}
echo ('rk.print (result)');
}
</programlisting>
</sect2>
<sect2 id="preview_data">
<title>Previews of (imported) data</title>
<note><para>This section discusses adding preview functionality to plugins creating (importing) data. It is recommended that you read the separate section on <link linkend="preview_plots">plot previews</link>, before this section.</para></note>
<para>
Creating a preview of imported data (any type of data that <command>rk.edit()</command> can handle), is very similar to creating a <link linkend="preview_plots">plot preview</link>. The following stripped down example should help illustrate how to create a data preview:
</para>
<programlisting>
<!-- In the plugin's XML file -->>
<dialog label="Import CSV data" >
<browser id="file" type="file" label="File name"/>
<!-- [...] -->>
<preview id="preview" active="true" mode="data"/>
</dialog>>
</programlisting>
<para>
Note that the <command><preview></command> element specifies <parameter>mode="data"</parameter> this time. <parameter>active="true"</parameter> simply makes the preview active by
default.
</para>
<programlisting>
// In the plugin's JS file
function preview () {
// generates the code used for preview
calculate (true);
}
function calculate (is_preview) {
echo ('imported <- read.csv (file="' + getString ("file") /* [+ options] */);
if (is_preview) {
echo ('preview_data <- imported\n');
} else {
echo ('.GlobalEnv$' + getString ("name") + ' >- imported\n');
}
}
function printout () {
// [...]
}
</programlisting>
<para>
Again, the <command>preview()</command> function generates almost the same &R; code as the <command>calculate()</command> function, so we create a helper function <command>doCalcuate()</command> to factor out the common parts. The most important thing to note is that you will have to assign the imported data to a object called
<parameter>preview_data</parameter> (inside the current - local - environment). <emphasis>Everything else will happen automatically</emphasis> (roughly speaking, &rkward; will call <command>rk.edit(preview_data)</command>, wrapped inside a call to <command>.rk.with.window.hints()</command>).
</para>
<note><para>
While previews are a great feature, they do consume resources. In the case of data previews, there may be cases, where previews can cause significant performance issues. This could be
for importing huge datasets (which are just too large to be opened for editing in &rkward;'s editor window), but also "normal" datasets could be mis-imported, creating a huge number of rows or columns. <emphasis>It is very much recommended that you limit the <parameter>preview_data</parameter></emphasis> to a dimension that provides a useful preview, without the danger of
creating noticable performance issues (⪚ 50 rows by 50 columns should be more than enough in most cases).
</para></note>
</sect2>
<sect2 id="preview_custom">
<title>Custom previews</title>
<para>
The <command><preview></command> element can be used to create previews for any type of "document" window that can be attached to &rkward;'s workplace. In addition to <link linkend="preview_plots">plots</link> and <link linkend="preview_data">data windows</link>, this includes HTML files, &R; scripts, and object summary windows. For the latter ones, you will have to use <command><preview mode="custom"></command>.
</para>
<para>
If you have read the sections describing plot preview and data previews, you should have a general idea on the procedure, but "custom" previews require slightly more manual work behind the scenes. The most important &R; function to look at is <command>rk.assign.preview.data()</command>, here. The following short listing shows what your generated (preview) &R; code could look like for a plugin creating a text file output:
</para>
<programlisting>
## To be generated in the preview() code section of a plugin
pdata <- rk.get.preview.data("SOMEID")
if (is.null (pdata)) {
outfile <- rk.get.tempfile.name(prefix="preview", extension=".txt")
pdata <- list(filename=outfile, on.delete=function (id) {
unlink(rk.get.preview.data(id)$filename)
})
rk.assign.preview.data("SOMEID", pdata)
}
try ({
cat ("This is a test", pdata$filename)
rk.edit.files(file=pdata$filename)
})
</programlisting>
<para>
Here you should get the value <parameter>SOMEID</parameter> from the <parameter>id</parameter> property of the <command><preview></command>-element. I.e. using <command>getString ("preview.id")</command> in the plugin's .js file.
</para>
</sect2>
</sect1>
<sect1 id="contextualized_plugins">
<title>Context-dependent plugins</title>
<para>
So far we have assumed, all plugins are always meaningful, and all placed in the main menu. However, some plugins are meaningful only (or additionally) in a certain context. For instance a plugin to export the contents of an &R; X11 graphics device is obviously most useful, when placed in the menu of an X11 device, not in the main menubar. Also, such a plugin should know about the device number that it should operate on, without having to ask the user about this.
</para>
<para>
We call such plugins context-dependent. Correspondingly, in the <link linkend="pluginmap">&pluginmap; file</link>, they are not (or not only) placed in the main <command><hierarchy></command> but rather into a <command><context></command> element. So far only two different contexts are supported (more will come later): x11 and file import. We will deal with those in turn. Even if you are only interested in the import context, please also read the section on the x11 context, as this is slightly more elaborate.
</para>
<sect2 id="context_x11">
<title>X11 device context</title>
<para>
To use a plugin in the context of an x11 device - that is place it in the menubar of the window you get when you call <function>x11()</function> in the console, first declare it as usual in the <link linkend="pluginmap">&pluginmap; file</link>:
</para>
<programlisting>
<document [...]>
<components>
[...]
<component id="my_x11_plugin" file="my_x11_plugin.xml" label="An X11 context plugin"/>
[...]
</components>
</programlisting>
<para>
However, you do not need to define it in the hierarchy (you can, if it is also meaningful as a top-level plugin):
</para>
<programlisting>
<hierarchy>
[...]
</hierarchy>
</programlisting>
<para>
Instead, add a definition of the "x11" context, and add it to the menus there:
</para>
<programlisting>
<context id="x11">
[...]
<menu id="edit">
[...]
<entry id="my_x11_plugin"/>
</menu>
</context>
</document>
</programlisting>
<para>
In the <link linkend="logic">logic section of the plugin xml</link>, you can now declare two <command><external></command> properties: <parameter>devnum</parameter> and <parameter>context</parameter>. <parameter>context</parameter> (if declared) will be set to <replaceable>"x11"</replaceable> when the plugin is invoked in this context. <parameter>devnum</parameter> will be set to the number of the graphics device to operate on. And that is all.
</para>
</sect2>
<sect2 id="context_import">
<title>Import data context</title>
<para>
Before reading this section, please make sure to read the section on the <link linkend="context_x11">X11 device context</link>, as that explains the basic concepts.
</para>
<para>
The <replaceable>"import"</replaceable> context is used to declare import file filter plugins. You simply place those in a context with <parameter>id=</parameter><replaceable>"import"</replaceable> in the &pluginmap; file. However, there is one additional twist when declaring these plugins: In order to offer a unified file selection dialog for all supported file types, you need to declare one additional bit of information on your component:
</para>
<programlisting>
<document [...]>
<components>
[...]
<component id="my_xyz_import_plugin" file="my_xyz_import_plugin.xml" label="Import XYZ files">
<attribute id="format" value="*.xyz *.zyx" label="XYZ data files"/>
</component>
[...]
</components>
<hierarchy>
[...]
</hierarchy>
<context id="import">
[...]
<menu id="import">
[...]
<entry id="my_xyz_import_plugin"/>
</menu>
</context>
[...]
</document>
</programlisting>
<para>
The attribute line simply says, that the associate filename extensions for XYZ files are <literal role="extension">*.xyz</literal> or <literal role="extension">*.zyx</literal>, and that the filter should be labeled <quote>XYZ data files</quote> in the file selection dialog.
</para>
<para>
You can declare two <command><external></command> properties in your plugin. <parameter>filename</parameter> will be set to the selected file name, and <parameter>context</parameter> will be set to <replaceable>"import"</replaceable>.
</para>
</sect2>
</sect1>
<sect1 id="querying_r_for_info">
<title>Querying &R; for information</title>
<para>In some cases, you may want to fetch further information from &R;, to be presented in your plugin's UI. For instance, you may want to offer a selection of the levels of a factor that the user
has selected for analysis. Since version 0.6.2 of &rkward; it is possible to do so. Before we start, it is important that you are aware of some caveats:</para>
<para>R Code run from inside the plugin's UI logic is evaluated in R's event loop, meaning they can be run <emphasis>while</emphasis> other computations are running. This is to make sure your plugin's UI will be usable, even while &R; is busy doing other things. However, this makes it really important, that your code does not have side effects. In particular:</para>
<itemizedlist>
<listitem><para>Do <emphasis>not</emphasis> make any assignments in .GlobalEnv or any other non-local environment.</para></listitem>
<listitem><para>Do <emphasis>not</emphasis> print anything to the output file.</para></listitem>
<listitem><para>Do <emphasis>not</emphasis> plot anything on-screen.</para></listitem>
<listitem><para>In general, do <emphasis>not</emphasis> do anything that has side-effects. Your code may <emphasis>read in information</emphasis>, not "<emphasis>do</emphasis>" anything.</para></listitem>
</itemizedlist>
<para>With this in mind, here is the general pattern. You will use this inside a <link linkend="logic_scripted">scripted UI logic</link> section:</para>
<programlisting>
<script><![CDATA[
last_command_id = -1;
gui.addChangeCommand ("variable", "update ()");
update = function () {
gui.setValue ("selector.enabled", 0);
variable = gui.getValue ("variable");
if (variable == "") return;
last_command_id = doRCommand ('levels (' + variable + ')', "commandFinished");
}
commandFinished = function (result, id) {
if (id != last_command_id) return; // another result is about to arrive
if (typeof (result) == "undefined") {
gui.setListValue ("selector.available", Array ("ERROR"));
return;
}
gui.setValue ("selector.enabled", 1);
gui.setListValue ("selector.available", result);
}
]]></script>
</programlisting>
<para>Here, <parameter>variable</parameter> is a property holding an object name (⪚ inside a <command><varslot></command>). Whenever that changes, you will want to update the display
of levels inside the <command><valueselector></command>, named <parameter>selector</parameter>. The key function here is <command>doRCommand()</command>, taking as first parameter
the command string to run, and as second parameter the name of a function to call, when the command has finished. Note that the command is running asynchronously, and this makes things
a bit more complex. For one thing you want to make sure, that your <command><valueselector></command> remains disabled, while it does not contain up-to-date information. Another
thing is that you could potentially have queued more than one command, before you get the first results. This is why every command is given an "id", and we store that in <parameter>last_command_id</parameter> for later reference.</para>
<para>When the command is done, the specified callback is called (<parameter>commandFinished</parameter>, in this case) with two parameters: The result itself, and the id of the corresponding
command. The result will be of a type resembling the representation in &R;, &ie; a numeric Array, if the result is numeric, &etc; It can even be an &R; <command>list()</command>, but in this case
it will be represented as a JS <command>Array()</command> without names.</para>
<para>Note that even this example is somewhat simplified. In reality you should take additional precautions, ⪚ to avoid putting an extreme amount of levels into the selector. The good news
is that probably you do not have to do all this yourself. The above example is taken from the <command>rkward::level_select</command> plugin, for instance, which you can simply <link linkend="embedding">embed</link> in your own
plugin. This even allows you to specify a different expression to run in place of <command>levels()</command>.</para>
</sect1>
<sect1 id="current_object">
<title>Referencing the current object or current file</title>
<para>
For many plugins it is desirable to work on the <quote>current</quote> object. For instance a <quote>sort</quote> plugin could pre-select the data.frame that is currently being edited for sorting. The name of the current object is available to plugins as a pre-defined property called <parameter>current_object</parameter>. You can connect to this property in the usual way. If no object is current, the property equates to an empty string. Similarly, the &URL; of the current script file
is accessible as a pre-defined property called <parameter>current_filename</parameter>. That property is empty if no script file is currently being edited, or the script file has not been saved, yet.
</para>
<para>
Currently the <parameter>current_object</parameter> can only be of class <function>data.frame</function>, but please do not rely on this, since this will be extended to other types of data in the future. If you are interested in <function>data.frame</function> objects, only, connect to the <parameter>current_dataframe</parameter> property, instead. Alternatively, you can enforce type requirements by using appropriate constraints on your <command><varslot></command>s, or by using <link linkend="logic_scripted">&GUI; logic scripting</link>.
</para>
</sect1>
<sect1 id="optionset">
<title>Repeating (a set of) options</title>
<para>
Sometimes you want to repeat a set of options for an arbitrary number of items. E.g. suppose you want to implement a plugin for sorting a data.frame. You may want to allow for sorting by an arbitrary number of columns (in case of ties among the first column(s)). This could simply be realized by allowing the user to select multiple variables in a <command><varslot></command> with <parameter>multi="true"</parameter>. But if you want to extend this, ⪚ allowing the user to specify for each variable whether it should be converted to character / numeric, or whether sorting should be ascending or descending, you need more flexibility. Other examples would be plotting multiple lines in one plot (allowing to select object, line style, line color, &etc; for each line), or specifying a mapping for recoding from a set of old values to new values.
</para>
<para>
Enter the <command><optionset></command>. Let's look at a simple example, first:
</para>
<programlisting>
<dialog [...]>
[...]
<optionset id="set" min_rows="1">
<content>
<row>
<input id="firstname" label="Given name(s)" size="small">
<input id="lastname" label="Family name" size="small">
<radio id="gender" label="Gender">
<optioncolumn label="Male" value="m"/>
<optioncolumn label="Female" value="f"/>
</radio>
</row>
</content>
<optioncolumn id="firstnames" label="Given name(s)" connect="firstname.text">
<optioncolumn id="lastnames" label="Family name" connect="lastname.text">
<optioncolumn id="gender" connect="gender.string">
</optionset>
[...]
</dialog>
</programlisting>
<para>
Here, we created a UI for specifying a number of persons (⪚ authors). The UI requires at least one entry (<parameter>min_rows="1"</parameter>). Inside the <command><optionset></command>-element, we begin by specifying the
<command><content></command>, &ie; those elements that belong to the option set. You will be familiar with most elements
inside the <command><content></command>.
</para><para>
Next we specify the variables of interest that we will want to read from the option set in our JS file. As we will be dealing with
an arbitrary number of items, we cannot just read <function>getString ("firstname")</function> in JS. Rather, for each value of
interest, we specify an <command><optioncolumn></command>. For the first optioncolumn in the example, <command><connect="firstname.text"></command> means that the content of the <command><input></command>
element "firstname" is read for each item. <command><optioncolumn></command>s for which a <parameter>label</parameter> is given,
will be shown in the display, in a column by that label. In JS, we can now fetch the first names for all authors using <function>getList("set.firstname")</function>, <function>getList("set.lastnames")</function> for the family
names, and <function>getList("set.gender")</function> for an array of "m"/"f" strings.
</para>
<para>
Note that there are no restrictions on what you can place inside an <command><optionset></command>. You can even use <link linkend="embedding">embedded</link> components. Just as with any other element, all you have to do is to collect the output
variables of interest in an <command><optioncolumn></command>-specification. In the case of embedded plugins, this is often a section of the "code" property. E.g.:
</para>
<programlisting>
<dialog [...]>
[...]
<optionset id="set" min_rows="1">
<content>
[...]
<embed id="color" component="rkward::color_chooser" label="Color"/>
</content>
[...]
<optioncolumn id="color_params" connect="color.code.printout">
</optionset>
[...]
</dialog>
</programlisting>
<para>
Of course you can also use <link linkend="logic">UI logic</link> inside an optionset. There are two options for doing this: You can do so by making connection (or scripting) in the main <command><logic></command> section of your plugin, as usual. However, you will access the UI elements in the contents region as (⪚) "set.contents.firstname.XYZ". Note the prefix "set" (the <parameter>id</parameter> you have assigned to the set and "contents"). Alternatively, you can add a separate <command><logic></command> section as a child element of your <command><optionset></command>. In this case, <parameter>id</parameter>s will be addressed relative to the contents region, ⪚ "firstname.XYZ". Only the <command><script></command>-element is not allowed in the logic section of an optionset. If you want to use scripting,
you will have to utilize the plugin's main <command><logic></command> section.
</para>
<note>
<para>
When scripting logic in an optionset, all you can do is access the <emphasis>current</emphasis> content region. Thus, typically,
it is only meaningful to connect elements inside the contents region to each other. Connecting a property outside the <command><optionset></command> to a property inside the content region, may be useful for initialization. However,
modifying the contents region after initialization will <emphasis>not</emphasis> apply to items that the user has already
defined. Only to the currently selected item in the set.
</para>
</note>
<sect2 id="optionset_driven">
<title>"Driven" optionsets</title>
<para>
So far we have considered an <command><optionset></command> that provides buttons for adding / removing items. However,
in some cases, it is much more natural to select items outside the <command><optionset></command>, and only provide
options for customizing some aspects of each item in an <command><optionset></command>. E.g. suppose you want to allow
the user to plot several objects inside one plot. For each object, the user should be able to specify line color.
You <emphasis>could</emphasis> solve this by placing a <command><varselector></command> and
<command><varslot></command> inside the <command><content></command> area, allowing the user to select one item
at a time. However, it will mean much less clicks for the user, if you use a <command><varslot multi="true"></command>
<emphasis>outside</emphasis> the <command><optionset></command>, instead. Then you will connect this selection of objects
to a so-called "driven" optionset. Here is how:
</para>
<programlisting>
<dialog [...]>
<logic>
<connect client="set.vars" governor="vars.available"/>
<connect client="set.varnames" governor="vars.available.shortname"/>
</logic>
[...]
<varselector id="varsel"/>
<varslot id="vars" label="Objects to plot"/>
<optionset id="set" keycolumn="var">
<content>
[...]
<embed id="color" component="rkward::color_chooser" label="Line color"/>
</content>
[...]
<optioncolumn id="vars" external="true">
<optioncolumn id="varnames" external="true" label="Variable">
<optioncolumn id="color_params" connect="color.code.printout">
</optionset>
[...]
</dialog>
</programlisting>
<para>
We will start looking at the example at the bottom. You will note that two <command><optioncolumn></command> specifications have
<parameter>external="true"</parameter>. This tells &rkward; that these are controlled from outside the <command><optionset></command>. Here, the sole purpose of the "varnames"-optioncolumn is to provide easy-to-read labels in the
optionset display (it is connected to the "shortname" modifier of the property holding the selected
objects). The purpose of the "vars"-optioncolumn is to serve as the "key" column, as specified by
<command><optionset keycolumn="vars"...></command>. This means that for each entry in this list, the set will offer
one set of options, and options are logically tied to these entries. This column is connected to the property holding the
selected objects in the <command><varslot></command>. That is for each object that is selected there, the <command><optionset></command> will allow to specify line color.
</para>
<note>
<para>
External column can also be <parameter>connect</parameter>ed to properties inside the
<command><content></command> region. However, it is important to note that optioncolumns declared
<parameter>external="true"</parameter> should never be modified from inside the <command><optionset></command>, and
optioncolumns declared <parameter>external="false"</parameter> (the default) should never be modified from outside the
<command><optionset></command>.
</para>
</note>
</sect2>
<sect2 id="optionset_alternatives">
<title>Alternatives: When not to use optionsets</title>
<para>
Optionsets are a powerful tool, but they can sometimes do more harm than good, as they add considerable complexity, both
from the perspective of a plugin developer, and from the perspective of a user. Thus, think twice, when using them. Here is
some advice:
</para>
<itemizedlist>
<listitem><para>For some simple cases, the <command><matrix></command> element may provide a useful lightweight alternative.</para></listitem>
<listitem><para>Do not make your plugin do too much. We gave the example of using an optionset for a plugin to
draw several lines within one plot. But in general it is not a good idea to create a plugin that will produce individual
plots for each item in an optionset. Rather make the plugin produce one plot, and the user can call it multiple times.
</para></listitem>
<listitem><para>If you do not expect more than two or three items in a set, consider repeating the options, manually,
instead.</para></listitem>
</itemizedlist>
</sect2>
</sect1>
</chapter>
<chapter id="chapter_dependencies">
<title>Handling dependencies and compatibility issues</title>
<sect1 id="sect_dependencies_rkward_version"><title>&rkward; version compatibility</title>
<para>We do our best to make sure that plugins developed for an old version of &rkward; will remain functional in later versions of &rkward;. However, the reverse is not always true as new features are been added. Since not all users are running the latest version of &rkward;, this means your plugin may not work for everybody.</para>
<para>When you are aware of such compatibility issues, you should make sure to document this fact in your &pluginmap; file, using the <command><dependencies></command> element. The <command><dependencies></command> can either be specified as a direct child of the &pluginmap;'s <document> element, or as a child element of individual <command><component></command> definitions. In the first case, the dependencies apply to <emphasis>all</emphasis> plugins in the map. In the latter case only to the individual <command><component></command>(s). You can also mix top "global" and "specific" dependencies. In this case the "global" dependencies are added to those of the individual component.</para>
<para>Let's look at a small example:</para>
<programlisting>
<document ...>
<dependencies rkward_min_version="0.5.0c" />
<components ...>
<component id="myplugin" file="reduced_version_of_myplugin.xml" ...>
<dependencies rkward_max_version="0.6.0z" />
</component>
<component id="myplugin" file="fancy_version_of_myplugin.xml" ...>
<dependencies rkward_min_version="0.6.1" />
</component>
...
x </components ...>
</document>
</programlisting>
<para>In this example, all plugins are known to require at least version 0.5.0c of &rkward;. One plugin, with <replaceable>id="myplugin"</replaceable> is provided in two alternative variants. The first, stripped down, version will be used for &rkward; versions before 0.6.1. The latter utilizes features that are new in &rkward; 0.6.1, and will only be used from &rkward; 0.6.1 onwards.</para>
<para>Providing alternative variants like this is a very user friendly way to make use of new features, while still keeping support for earlier versions of &rkward;. Alternative versions should share the same <parameter>id</parameter> (warnings will be produced, otherwise), and may only be defined <emphasis>within the same</emphasis> &pluginmap; file.</para>
<para>Plugin which are not compatible with the running version of &rkward;, and which do not come with an alternative version will be ignored with a warning.</para>
<note><para>Actually &rkward; 0.6.1 is the first version to interpret dependencies - and to report dependency errors - at all. Thus, contrary to what the example may suggest, specifying any earlier versions in the dependencies will not have any direct effect (but may still be a good idea for documentation purposes).</para></note>
<para><emphasis>Sometimes</emphasis> it will even be possible to handle version incompatibility issues <emphasis>inside</emphasis> a single &pluginmap; file, using the <command><dependency_check></command> element, described in the following section.</para>
</sect1>
<sect1 id="sect_dependencies_r_version"><title>&R; version compatibility</title>
<para>Similar to <parameter>rkward_min_version</parameter> and <parameter>rkward_max_version</parameter>, the <command><dependencies></command> element allows specification of the attributes <parameter>R_min_version</parameter> and <parameter>R_max_version</parameter>. However, there are the following differences:</para>
<itemizedlist>
<listitem><para>Plugins which fail to meet the &R; version requirement are <emphasis>not</emphasis> currently skipped when reading a &pluginmap; file. The user can still call the plugin, and will not see any immediate warning (in future versions, a warning message will probably be shown)</para></listitem>
<listitem><para>In consequence it is also <emphasis>not</emphasis> possible to define alternative versions of a plugin depending on the running version of &R;.</para></listitem>
<listitem><para>However, it is often easy to achieve backwards compatibility as shown below. If you are aware of &R; compatibility issues, please consider using this method, instead of defining a dependency on a particular version of &R;.</para></listitem>
</itemizedlist>
<para>In many cases, it is easily possible to provide reduced functionality, if a certain feature is not available in the running version of &R;. Consider the following short example of a plugin <literal role="extension">.xml</literal> file:</para>
<programlisting>
<dialog [...]>
<logic>
<dependency_check id="ris210" R_min_version="2.10.0"/>
<connect client="compression.xz.enabled" governor="ris210"/>
</logic>
[...]
<radio id="compression" label="Compression method">
<option label="None" value="">
<option label="gzip" value="gzip">
<option id="xz" label="xz" value="xz">
</radio>
[...]
</dialog>
</programlisting>
<para>In this example the compression option "xz" will simply be disabled when the &R; runtime version is older than 2.10.0 (which did not support xz compression). The <command><dependency_check></command> element supports the same attributes as the <command><dependencies></command> element in &pluginmap; files. It creates a boolean property, which is true, if the specified dependencies are met, false otherwise.</para>
</sect1>
<sect1 id="sect_dependencies_r_packages"><title>Dependencies on &R; packages</title>
<para>Dependencies on specific &R; packages can be defined, but as of &rkward; 0.6.1, these dependencies are neither checked, nor installed / loaded, automatically. They are shown in the plugin help files, however. Here is an example definition:</para>
<programlisting>
<dependencies>
<package
name="heisenberg"
min_version="0.11-2"
repository="http://rforge.r-project.org"
/>
</dependencies>
</programlisting>
<note><para>Always make sure to add appropriate <function>require()</function> calls, if you plugin needs certain packages to be loaded.</para></note>
<note><para>If you <link linkend="external_plugins">distribute your &pluginmap; as an &R; package</link>, and all plugins depend on a particular package, then you should define that dependency on the &R; package level. Defining dependencies to &R; packages on the level of the &rkward; &pluginmap; is most useful, if only some of your plugins need the dependency, the dependency is not available from CRAN, or your &pluginmap; is not distributed as an &R; package.</para></note>
</sect1>
<sect1 id="sect_dependencies_other_pluginmaps"><title>Dependencies on other &rkward; &pluginmap;s</title>
<para>If your plugins depend on plugins defined in another &pluginmap; (that is <emphasis>not</emphasis> part of your package) you can define this dependency like this:</para>
<programlisting>
<dependencies>
<pluginmap
name="heisenberg_plugins"
url="http://eternalwondermaths.example.org/hsb"
/>
</dependencies>
</programlisting>
<para>Currently will neither load, nor install, nor even warn about missing &pluginmap;s, but at least information on dependencies (and where to obtain them) will be shown on the plugin's help page. You do not have to (and you should not) declare dependencies on &pluginmap;s that are shipped with the official &rkward; distribution, or on &pluginmap;s that are inside your own package. Further, if a required &pluginmap; is <link linkend="external_plugins">distributed as an &R; package</link>, declare a dependency of the package (as shown in the previous section), rather than on the map.</para>
<para>To make sure that required &pluginmap;s are actually loaded, use the <command><require></command>-tag (refer to the <link linkend="pluginmapelements">reference</link> for details).</para>
</sect1>
<sect1 id="sect_dependencies_example"><title>An example</title>
<para>To clarify how dependency definitions can be mixed, here is a combined example:</para>
<programlisting>
<document ...>
<dependencies rkward_min_version="0.5.0c">
<package
name="heisenberg"
min_version="0.11-2"
repository="http://rforge.r-project.org"
/>
<package
name="DreamsOfPi"
min_version="0.2"
/>
<pluginmap
name="heisenberg_plugins"
url="http://eternalwondermaths.example.org/hsb"
/>
<dependencies>
<require map="heisenberg::heisenberg_plugins"/>
<components ...>
<component id="myplugin" file="reduced_version_of_myplugin.xml" ...>
<dependencies rkward_max_version="0.6.0z" />
</component>
<component id="myplugin" file="fancy_version_of_myplugin.xml" ...>
<dependencies rkward_min_version="0.6.1" />
</component>
...
x </components ...>
</document>
</programlisting>
</sect1>
</chapter>
<chapter id="i18n">
<title>Plugin translations</title>
<para>
So far we have used a few concepts regarding translations or "i18n" (short for "internationalization", which has 18 characters between i and n) in passing. In this chapter we
give a more in-depth account of what i18n functionally for &rkward; plugins. For the most part you will <emphasis>not</emphasis> need all of this in your plugins. However,
it may be a good idea to read over this chapter in full, as understanding these concepts should help you creating plugins that are fully translatable, and that allow for a high
quality of translations.
</para>
<sect1 id="i18n_general"><title>General considerations</title>
<para>
One important point to understand about software translations, in contrast to translations of other text materials, is that translators will often have a rather hard
time getting a complete picture of <emphasis>what</emphasis> they are translating. Software translations are necessarily based on rather short fragments of text: Every
label you give to an <command><option></command> in a <command><radio></command>, every string that you mark for translation in an
<command>i18n()</command>-function call, will form a separate "translation unit". In essence, each such fragment will be presented to the translator in isolation. Well,
not complete isolation, as we do try to provide translator with as much meaningful context as can be extracted, automatically. But at some points translators will need
additional context to make sense of a string, especially where strings are short.
</para>
</sect1>
<sect1 id="i18n_xml"><title>i18n in &rkward;'s xml files</title>
<para>
For &rkward;'s &XML; files, i18n will mostly just work. If you are writing your own <command>.pluginmap</command> (⪚ for an <link linkend="external_plugins">external plugin</link>),
you will have to specify a <replaceable>po_id</replaceable> next to the pluginmap's <replaceable>id</replaceable>. This defines the "message catalog" to use. In general this should
be set identical to the <replaceable>id</replaceable> of your <command>.pluginmap</command>, but if you provide several related <command>.pluginmap</command>s in a single package, you will
probably want to specify a common <replaceable>po_id</replaceable> in your maps. The <replaceable>po_id</replaceable> of a <command>.pluginmap</command> file is inherited by all plugins
declared in it, unless that declares a different <replaceable>po_id</replaceable>.
</para>
<para>
For plugins and help pages, you do not need to tell &rkward; which strings are to be translated, because that is generally evident from their usage. However, as explained above,
you should keep an eye out for strings that may be ambiguous or need some explaining in order to be translated, correctly. For strings that could have different meanings, provide
an <replaceable>i18n_context</replaceable> like this:
</para>
<programlisting>
<checkbox id="scale" label="Scale" i18n_context="Show the scale"/>
<checkbox id="scale" label="Scale" i18n_context="Scale the plot"/>
</programlisting>
<para>
Providing <replaceable>i18n_context</replaceable> will cause the two strings to be translated separately. Otherwise they would share a single translation. In addition, the context
is shown to the translator. The <replaceable>i18n_context</replaceable>-attribute is supported on all elements that can have translatable strings, somewhere, including elements that
contain text inside them (⪚ <command><text></command>-elements).
</para>
<para>
In other cases the string to translate has a single non-ambiguous meaning, but may still need some explaining. In this case you can add a comment that will be shown to translators.
Examples might include:
</para>
<programlisting>
<!-- i18n: No, this is not a typo for screen plot! -->
<component id="scree_plot" label="Scree plot"/>
<!-- i18n: If you can, please make this string short. Having more than some 15 chars
looks really ugly at this point, and the meaning should be mostly self-evident to the
user (selection from a list of values shown next to this element) -->
<valueslot id="selected" label="Pick one"/>
</programlisting>
<para>
Note that such comments must precede the element they apply to, and must start with either "i18n:" or "TRANSLATORS:".
</para>
<para>
Finally, in rare cases, you may want to exclude certain strings from translation. This may make sense, for example, if you offer a choice between
several &R; function names in a <command><radio></command>-control. You do not want these to be translated, then (but depending on the context,
you should consider giving a descriptive label, instead):
</para>
<programlisting>
<radio id="transformation" label="R function to apply">
<option id="as.list" noi18n_label="as.list()"/>
<option id="as.vector" noi18n_label="as.vector()"/>
[...]
</radio>
</programlisting>
<para>
Note that you will omit the <replaceable>label</replaceable>-attribute, then, and specify <replaceable>noi18n_label</replaceable>, instead. Also, note that in contrast to
<replaceable>i18n_context</replaceable> and comments, using <replaceable>noi18n_label</replaceable> will make your plugin incompatible with versions of &rkward; prior to 0.6.3.
</para>
</sect1>
<sect1 id="i18n_js"><title>i18n in &rkward;'s js files and sections</title>
<para>
In contrast to the <literal role="extension">.xml</literal> files, making the <literal role="extension">.js</literal> files of a plugin translatable requires more custom work. The key difference, here, is that there is no decent automatic way to tell,
whether a string is meant to be displayed as a human readable string, or a piece of code. So you need to mark this up, yourself. We have already shown examples of this, all along. Here
is a more complete description of the i18n-functions available in js code, and some hints for more complex cases:
</para>
<variablelist>
<varlistentry>
<term><command>i18n (msgid, [...])</command></term>
<listitem><para>The most important function. Marks the string for translation. The string (whether translated or not) is returned quoted using double quotes ('"'). An arbitrary
number of placeholders can be used in the string like shown below. Using such placeholders instead of concatenating small substrings is much easier for translators:</para>
<programlisting>
i18n ("Compare objects %1 and %2", getString ('x'), getString ('y'));
</programlisting></listitem>
</varlistentry>
<varlistentry>
<term><command>i18nc (msgctxt, msgid, [...])</command></term>
<listitem><para>Same as <command>i18n()</command>, but additionally providing a message context:</para>
<programlisting>
i18nc ("proper name, not state of mind", "Mood test");
</programlisting></listitem>
</varlistentry>
<varlistentry>
<term><command>i18np (msgid_singular, msgid_plural, n, [...])</command></term>
<listitem><para>Same as <command>i18n()</command>, but for messages that may be different in singular or plural form (and some languages have differentiate yet more numerical forms). Note
that just like with <command>i18n()</command>, you can use an arbitrary number of replacements, but the first ('%1') is required, and has to be an integer.</para>
<programlisting>
i18np ("Comparing a single pair", "Comparing %1 distinct pairs", n_pairs);
</programlisting></listitem>
</varlistentry>
<varlistentry>
<term><command>i18ncp (msgctxt, msgid_singular, msgid_plural, n, [...])</command></term>
<listitem><para><command>i18np()</command> with added message context.</para></listitem>
</varlistentry>
<varlistentry>
<term><command>comment (comment, [indentation])</command></term>
<listitem><para>Echos a code comment, marked for translation. In contrast to the other i18n() functions, this is not quoted, but a '#' is added to each line of the comment.</para>
<programlisting>
comment ("Transpose the matrix");
echo ('x <- t (x)\n');
</programlisting></listitem>
</varlistentry>
</variablelist>
<para>
To add comments to the translators (see <link linkend="i18n_xml">above</link> for a discussion of the differences between comment and context), add a comment starting with "i18n:" or
"translators:" directly above the <command>i18n()</command>-call to comment. E.g.:
</para>
<programlisting>
// i18n: Spelling is correct: Scree plot.
echo ('rk.header (' + i18n ("Scree plot") + ')\n');
</programlisting>
<sect2 id="i18n_js_quoting"><title>i18n and quotes</title>
<para>
For the most part, you will not have to worry about i18n() behavior with respect to quotes. As, typically, translatable strings are string literals, quoting them is just the
right thing to do, and saves you some typing. Also, in functions like <command>makeHeaderCode()/Header()</command> that usually quote their arguments, i18n()'ed strings are protected
from duplicate quoting. Essentially, this works, by sending the translated string first through <command>quote()</command> (to make it quoted), then through
<command>noquote()</command> (to protect it from additional quoting). Should you require a translatable string that is not quoted, use <command>i18n(noquote ("My message"))</command>.
Should you require a translatable string to be quoted, a second time, send it through <command>quote()</command>, <emphasis>twice</emphasis>.
</para>
<para>
That said, it is generally not a good idea to make bits like function names or variable names translatable. For one thing, &R;, the programming language, is inherently in English,
and there is no internationalization of the language itself. Code comments are a different beast, but you should use the <command>comment()</command>-function for those. Secondly,
making syntactically relevant parts of the generated code translatable means that translations could actually break your plugin.
E.g. if an unsuspecting translator translates a string meant as a variable name in two distinct words with a space in between.
</para>
</sect2>
</sect1>
<sect1 id="i18n_workflow"><title>Translation maintainance</title>
<para>
Now that you have made your plugin translatable, how do you actually get it translated? In general you only need to worry about this, when developing an <link linkend="external_plugins">
external plugin</link>. For plugins in &rkward;'s main repository, all the magic is done for you. Here is the basic workflow for a external plugins. Note that you need the "gettext" tools, installed:
</para>
<itemizedlist>
<listitem><para>Mark up all strings, providing context and comments as needed</para></listitem>
<listitem><para>Run <command>python3 scripts/update_plugin_messages.py --extract-only /path/to/my.pluginmap</command>. scripts/update_plugin_messages.py is not currently part of the source
releases, but can be found in a source repository checkout.</para></listitem>
<listitem><para>Distribute the resulting <command>rkward__<replaceable>POID</replaceable>.pot</command> file to your translators. For external plugins, it is recommended to place it
in a subfolder "po" in inst/rkward.</para></listitem>
<listitem><para>Translator opens the file in a translation tool such as <command>lokalize</command>. Actually, even if you are not going to prepare any translation, yourself,
you should try this step for yourself. Browse the extracted strings looking out for problems / ambiguities.</para></listitem>
<listitem><para>Translator saves the translation as <command>rkward__<replaceable>POID</replaceable>.<replaceable>xx</replaceable>.po</command> (where
<replaceable>xx</replaceable> is the language code), and sends it back to you.</para></listitem>
<listitem><para>Copy <command>rkward__<replaceable>POID</replaceable>.<replaceable>xx</replaceable>.po</command> to your sources, next to
<command>rkward__<replaceable>POID</replaceable>.pot</command>. Run <command>python3 scripts/update_plugin_messages.py /path/to/my.pluginmap</command> (Note: without
<replaceable>--extract-only</replaceable>, this time). This will merge the translation with any interim string changes, compile the translation, and install it into
<command><replaceable>DIR_OF_PLUGINMAP</replaceable>/po/<replaceable>xx</replaceable>/LC_MESSAGES/rkward__<replaceable>POID</replaceable>.mo</command> (where
<replaceable>xx</replaceable> is the language code, again).</para></listitem>
<listitem><para>You should also include the non-compiled translation (&ie; <command>rkward__<replaceable>POID</replaceable>.<replaceable>xx</replaceable>.po</command>) in
your distribution, in the "po" subdirectory.</para></listitem>
<listitem><para>For any update of your plugin, run <command>python3 scripts/update_plugin_messages.py /path/to/my.pluginmap</command> to update the .pot file, but also the
existing .po-files, and the compiled message catalogs.</para></listitem>
</itemizedlist>
</sect1>
<sect1 id="i18n_translators"><title>Writing plugin translations</title>
<para>
We assume you know your trade as a translator, or are willing to read up on it, elsewhere. A few words specifically about translations of &rkward; plugins, though:
</para>
<itemizedlist>
<listitem><para>&rkward; plugins were not translatable until version 0.6.3, and were mostly not written with i18n in mind, before then. Thus you are going to encounter rather
more ambiguous strings, and other i18n problems than in other mature projects. Please do not just silently work around these, but let us (or the plugin maintainers)
know, so we can fix these issues.</para></listitem>
<listitem><para>Many &rkward; plugins refer to highly specialized terms, from data handling and statistics, but also from other fields of science. In many cases, a good translation
will require at least basic knowledge of these fields. In some cases, there <emphasis>is</emphasis> no good translation for a technical term, and the best option may
be to leave the term untranslated, or to include the English term in parentheses. Do not focus too much on the 100% mark of translated strings, focus on providing
a good translation, even if that means skipping some strings (or even skipping some message catalogs as a whole). Other users may be able to fill in any gaps in technical
terms.</para></listitem>
</itemizedlist>
</sect1>
</chapter>
<chapter id="chapter_about_information">
<title>Author, license and version information</title>
<para>So you have written a set of plugins, and you are getting ready to <link linkend="external_plugins">share your work</link>. To make sure users will know what your work is all about, under what terms they can use and distribute it, and whom they should contact about issues or ideas, you should add some information <emphasis>about</emphasis> your plugins. This can be done using the <command><about></command> element. It can be used in either the &pluginmap; or in individual plugin <literal role="extension">.xml</literal> files (in both cases as a direct child of the document tag). When specified in the &pluginmap; it will apply to all plugins. If <command><about></command> is specified in both places, the <command><about></command> information in the plugin <literal role="extension">.xml</literal> file will override that in the &pluginmap; file. You can also add an <command><about></command> element to .rkh-pages, which are not connected to a plugin, if there is a need for that.</para>
<para>Here is an example &pluginmap; file with only a few explanations, below. In cases of doubt, more information may be available from the reference.</para>
<programlisting>
<document
namespace="rkward"
id="SquaretheCircle_rkward"
>
<about
name="Square the Circle"
shortinfo="Squares the circle using Heisenberg compensation."
version="0.1-3"
releasedate="2011-09-19"
url="http://eternalwondermaths.example.org/23/stc.html"
license="GPL"
category="Geometry"
>
<author
given="E.A."
family="Dölle"
email="doelle@eternalwondermaths.example.org"
role="aut"
/>
<author
given="A."
family="Assistant"
email="alterego@eternalwondermaths.example.org"
role="cre, ctb"
/>
</about>
<dependencies>
...
</dependencies>
<components>
...
</components>
<hierarchy>
...
</hierarchy>
</document>
</programlisting>
<para>Most of this should explain itself, so we’ll not discuss each and every tag element. But let’s look at some details that probably need some commentary for easier understanding. </para>
<para>The <parameter>category</parameter> element in <command><about></command> can be defined rather freely, but should be meaningful, as it’s thought to be used to order plugins into groups. All other attributes in this opening tag are mandatory and must be filled with reasonable content. </para>
<para>At least one <command><author></command> with a valid email address and the role <quote>aut</quote> (<quote>author</quote>) must also be given. In case your plugin causes problems or someone would like to share its gratitude with you, it should be easy to contact someone who’s involved. For further information on other valid roles, like <quote>ctb</quote> for code contributors or <quote>cre</quote> for package maintenance, please refer to the <ulink url="http://stat.ethz.ch/R-manual/R-patched/library/utils/html/person.html">R documentation on <function>person()</function></ulink>. </para>
<note><para>Remember that you can use <command><include></command> and / or <command><insert></command> to repeat information across several <literal role="extension">.xml</literal> files (⪚ information on an author who was involved with several plugins). <link linkend="sect_similar_plugins">More information</link>.</para></note>
<tip><para>You do not have to write this &XML; code by hand. If you use the function <function>rk.plugin.skeleton()</function> from the <link linkend="rkwarddev"><application>rkwarddev</application> package</link> and provide all necessary information via the <parameter>about</parameter> option, it will automatically create a &pluginmap; file with a working <about> section for you.</para></tip>
</chapter>
<chapter id="external_plugins">
<title>Share your work with others</title>
<sect1 id="sect_external_plugins"><title>External plugins</title>
<para>
As of version 0.5.5, &rkward; provides a comfortable way to install additional third party plugins which do not belong to the core package itself. We call these <quote>external plugins</quote>. They come in form of an &R; package and can be managed directly via the usual package management features of &R; and/or &rkward;.
</para>
<para>
This section of the documentation describes how external plugins are to be packaged, so that &rkward; can use them. The plugin creation itself is of course identical to the previous sections. That is, you should probably first write a working plugin, and then check back here to learn how to distribute it.
</para>
<para>
Since external plugins are a relatively young feature, details of this might probably change in future releases. You’re welcome to contribute your ideas to improve the process.
</para>
<tip>
<para>
These docs explain the details of external plugins so you can learn how they work. In addition to that, also have a look at the <link linkend="rkwarddev"><application>rkwarddev</application> package</link>, which was designed to automate a lot of the writing process.
</para>
</tip>
</sect1>
<sect1 id="why_external_plugins">
<title>Why external plugins?</title>
<para>
The number of packages to extend the functionality of &R; is immense already, and climbing. On one hand, we want to encourage you to write plugins for even the most specialised tasks you need solved. On the other hand, the average user should not get lost in huge menu trees full of unknown statistical terms. Therefore it seemed reasonable to keep the plugin handling in &rkward; quite modular as well. The &rkward; team maintains its own public package repository at <ulink url="https://files.kde.org/rkward/R/">https://files.kde.org/rkward/R/</ulink>, designated to host your external plugins.
</para>
<para>
As a rule of thumb, plugins that seem to serve a widely used purpose (⪚ t-Tests) should become part of the core package, while those who serve a rather limited group of people with special interests should be provided as an optional package. For you as a plugin author it’s best practice to just start with an external plugin.
</para>
</sect1>
<sect1 id="structure_of_a_plugin_package">
<title>Structure of a plugin package</title>
<para>For external plugins to install and work properly, they must follow some structural guidelines regarding their file hierarchy. </para>
<sect2 id="file_hierarchy"><title>File hierarchy</title>
<para>
Let's have a look at the prototypic file hierarchy of an elaborate plugin archive. You don’t have to include all of these directories and/or files for a plugin to work (read on to learn what’s absolutely necessary), consider this a <quote>best practice</quote> example:
</para>
<programlisting>
plugin_name/
inst/
rkward/
plugins/
plugin_name.xml
plugin_name.js
plugin_name.rkh
...
po/
ll/
LC_MESSAGES/
rkward__plugin_name_rkward.mo
rkward__plugin_name_rkward.ll.po
rkward__plugin_name_rkward.pot
tests/
testsuite_name/
RKTestStandards.sometest_name.rkcommands.R
RKTestStandards.sometest_name.rkout
...
testsuite.R
plugin_name.pluginmap
...
ChangeLog
README
AUTHORS
LICENSE
DESCRIPTION
</programlisting>
<note>
<para>
In this example, all occasions of <token>plugin_name</token>, <token>testsuite_name</token> and <token>sometest_name</token> are to be replaced with their correct names, accordingly. Also, <token>ll</token> is a placeholder for a language abbreviation (⪚, <quote>de</quote>, <quote>en</quote> or <quote>es</quote>).
</para>
</note>
<tip>
<para>
You do not have to create this file hierarchy by hand. If you use the function <function>rk.plugin.skeleton()</function> from the <link linkend="rkwarddev"><application>rkwarddev</application> package</link>, it will automatically create all necessary files and directories for you, except the <filename>po</filename> directory which is created and managed by the <link linkend="i18n_workflow">translation script</link>.
</para>
</tip>
<sect3 id="basic_plugin_components">
<title>Basic plugin components</title>
<para>
It is mandatory to include at least three files: a <link linkend="pluginmap">&pluginmap;</link>, a plugin <link linkend="mainxml">.xml</link> description and a plugin <link linkend="jstemplate">.js</link> file. That is, even the "plugins" directory is optional. It might just help to give your files some order, especially if you include more that one plugin/dialog in the archive, which is of course no problem. You can have as many directories for the actual plugin files as you see fit, they just have to resemble the <link linkend="pluginmap">&pluginmap;</link>, respectively. It is also possible to even include several &pluginmap; files, if it fits your needs, but you should include them all in <quote>plugin_name.pluginmap</quote> then.
</para>
<para>
Each &R; package must have a valid <filename>DESCRIPTION</filename> file, which is also crucial for &rkward; recognizing it as a plugin provider. Most of the information it carries is also needed in the plugin <link linkend="chapter_about_information">Meta-information</link> and possibly <link linkend="chapter_dependencies">dependencies</link>, but in a different format (the &R; documentation explains <ulink url="http://cran.r-project.org/doc/manuals/R-exts.html#The-DESCRIPTION-file">the <filename>DESCRIPTION</filename> file in detail</ulink>).
</para>
<para>
In addition to the general contents of a <filename>DESCRIPTION</filename> file, make sure to also include the line <quote>Enhances: rkward</quote>. This will cause &rkward; to automatically scan the package for plugins if it is installed. An example <filename>DESCRIPTION</filename> file looks like this:
</para>
<programlisting>
Package: SquaretheCircle
Type: Package
Title: Square the circle
Version: 0.1-3
Date: 2011-09-19
Author: E.A. Dölle <doelle@eternalwondermaths.example.org>
Maintainer: A. Assistant <alterego@eternalwondermaths.example.org>
Enhances: rkward
Description: Squares the circle using Heisenberg compensation.
License: GPL
LazyLoad: yes
URL: http://eternalwondermaths.example.org/23/stc.html
Authors@R: c(person(given="E.A.", family="Dölle", role="aut",
email="doelle@eternalwondermaths.example.org"),
person(given="A.", family="Assistant", role=c("cre",
"ctb"), email="alterego@eternalwondermaths.example.org"))
</programlisting>
<tip>
<para>
You do not have to write this file by hand. If you use the function <function>rk.plugin.skeleton()</function> from the <link linkend="rkwarddev"><application>rkwarddev</application> package</link> and provide all necessary information via the <quote>about</quote> option, it will automatically create a working <filename>DESCRIPTION</filename> file for you.
</para>
</tip>
</sect3>
<sect3 id="additional_information">
<title>Additional information (optional)</title>
<para>
<filename>ChangeLog</filename>, <filename>README</filename>, <filename>AUTHORS</filename>, <filename>LICENSE</filename> should be self-explaining and are entirely optional. Actually, they won’t be interpreted by &rkward;, so they are rather meant to carry additional information that might be relevant ⪚ for distributors. Most of their relevant content (author credits, licence terms &etc;) will be included in the actual plugin files anyway, though (see the <link linkend="chapter_about_information">section on meta-information</link>). Note that all of these files could also be placed somewhere in the "inst" directory, if you want them not only to be present in the source archive but the installed package as well.
</para>
</sect3>
<sect3 id="automated_plugin_testing">
<title>Automated plugin testing (optional)</title>
<para>
Another optional directory is "tests", which is meant to provide files needed for <ulink url="http://sourceforge.net/apps/mediawiki/rkward/index.php?title=Automated_Plugin_Testing">automated plugin testing</ulink>. These tests are helpful to quickly check if your plugins still work with new versions of &R; or &rkward;. If you want to include tests, you should really restrain yourself to the naming scheme and hierarchy shown here. That is, tests should reside in a directory called <filename>tests</filename>, which includes a file <filename>testsuite.R</filename> and a folder with tests standards named after the appropriate test suite. You can, however, provide more than one test suite; in that case, if you don’t want to append them all in the one <filename>testsuite.R</filename> file, you can split them in ⪚ one file for each test suite and create one <filename>testsuite.R</filename> with <function>source()</function> calls for each suite file. In either case, create separate subdirectories with test
standards for each defined suite.
</para>
<para>
The benefits of upholding to this structure is that plugin tests can be run simply by calling <function>rktests.makplugintests()</function> from the <ulink url="rkward://rhelp/rkwardtests">rkwardtests</ulink> package without additional arguments. Have a look at the online documentation on <ulink url="http://sourceforge.net/apps/mediawiki/rkward/index.php?title=Automated_Plugin_Testing">Automated Plugin Testing</ulink> for further details.
</para>
</sect3>
</sect2>
</sect1>
<sect1 id="building_the_plugin_package">
<title>Building the plugin package</title>
<para>As explained earlier, external &rkward; plugins are in effect &R; packages, and therefore the packaging process is identical. In contrast to "real" &R; packages, a pure plugin package does not carry any further &R; code (although you can of course add &rkward; plugins to usual &R; packages as well, using the same methods explained here). This should make it even easier to create a functioning package, as long as you have a valid <filename>DESCRIPTION</filename> file and adhere to the file hierarchy explained in <link linkend="structure_of_a_plugin_package">previous sections</link>.</para>
<para>The easiest way to actually build and test your plugin is to use the <application>R</application> command on the command line, for example:</para>
<para><userinput>
<command>R</command> <option>CMD build</option> <parameter><filename>SquaretheCircle</filename></parameter>
</userinput></para>
<para><userinput>
<command>R</command> <option>CMD INSTALL</option> <parameter><filename>SquaretheCircle_0.1-3.tar.gz</filename></parameter>
</userinput></para>
<tip><para>You do not have to build the package like this on the command line. If you use the function <function>rk.build.package()</function> from the <link linkend="rkwarddev"><application>rkwarddev</application> package</link>, it will build and/or check your plugin package for you.</para></tip>
</sect1>
</chapter>
<chapter id="rkwarddev">
<title>Plugin development with the <application>rkwarddev</application> package</title>
<sect1 id="rkdev_overview"><title>Overview</title>
<para>Writing external plugins involves writing files in three languages (&XML;, &javascript; and R) and the creation of a standardized hierarchy of directories. To make this a lot easier for willing plugin developers, we are providing the <application>rkwarddev</application> package. It provides a number of simple &R; functions to create the &XML; code for all dialog elements like tabbooks, checkboxes, dropdownlists or filebrowsers, as well as functions to create &javascript; code and &rkward; help files to start with. The function <function>rk.plugin.skeleton()</function> creates the expected directory tree and all necessary files where they are supposed to be.</para>
<para>This package is not installed by default, but has to be installed manually from <ulink url="https://files.kde.org/rkward/R/">&rkward;'s own repository</ulink>. You can either do that by using the &GUI; interface (<menuchoice><guimenu>Settings</guimenu><guimenuitem>Configure packages</guimenuitem></menuchoice>), or from any running &R; session:</para>
<programlisting>
install.packages("rkwarddev", repos="https://files.kde.org/rkward/R")
library(rkwarddev)
</programlisting>
<para><application>rkwarddev</application> depends on another small package called <quote>XiMpLe</quote>, which is a very simple &XML; parser and generator and also present in the same repository.</para>
<para>The full <ulink url="https://files.kde.org/rkward/R/pckg/rkwarddev/rkwarddev.pdf">documentation in PDF format</ulink> can also be found there. A more detailed introduction to working with the package can be found in the <ulink url="https://files.kde.org/rkward/R/pckg/rkwarddev/rkwarddev_vignette.pdf">rkwarddev vignette</ulink>.</para>
</sect1>
<sect1 id="rkdev_example"><title>Practical example</title>
<para>To get you an idea how <quote>scripting a plugin</quote> looks like, compared to the direct approach you have seen in the previous chapters, we will create the full t-test plugin once again -- this time only with the &R; functions of the <application>rkwarddev</application> package.</para>
<tip><para>The package will add a new &GUI; dialog to &rkward; under <menuchoice><guimenu>File</guimenu><guimenuitem>Export</guimenuitem><guimenuitem>Create &rkward; plugin script</guimenuitem></menuchoice>. Like the name suggests, you can create plugin skeletons for further editing with it. This dialog itself was in turn generated by an <application>rkwarddev</application> script which you can find in the <quote>demo</quote> directory of the installed package and package sources, as an additional example. You can also run it by calling <function>demo("skeleton_dialog")</function></para></tip>
<sect2 id="rkdev_gui"><title>&GUI; description</title>
<para>You will immediately notice that the workflow is considerably different: Contrary to writing the XML code directly, you do not begin with the <command><document></command> definition, but directly with the plugin elements you would like to have in the dialog. You can assign each interface element -- be it check boxes, dropdown menus, variable slots or anything else -- to individual &R; objects, and then combine these objects to the actual &GUI;. The package has functions for <link linkend="interfaceelements">each XML tag</link> that can be used to define the plugin &GUI;, and most of them even have the same name, only with the prefix <function>rk.XML.*</function>. For example, defining a <command><varselector></command> and two <command><varslot></command> elements for the <replaceable>"x"</replaceable> and <replaceable>"y"</replaceable> variable of the t-test example can be done by:</para>
<programlisting>
variables <- rk.XML.varselector(id.name="vars")
var.x <- rk.XML.varslot("compare", source=variables, types="number", required=TRUE, id.name="x")
var.y <- rk.XML.varslot("against", source=variables, types="number", required=TRUE, id.name="y")
</programlisting>
<para>The most interesting detail is probably <parameter>source=</parameter><replaceable>variables</replaceable>: A prominent feature of the package is that all functions can generate automatic IDs, so you do not have to bother with either thinking of <parameter>id</parameter> values or remembering them to refer to a specific plugin element. You can simply give the &R; objects as reference, as all functions who need an ID from some other element can also read it from these objects. <function>rk.XML.varselector()</function> is a little special, as it usually has no specific content to make an ID from (it can, but only if you specify a label), so we have to set an ID name. But <function>rk.XML.varslot()</function> would not need the <parameter>id.name</parameter> arguments here, so this would suffice:</para>
<programlisting>
variables <- rk.XML.varselector(id.name="vars")
var.x <- rk.XML.varslot("compare", source=variables, types="number", required=TRUE)
var.y <- rk.XML.varslot("against", source=variables, types="number", required=TRUE)
</programlisting>
<para>In order to recreate the example code to the point, you would have to set all ID values manually. But since the package shall make our lives easier, from now on we will no longer care about that.</para>
<tip>
<para>
<application>rkwarddev</application> is capable of a lot of automation to help you build your plugins. However, it might be preferable to not use it to its full extend. If your goal is to produce code that is not only working but can also be easily read and compared to your generator script by a human being, you should consider to always set useful IDs with <parameter>id.name</parameter>. Naming your &R; objects identical to these IDs will also help in getting script code that is easy to understand.
</para>
</tip>
<para>If you want to see how the XML code of the defined element looks like if you exported it to a file, you can just call the object by its name. So, if you now called <quote>var.x</quote> in your &R; session, you should see something like this:</para>
<programlisting>
<varslot id="vrsl_compare" label="compare" source="vars" types="number" required="true" />
</programlisting>
<para>Some tags are only useful in the context of others. Therefore, for instance, you will not find a function for the <command><option></command> tag. Instead, both radio buttons and dropdown lists are defined including their options as a named list, where the names represent the labels to be shown in the dialog, and their value is a named vector which can have two entries, <parameter>val</parameter> for the value of an option and the boolean <parameter>chk</parameter> to specify if this option is checked by default.</para>
<programlisting>
test.hypothesis <- rk.XML.radio("using test hypothesis",
options=list(
"Two-sided"=c(val="two.sided"),
"First is greater"=c(val="greater"),
"Second is greater"=c(val="less")
)
)
</programlisting>
<para>The result looks like this:</para>
<programlisting>
<radio id="rad_usngtsth" label="using test hypothesis">
<option label="Two-sided" value="two.sided" />
<option label="First is greater" value="greater" />
<option label="Second is greater" value="less" />
</radio>
</programlisting>
<para>All that is missing from the elements of the <quote>Basic settings</quote> tab is the check box for paired samples, and the structuring of all of these elements in rows and columns:</para>
<programlisting>
check.paired <- rk.XML.cbox("Paired sample", value="1", un.value="0")
basic.settings <- rk.XML.row(variables, rk.XML.col(var.x, var.y, test.hypothesis, check.paired))
</programlisting>
<para><function>rk.XML.cbox()</function> is a rare exception where the function name does not contain the full tag name, to save some typing for this often used element. This is what <function>basic.settings</function> now contains:</para>
<programlisting>
<row id="row_vTFSPP10TF">
<varselector id="vars" />
<column id="clm_vrsTFSPP10">
<varslot id="vrsl_compare" label="compare" source="vars" types="number" required="true" />
<varslot id="vrsl_against" label="against" i18n_context="compare against" source="vars" types="number" required="true" />
<radio id="rad_usngtsth" label="using test hypothesis">
<option label="Two-sided" value="two.sided" />
<option label="First is greater" value="greater" />
<option label="Second is greater" value="less" />
</radio>
<checkbox id="chc_Pardsmpl" label="Paired sample" value="1" value_unchecked="0" />
</column>
</row>
</programlisting>
<para>In a similar manner, the next lines will create &R; objects for the elements of the <quote>Options</quote> tab, introducing functions for spinboxes, frames and stretch:</para>
<programlisting>
check.eqvar <- rk.XML.cbox("assume equal variances", value="1", un.value="0")
conf.level <- rk.XML.spinbox("confidence level", min=0, max=1, initial=0.95)
check.conf <- rk.XML.cbox("print confidence interval", val="1", chk=TRUE)
conf.frame <- rk.XML.frame(conf.level, check.conf, rk.XML.stretch(), label="Confidence Interval")
</programlisting>
<para>Now all we need to do is to put the objects together in a tabbook, and place that in a dialog section:</para>
<programlisting>
full.dialog <- rk.XML.dialog(
label="Two Variable t-Test",
rk.XML.tabbook(tabs=list("Basic settings"=basic.settings, "Options"=list(check.eqvar, conf.frame)))
)
</programlisting>
<para>We can also create the wizard section with its two pages using the same objects, so their IDs will be extracted for the <command><copy></command> tags:</para>
<programlisting>
full.wizard <- rk.XML.wizard(
label="Two Variable t-Test",
rk.XML.page(
rk.XML.text("As a first step, select the two variables you want to compare against
each other. And specify, which one you theorize to be greater. Select two-sided,
if your theory does not tell you, which variable is greater."),
rk.XML.copy(basic.settings)),
rk.XML.page(
rk.XML.text("Below are some advanced options. It is generally safe not to assume the
variables have equal variances. An appropriate correction will be applied then.
Choosing \"assume equal variances\" may increase test-strength, however."),
rk.XML.copy(check.eqvar),
rk.XML.text("Sometimes it is helpful to get an estimate of the confidence interval of
the difference in means. Below you can specify whether one should be shown, and
which confidence-level should be applied (95% corresponds to a 5% level of
significance)."),
rk.XML.copy(conf.frame)))
</programlisting>
<para>That is it for the &GUI;. The global document will be combined in the end by <function>rk.plugin.skeleton()</function>.</para>
</sect2>
<sect2 id="rkdev_jscode"><title>&javascript; code</title>
<para>Until now, using the <application>rkwarddev</application> package might not seem to have helped so much. This is going to change right now.</para>
<para>First of all, just like we did not have to care about IDs for elements when defining the &GUI; layout, we do not have to care about &javascript; variable names in the next step. If you want more control, you can write plain &javascript; code and have it pasted to the generated file. But it is probably much more efficient to do it the <application>rkwarddev</application> way.</para>
<para>Most notably you do not have to define any variable yourself, as <function>rk.plugin.skeleton()</function> can scan your &XML; code and automatically define all variables you will probably need -- for instance, you would not bother to include a check box if you do not use its value or state afterwards. So we can start writing the actual &R; code generating JS immediately.</para>
<tip><para>The function <function>rk.JS.scan()</function> can also scan existing &XML; files for variables.</para></tip>
<para>The package has some functions for JS code constructs that are commonly used in &rkward; plugins, like the <function>echo()</function> function or <function>if() {...} else {...}</function> conditions. There are some differences between JS and &R;, ⪚, for <function>paste()</function> in &R; you use the comma to concatenate character strings, whereas for <function>echo()</function> in JS you use <quote>+</quote>, and lines must end with a semicolon. By using the &R; functions, you can almost forget about these differences and keep writing &R; code.</para>
<para>These functions can take different classes of input objects: Either plain text, &R; objects with &XML; code like above, or in turn results of some other JS functions of the package. In the end, you will always call <function>rk.paste.JS()</function>, which behaves similar to <function>paste()</function>, but depending on the input objects it will replace them with their &XML; ID, &javascript; variable name or even complete &javascript; code blocks.</para>
<para>For the t-test example, we need two JS objects: One to calculate the results, and one to print them in the <function>printout()</function> function:</para>
<programlisting>
JS.calc <- rk.paste.JS(
echo("res <- t.test (x=", var.x, ", y=", var.y, ", hypothesis=\"", test.hypothesis, "\""),
js(
if(check.paired){
echo(", paired=TRUE")
},
if(!check.paired && check.eqvar){
echo(", var.equal=TRUE")
},
if(conf.level != "0.95"){
echo(", conf.level=", conf.level)
},
linebreaks=TRUE
),
echo(")\n"),
level=2
)
JS.print <- rk.paste.JS(echo("rk.print (res)\n"), level=2)
</programlisting>
<para>As you can see, <application>rkwarddev</application> also provides an &R; implementation of the <function>echo()</function> function. It returns exactly one character string with a valid JS version of itself. You might also notice that all of the &R; objects here are the ones we created earlier. They will automatically be replaced with their variable names, so this should be quite intuitive. Whenever you need just this replacement, the function <function>id()</function> can be used, which also will return exactly one character string from all the objects it was given (you could say it behaves like <function>paste()</function> with a very specific object substitution).</para>
<para>The <function>js()</function> function is a wrapper that allows you to use &R;'s <command>if(){...} else {...}</command> conditions like you are used to. They will be translated directly into JS code. It also preserves some operators like <command><</command>, <command>>=</command> or <command>||</command>, so you can logically compare your &R; objects without the need for quoting most of the time. Let's have a look at the resulting <quote>JS.calc</quote> object, which now contains a character string with this content:</para>
<programlisting>
echo("res <- t.test (x=" + vrslCompare + ", y=" + vrslAgainst + ", hypothesis=\"" + radUsngtsth + "\"");
if(chcPardsmpl) {
echo(", paired=TRUE");
} else {}
if(!chcPardsmpl && chcAssmqlvr) {
echo(", var.equal=TRUE");
} else {}
if(spnCnfdnclv != "0.95") {
echo(", conf.level=" + spnCnfdnclv);
} else {}
echo(")\n");
</programlisting>
<note>
<para>
Alternatively for <function>if()</function> conditions nested in <function>js()</function>, you can use the <function>ite()</function> function, which behaves similar to &R;'s <function>ifelse()</function>. However, conditional statements constructed using <function>ite()</function> are usually harder to read and should be replaced by <function>js()</function> whenever possible.
</para>
</note>
</sect2>
<sect2 id="rkdev_pluginmap"><title>Plugin map</title>
<para>This section is very short: We do not need to write a &pluginmap; at all, as it can be generated automatically by <function>rk.plugin.skeleton()</function>. The menu hierarchy can be specified via the <parameter>pluginmap</parameter> option:</para>
<programlisting>
[...]
pluginmap=list(
name="Two Variable t-Test",
hierarchy=list("analysis", "means", "t-Test"))
[...]
</programlisting>
</sect2>
<sect2 id="rkdev_rkh"><title>Help page</title>
<para>This section is very short as well: <function>rk.plugin.skeleton()</function> cannot write a whole help page from the information it has. But it can scan the &XML; document also for elements which probably deserve a help page entry, and automatically create a help page template for our plugin. All we have to do afterwards is to write some lines for each listed section.</para>
<tip><para>The function <function>rk.rkh.scan()</function> can also scan existing &XML; files to create a help file skeleton.</para></tip>
</sect2>
<sect2 id="rkdev_plugin_generator"><title>Generate the plugin files</title>
<para>Now comes the final step, in which we will hand over all generated objects to <function>rk.plugin.skeleton()</function>:</para>
<programlisting>
plugin.dir <- rk.plugin.skeleton("t-Test",
xml=list(
dialog=full.dialog,
wizard=full.wizard),
js=list(
results.header="Two Variable t-Test",
calculate=JS.calc,
printout=JS.print),
pluginmap=list(
name="Two Variable t-Test",
hierarchy=list("analysis", "means", "t-Test")),
load=TRUE,
edit=TRUE,
show=TRUE)
</programlisting>
<para>The files will be created in a temporal directory by default. The last three options are not necessary, but very handy: <parameter>load=</parameter><replaceable>TRUE</replaceable> will automatically add the new plugin to &rkward;s configuration (since it is in a temp dir and hence will cease to exist when &rkward; is closed, it will automatically be removed again by &rkward; during its next start), <parameter>edit=</parameter><replaceable>TRUE</replaceable> will open all created files for editing in &rkward; editor tabs, and <parameter>show=</parameter><replaceable>TRUE</replaceable> will attempt to directly launch the plugin, so you can examine what it looks like without a click. You might consider adding <parameter>overwrite=</parameter><replaceable>TRUE</replaceable> if you are about to run your script repeatedly (⪚ after changes to the code), as by default no files will be overwritten.</para>
<para>The result object <quote>plugin.dir</quote> contains the path to the directory in which the plugin was created. This can be useful in combination with the function <function>rk.build.package()</function>, to build an actual &R; package to share your plugin with others -- ⪚ by sending it to the &rkward; development team to be added to our plugin repository.</para>
</sect2>
<sect2 id="rkdev_ttest_script"><title>The full script</title>
<para>To recapitulate all of the above, here is the full script to create the working t-test example. Adding to the already explained code, it also loads the package if needed, and it uses the <function>local()</function> environment, so all the created objects will not end up in your current workspace (except for <quote>plugin.dir</quote>):</para>
<programlisting>
require(rkwarddev)
local({
variables <- rk.XML.varselector(id.name="vars")
var.x <- rk.XML.varslot("compare", source=variables, types="number", required=TRUE)
var.y <- rk.XML.varslot("against", source=variables, types="number", required=TRUE)
test.hypothesis <- rk.XML.radio("using test hypothesis",
options=list(
"Two-sided"=c(val="two.sided"),
"First is greater"=c(val="greater"),
"Second is greater"=c(val="less")
)
)
check.paired <- rk.XML.cbox("Paired sample", value="1", un.value="0")
basic.settings <- rk.XML.row(variables, rk.XML.col(var.x, var.y, test.hypothesis, check.paired))
check.eqvar <- rk.XML.cbox("assume equal variances", value="1", un.value="0")
conf.level <- rk.XML.spinbox("confidence level", min=0, max=1, initial=0.95)
check.conf <- rk.XML.cbox("print confidence interval", val="1", chk=TRUE)
conf.frame <- rk.XML.frame(conf.level, check.conf, rk.XML.stretch(), label="Confidence Interval")
full.dialog <- rk.XML.dialog(
label="Two Variable t-Test",
rk.XML.tabbook(tabs=list("Basic settings"=basic.settings, "Options"=list(check.eqvar, conf.frame)))
)
full.wizard <- rk.XML.wizard(
label="Two Variable t-Test",
rk.XML.page(
rk.XML.text("As a first step, select the two variables you want to compare against
each other. And specify, which one you theorize to be greater. Select two-sided,
if your theory does not tell you, which variable is greater."),
rk.XML.copy(basic.settings)),
rk.XML.page(
rk.XML.text("Below are some advanced options. It is generally safe not to assume the
variables have equal variances. An appropriate correction will be applied then.
Choosing \"assume equal variances\" may increase test-strength, however."),
rk.XML.copy(check.eqvar),
rk.XML.text("Sometimes it is helpful to get an estimate of the confidence interval of
the difference in means. Below you can specify whether one should be shown, and
which confidence-level should be applied (95% corresponds to a 5% level of
significance)."),
rk.XML.copy(conf.frame)))
JS.calc <- rk.paste.JS(
echo("res <- t.test (x=", var.x, ", y=", var.y, ", hypothesis=\"", test.hypothesis, "\""),
js(
if(check.paired){
echo(", paired=TRUE")
},
if(!check.paired && check.eqvar){
echo(", var.equal=TRUE")
},
if(conf.level != "0.95"){
echo(", conf.level=", conf.level)
},
linebreaks=TRUE
),
echo(")\n"), level=2)
JS.print <- rk.paste.JS(echo("rk.print (res)\n"), level=2)
plugin.dir <<- rk.plugin.skeleton("t-Test",
xml=list(
dialog=full.dialog,
wizard=full.wizard),
js=list(
results.header="Two Variable t-Test",
calculate=JS.calc,
printout=JS.print),
pluginmap=list(
name="Two Variable t-Test",
hierarchy=list("analysis", "means", "t-Test")),
load=TRUE,
edit=TRUE,
show=TRUE,
overwrite=TRUE)
})
</programlisting>
</sect2>
</sect1>
<sect1 id="rkwarddev_rkh"><title>Adding help pages</title>
<para>
If you want to write a help page for your plugin, the most straight forward way to do so is to add the particular instructions directly to the definitions of the &XML; elements they belong to:
</para>
<programlisting>
variables <- rk.XML.varselector(
id.name="vars",
help="Select the data object you would like to analyse.",
component="Data"
)
</programlisting>
<para>
The text given to the <parameter>help</parameter> parameter can then be fetched by <function>rk.rkh.scan()</function> and written to the help page of this plugin component. For this to work technically, however, <function>rk.rkh.scan()</function> must know which &R; objects belong to one plugin component. This is why you must also provide the <parameter>component</parameter> parameter and make sure it is identical for all objects belonging together.
</para>
<para>
Since you will usually combine many objects into one dialog and might also like to be able to re-use objects like the <command><varslot></command> in multiple components of your plugins, it is possible to globally define a component with the <function>rk.set.comp()</function>. If set, it is assumed that all the following objects used in your script belong to that particular component, until <function>rk.set.comp()</function> is being called again with a different component name. You can then omit the <parameter>component</parameter> parameter:
</para>
<programlisting>
rk.set.comp("Data")
variables <- rk.XML.varselector(
id.name="vars",
help="Select the data object you would like to analyse."
)
</programlisting>
<para>
To add global sections like <command><summary></command> or <command><usage></command> to the help page, you use functions like <function>rk.rkh.summary()</function> or <function>rk.rkh.usage()</function> accordingly. Their results are then used to set the list elements like <parameter>summary</parameter> or <parameter>usage</parameter> in the <parameter>rkh</parameter> parameter of <function>rk.plugin.component()</function>/<function>rk.plugin.skeleton()</function>.
</para>
</sect1>
<sect1 id="rkwarddev_i18n"><title>Translating plugins</title>
<para>
The <application>rkwarddev</application> package is capable of producing external plugins with full i18n support. For instance, all relevant functions generating XML objects offer an optional parameter to specify <replaceable>i18n_context</replaceable> or <replaceable>noi18n_label</replaceable>:
</para>
<programlisting>
varComment <- rk.XML.varselector(id.name="vars", i18n=list(comment="Main variable selector"))
varContext <- rk.XML.varselector(id.name="vars", i18n=list(context="Main variable selector"))
cboxNoi18n <- rk.XML.cbox(label="Power", id.name="power", i18n=FALSE)
</programlisting>
<para>The above examples produce output like this:</para>
<programlisting>
# varComment
<!-- i18n: Main variable selector -->
<varselector id="vars" />
# varContext
<varselector id="vars" i18n_context="Main variable selector" />
# cboxNoi18n
<checkbox id="power" noi18n_label="Power" value="true" />
</programlisting>
<para>
There is also support for translatable JS code. In fact, the package tries add <function>i18n()</function> calls by default in places where this is usually helpful. The <function>rk.JS.header()</function> function is a good example:
</para>
<programlisting>
jsHeader <- rk.JS.header("Test results")
</programlisting>
<para>This produces the following JS code:</para>
<programlisting>
new Header(i18n("Test results")).print();
</programlisting>
<para>But you can also manually mark strings in your JS code as translatable, by using the <function>i18n()</function> function just like you would if you wrote the JS file directly.</para>
</sect1>
</chapter>
<appendix id="reference">
<title>Reference</title>
<sect1 id="propertytypes"><title>Types of properties/Modifiers</title>
<para>
At some places in this introduction we have talked about <quote>properties</quote> of &GUI; elements or otherwise. In fact there are several different types of properties. Usually you do not need to worry about this, as you can use common sense to connect any property to any other property. However, internally, there are different types of properties. What this matters for, is when fetching some special values in the JS-template. In getString ("id")/getBoolean ("id")/getList ("id") statements you can also specify some so called <quote>modifiers</quote> like this: <function>getString ("id.modifier")</function>. This modifier will affect, in which way the value is printed. Read on for the list of properties, and the modifiers they each make available:
</para>
<variablelist>
<varlistentry>
<term>String properties</term>
<listitem><para>The most simple type of property, used to simply hold a piece of text. Modifiers:
<variablelist>
<varlistentry>
<term>No modifier ("")</term>
<listitem><para>The string as defined / set.</para></listitem>
</varlistentry>
<varlistentry>
<term>quoted</term>
<listitem><para>The string in quoted form (suitable for passing to &R; as character).</para></listitem>
</varlistentry>
</variablelist></para></listitem>
</varlistentry>
<varlistentry>
<term>Boolean properties</term>
<listitem><para>Properties that can either be on or off, true or false. For instance the properties created by <convert>-tags, also the property accompanying a <checkbox> (see below). The following values will be returned according to the given modifier:
<variablelist>
<varlistentry>
<term>No modifier ("")</term>
<listitem><para>By default the property will return 1 if it is true, and 0 otherwise. The recommended way to fetch boolean values is using <function>getBoolean()</function>. Note that for <function>getString()</function>, the string "0" will be returned when the property is false. This string would evaluate to true, not to false in JS.</para></listitem>
</varlistentry>
<varlistentry>
<term>"labeled"</term>
<listitem><para>Returns the string "true" when true, "false", when false, or whichever custom strings have been specified (typically in a <checkbox>).</para></listitem>
</varlistentry>
<varlistentry>
<term>"true"</term>
<listitem><para>Return the string as if the property was true, even if it is false</para></listitem>
</varlistentry>
<varlistentry>
<term>"false"</term>
<listitem><para>Return the string as if the property was false, even if it is true</para></listitem>
</varlistentry>
<varlistentry>
<term>"not"</term>
<listitem><para>This actually returns another Boolean property, which is the reverse of the current (&ie; false if true, true if false)</para></listitem>
</varlistentry>
<varlistentry>
<term>"numeric"</term>
<listitem><para>Obsolete, provided for backwards compatibility. Same as no modifier "". Return "1" if the property is true, or "0" if it is false.</para></listitem>
</varlistentry>
</variablelist></para></listitem>
</varlistentry>
<varlistentry>
<term>Integer properties</term>
<listitem><para>A property designed to hold an integer value (but of course it still returns a numeric character string to the JS-template). It does not accept any modifiers. Used in <spinbox>es (see below)</para></listitem>
</varlistentry>
<varlistentry>
<term>Real number properties</term>
<listitem><para>A property designed to hold a real number value (but of course it still returns a numeric character string to the JS-template). Used in <spinbox>es (see below)
<variablelist>
<varlistentry>
<term>No modifier ("")</term>
<listitem><para>For <function>getValue() / getString()</function>, this returns the same as "formatted". In future versions, it will be possible to obtain a numeric representation, instead.</para></listitem>
</varlistentry>
<varlistentry>
<term>"formatted"</term>
<listitem><para>Returns the formatted number (as a string).</para></listitem>
</varlistentry>
</variablelist></para></listitem>
</varlistentry>
<varlistentry>
<term>RObject properties</term>
<listitem><para>A property designed a selection of one or more &R; objects. Used most prominently in varselectors and varslots. The following values will be returned according to the given modifier:
<variablelist>
<varlistentry>
<term>No modifier ("")</term>
<listitem><para>By default the property will return the full name of the selected object. If more than one object is selected, the object names will be separated by line breaks ("\n").</para></listitem>
</varlistentry>
<varlistentry>
<term>"shortname"</term>
<listitem><para>Like above, but returns only short name(s) for the object(s). For instance an object inside a list would only be given the name it has inside the list, without the name of the list.</para></listitem>
</varlistentry>
<varlistentry>
<term>"label"</term>
<listitem><para>Like above, but returns the &rkward; label(s) of the object(s) (if no label available, this is the same as shortname)</para></listitem>
</varlistentry>
</variablelist></para></listitem>
</varlistentry>
<varlistentry>
<term>String list properties</term>
<listitem><para>This property holds a list of strings.
<variablelist>
<varlistentry>
<term>No modifier ("")</term>
<listitem><para>For <function>getValue()/getString()</function>, this returns all strings separated by "\n". Any "\n" characters in each item are escaped as literal "\n". However, the recommended usage is to fetch the value with <function>getList()</function>, instead, which will return an array of strings.</para></listitem>
</varlistentry>
<varlistentry>
<term>"joined"</term>
<listitem><para>Returns the list as a single string, with items joined by "\n". In contrast to no modifier (""), the individual strings are _not_ escaped.</para></listitem>
</varlistentry>
</variablelist></para></listitem>
</varlistentry>
<varlistentry>
<term>Code properties</term>
<listitem><para>A property held by plugins that generated code. This is important for embedding plugins, in order to embed the code generated by the embedded plugin into the code generated by the embedding (top-level) plugin. The following values will be returned according to the given modifier:
<variablelist>
<varlistentry>
<term>No modifier ("")</term>
<listitem><para>Returns the full code, &ie; the sections "preprocess", "calculate", "printout", and (but not "preview") concatenated to one string.</para></listitem>
</varlistentry>
<varlistentry>
<term>"preprocess"</term>
<listitem><para>Returns only the preprocess section of the code</para></listitem>
</varlistentry>
<varlistentry>
<term>"calculate"</term>
<listitem><para>Returns only the calculate section of the code</para></listitem>
</varlistentry>
<varlistentry>
<term>"printout"</term>
<listitem><para>Returns only the printout section of the code</para></listitem>
</varlistentry>
<varlistentry>
<term>"preview"</term>
<listitem><para>Returns the preview section of the code</para></listitem>
</varlistentry>
</variablelist></para></listitem>
</varlistentry>
</variablelist>
</sect1>
<sect1 id="globalxmlelements">
<title>General purpose elements to be used in any &XML; file (<literal role="extension">.xml</literal>, <literal role="extension">.rkh</literal>, &pluginmap;)</title>
<variablelist>
<varlistentry>
<term><snippets></term>
<listitem><para>Allowed as a direct child of the <document> node and only there. Should be placed near the top of the file. See <link linkend="snippets">section on using snippets</link>. Only one <snippets> element may be present. Optional, no attributes.</para></listitem>
</varlistentry>
<varlistentry>
<term><snippet></term>
<listitem><para>Defines a single snippet. Allowed only as a direct child of the <snippets/> element. Attributes:
<variablelist>
<varlistentry>
<term><id></term>
<listitem><para>An identifier string for the snippet. Required.</para></listitem>
</varlistentry>
</variablelist></para></listitem>
</varlistentry>
<varlistentry>
<term><insert></term>
<listitem><para>Insert the contents of a <snippet>. Allowed anywhere. Attributes:
<variablelist>
<varlistentry>
<term><snippet></term>
<listitem><para>The identifier string of the snippet to insert. Required.</para></listitem>
</varlistentry>
</variablelist></para></listitem>
</varlistentry>
<varlistentry>
<term><include></term>
<listitem><para>Include the contents of another &XML; file (everything inside the <document> element of that file). Allowed anywhere. Attributes:
<variablelist>
<varlistentry>
<term><file></term>
<listitem><para>The filename, relative to the directory, the current file is in. Required.</para></listitem>
</varlistentry>
</variablelist></para></listitem>
</varlistentry>
</variablelist>
</sect1>
<sect1 id="xmlelements"><title>Elements to be used in the &XML; description of the plugin</title>
<para>Properties held by the elements are listed in a <link linkend="elementproperties">separate section</link>.</para>
<sect2 id="generalelements"><title>General elements</title>
<variablelist>
<varlistentry>
<term><document></term>
<listitem><para>Needs to be present in each description.xml-file as the root-node. No special function. No attributes</para></listitem>
</varlistentry>
<varlistentry>
<term><about></term>
<listitem><para>Information about this plugin (author, licence, &etc;). This element is allowed in both an individual plugin's <literal role="extension">.xml</literal> file, and in &pluginmap; files. Refer to the <link linkend="pluginmapelements">&pluginmap; file reference</link> for reference details, <link linkend="chapter_about_information">the chapter on 'about' information</link> for an introduction.</para></listitem>
</varlistentry>
<varlistentry>
<term><code></term>
<listitem><para>Defines where to look for the JS template to the plugin. Use only once per file, as a direct child of the document-tag. Attributes:
<variablelist>
<varlistentry>
<term><parameter>file</parameter></term>
<listitem><para>Filename of the JS template, relative to the directory the plugin-xml is in</para></listitem>
</varlistentry>
</variablelist></para></listitem>
</varlistentry>
<varlistentry>
<term><help></term>
<listitem><para>Defines where to look for the help file for the plugin. Use only once per file, as a direct child of the document-tag. Attributes:
<variablelist>
<varlistentry>
<term><parameter>file</parameter></term>
<listitem><para>Filename of the help file, relative to the directory the plugin-xml is in</para></listitem>
</varlistentry>
</variablelist></para></listitem>
</varlistentry>
<varlistentry>
<term><copy></term>
<listitem><para>Can be used as a child (direct or indirect) of the main layout elements, &ie; <dialog> and <wizard>. This is used to copy an entire block a &XML; elements 1:1. Attributes:
<variablelist>
<varlistentry>
<term><parameter>id</parameter></term>
<listitem><para>The ID to look for. The <copy> tag will look for a previous &XML; element that has been given the same ID, and copy it including all descendant elements.</para></listitem>
</varlistentry>
<varlistentry>
<term><parameter>copy_element_tag_name</parameter></term>
<listitem><para>In some few cases, you will want an almost literal copy, but change the tag-name of the element to copy. The most important example of this is, when you want to copy an entire <tab> from a dialog interface to the <page> of a wizard interface. In this case, you would set copy_element_tag_name="page" to do this conversion automatically.</para></listitem>
</varlistentry>
</variablelist></para></listitem>
</varlistentry>
</variablelist>
</sect2>
<sect2 id="interfaceelements"><title>Interface definitions</title>
<variablelist>
<varlistentry>
<term><dialog></term>
<listitem><para>Defines a dialog-type interface. Place the &GUI; definition inside this tag. Use only once per file, as a direct child of the document-tag. At least one of "dialog" or "wizard" tags is required for a plugin. Attributes:
<variablelist>
<varlistentry>
<term><parameter>label</parameter></term>
<listitem><para>Caption for the dialog</para></listitem>
</varlistentry>
<varlistentry>
<term><parameter>recommended</parameter></term>
<listitem><para>Should the dialog be used as the "recommended" interface (&ie; the interface that will be shown by default, unless the user has configured &rkward; to default to a specific interface)? This attribute does not currently have an effect, as it is implicitly "true", unless the wizard is recommended.</para></listitem>
</varlistentry>
</variablelist></para></listitem>
</varlistentry>
<varlistentry>
<term><wizard></term>
<listitem><para>Defines a wizard-type interface. Place the &GUI; definition inside this tag. Use only once per file, as a direct child of the document-tag. At least one of "dialog" or "wizard" tags is required for a plugin. Accepts only <page> or <embed>-tags as direct children. Attributes:
<variablelist>
<varlistentry>
<term><parameter>label</parameter></term>
<listitem><para>Caption for the wizard</para></listitem>
</varlistentry>
<varlistentry>
<term><parameter>recommended</parameter></term>
<listitem><para>Should the wizard be used as the "recommended" interface (&ie; the interface that will be shown by default, unless the user has configured &rkward; to default to a specific interface)? Optional, defaults to "false".</para></listitem>
</varlistentry>
</variablelist></para></listitem>
</varlistentry>
</variablelist>
</sect2>
<sect2 id="layoutelements"><title>Layout elements</title>
<para>All elements in this section accept an attribute id="identifierstring". This attribute is optional for all elements. It can be used, for example, to hide/disable the entire layout element and all the elements contained therein (see <link linkend="logic">chapter &GUI; logic</link>). The id-string may not contain "." (dot) or ";" (semicolon), and should generally be limited to alphanumeric characters and the underscore ("_"). Only the additional attributes are listed.</para>
<variablelist>
<varlistentry>
<term><page></term>
<listitem><para>Defines a new page inside a wizard. Only allowed as a direct child of a <wizard> element.</para></listitem>
</varlistentry>
<varlistentry>
<term><row></term>
<listitem><para>All direct children of a "row" tag will be placed left-to-right.</para></listitem>
</varlistentry>
<varlistentry>
<term><column></term>
<listitem><para>All direct children of a "column" tag will be placed top-to-bottom.</para></listitem>
</varlistentry>
<varlistentry>
<term><stretch></term>
<listitem><para>By default, elements in the &GUI; take up all the space that is available. For instance, if you have two columns side by side, the left one is packed with elements, but the right one only contains a lonely <command><radio></command>, the <command><radio></command> control will expand vertically, even though it does not really need the available space, and it will look ugly. In this case you really want to add a "blank" below the <command><radio></command>. For this, use the <stretch> element. It will simply use up some space. Do not overuse this element, usually it is a good idea for &GUI; elements to get all the available space, only sometimes will the layout become spaced out. The <stretch> element does not take any arguments, not even an "id". Also you can place no children inside the <stretch> element (in other words, you will only ever use it as "<stretch/>")</para></listitem>
</varlistentry>
<varlistentry>
<term><frame></term>
<listitem><para>Draws a frame/box around its direct children. Can be used to visually group related options. Layout inside a frame is top-to-bottom, unless you place a <row> inside. Attributes:
<variablelist>
<varlistentry>
<term><parameter>label</parameter></term>
<listitem><para>Caption for the frame (optional)</para></listitem>
</varlistentry>
<varlistentry>
<term><parameter>checkable</parameter></term>
<listitem><para>Frames can be made checkable. In this case, all contained elements will be disabled when the frame is unchecked, and enabled, when it is checked. (optional, defaults to "false")</para></listitem>
</varlistentry>
<varlistentry>
<term><parameter>checked</parameter></term>
<listitem><para>For checkable frames only: Should the frame be checked by default? Defaults to "true". Not interpreted for non-checkable frames.</para></listitem>
</varlistentry>
</variablelist></para></listitem>
</varlistentry>
<varlistentry>
<term><tabbook></term>
<listitem><para>Organizes elements in a tabbook. Accepts only <tab>-tags as direct children.</para></listitem>
</varlistentry>
<varlistentry>
<term><tab></term>
<listitem><para>Defines a page in a tabbook. Place the &GUI; definition for the tab inside this tag. May be used only as a direct child of a <tabbook> tag. A <tabbook> should have at least two defined tabs. Attributes:
<variablelist>
<varlistentry>
<term><parameter>label</parameter></term>
<listitem><para>Caption for the tab page (required)</para></listitem>
</varlistentry>
</variablelist></para></listitem>
</varlistentry>
<varlistentry>
<term><text></term>
<listitem><para>Shows the text enclosed in this tag in the &GUI;. Some simple &HTML; style markup is supported (notably <markup><b></markup>, <markup><i></markup>, <markup><p></markup>, and <markup><br/></markup>). Please keep formatting to a minimum, however. Inserting a completely empty line adds a hard line break. Attributes:
<variablelist>
<varlistentry>
<term><parameter>type</parameter></term>
<listitem><para>Type of the text. One of "normal", "warning" or "error". This influences the look of the text (optional, defaults to normal)</para></listitem>
</varlistentry>
</variablelist></para></listitem>
</varlistentry>
</variablelist>
</sect2>
<sect2 id="activeelements"><title>Active elements</title>
<para>All elements in this section accept an attribute id="identifierstring". This attribute is required for all elements. Only the additional attributes are listed. The id-string may not contain "." (dots).</para>
<variablelist>
<varlistentry>
<term><varselector></term>
<listitem><para>Provides a list of available objects from which the user can select one or more. Requires one or more <varslot>s as a counterpart to be useful. Attributes:
<variablelist>
<varlistentry>
<term><parameter>label</parameter></term>
<listitem><para>Label for the varselector (optional, defaults to "Select variable(s)")</para></listitem>
</varlistentry>
</variablelist></para></listitem>
</varlistentry>
<varlistentry>
<term><varslot></term>
<listitem><para>Used in conjunction with a "varselector" to allow the user to select one or more variables. Attributes:
<variablelist>
<varlistentry>
<term><parameter>label</parameter></term>
<listitem><para>Label for the varslot (recommended, defaults to "Variable:")</para></listitem>
</varlistentry>
<varlistentry>
<term><parameter>source</parameter></term>
<listitem><para>The varselector to fetch the selection from (required, unless you connect manually or using source_property)</para></listitem>
</varlistentry>
<varlistentry>
<term><parameter>source_property</parameter></term>
<listitem><para>An arbitrary property to copy values from, when the select button is clicked. If specified, this overrides the "source"-attribute.</para></listitem>
</varlistentry>
<varlistentry>
<term><parameter>required</parameter></term>
<listitem><para>Whether - for submitting the code - it is required that this varslot holds a valid value. See <link linkend="elementproperties">required-property</link> (optional, defaults to false)</para></listitem>
</varlistentry>
<varlistentry>
<term><parameter>multi</parameter></term>
<listitem><para>Whether the varslot holds only one (default, "false"), or several objects</para></listitem>
</varlistentry>
<varlistentry>
<term><parameter>allow_duplicates</parameter></term>
<listitem><para>Whether the varslot may accept only unique objects (default, "false"), or if the same object may be added several times.</para></listitem>
</varlistentry>
<varlistentry>
<term><parameter>min_vars</parameter></term>
<listitem><para>Only meaningful if multi="true": Minimum number of vars to be selected for the selection to be considered valid (optional, defaults to "1")</para></listitem>
</varlistentry>
<varlistentry>
<term><parameter>min_vars_if_any</parameter></term>
<listitem><para>Only meaningful if multi="true": Some varslots may be considered valid, if, for instance, the varslot is either empty, or holds at least two values. This specifies how many variables have to be selected if any at all (2 in the example). (optional, defaults to "1")</para></listitem>
</varlistentry>
<varlistentry>
<term><parameter>max_vars</parameter></term>
<listitem><para>Only meaningful if multi="true": Maximum number of variables to select (optional, defaults to "0", which means no maximum)</para></listitem>
</varlistentry>
<varlistentry>
<term><parameter>classes</parameter></term>
<listitem><para>If you specify one or more &R; classnames (separated by spaces (" ")), here, the varslot will only accept objects belonging to those classes (optional, <emphasis>use with great care</emphasis>, the user should not be prevented from making valid choices, and &R; has <emphasis>a lot</emphasis> of different classes)</para></listitem>
</varlistentry>
<varlistentry>
<term><parameter>types</parameter></term>
<listitem><para>If you specify one or more variables types (separated by spaces (" ")), here, the varslot will only accept objects of those types. Valid types are "unknown", "number", "string", "factor", "invalid". (Optional, <emphasis>use with great care</emphasis>, the user should not be prevented from making valid choices, and &rkward; does not always know the type of a variable)</para></listitem>
</varlistentry>
<varlistentry>
<term><parameter>num_dimensions</parameter></term>
<listitem><para>The number of dimensions, an object needs to have. "0" (the default) means, any number of dimensions is acceptable. (optional, defaults to "0")</para></listitem>
</varlistentry>
<varlistentry>
<term><parameter>min_length</parameter></term>
<listitem><para>The minimum length, an object needs to have in order to be acceptable. (optional, defaults to "0")</para></listitem>
</varlistentry>
<varlistentry>
<term><parameter>max_length</parameter></term>
<listitem><para>The maximum length, an object needs to have in order to be acceptable. (optional, defaults to the largest integer number representable on the system)</para></listitem>
</varlistentry>
</variablelist></para></listitem>
</varlistentry>
<varlistentry>
<term><valueselector></term>
<listitem><para>Provides a list of available strings (not &R; objects) to be selected in one or more accompanying <valueslot>s. String options can be defined using <option>-tags as direct children (see below), or set using dynamic <link linkend="elementproperties">properties</link>. Attributes:
<variablelist>
<varlistentry>
<term><parameter>label</parameter></term>
<listitem><para>Label for the valueselector (optional, defaults to no label)</para></listitem>
</varlistentry>
</variablelist></para></listitem>
</varlistentry>
<varlistentry>
<term><valueslot></term>
<listitem><para>Used in conjunction with a <valueselector> to allow the user to select one or more string items. This element is mostly identical to <varslot>, and shares the same attributes, except for those which refer to properties of the acceptable items (&ie; classes, types, num_dimensions, min_length, max_length).</para></listitem>
</varlistentry>
<varlistentry>
<term><radio></term>
<listitem><para>Defines a group of radio-exclusive buttons (only one can be selected at a time). Requires at least two <option>-tags as direct children. No other tags are allowed as children. Attributes:
<variablelist>
<varlistentry>
<term><parameter>label</parameter></term>
<listitem><para>Label for the radio control (recommended, defaults to "Select one:")</para></listitem>
</varlistentry>
</variablelist></para></listitem>
</varlistentry>
<varlistentry>
<term><dropdown></term>
<listitem><para>Defines a group of options of which one and only one can be selected at the same time, using a dropdown list. This is functionally equivalent to a <radio>, but looks different. Requires at least two <option>-tags as direct children. No other tags are allowed as children. Attributes:
<variablelist>
<varlistentry>
<term><parameter>label</parameter></term>
<listitem><para>Label for the dropdown list (recommended, defaults to "Select one:")</para></listitem>
</varlistentry>
</variablelist></para></listitem>
</varlistentry>
<varlistentry>
<term><select></term>
<listitem><para>Provides a list of available strings from which the user can select an arbitrary number. String options can be defined using <option>-tags as direct children (see below), or set using dynamic <link linkend="elementproperties">properties</link>. Attributes:
<variablelist>
<varlistentry>
<term><parameter>label</parameter></term>
<listitem><para>Label for the <select> (optional, defaults to no label)</para></listitem>
</varlistentry>
<varlistentry>
<term><parameter>single</parameter></term>
<listitem><para>If set to true, only a single value will be selectable, instead of multiple values at once (boolean, defaults to false)</para></listitem>
</varlistentry>
</variablelist></para></listitem>
</varlistentry>
<varlistentry>
<term><option></term>
<listitem><para>Can only be used as a direct child of a <radio>, <dropdown>, <valueselector> or <select> element. Represents one selectable option in a radio control or dropdown list. As <option> elements are always part of one of the selection elements, they do not normally
have an "id" of their own, but see below. Attributes:
<variablelist>
<varlistentry>
<term><parameter>label</parameter></term>
<listitem><para>Label for the option (required)</para></listitem>
</varlistentry>
<varlistentry>
<term><parameter>value</parameter></term>
<listitem><para>The string value the parent element will return if this option is checked/selected (required)</para></listitem>
</varlistentry>
<varlistentry>
<term><parameter>checked</parameter></term>
<listitem><para>Whether the option should be checked/selected by default "true" or "false". In a <radio> or <dropdown>, only one option may be set to <parameter>checked=</parameter><replaceable>"true"</replaceable>, and if no option is set to checked, the first option in the parent element will be checked/selected automatically. In a <select>, any number of options may be set to checked. (optional, default to "false")</para></listitem>
</varlistentry>
<varlistentry>
<term><parameter>id</parameter></term>
<listitem><para>Specifying the "id" parameter for the <option> elements is optional (and in fact it is recommended, not to set an "id", unless you really need one). However, specifying an "id" will allow you to enable/disable <option>s, dynamically, by connecting to the boolean property <replaceable>id_of_radio.id_of_optionX.enabled</replaceable>. Currently this works for options inside <radio> or <dropdown>
elements, only; <valueselector> and <select> options do not currently support ids.</para></listitem>
</varlistentry>
</variablelist></para></listitem>
</varlistentry>
<varlistentry>
<term><checkbox></term>
<listitem><para>Defines a check box, &ie; a single option that can either be set to on or off. Attributes:
<variablelist>
<varlistentry>
<term><parameter>label</parameter></term>
<listitem><para>Label for the check box (required)</para></listitem>
</varlistentry>
<varlistentry>
<term><parameter>value</parameter></term>
<listitem><para>The value the check box will return if checked (required)</para></listitem>
</varlistentry>
<varlistentry>
<term><parameter>value_unchecked</parameter></term>
<listitem><para>The value that will be returned if the check box is not checked (optional, defaults to "", &ie; an empty string)</para></listitem>
</varlistentry>
<varlistentry>
<term><parameter>checked</parameter></term>
<listitem><para>Whether the option should be checked by default "true" or "false" (optional, default to "false")</para></listitem>
</varlistentry>
</variablelist></para></listitem>
</varlistentry>
<varlistentry>
<term><frame></term>
<listitem><para>The frame element is generally used as a pure layout element, and is listed in the section on <link linkend="layoutelements">layout elements</link>. However, it can also be
made checkable, thus acting like a simple check box at the same time.
</para></listitem>
</varlistentry>
<varlistentry>
<term><input></term>
<listitem><para>Defines a free text input field. Attributes:
<variablelist>
<varlistentry>
<term><parameter>label</parameter></term>
<listitem><para>Label for the input field (required)</para></listitem>
</varlistentry>
<varlistentry>
<term><parameter>initial</parameter></term>
<listitem><para>Initial text of the text field (optional, defaults to "", &ie; an empty string)</para></listitem>
</varlistentry>
<varlistentry>
<term><parameter>size</parameter></term>
<listitem><para>One of "small", "medium", or "large". "large" defines a multi-line input field, "small", and "medium" are single line fields (optional, defaults to "medium")</para></listitem>
</varlistentry>
<varlistentry>
<term><parameter>required</parameter></term>
<listitem><para>Whether - for submitting the code - it is required that this input is not empty. See <link linkend="elementproperties">required-property</link> (optional, defaults to false)</para></listitem>
</varlistentry>
</variablelist></para></listitem>
</varlistentry>
<varlistentry>
<term><matrix></term>
<listitem><para>A table for entering matrix data (or vectors) in the &GUI;.</para> <note><para>This input element is <emphasis>not</emphasis> optimized for entering/editing large amounts of data. While there is no strict limit on the size of a <matrix>, in general it should not exceed around ten rows / columns. If you expect larger data, allow users to select it as an &R; object (which may be a good idea as an alternative option, in almost <emphasis>every</emphasis> instance where you use a matrix element).</para></note> <para>Attributes:
<variablelist>
<varlistentry>
<term><parameter>label</parameter></term>
<listitem><para>Label for the table (required)</para></listitem>
</varlistentry>
<varlistentry>
<term><parameter>mode</parameter></term>
<listitem><para>One of "integer", "real", or "string". The type of data that will be accepted in the table (required)</para></listitem>
</varlistentry>
<varlistentry>
<term><parameter>min</parameter></term>
<listitem><para>Minimum acceptable value (for matrices of type "integer" or "real") (optional, defaults to the smallest representable value)</para></listitem>
</varlistentry>
<varlistentry>
<term><parameter>max</parameter></term>
<listitem><para>Maximum acceptable value (for matrices of type "integer" or "real") (optional, defaults to the largest representable value)</para></listitem>
</varlistentry>
<varlistentry>
<term><parameter>allow_missings</parameter></term>
<listitem><para>Whether missing (empty) values are allowed in the matrix. This is implied for matrices or mode "string" (optional, defaults to false).</para></listitem>
</varlistentry>
<varlistentry>
<term><parameter>allow_user_resize_columns</parameter></term>
<listitem><para>When set to true, the user can add columns by typing on the rightmost (inactive) cells (optional, defaults to true).</para></listitem>
</varlistentry>
<varlistentry>
<term><parameter>allow_user_resize_rows</parameter></term>
<listitem><para>When set to true, the user can add rows by typing on the bottommost (inactive) cells (optional, defaults to true).</para></listitem>
</varlistentry>
<varlistentry>
<term><parameter>rows</parameter></term>
<listitem><para>Number of rows in the matrix. Has no effect for allow_user_resize_rows="true". <note><para>This can also be controlled by setting the "rows" property.</para></note> (optional, defaults to 2).</para></listitem>
</varlistentry>
<varlistentry>
<term><parameter>columns</parameter></term>
<listitem><para>Number of columns in the matrix. Has no effect for allow_user_resize_columns="true". <note><para>This can also be controlled by setting the "columns" property.</para></note> (optional, defaults to 2).</para></listitem>
</varlistentry>
<varlistentry>
<term><parameter>min_rows</parameter></term>
<listitem><para>Minimum number of rows in the matrix. The matrix will refuse shrink below this size. (optional, defaults to 0; see also: <parameter>allow_missings</parameter>.).</para></listitem>
</varlistentry>
<varlistentry>
<term><parameter>min_columns</parameter></term>
<listitem><para>Minimum number of columns in the matrix. The matrix will refuse shrink below this size. (optional, defaults to 0; see also: <parameter>allow_missings</parameter>.).</para></listitem>
</varlistentry>
<varlistentry>
<term><parameter>fixed_height</parameter></term>
<listitem><para>Force the &GUI; element to stay at its initial height. Do not use in combination with matrices, where the number of rows may change in any way. Useful, esp. when creating a vector input element (columns="1"). With this option set to true, no horizontal scroll bar will be shown, even in the matrix exceeds the available width (as this would affect the height). (optional, defaults to false).</para></listitem>
</varlistentry>
<varlistentry>
<term><parameter>fixed_width</parameter></term>
<listitem><para>Slightly misnamed: Assume the column count will not change. The last (or typically only) column will be stretched to take up the available width. Do not use in combination with matrices, where the number of columns may change in any way. Useful, esp. when creating a vector input element (rows="1"). (optional, defaults to false).</para></listitem>
</varlistentry>
<varlistentry>
<term><parameter>horiz_headers</parameter></term>
<listitem><para>Strings to use for the horizontal header, separated by ";". The header will be hidden, if set to "". (optional, defaults to column number).</para></listitem>
</varlistentry>
<varlistentry>
<term><parameter>vert_headers</parameter></term>
<listitem><para>Strings to use for the vertical header, separated by ";". The header will be hidden, if set to "". (optional, defaults to row number).</para></listitem>
</varlistentry>
</variablelist></para></listitem>
</varlistentry>
<varlistentry>
<term><optionset></term>
<listitem><para>A UI for repeating a set of options for an arbitrary number of items (<link linkend="optionset">introduction to optionsets</link>). Attributes:</para>
<variablelist>
<varlistentry>
<term><parameter>min_rows</parameter></term>
<listitem><para>If specified, the set will be marked invalid, unless it has at least this number of rows (optional, integer).</para></listitem>
</varlistentry>
<varlistentry>
<term><parameter>min_rows_if_any</parameter></term>
<listitem><para>Like min_rows, but will only be tested, if there is at least one row (optional, integer).</para></listitem>
</varlistentry>
<varlistentry>
<term><parameter>max_rows</parameter></term>
<listitem><para>If specified, the set will be marked invalid, unless it has at most this number of rows (optional, integer).</para></listitem>
</varlistentry>
<varlistentry>
<term><parameter>keycolumn</parameter></term>
<listitem><para>Id of the column to act as keycolumn. An optionset with a (valid) keycolumn will act as a "driven" optionset. An optionset with no keycolumn will allow manual insertion / removal of items. The keycolumn must be marked as external. (optional, defaults to no keycolumn).</para></listitem>
</varlistentry>
</variablelist>
<para>Child-elements:</para>
<variablelist>
<varlistentry>
<term><optioncolumn></term>
<listitem><para>Declares one optioncolumn of the set. For each value that you want to fetch from the optionset, you must declare a separate <optioncolumn>. Attributes:
<variablelist>
<varlistentry><term><parameter>id</parameter></term>
<listitem><para>The id of the optioncolumn (required, string).</para></listitem></varlistentry>
<varlistentry><term><parameter>external</parameter></term>
<listitem><para>Set to true, if the optioncolumn is controlled from outside the optionset (optional, boolean, defaults to false).</para></listitem></varlistentry>
<varlistentry><term><parameter>label</parameter></term>
<listitem><para>If given, the optioncolumn will be displayed in a column by that label (optional, string, defaults to not displayed).</para></listitem></varlistentry>
<varlistentry><term><parameter>connect</parameter></term>
<listitem><para>The property to connect this optioncolumn to, given as id inside the <content>-area. For external <optioncolumn>s, the corresponding value will be set to the externally set value. For regular (non-external) <optioncolumn>s,
the corresponding row of the <optioncolumn>-property, will be set when the property changes inside the content-area. (optional, string, defaults to not connected).</para></listitem></varlistentry>
<varlistentry><term><parameter>default</parameter></term>
<listitem><para>Only for external columns: The value to assume for this column, if no value is known for an entry. Rarely useful. (Optional, defaults to empty string)</para></listitem></varlistentry>
</variablelist>
</para></listitem></varlistentry>
<varlistentry>
<term><content></term>
<listitem><para>Declare the content / UI of the set. No attributes. All usual active, passive, and layout elements are allowed as childname elements. In addition, in earlier versions of &rkward; (up to 0.6.3), the special child-element <command><optiondisplay></command> was allowed. This is obsolete in &rkward; 0.6.4, and should simply be removed from existing plugins.
</para></listitem></varlistentry>
<varlistentry>
<term><logic></term>
<listitem><para>Optional specification of UI logic to apply <emphasis>inside</emphasis> the contents region the optionset. See <link linkend="logicelements">the reference on <logic></link>
</para></listitem></varlistentry>
</variablelist>
</listitem>
</varlistentry>
<varlistentry>
<term><browser></term>
<listitem><para>An element designed to select a single filename (or directory name). Note that this field will take any string, even though it is meant to be used for files, only:
<variablelist>
<varlistentry>
<term><parameter>label</parameter></term>
<listitem><para>Label for the browser (optional, defaults to "Enter filename")</para></listitem>
</varlistentry>
<varlistentry>
<term><parameter>initial</parameter></term>
<listitem><para>Initial text of the browser (optional, defaults to "", &ie; an empty string)</para></listitem>
</varlistentry>
<varlistentry>
<term><parameter>type</parameter></term>
<listitem><para>One of "file", "dir", or "savefile". To select an existing file, existing directory, or non-existing file, respectively (optional, defaults to "file")</para></listitem>
</varlistentry>
<varlistentry>
<term><parameter>allow_urls</parameter></term>
<listitem><para>Whether (non-local) &URL;s can be selected (optional, defaults to "false")</para></listitem>
</varlistentry>
<varlistentry>
<term><parameter>filter</parameter></term>
<listitem><para>File type filter, ⪚ ("*.txt *.csv" for .txt and .csv files). A separate entry for "All files" is added, automatically (optional, defaults to "", &ie; All files)</para></listitem>
</varlistentry>
<varlistentry>
<term><parameter>required</parameter></term>
<listitem><para>Whether - for submitting the code - it is required that the field is not empty. Note that this does not necessarily mean that the selected filename is valid. See <link linkend="elementproperties">required-property</link> (optional, defaults to true)</para></listitem>
</varlistentry>
</variablelist></para></listitem>
</varlistentry>
<varlistentry>
<term><saveobject></term>
<listitem><para>An element designed to select the name of an &R; object to save to (&ie; generally not already existing, in contrast to a varslot):
<variablelist>
<varlistentry>
<term><parameter>label</parameter></term>
<listitem><para>Label for the input (optional, defaults to "Save to:")</para></listitem>
</varlistentry>
<varlistentry>
<term><parameter>initial</parameter></term>
<listitem><para>Initial text of the input (optional, defaults to "my.data")</para></listitem>
</varlistentry>
<varlistentry>
<term><parameter>required</parameter></term>
<listitem><para>Whether - for submitting the code - it is required that the field holds a permissible object name. See <link linkend="elementproperties">required-property</link> (optional, defaults to true)</para></listitem>
</varlistentry>
<varlistentry>
<term><parameter>checkable</parameter></term>
<listitem><para>In many use cases, saving to an &R; object is optional. In these cases, a check box can be integrated into the saveobject-element using this attribute. When set to true, the saveobject will be activated / deactivated by the check box. See the <link linkend="elementproperties">active-property</link> of saveobject (optional, defaults to false)</para></listitem>
</varlistentry>
<varlistentry>
<term><parameter>checked</parameter></term>
<listitem><para>For checkable saveobject-elements, only: Whether the control is checked/enabled by default (optional, defaults to false)</para></listitem>
</varlistentry>
</variablelist></para></listitem>
</varlistentry>
<varlistentry>
<term><spinbox></term>
<listitem><para>A spinbox in which the user can select a numeric value, using either direct keyboard input or small up/down arrows. Attributes:
<variablelist>
<varlistentry>
<term><parameter>label</parameter></term>
<listitem><para>Label for the spinbox (recommend, default to "Enter value:")</para></listitem>
</varlistentry>
<varlistentry>
<term><parameter>min</parameter></term>
<listitem><para>The lowest value the user is allowed to enter in the spinbox (optional, defaults to the lowest value technically representable in the spinbox)</para></listitem>
</varlistentry>
<varlistentry>
<term><parameter>max</parameter></term>
<listitem><para>The largest value the user is allowed to enter in the spinbox (optional, defaults to the highest value technically representable in the spinbox)</para></listitem>
</varlistentry>
<varlistentry>
<term><parameter>initial</parameter></term>
<listitem><para>The initial value shown in the spinbox (optional, defaults to "0")</para></listitem>
</varlistentry>
<varlistentry>
<term><parameter>type</parameter></term>
<listitem><para>One of "real" or "integer". Whether the spinbox will accept real numbers or only integers (optional, defaults to "real")</para></listitem>
</varlistentry>
<varlistentry>
<term><parameter>default_precision</parameter></term>
<listitem><para>Only meaningful if the spinbox is of type="real". Specifies the default number of decimal places shown in the spinbox (only this many trailing zeros will be shown). When the user presses the up/down arrows, this decimal place will be changed. The user may still be able to enter values with a higher precision, however (see below) (optional, defaults to "2")</para></listitem>
</varlistentry>
<varlistentry>
<term><parameter>max_precision</parameter></term>
<listitem><para>The maximum number of digits that can be meaningfully represented (optional, defaults to "8")</para></listitem>
</varlistentry>
</variablelist></para></listitem>
</varlistentry>
<varlistentry>
<term><formula></term>
<listitem><para>This advanced element allows the user to select a formula/set of interactions from selected variables. For instance for a GLM, this element can be used to allow the user to specify the interaction-terms in the model. Attributes:
<variablelist>
<varlistentry>
<term><parameter>fixed_factors</parameter></term>
<listitem><para>The ID of the varslot holding the selected fixed factors (required)</para></listitem>
</varlistentry>
<varlistentry>
<term><parameter>dependent</parameter></term>
<listitem><para>The ID of the varslot holding the selected dependent variable (required)</para></listitem>
</varlistentry>
</variablelist></para></listitem>
</varlistentry>
<varlistentry>
<term><embed></term>
<listitem><para>Embed a different plugin into this one (see <link linkend="embedding">chapter on embedding</link>). Attributes:
<variablelist>
<varlistentry>
<term><parameter>component</parameter></term>
<listitem><para>The registered name of the component to embed (see <link linkend="pluginmap">chapter on registering components</link>) (required)</para></listitem>
</varlistentry>
<varlistentry>
<term><parameter>as_button</parameter></term>
<listitem><para>If set to "true", only a pushbutton will be placed in the embedding &GUI;, the embedded &GUI; will only be shown (in a separate window) when the pushbutton is pressed (optional, default is "false")</para></listitem>
</varlistentry>
<varlistentry>
<term><parameter>label</parameter></term>
<listitem><para>Only meaningful if as_button="true": The label of the button (recommend, default is "Options")</para></listitem>
</varlistentry>
</variablelist></para></listitem>
</varlistentry>
<varlistentry>
<term><preview></term>
<listitem><para>Checkbox to toggle preview functionality. Note that starting with version 0.6.5 of &rkward; <command><preview></command> preview elements are special-
cased in plugin dialogs (not wizards): They will be placed in the button-column, irrespective of where exactly they are defined in the UI. It is still a good idea to
define them at a sensible place in the layout, for backwards compatibility. Attributes:
<variablelist>
<varlistentry>
<term><parameter>label</parameter></term>
<listitem><para>Label of the box (optional, default is "Preview")</para></listitem>
</varlistentry>
<varlistentry>
<term><parameter>mode</parameter></term>
<listitem><para>Type of preview. Supported types are "plot" (see <link linkend="preview_plots">chapter on graph previews</link>), "output" (see <link linkend="preview_output">chapter on (&HTML;) output previews</link>), "data" (see <link linkend="preview_data">data previews</link>), and "custom" (see <link linkend="preview_custom">custom previews</link>). (optional, default is "plot")</para></listitem>
</varlistentry>
<varlistentry>
<term><parameter>placement</parameter></term>
<listitem><para>Placement of the preview: "attached" (to the main workplace), "detached" (standalone window), "docked" (attached to the plugin dialog) and "default" (currently this is the same as "docked", but might become user-configurable at some point). In general, it is recommended to leave this as the default setting for best UI-consistency (optional, default is "default")</para></listitem>
</varlistentry>
<varlistentry>
<term><parameter>active</parameter></term>
<listitem><para>Whether the preview is active by default. In general, only docked previews should be made active by default, and even for these, there is a reason why the default is in-active previews (optional, default is "false")</para></listitem>
</varlistentry>
</variablelist></para></listitem>
</varlistentry>
</variablelist>
</sect2>
<sect2 id="logicelements"><title>Logic section</title>
<variablelist>
<varlistentry>
<term><logic></term>
<listitem><para>The containing element for the logic section. All elements below are allowed only inside the <logic> element. The <logic> element is allowed only as a direct child of the <document> element (at most once per document), or of <optionset> elements (at most once per optionset). The document's logic section applies to both <dialog> and <wizard> GUIs in the same way.</para></listitem>
</varlistentry>
<varlistentry>
<term><external></term>
<listitem><para>Creates a new (string) property that is supposed to be connected to an outside property if the plugin gets embedded. See <link linkend="embedding_incomplete">section on "incomplete" plugins</link>. Attributes:
<variablelist>
<varlistentry>
<term><parameter>id</parameter></term>
<listitem><para>The ID of the new property (required)</para></listitem>
</varlistentry>
<varlistentry>
<term><parameter>default</parameter></term>
<listitem><para>The default string value of the new property, &ie; the value used, if the property is not connected to an outside property (optional, defaults to an empty string)</para></listitem>
</varlistentry>
</variablelist></para></listitem>
</varlistentry>
<varlistentry>
<term><i18n></term>
<listitem><para>Creates a new (string) property that is supposed to be provide an i18n'ed label. Attributes:
<variablelist>
<varlistentry>
<term><parameter>id</parameter></term>
<listitem><para>The ID of the new property (required)</para></listitem>
</varlistentry>
<varlistentry>
<term><parameter>label</parameter></term>
<listitem><para>The label. This will be translated. (required)</para></listitem>
</varlistentry>
</variablelist></para></listitem>
</varlistentry>
<varlistentry>
<term><set></term>
<listitem><para>Set a property to a fixed value (of course, if you additionally connect the property to some other property, the value does not remain fixed). For instance, if you embed a plugin, but want to hide some of its elements, you might set the visibility property of those elements to false. Useful esp. for embedded/embedding plugins. Note: If there are several <set> elements
for a single <parameter>id</parameter>, the latest one to be defined takes precedence. This will sometimes be useful to rely on when using <include>d parts.
Attributes:
<variablelist>
<varlistentry>
<term><parameter>id</parameter></term>
<listitem><para>The ID of the property to set (required)</para></listitem>
</varlistentry>
<varlistentry>
<term><parameter>to</parameter></term>
<listitem><para>The string value to set the property to (required). Note: For boolean properties such as visibility, enabledness, you will typically set the to attribute to either to="true" or to="false".</para></listitem>
</varlistentry>
</variablelist></para></listitem>
</varlistentry>
<varlistentry>
<term><convert></term>
<listitem><para>Create a new boolean properties that depends on the state of one or more different properties. Attributes:
<variablelist>
<varlistentry>
<term><parameter>id</parameter></term>
<listitem><para>The ID of the new property (required)</para></listitem>
</varlistentry>
<varlistentry>
<term><parameter>sources</parameter></term>
<listitem><para>The ids of the properties this property will depend on. One or more properties may be specified, separated by ";" (required)</para></listitem>
</varlistentry>
<varlistentry>
<term><parameter>mode</parameter></term>
<listitem><para>The mode of conversion/operation. One of "equals", "notequals", "range", "and", "or". If in mode equals, the property will only be true, if the value of all of its sources equals the attribute standard (see below). If in at mode notequals, the property will only be true, if the value of all of its sources are different from the attribute standard (see below). If in mode range, the sources have to be numeric (integer or real). The property will only be true, if all sources are in the range specified by the attributes min and max (see below). If in mode and, the sources have to be boolean properties. The property will only be true, if all the sources are true simultaneously. If in mode or, the sources have to be boolean properties. The property will only be true, if at least one of the sources is true. (required)</para></listitem>
</varlistentry>
<varlistentry>
<term><parameter>standard</parameter></term>
<listitem><para>Only meaningful in modes equals or notequals: the string value to compare against (required if in one of these modes)</para></listitem>
</varlistentry>
<varlistentry>
<term><parameter>min</parameter></term>
<listitem><para>Only meaningful in mode range: the minimum value to compare against (optional, defaults to the lowest floating point number representable on the machine)</para></listitem>
</varlistentry>
<varlistentry>
<term><parameter>max</parameter></term>
<listitem><para>Only meaningful in mode range: the maximum value to compare against (optional, defaults to the largest floating point number representable on the machine)</para></listitem>
</varlistentry>
<varlistentry>
<term><parameter>require_true</parameter></term>
<listitem><para>If set to "true", the property will become required, and will only be considered valid, if its state is true/on. Hence, if the property is false, it will block the <guibutton>Submit</guibutton> button (optional, defaults to "false").
<caution><para>If you use this, make sure the user can easily detect what is wrong, such as by showing an explanatory <text>.</para></caution></para></listitem>
</varlistentry>
</variablelist></para></listitem>
</varlistentry>
<varlistentry>
<term><switch></term>
<listitem><para>Create a new property that will relay to different target properties (or fixed strings) based on the value of a condition property. This allows to create logic similar to <function>if()</function> or <function>switch()</function> constructs. Attributes:</para>
<variablelist>
<varlistentry>
<term><parameter>id</parameter></term>
<listitem><para>The ID of the new property (required)</para></listitem>
</varlistentry>
<varlistentry>
<term><parameter>condition</parameter></term>
<listitem><para>The id of the condition property (required)</para></listitem>
</varlistentry>
</variablelist>
<para>Child elements:</para>
<variablelist>
<varlistentry>
<term><true></term>
<listitem><para>If the condition property is boolean, you can specify the two child elements <true> and <false> (and only these). (Required, if <false> is also given)</para></listitem>
</varlistentry>
<varlistentry>
<term><false></term>
<listitem><para>If the condition property is boolean, you can specify the two child elements <true> and <false> (and only these). (Required, if <true> is also given)</para></listitem>
</varlistentry>
<varlistentry>
<term><case></term>
<listitem><para>If the condition property is not boolean, you can supply an arbitrary number of <case>-elements, one for each
value of the condition property that you want to match (at least one such element is required, if the condition property is not boolean)</para></listitem>
</varlistentry>
<varlistentry>
<term><default></term>
<listitem><para>If the condition property is not boolean, the optional <default>-element, allows to specify the behavior, if no
<case> element is matches the value of the condition property (optional, allowed only once, in combination with one or more <case> elements).</para></listitem>
</varlistentry>
</variablelist>
<para>Child elements <true>, <false>, <case>, and <default> take the following attributes:</para>
<variablelist>
<varlistentry>
<term><parameter>standard</parameter></term>
<listitem><para>Only for <case>-elements: The value to match the condition property against (required, string).</para></listitem>
</varlistentry>
<varlistentry>
<term><parameter>fixed_value</parameter></term>
<listitem><para>A fixed string that should be supplied as the value of the <switch> property, if the current condition matches (required, if dynamic_value is not supplied).</para></listitem>
</varlistentry>
<varlistentry>
<term><parameter>dynamic_value</parameter></term>
<listitem><para>The <parameter>id</parameter> of the target property that should be supplied as the value of the <switch> property, if the current condition matches (required, if fixed_value is not supplied).</para></listitem>
</varlistentry>
</variablelist>
</listitem>
</varlistentry>
<varlistentry>
<term><connect></term>
<listitem><para>Connects two properties. The client property will be changed whenever the governor property changes (but not the other way around). Attributes:
<variablelist>
<varlistentry>
<term><parameter>client</parameter></term>
<listitem><para>The ID of the client property, &ie; the property that will be adjusted (required)</para></listitem>
</varlistentry>
<varlistentry>
<term><parameter>governor</parameter></term>
<listitem><para>The ID of the governor property, &ie; the property that will adjusts the client property. This may include a modifier (required)</para></listitem>
</varlistentry>
<varlistentry>
<term><parameter>reconcile</parameter></term>
<listitem><para>If "true", the client property will make adjust the governor property on connection in such a way that the governor property will only accept values that are also acceptable by the client (⪚ suppose the governor is a numeric property with min value "0", and the client is a numeric property with min value "100". The min of both properties will be adjusted to 100, if reconcile="true"). Generally works only for properties of the same basic type (optional, default to "false")</para></listitem>
</varlistentry>
</variablelist></para></listitem>
</varlistentry>
<varlistentry>
<term><dependency_check></term>
<listitem><para>Creates a boolean property that is true, if the specified dependencies are met, false otherwise. The &XML; syntax of the element is the same as that of the <command><dependencies></command> element, described in the <link linkend="pluginmapelements">&pluginmap; reference</link>. As of &rkward; 0.6.1, only the &rkward; and &R; version specifications are taken into account, not dependencies on packages or pluginmaps.</para></listitem>
</varlistentry>
<varlistentry>
<term><script></term>
<listitem><para>Define script code to control UI logic. See <link linkend="logic_scripted">the section on scripted GUJI logic</link> for details. The script code to run can be given either using the <parameter>"file"</parameter> attribute, or as a (commented) text of the element. The <command><script></command> element is not allowed in the <command><logic></command> section of an optionset. Attributes:
<variablelist>
<varlistentry>
<term><parameter>file</parameter></term>
<listitem><para>File name of the script file. (required)</para></listitem>
</varlistentry>
</variablelist></para></listitem>
</varlistentry>
</variablelist>
</sect2>
</sect1> <!-- Elements in main XML -->
<sect1 id="elementproperties"><title>Properties of plugin elements</title>
<para>All <link linkend="layoutelements">layout elements</link>, and all <link linkend="activeelements">active elements</link> hold the following properties, accessible via "id_of_element.name_of_property":
</para>
<variablelist>
<varlistentry>
<term>visible</term>
<listitem><para>Whether the &GUI; element is visible or not (boolean)</para></listitem>
</varlistentry>
<varlistentry>
<term>enabled</term>
<listitem><para>Whether the &GUI; element is enabled or not (boolean)</para></listitem>
</varlistentry>
<varlistentry>
<term>required</term>
<listitem><para>Whether the &GUI; element is required (to hold a valid setting) or not. Note that any element which is disabled or hidden is also implicitly non-required (boolean).</para></listitem>
</varlistentry>
</variablelist>
<para>
In addition to this, some elements have additional properties you can connect to. Most active elements also have a "default" property whose value will be returned on calls to <function>getBoolean/getString/getList ("...")</function>, if no specific property was named, as described below.
</para>
<variablelist>
<varlistentry>
<term><text></term>
<listitem><para>Default property is text
<variablelist>
<varlistentry>
<term>text</term>
<listitem><para>The text displayed (text)</para></listitem>
</varlistentry>
</variablelist></para></listitem>
</varlistentry>
<varlistentry>
<term><varselector></term>
<listitem><para>No default property
<variablelist>
<varlistentry>
<term>selected</term>
<listitem><para>The objects currently selected. You probably do not want to use this. Used internally (RObject)</para></listitem>
</varlistentry>
<varlistentry>
<term>root</term>
<listitem><para>The root/parent object of the objects offered for selection (RObject)</para></listitem>
</varlistentry>
</variablelist></para></listitem>
</varlistentry>
<varlistentry>
<term><varslot></term>
<listitem><para>Default property is "available"
<variablelist>
<varlistentry>
<term>available</term>
<listitem><para>All objects held in the varslot (RObject)</para></listitem>
</varlistentry>
<varlistentry>
<term>selected</term>
<listitem><para>Of the objects held in the varslot, those that are currently selected. You probably do not want to use this. Used internally (RObject)</para></listitem>
</varlistentry>
<varlistentry>
<term>source</term>
<listitem><para>A copy of the objects selected in the corresponding varselector. You probably do not want to use this. Used internally (RObject)</para></listitem>
</varlistentry>
</variablelist></para></listitem>
</varlistentry>
<varlistentry>
<term><valueselector></term>
<listitem><para>Default property is "selected"
<variablelist>
<varlistentry>
<term>selected</term>
<listitem><para>The strings currently selected. Modifier "labeled" to retrieve the corresponding labels. In a <valueselector> you probably do not want to use this, directly (only in a <select>). (read/write StringList)</para></listitem>
</varlistentry>
<varlistentry>
<term>available</term>
<listitem><para>The list of string values to select from. (read/write StringList)</para></listitem>
</varlistentry>
<varlistentry>
<term>labels</term>
<listitem><para>Labels to display for the string values. (read/write StringList)</para></listitem>
</varlistentry>
</variablelist></para></listitem>
</varlistentry>
<varlistentry>
<term><valueslot></term>
<listitem><para>Same as <varslot>, but the properties are lists of strings, instead of RObjects.</para></listitem>
</varlistentry>
<varlistentry>
<term><radio></term>
<listitem><para>Default property is "string"
<variablelist>
<varlistentry>
<term>string</term>
<listitem><para>The value of the currently selected option (string)</para></listitem>
</varlistentry>
<varlistentry>
<term>number</term>
<listitem><para>The number of the currently selected option (options are numbered top-to-bottom, starting at 0) (integer)</para></listitem>
</varlistentry>
</variablelist></para></listitem>
</varlistentry>
<varlistentry>
<term><dropdown></term>
<listitem><para>Same as <radio></para></listitem>
</varlistentry>
<varlistentry>
<term><select></term>
<listitem><para>Same as <valueselector></para></listitem>
</varlistentry>
<varlistentry>
<term><option></term>
<listitem><para>No default property. "enabled" is the *only* property, and it is not currently available for options inside a <select> or <valueselector>. <option> does not have the "visible" or "required" properties.
<variablelist>
<varlistentry>
<term>enabled</term>
<listitem><para>Whether this single option should be enabled or disabled. In most cases you will enable/disable the entire <radio< or <dropdown<, instead. But this can be used to dynamically set the enabledness of a single option inside a <radio< or <dropdown< (bool)</para></listitem>
</varlistentry>
</variablelist></para></listitem>
</varlistentry>
<varlistentry>
<term><checkbox></term>
<listitem><para>Default property is "state.labeled", which means that the values specified by the <parameter>value</parameter>, and <parameter>value_unchecked</parameter>-attributes are returned, <emphasis>not</emphasis> the displayed label of the check box.
<variablelist>
<varlistentry>
<term>state</term>
<listitem><para>State of the check box (on or off). Note that useful modifiers of this property (as of all boolean properties) are "not" and "labeled" (see <link linkend="propertytypes">types of properties</link>). However, often it is most useful to connect to the property with no modifier, &ie; "<emphasis>checkbox_id</emphasis>.state", which will return the state of the check box in a format suitable for use in an if statement (0 or 1). (boolean)</para></listitem>
</varlistentry>
</variablelist></para></listitem>
</varlistentry>
<varlistentry>
<term><frame></term>
<listitem><para>Default property is "checked", if - and only if - the frame is checkable. For non-checkable frames, there is no default property.
<variablelist>
<varlistentry>
<term>checked</term>
<listitem><para>Available for checkable frames, only: state of the check box (on or off). Note that useful modifiers of this property (as of all boolean properties) are "not" and "numeric" (see <link linkend="propertytypes">types of properties</link>). (boolean)</para></listitem>
</varlistentry>
</variablelist></para></listitem>
</varlistentry>
<varlistentry>
<term><input></term>
<listitem><para>Default property is "text"
<variablelist>
<varlistentry>
<term>text</term>
<listitem><para>Current text in the input field (string)</para></listitem>
</varlistentry>
</variablelist></para></listitem>
</varlistentry>
<varlistentry>
<term><matrix></term>
<listitem><para>Default property is "cbind".
<variablelist>
<varlistentry>
<term>rows</term>
<listitem><para>Number of rows in the matrix (integer). If the matrix allows the user to add / remove rows, this property should be treated as read-only. Otherwise, changing it, will change the size of the matrix.</para></listitem>
</varlistentry>
<varlistentry>
<term>columns</term>
<listitem><para>Number of columns in the matrix (integer). If the matrix allows the user to add / remove columns, this property should be treated as read-only. Otherwise, changing it, will change the size of the matrix.</para></listitem>
</varlistentry>
<varlistentry>
<term>tsv</term>
<listitem><para>Data in the matrix in tsv format (string; read-write). Note that compared to the usual tsv layout, <emphasis>columns</emphasis>, not rows, are separated by newline characters, and cells within a column are separated by tabulator characters.</para></listitem>
</varlistentry>
<varlistentry>
<term>0,1,2...</term>
<listitem><para>The data from a single column (0 for leftmost column). <function>getValue()</function>/<function>getString()</function> returns this as a single string, separated by "\n". However, the recommended way to get this is using <function>getList()</function>, which returns this column as an array of strings.</para></listitem>
</varlistentry>
<varlistentry>
<term>row.0,row.1,row.2...</term>
<listitem><para>The data from a single row (0 for topmost row). <function>getValue()</function>/<function>getString()</function> returns this as a single string, separated by "\n". However, the recommended way to get this is using <function>getList()</function>, which returns this row as an array of strings.</para></listitem>
</varlistentry>
<varlistentry>
<term>cbind</term>
<listitem><para>Data in a format suitable for pasting to &R;, wrapped in a cbind statement (string; read-only).</para></listitem>
</varlistentry>
</variablelist></para></listitem>
</varlistentry>
<varlistentry>
<term><optionset></term>
<listitem><para>No default property.
<variablelist>
<varlistentry>
<term>row_count</term>
<listitem><para>Number of items in the optionset (integer). Read-only.</para></listitem>
</varlistentry>
<varlistentry>
<term>current_row</term>
<listitem><para>Currently active item in the optionset (integer). -1 for no active item. Read-write.</para></listitem>
</varlistentry>
<varlistentry>
<term><emphasis>optioncolumn_ids</emphasis></term>
<listitem><para>For each <optioncolumn> you define, a string list property will be created with the specified id.</para></listitem>
</varlistentry>
</variablelist></para></listitem>
</varlistentry>
<varlistentry>
<term><browser></term>
<listitem><para>Default property is "selection"
<variablelist>
<varlistentry>
<term>selection</term>
<listitem><para>Current text (selected file name) in the browser (string)</para></listitem>
</varlistentry>
</variablelist></para></listitem>
</varlistentry>
<varlistentry>
<term><saveobject></term>
<listitem><para>Default property is "selection"
<variablelist>
<varlistentry>
<term>selection</term>
<listitem><para>Full name of the selected object (string; read-only - to set this programmatically, use "parent", and "objectname")</para></listitem>
</varlistentry>
<varlistentry>
<term>parent</term>
<listitem><para>The parent object of the selected object. This is always an existing &R; object of a type that can contain other objects (⪚ a list or data.frame). When set to an empty string or an invalid object, ".GlobalEnv" is assumed (RObject)</para></listitem>
</varlistentry>
<varlistentry>
<term>objectname</term>
<listitem><para>The base-name of the selected object, &ie; the string entered by the user (changed to a valid &R; name, if necessary) (string)</para></listitem>
</varlistentry>
<varlistentry>
<term>active</term>
<listitem><para>For checkable saveobjects, only: Whether the control is checked/enabled. Always true for non-checkable saveobjects (bool)</para></listitem>
</varlistentry>
</variablelist></para></listitem>
</varlistentry>
<varlistentry>
<term><spinbox></term>
<listitem><para>Default property is either "int" or "real.formatted" depending on the spinbox's mode
<variablelist>
<varlistentry>
<term>int</term>
<listitem><para>Integer value held by the spinbox, or nearest integer, if in real mode (integer)</para></listitem>
</varlistentry>
<varlistentry>
<term>real</term>
<listitem><para>Real value held by the spinbox (and integer, if in integer) (real)</para></listitem>
</varlistentry>
</variablelist></para></listitem>
</varlistentry>
<varlistentry>
<term><formula></term>
<listitem><para>Default property is "model"
<variablelist>
<varlistentry>
<term>model</term>
<listitem><para>The current model string (string)</para></listitem>
</varlistentry>
<varlistentry>
<term>table</term>
<listitem><para>The data.frame holding the required variables. If variables from only one data.frame are used, the name of that data.frame is returned. Otherwise a new data.frame is constructed as required (string)</para></listitem>
</varlistentry>
<varlistentry>
<term>labels</term>
<listitem><para>If variables from multiple data.frames are involved, their names may get mangled (for instance, if both data.frames contain a variable named "x"). This returns a list with the mangled names as indices and the descriptive label as value (string)</para></listitem>
</varlistentry>
<varlistentry>
<term>fixed_factors</term>
<listitem><para>The fixed factors. You probably do not want to use this. Used internally (RObject)</para></listitem>
</varlistentry>
<varlistentry>
<term>dependent</term>
<listitem><para>The dependent variable(s). You probably do not want to use this. Used internally (RObject)</para></listitem>
</varlistentry>
</variablelist></para></listitem>
</varlistentry>
<varlistentry>
<term><embed></term>
<listitem><para>No default property
<variablelist>
<varlistentry>
<term>code</term>
<listitem><para>The code generated by the embedded plugin (code)</para></listitem>
</varlistentry>
</variablelist></para></listitem>
</varlistentry>
<varlistentry>
<term><preview></term>
<listitem><para>Default property is "state"
<variablelist>
<varlistentry>
<term>state</term>
<listitem><para>Whether the preview box is checked (not necessarily whether the preview has already been shown) (boolean)</para></listitem>
</varlistentry>
</variablelist></para></listitem>
</varlistentry>
<varlistentry>
<term><convert></term>
<listitem><para>This element (used in the <logic> section) is special, in that is technically *is* a property, instead of just holding one or more properties. It is of boolean kind. Note that useful modifiers of this property (as of all boolean properties) are "not" and "numeric" (see <link linkend="propertytypes">types of properties</link>)</para></listitem>
</varlistentry>
<varlistentry>
<term><switch></term>
<listitem><para>This element (used in the <logic> section) is special, in that is technically *is* a (string) property, instead of just holding one or more properties. It allows to switch between several target properties depending on the value of a condition property, or to re-map values of the condition property. Any modifiers that you supply are passed on to the target properties, thus, ⪚ if all target
properties are RObject properties, you can use the "shortname" modifier on the switch, too. However, if the target properties are of
different types, using modifiers may lead to errors. For <replaceable>fixed_value</replaceable>s, any modifier is dropped, silently. Note that target properties, when accessed through a switch, are always read-only.</para></listitem>
</varlistentry>
</variablelist>
</sect1>
<sect1 id="standard_embeddable_plugins"><title>Embeddable plugins shipped with the official &rkward; release</title>
<para>A number of embeddable plugins is shipped with &rkward;, and can be used in your own plugins. Detailed documentation is currently available
only in these plugins source or help files. However, here is a list to give you a quick overview of what is available:</para>
<table frame='all'><title>Standard embeddable plugins</title>
<tgroup cols='4'>
<thead>
<row>
<entry>ID</entry>
<entry>Pluginmap</entry>
<entry>Description</entry>
<entry>Example usage</entry>
</row>
</thead>
<tbody>
<row>
<entry>rkward::plot_options</entry>
<entry>embedded.pluginmap</entry>
<entry>Provides a wide range of options for plots. Most plotting plugins utilize this.</entry>
<entry>Plots->Barplot, most other plotting plugins</entry>
</row>
<row>
<entry>rkward::color_chooser</entry>
<entry>embedded.pluginmap</entry>
<entry>Very simple plugin for specifying a color. Current implementation provides a list of color names. Future implementations may provide
more elaborate color picking.</entry>
<entry>Plots->Histogram</entry>
</row>
<row>
<entry>rkward::plot_stepfun_options</entry>
<entry>embedded.pluginmap</entry>
<entry>Step function plot options</entry>
<entry>Plots->ECDF plot</entry>
</row>
<row>
<entry>rkward::histogram_options</entry>
<entry>embedded.pluginmap</entry>
<entry>Histogram (plot) options</entry>
<entry>Plots->Histogram</entry>
</row>
<row>
<entry>rkward::barplot_embed</entry>
<entry>embedded.pluginmap</entry>
<entry>Barplot options</entry>
<entry>Plots->Barplot</entry>
</row>
<row>
<entry>rkward::one_var_tabulation</entry>
<entry>embedded.pluginmap</entry>
<entry>Provides tabulation on a single variable.</entry>
<entry>Plots->Barplot</entry>
</row>
<row>
<entry>rkward::limit_vector_length</entry>
<entry>embedded.pluginmap</entry>
<entry>Limit the length of a vector (to the n largest or smallest elements).</entry>
<entry>Plots->Barplot</entry>
</row>
<row>
<entry>rkward::level_select</entry>
<entry>embedded.pluginmap</entry>
<entry>Provides a <valueselector> filled with the levels (or unique values) of a vector.</entry>
<entry>Data->Recode Categorical data</entry>
</row>
<row>
<entry>rkward::multi_input</entry>
<entry>embedded.pluginmap</entry>
<entry>Combines spinbox, input and radio controls to provide input for character, numeric, logical data.</entry>
<entry>Data->Recode Categorical data</entry>
</row>
</tbody>
</tgroup>
</table>
</sect1>
<sect1 id="pluginmapelements"><title>Elements for use in &pluginmap; files</title>
<variablelist>
<varlistentry>
<term><document></term>
<listitem><para>Needs to be present in each &pluginmap; file as the root-node (exactly once). Attributes:
<variablelist>
<varlistentry>
<term>base_prefix</term>
<listitem><para>Filenames specified in the &pluginmap; file are assumed to be relative to the directory of the &pluginmap; file + the prefix you specify here. Useful, esp., if all your components are located below a single subdirectory.</para></listitem>
</varlistentry>
<varlistentry>
<term>namespace</term>
<listitem><para>A namespace for the component ids. When looking up components for embedding, the components will be retrievable via a string "namespace::component_id". Set to "rkward" for now.</para></listitem>
</varlistentry>
<varlistentry>
<term>id</term>
<listitem><para>An optional identifier string for this &pluginmap;. Specifying this allows third authors to refer to and load your &pluginmap; from theirs (see <link linkend="chapter_dependencies">chapter on handling dependencies</link>).</para></listitem>
</varlistentry>
<varlistentry>
<term>priority</term>
<listitem><para>One of <replaceable>"hidden"</replaceable>, <replaceable>"low"</replaceable>, <replaceable>"medium"</replaceable>, or <replaceable>"high"</replaceable>. &pluginmap;s with priority "medium" or "high" are activated, automatically, when &rkward; first finds them. Use <replaceable>priority="hidden"</replaceable> for &pluginmap;s that are not meant to be activated, directory (only meant for inclusion). In the current implementation this does not actually hide the &pluginmap;, however. (Optional, defaults to "medium").</para></listitem>
</varlistentry>
</variablelist></para></listitem>
</varlistentry>
<varlistentry>
<term><dependencies></term>
<listitem><para>This element, specifying dependencies, is allowed as a direct child of the <document> element (once), and as a child of <component> elements (once for each <component> element). Specifies the dependencies that must be met in order to use the plugin(s). See the <link linkend="chapter_dependencies">chapter on dependencies</link> for an overview. Attributes:</para>
<variablelist>
<varlistentry>
<term>rkward_min_version, rkward_max_version</term>
<listitem><para>Minimum and maximum allowed version of &rkward;. Version specifications may include non-numeric suffixes, like "0.5.7z-devel1". If a specified dependency is not met, the plugin(s) it applies to <emphasis>will be ignored</emphasis>. <link linkend="sect_dependencies_rkward_version">More information</link>. Optional; if not specified, no minimum / maximum version of &rkward; will be required.</para></listitem>
</varlistentry>
<varlistentry>
<term>R_min_version, R_max_version</term>
<listitem><para>Minimum and maximum allowed version of &R;. Version specifications may <emphasis>not</emphasis> include non-numeric suffixes, like "0.5.7z-devel1". The &R; version dependency will be shown on the plugins' help pages, but does not have any direct effect, as of &rkward; 0.6.1. <link linkend="sect_dependencies_r_version">More information</link>. Optional; if not specified, no minimum / maximum version of &R; will be required.</para></listitem>
</varlistentry>
</variablelist>
<para>Child elements:</para>
<variablelist>
<varlistentry>
<term><package></term>
<listitem><para>Adds a dependency on a specific &R; package. Attributes:
<variablelist>
<varlistentry>
<term>name</term>
<listitem><para>Package name (required).</para></listitem>
</varlistentry>
<varlistentry>
<term>min_version, max_version</term>
<listitem><para>Minimum / maximum allowed version (optional).</para></listitem>
</varlistentry>
<varlistentry>
<term>repository</term>
<listitem><para>Repository where the package can be found. Optional, but highly recommended, if the package is not available on CRAN.</para></listitem>
</varlistentry>
</variablelist>
</para></listitem>
</varlistentry>
<varlistentry>
<term><pluginmap></term>
<listitem><para>Adds a dependency on a specific &rkward; &pluginmap;. Attributes:
<variablelist>
<varlistentry>
<term>name</term>
<listitem><para>Id string of the required &pluginmap; (required).</para></listitem>
</varlistentry>
<varlistentry>
<term>min_version, max_version</term>
<listitem><para>Minimum / maximum allowed version (optional).</para></listitem>
</varlistentry>
<varlistentry>
<term>url</term>
<listitem><para>&URL; where the &pluginmap; can be found. Required.</para></listitem>
</varlistentry>
</variablelist>
</para></listitem>
</varlistentry>
</variablelist>
</listitem>
</varlistentry>
<varlistentry>
<term><about></term>
<listitem><para>May be present exactly once as a direct child of the <document> element. Contains meta information on the &pluginmap; (or plugin). See the <link linkend="chapter_about_information">chapter on 'about' information</link> for an overview. Attributes:</para>
<variablelist>
<varlistentry>
<term>name</term>
<listitem><para>User visible name. Optional. Does not have to be the same as the "id".</para></listitem>
</varlistentry>
<varlistentry>
<term>version</term>
<listitem><para>Version number. Optional. The format is not restricted, but to be on the safe side, please follow common versioning schemes such as "x.y.z".</para></listitem>
</varlistentry>
<varlistentry>
<term>releasedate</term>
<listitem><para>Release date specification. Optional in format "YYYY-MM-DD".</para></listitem>
</varlistentry>
<varlistentry>
<term>shortinfo</term>
<listitem><para>A <emphasis>short</emphasis> description of the plugin / &pluginmap;. Optional.</para></listitem>
</varlistentry>
<varlistentry>
<term>url</term>
<listitem><para>&URL; where more information can be found. Optional, but recommended.</para></listitem>
</varlistentry>
<varlistentry>
<term>copyright</term>
<listitem><para>Copyright specification, ⪚ "2012-2013 by John Doe". Optional, but recommended.</para></listitem>
</varlistentry>
<varlistentry>
<term>licence</term>
<listitem><para>License specification, ⪚ "GPL" or "BSD". Please make sure to accompany your files with a complete copy of the relevant licence. Optional, but recommended.</para></listitem>
</varlistentry>
<varlistentry>
<term>category</term>
<listitem><para>Category of plugin(s), ⪚ "Item response theory". As of &rkward; 0.6.1, no categories are predefined. Optional.</para></listitem>
</varlistentry>
</variablelist>
<para>Child elements:</para>
<variablelist>
<varlistentry>
<term><author></term>
<listitem><para>Adds information on an author. Attributes:
<variablelist>
<varlistentry>
<term>name, given, family</term>
<listitem><para>Either specify the full name for <parameter>name</parameter>, or specify both <parameter>given</parameter> and <parameter>family</parameter>, separately.</para></listitem>
</varlistentry>
<varlistentry>
<term>role</term>
<listitem><para>Author role description (optional).</para></listitem>
</varlistentry>
<varlistentry>
<term>email</term>
<listitem><para>E-mail address, where author can be contacted. Required. May be set to the rkward-devel mailing list, if you are subscribed, and your plugin is meant to be included in the official &rkward; release.</para></listitem>
</varlistentry>
<varlistentry>
<term>url</term>
<listitem><para>&URL; with more information on the author, ⪚ homepage (optional).</para></listitem>
</varlistentry>
</variablelist>
</para></listitem>
</varlistentry>
</variablelist>
</listitem>
</varlistentry>
<varlistentry>
<term><components></term>
<listitem><para>Needs to be present exactly once as a direct child of the <document> element. Contains the individual <component>-elements described below. No attributes.</para></listitem>
</varlistentry>
<varlistentry>
<term><component></term>
<listitem><para>One or more <component> elements should be given as direct children of the <components> element (and only there). Registers a component/plugin with rkward. Attributes:
<variablelist>
<varlistentry>
<term>type</term>
<listitem><para>For future extension: The type of component/plugin. Always set to "standard" for now (the only type currently supported).</para></listitem>
</varlistentry>
<varlistentry>
<term>id</term>
<listitem><para>The ID by which this component can be retrieved (for placing it in the menu (see below), or for embedding). See <document>-namespace above.</para></listitem>
</varlistentry>
<varlistentry>
<term>file</term>
<listitem><para>Required at least for components of type="standard": The filename of the &XML; file describing the &GUI;.</para></listitem>
</varlistentry>
<varlistentry>
<term>label</term>
<listitem><para>The label for this component, when placed in the menu hierarchy.</para></listitem>
</varlistentry>
</variablelist></para></listitem>
</varlistentry>
<varlistentry>
<term><attribute></term>
<listitem><para>Defines an attribute of a component. Only meaningful for <link linkend="context_import">import plugins</link> so far. Only allowed as a direct child of <component>. Attributes:
<variablelist>
<varlistentry>
<term>id</term>
<listitem><para>Id of the attribute</para></listitem>
</varlistentry>
<varlistentry>
<term>value</term>
<listitem><para>Value of the attribute</para></listitem>
</varlistentry>
<varlistentry>
<term>labels</term>
<listitem><para>Label associated with the attribute</para></listitem>
</varlistentry>
</variablelist></para></listitem>
</varlistentry>
<varlistentry>
<term><hierarchy></term>
<listitem><para>Needs to be present exactly once as a direct child of the <document> element. Describes where the components declared above should be placed in the menu hierarchy. Accepts only <menu> elements as direct children. No attributes.</para></listitem>
</varlistentry>
<varlistentry>
<term><menu></term>
<listitem><para>One or more <menu> elements should be given as direct children of the <hierarchy> element. Declares a new (sub-)menu. If a menu by the given ID (see below) already exists, the two menus are merged. The <menu> element is allowed either as a direct child of the <hierarchy> element (top level menu), or as the direct child on any other <menu> element (sub-menu). Conversely, the <menu> element accepts other <menu> elements or <entry> elements as children. Attributes:
<variablelist>
<varlistentry>
<term>id</term>
<listitem><para>An identifier string of the menu. Useful, when menu definitions are read from several &pluginmap; files, to make sure plugins can be placed in the same menu(s). Some menu-ids such as "file" refer to predefined menus (in this case the "File" menu). Be sure to check with existing &pluginmap; files to use consistent ids.</para></listitem>
</varlistentry>
<varlistentry>
<term>label</term>
<listitem><para>A label for the menu.</para></listitem>
</varlistentry>
<varlistentry>
<term>group</term>
<listitem><para>Allows to control ordering of menu entries. See <link linkend="pluginmap_grouping">menu item ordering</link>. Optional.</para></listitem>
</varlistentry>
</variablelist></para></listitem>
</varlistentry>
<varlistentry>
<term><entry></term>
<listitem><para>A menu entry, &ie; a menu option to invoke a plugin. May be used only as a direct child of a <menu> element, accepts no child elements. Attributes:
<variablelist>
<varlistentry>
<term>component</term>
<listitem><para>The ID of the component that should be invoked, when this menu entry is activated.</para></listitem>
</varlistentry>
<varlistentry>
<term>group</term>
<listitem><para>Allows to control ordering of menu entries. See <link linkend="pluginmap_grouping">menu item ordering</link>. Optional.</para></listitem>
</varlistentry>
</variablelist></para></listitem>
</varlistentry>
<varlistentry>
<term><group></term>
<listitem><para>Declares a group of items in the menu. See <link linkend="pluginmap_grouping">menu item ordering</link>. Attributes:
<variablelist>
<varlistentry>
<term>id</term>
<listitem><para>The name of this group.</para></listitem>
</varlistentry>
<varlistentry>
<term>separated</term>
<listitem><para>Optional. If set to "true" the item in this group will be visually separated from surrounding items.</para></listitem>
</varlistentry>
<varlistentry>
<term>group</term>
<listitem><para>The name of the group to append this group to (optional).</para></listitem>
</varlistentry>
</variablelist></para></listitem>
</varlistentry>
<varlistentry>
<term><context></term>
<listitem><para>Declares the entries in a <link linkend="contextualized_plugins">context</link>. Only allowed as a direct child of the <document> tag. Accepts only <menu> tags as direct children. Attributes:
<variablelist>
<varlistentry>
<term>id</term>
<listitem><para>The ID of the context. Only two contexts are implemented so far: "x11" and "import".</para></listitem>
</varlistentry>
</variablelist></para></listitem>
</varlistentry>
<varlistentry>
<term><require></term>
<listitem><para>Include another &pluginmap; file. This &pluginmap; file is only loaded once, even if it is <require>d from several other files. The most important use case is to include a pluginmap file, which declares some components, which are embedded by components declared in this &pluginmap;. <require>-elements are only allowed as direct children of the <document>-node. Attributes:
<variablelist>
<varlistentry>
<term>file</term>
<listitem><para>The filename of the &pluginmap; to include. This is seen relative to the directory of the current &pluginmap; file + the base_prefix (see above, <document>-element). If you do not know the relative path to the &pluginmap; to be included, use the <parameter>map</parameter> attribute to refer to it by id, instead.</para></listitem>
</varlistentry>
<varlistentry>
<term>map</term>
<listitem><para>To include a &pluginmap; file from a different package (or an &rkward; &pluginmap; from your external &pluginmap;), you can refer to it by its <replaceable>namespacename::id</replaceable>, as specified in the required &pluginmap;s <document> element. Inclusion will fail, if no &pluginmap; by that id is known (⪚ not installed on the user's system). You should use this method for including &pluginmap;s outside your package, only. For maps inside your package, specifying a relative path (<parameter>file</parameter> attribute) is faster, and more reliable.
</para></listitem>
</varlistentry>
</variablelist></para></listitem>
</varlistentry>
</variablelist>
</sect1>
<sect1 id="helpfileelements"><title>Elements for use in .rkh (help) files</title>
<variablelist>
<varlistentry>
<term><document></term>
<listitem><para>Needs to be present in each <literal role="extension">.xml</literal> file as the root-node (exactly once). No attributes.</para></listitem>
</varlistentry>
<varlistentry>
<term><title></term>
<listitem><para>Title of the help page. This is <emphasis>not</emphasis> interpreted for help pages for a plugin (this takes the title from the plugin itself), only for stand-alone pages. No attributes. The text contained within the <title> tag will become the caption of the help page. May only be defined once, as a direct child of the <document> node.</para></listitem>
</varlistentry>
<varlistentry>
<term><summary></term>
<listitem><para>A short summary of the help page (or what this plugin is used for). This will always be shown at the top of the help page. No attributes. The text contained within the <summary> tag will be displayed. Recommended but not required. May only be defined once, as a direct child of the <document> node.</para></listitem>
</varlistentry>
<varlistentry>
<term><usage></term>
<listitem><para>A slightly more elaborate summary of the usage. This will always be shown directly after the <summary>. No attributes. The text contained within the <usage> tag will be displayed. Recommended for plugin help pages, but not required. May only be defined once, as a direct child of the <document> node.</para></listitem>
</varlistentry>
<varlistentry>
<term><section></term>
<listitem><para>A general purposes section. May be used any number of times as a direct child of the <document> node. These sections are displayed in the order of their definition, but all <emphasis>after</emphasis> the <usage> section and <emphasis>before</emphasis> the <settings> section. The text contained within the <section> tag will be displayed.
<variablelist>
<varlistentry>
<term>id</term>
<listitem><para>An identifier needed to jump to this section from the navigation bar (or a link). Needs to be unique within the file. Required, no default.</para></listitem>
</varlistentry>
<varlistentry>
<term>title</term>
<listitem><para>The title (caption) of this section. Required, no default.</para></listitem>
</varlistentry>
<varlistentry>
<term>short_title</term>
<listitem><para>A short title suitable to be displayed in the navigation bar. Optional, defaults to the full title.</para></listitem>
</varlistentry>
</variablelist></para></listitem>
</varlistentry>
<varlistentry>
<term><settings></term>
<listitem><para>Defines the section containing reference on the various &GUI; settings. Only meaningful and only used for plugin related help pages. Use as a direct child of the <document>. May contain only <setting> and <caption> elements as direct children. No attributes.</para></listitem>
</varlistentry>
<varlistentry>
<term><setting></term>
<listitem><para>Explains a single setting in the &GUI;. Only allowed as a direct child of the <settings> element. The text contained within the element is displayed.
<variablelist>
<varlistentry>
<term>id</term>
<listitem><para>The ID of the setting in the plugin <literal role="extension">.xml</literal>. Required, no default.</para></listitem>
</varlistentry>
<varlistentry>
<term>title</term>
<listitem><para>An optional title for the setting. If omitted (omission is recommended in most cases), the title will be taken from the plugin <literal role="extension">.xml</literal>.</para></listitem>
</varlistentry>
</variablelist></para></listitem>
</varlistentry>
<varlistentry>
<term><caption></term>
<listitem><para>A caption to visually group several settings. May only be used as a direct child of the <settings> element.
<variablelist>
<varlistentry>
<term>id</term>
<listitem><para>The ID of the corresponding element (typically a <frame>, <page> or <tab>) in the plugin <literal role="extension">.xml</literal>.</para></listitem>
</varlistentry>
<varlistentry>
<term>title</term>
<listitem><para>An optional title for the caption. If omitted (omission is recommended in most cases), the title will be taken from the plugin <literal role="extension">.xml</literal>.</para></listitem>
</varlistentry>
</variablelist></para></listitem>
</varlistentry>
<varlistentry>
<term><related></term>
<listitem><para>Defines a section containing links to further related information. Will always be displayed after the <settings> section. No attributes. The text contained within the <related> tag will be displayed. Typically this will contain an &HTML;-style list. Recommended for plugin help pages, but not required. May only be defined once, as a direct child of the <document> node.</para></listitem>
</varlistentry>
<varlistentry>
<term><technical></term>
<listitem><para>Defines a section containing technical information of no relevance to end users (such as internal structure of the plugin). Will always be displayed last in a help page. No attributes. The text contained within the <related> tag will be displayed. Not required, and not recommended for most plugin help pages. May only be defined once, as a direct child of the <document> node.</para></listitem>
</varlistentry>
<varlistentry>
<term><link></term>
<listitem><para>A link. Can be used in any of the sections described above.
<variablelist>
<varlistentry>
<term>href</term>
<listitem><para>The target &URL;. Note that several &rkward; specific &URL;s are available. See <link linkend="pluginhelp">section on writing help pages</link> for details.</para></listitem>
</varlistentry>
</variablelist></para></listitem>
</varlistentry>
<varlistentry>
<term><label></term>
<listitem><para>Inserts the value of a UI label. Can be used in any of the sections described above.
<variablelist>
<varlistentry>
<term>id</term>
<listitem><para>The id of the element in the plugin, of which to copy the <replaceable>label</replaceable>-attribute.</para></listitem>
</varlistentry>
</variablelist></para></listitem>
</varlistentry>
<varlistentry>
<term><various &HTML; tags></term>
<listitem><para>Most basic &HTML; tags are allowed within the sections. Please keep manual formatting to a minimum, however.</para></listitem>
</varlistentry>
</variablelist>
</sect1>
<sect1 id="guilogic_functions"><title>Functions available for &GUI; logic scripting</title>
<variablelist>
<varlistentry><term>Class "Component"</term>
<listitem><para>Class which represents a single component or component-property. The most important instance of this class is the variable "gui" which is predefined as the root property of the current component. The following methods are available for instances of class "Component":
<variablelist>
<varlistentry><term>absoluteId(base_id)</term><listitem><para>Returns the absolute ID of <emphasis>base_id</emphasis>, or - if base_id is omitted - the identifier of the component.</para></listitem></varlistentry>
<varlistentry><term>getValue(id)</term><listitem><para>Discouraged. Use <function>getString(), getBoolean(), or getList()</function>, instead. Returns the value of the given child property. Returns the value of this property, if ID is omitted.</para></listitem></varlistentry>
<varlistentry><term>getString(id)</term><listitem><para>Returns the value of the given child property as a string. Returns the value of this property, if ID is omitted.</para></listitem></varlistentry>
<varlistentry><term>getBoolean(id)</term><listitem><para>Returns the value of the given child property as a boolean (if possible). Returns the value of this property, if ID is omitted.</para></listitem></varlistentry>
<varlistentry><term>getList(id)</term><listitem><para>Returns the value of the given child property as an array of strings (if possible). Returns the value of this property, if ID is omitted.</para></listitem></varlistentry>
<varlistentry><term>setValue(id, value)</term><listitem><para>Set the value of the given child property to <emphasis>value</emphasis>.</para></listitem></varlistentry>
<varlistentry><term>getChild(id)</term><listitem><para>Return an instance of the child-property with the given <emphasis>id</emphasis>.</para></listitem></varlistentry>
<varlistentry><term>addChangeCommand(id, command)</term><listitem><para>Execute <emphasis>command</emphasis> whenever the child property given by <emphasis>id</emphasis> changes.</para></listitem></varlistentry>
</variablelist></para></listitem>
</varlistentry>
<varlistentry><term>Class "RObject"</term>
<listitem><para>Class which represents a single &R; object. An instance of this class can be obtained by using <command>makeRObject(objectname)</command>. The following methods are available for instances of class "RObject": <warning><para>If any commands are still pending in the backend, the information provided by these methods can be out-of-date by the time that the plugin code is run. Do <emphasis>not</emphasis> rely on it for critical operations (risking loss of data).</para></warning>
<variablelist>
<varlistentry><term>getName()</term><listitem><para>Returns the absolute name of the object.</para></listitem></varlistentry>
<varlistentry><term>exists()</term><listitem><para>Returns whether the object exists. You should generally check this before using any of the methods listed below.</para></listitem></varlistentry>
<varlistentry><term>dimensions()</term><listitem><para>Returns an array of dimensions (similar to <command>dim()</command> in R).</para></listitem></varlistentry>
<varlistentry><term>classes()</term><listitem><para>Returns an array of classes (similar to <command>class()</command> in R).</para></listitem></varlistentry>
<varlistentry><term>isClass(class)</term><listitem><para>Returns true, if the object is of class <emphasis>class</emphasis>.</para></listitem></varlistentry>
<varlistentry><term>isDataFrame()</term><listitem><para>Returns true, if the object is a data.frame.</para></listitem></varlistentry>
<varlistentry><term>isMatrix()</term><listitem><para>Returns true, if the object is a matrix.</para></listitem></varlistentry>
<varlistentry><term>isList()</term><listitem><para>Returns true, if the object is a list.</para></listitem></varlistentry>
<varlistentry><term>isFunction()</term><listitem><para>Returns true, if the object is a function.</para></listitem></varlistentry>
<varlistentry><term>isEnvironment()</term><listitem><para>Returns true, if the object is an environment.</para></listitem></varlistentry>
<varlistentry><term>isDataNumeric()</term><listitem><para>Returns true, if the object is a vector of numeric data.</para></listitem></varlistentry>
<varlistentry><term>isDataFactor()</term><listitem><para>Returns true, if the object is a vector of factor data.</para></listitem></varlistentry>
<varlistentry><term>isDataCharacter()</term><listitem><para>Returns true, if the object is a vector of character data.</para></listitem></varlistentry>
<varlistentry><term>isDataLogical()</term><listitem><para>Returns true, if the object is a vector of logical data.</para></listitem></varlistentry>
<varlistentry><term>parent()</term><listitem><para>Returns an instance of "RObject" representing the parent of this object.</para></listitem></varlistentry>
<varlistentry><term>child(childname)</term><listitem><para>Returns an instance of "RObject" representing the child <emphasis>childname</emphasis> of this object.</para></listitem></varlistentry>
</variablelist></para></listitem>
</varlistentry>
<varlistentry><term>Class "RObjectArray"</term>
<listitem><para>An array of RObject instances. An instance of this class can be obtained by using <command>makeRObjectArray(objectnames)</command>. It is particularly useful when dealing with varslots which allow to select multiple objects.</para></listitem>
</varlistentry>
<varlistentry><term>include()-function</term>
<listitem><para><command>include(filename)</command> can be used to include a separate JS file.</para></listitem>
</varlistentry>
<varlistentry><term>doRCommand()-function</term>
<listitem><para><command>doRCommand(command, callback)</command> can be used to query &R; for information. Please read the section on <link linkend="querying_r_for_info">querying &R; from inside a plugin</link> for details, and caveats.</para></listitem>
</varlistentry>
</variablelist>
</sect1>
</appendix>
<appendix id="troubleshooting">
<title>Troubleshooting during plugin development</title>
<para>
So you have read all the documentation, did everything right, and still cannot get it to work? Do not worry, we will work it out. First thing to do is: Activate <guilabel>&rkward; Debug Messages</guilabel> - window (available from the <guimenu>Windows</guimenu> - menu, or right click on one of the tool bars), and then start your plugin, again. As a general rule of thumb, you should not see any output in the messages window when your plugin gets invoked, or at any other time. If there is one, it is likely related to your plugin. See if it helps you.
</para>
<para>
If everything seems fine on the console, try to increase the debug-level (from the command line, using <command>rkward --debug-level 3</command>, or by setting debug level to 3 in <menuchoice><guimenu>Settings</guimenu> <guimenuitem>Configure &rkward;</guimenuitem> <guimenuitem>Debug</guimenuitem></menuchoice>). Not all messages shown at higher debug levels necessarily indicate a problem, but chance are, your problem shows up somewhere between the messages.
</para>
<para>
If you still cannot find out what is wrong, do not despair. We know this is complicated stuff, and - after all - possibly you have also come across a bug in &rkward;, and &rkward; needs to be fixed. Just write to the development mailing list, and tell us about the problem. We will be happy to help you.
</para>
<para>
Finally, even if you found out how to do it on your own, but found the documentation to be not-so-helpful or even wrong in some respects, please tell us on the mailing list as well, so we can fix/improve the documentation.
</para>
</appendix>
<appendix id="license">
<title>License</title>
<!-- TRANS:CREDIT_FOR_TRANSLATORS -->
&underFDL;
</appendix>
&documentation.index;
</book>
<!--
Local Variables:
mode: sgml
sgml-minimize-attributes:nil
sgml-general-insert-case:lower
sgml-indent-step:0
sgml-indent-data:nil
End:
-->
|