Kapitel 10. Koncept för användning i specialiserade insticksprogram

Använd rk.graph.on() direkt innan diagrammet skapas, och rk.graph.off() direkt efteråt, för att rita ett diagram i utmatningsfönstret. Det liknar t.ex. anrop av postscript() och dev.off() i en vanlig R-session.

Det är dock viktigt att alltid anropa rk.graph.off() efter att ha anropat rk.graph.on(). Annars lämnas utdatafilen i ett felaktigt tillstånd. För att försäkra att rk.graph.off() verkligen anropas, måste alla R-kommandon mellan de två anropen omges med en try()-sats. Har du aldrig hört talas om det? Var inte orolig, det är enkelt. Allt du behöver göra är att följa mönstret som visas i exemplet nedan.

En mycket användbar funktion för alla insticksprogram som skapar ett diagram eller graf är att tillhandahålla en förhandsgranskning med automatisk uppdatering. Det behövs två saker för att göra det: Tillägg av kryssrutan <preview> i definitionen av det grafiska användargränssnittet, och justering av den genererade koden för förhandsgranskningen.

Att lägga till kryssrutan <preview> är enkelt. Placera bara följande någonstans i det grafiska användargränssnittet. Det tar hand om all magi bakom kulisserna för att skapa en förhandsgranskningsenhet, uppdatera förhandsgranskningen så fort inställningarna har ändrats, etc. Exempel:

<document>
                [...]
                <dialog [...]>
                        [...]
                        <preview id="preview"/>
                        [...]
                </dialog>
                [...]
        </document>
                

Och det är allt för definitionen av det grafiska användargränssnittet.

Att justera JS-mallen är bara lite mer arbete. Här måste man säkerställa att bara själva diagrammet skapas, och visas på en skärmenhet, istället för att skickas som utdata, dvs. ingen utskrift av rubriker, rk.graphics.on(), eller liknande anrop. För att hjälpa till med det, anropar RKWard funktionerna preprocess(), calculate() och printout() med en ytterligare parameter som ställs in till true när kod genereras för en förhandsgranskning. (Parametern utelämnas när den slutliga koden skapas. I Javascript utvärderas det som false när det används inne i en if-sats.) Se exemplet nedan för det typiska mönstret man ska använda.

Som ett alternativ, om mer kontroll behövs än så här, kan man istället lägga till en ny funktion vid namn preview() i JS-mallen, och generera koden som krävs för en förhandsgranskning där (troligen, åtminstone delvis, igen genom att anropa calculate(), etc.).

Du har märkt att de flesta diagraminsticksprogram i RKWard tillhandahåller ett stort antal generella alternativ, t.ex. för att anpassa axlarnas rubriker eller figurmarginaler. Det är enkelt att lägga till alternativen i ett insticksprogram. De tillhandahålls av ett inbäddningsbart insticksprogram som heter rkward::plot_options. Inbädda det i insticksprogrammets användargränssnitt så här:

<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>
                

Det lägger till en knapp i användargränssnittet för att visa ett fönster med diagramalternativ. Sektionen logic är bara ett exempel. Den ger en viss kontroll över insticksprogrammet för diagramalternativ. Läs mer på insticksprogrammet plot_options hjälpsida (länkad från hjälpsidan i alla insticksprogram som tillhandahåller de generella alternativen).

Därefter måste du försäkra dig om att koden som motsvarar diagramalternativen läggs till i koden som genereras för ditt diagram. Hämta egenskaperna code.preprocess, code.printout och code.calculate från det inbäddade insticksprogrammet för diagramalternativ för att göra det, och infoga dem i din kod som visas i exemplet nedan.

Här är ett exempel på en .JS-fil som bör användas som mall, så fort ett diagraminsticksprogram skapas:

function preprocess () {
    // "somepackage" behövs för att skapa diagrammet
    echo ("require (somepackage)\n");
  }

  function printout (is_preview) {
    // Om "is_preview" tilldelas false/odefinierad,skapas fullständig kod, inklusive rubriker.
    // Om "is_preview" tilldelas true, skapas bara det viktigaste.

    if (!is_preview) {
      echo ('rk.header (' + i18n ("Ett exempeldiagram") + ')\n\n');
      echo ('rk.graph.on ()\n');
    }
    // bara följande del skapas när is_preview==true

    // kom ihåg att allting mellan rk.graph.on() och rk.graph.off() ska omges med en try()-sats:
    echo ('try ({\n');
    // infoga eventuell kod för inställning av alternativ som ska köras innan själva uppritningskommandona.
    // Själva koden tillhandahålls av det inbäddade insticksprogrammet för uppritningsalternativ. printIndentedUnlessEmpty() tar hand om snygg formatering.
    printIndentedUnlessEmpty ('\t', getString ("plotoptions.code.preprocess"), '', '\n');

    // skapa själva diagrammet. plotoptions.code.printout tillhandahåller de generella uppritningsalternativen
    // som måste läggas till i själva uppritningsanropet.
    echo ('plot (5, 5' + getString ("plotoptions.code.printout") + ')\n');

    // infoga eventuell kod för inställning av alternativ som ska köras efter själva uppritningen.
    printIndentedUnlessEmpty ('\t', getString ("plotoptions.code.calculate"), '\n');
    echo ('})'\n);  // avslutning av try()-satsen

    if (!is_preview) {
      echo ('rk.graph.off ()\n');
    }
  }