Hoofdstuk 10. Te gebruiken concepten voor gespecialiseerde plugins

Om een plot te tekenen in het uitvoervenster, gebruikt u rk.graph.on() direct voor het tekenen van een plot, en rk.graph.off(), direct daarna. Dit is vergelijkbaar met bijv. het aanroepen van postscript() en dev.off() in een normale R-sessie.

Maar het is belangrijk dat u altijd rk.graph.off() aanroept na de aanroep van rk.graph.on(). Anders wordt het uitvoerbestand beschadigd. Om er zeker van te zijn dat rk.graph.off() werkelijk wordt aangeroepen, moet u alle R-opdrachten tussen de twee statements inpakken in een try()-statement. Nooit van gehoord? Maak u geen zorgen, het is eenvoudig. Alles wat nodig is, is dat u het patroon volgt in onderstaand voorbeeld.

Een erg nuttige eigenschap van alle plugins die plots/grafieken maken is dat ze een automatische voorbeeldweergave (preview) geven na een wijziging. Hiervoor moet u twee dingen doen: Een <preview> keuzevakje toevoegen aan de GUI-definitie, en de gegenereerde code voor de preview aanpassen.

Toevoegen van een <preview> keuzevakje is eenvoudig. Plaats het volgende ergens in uw GUI. Dit zorgt dan voor alles wat achter de schermen gebeurt wat nodig is voor het maken van een preview, waarbij deze wordt bijgewerkt wanneer er iets aan is gewijzigd, etc.. Voorbeeld:

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

En dat is het dan wat de GUI betreft.

Aanpassen van de JS-sjabloon (template) is wat meer werk, hier moet u nagaan dat alleen de plot zelf wordt gegenereerd en getoond op een apparaat op het scherm, in plaats van gestuurd naar de uitvoer. D.w.z. geen afdrukken van koppen, rk.graphics.on(), of soortgelijke aanroepen. Om u te hiermee te assisteren zal RKWard de functies preprocess(), calculate() en printout() aanroepen met een extra parameter die is ingesteld op true, wanneer de gegenereerde code voor een voorbeeld is. (De parameter wordt weggelaten bij genereren van de uiteindelijke code. In javascript zal dit geëvalueerd worden naar false indien gebruikt binnen een if-statement.) Zie het onderstaande voorbeeld, voor het typische patroon dat u zult gebruiken.

Als alternatief zou u meer controle dan dit nodig moeten hebben, u kunt in plaats daarvan een nieuwe functie genaamd preview() toevoegen aan uw JS-sjabloon en de code genereren, die daar is vereist voor een voorbeeld (mogelijk, minstens gedeeltelijk, opnieuw door calculate() aan te roepen, etc.).

U zult gemerkt hebben dat de meeste plot-plugins in RKWard een groot aantal generieke opties hebben, bijv. voor as-aanpassingen en ruimte om de cijfers heen. Deze opties toevoegen aan uw plugin is eenvoudig. Zij worden verzorgd door een inbedbare plugin met de naam rkward::plot_opties. U kunt die zo in uw plugin inbedden:

<document>
                [...]
                <logic [...]>
                        <connect client="plotopties.xvar" governor="x.beschikbaar"/>
                        <set id="plotopties.toestaan_type" to="true"/>
                        <set id="plotopties.toestaan_ylim" to="true"/>
                        <set id="plotopties.toestaan_xlim" to="false"/>
                        <set id="plotopties.toestaan_log" to="false"/>
                        <set id="plotopties.toestaan_grid" to="true"/>
                </logic>
                <dialog [...]>
                        [...]
                        <embed id="plotopties" component="rkward::plot_opties" as_button="true" label="Plot Opties"/>
                        [...]
                </dialog>
                [...]
        </document>
                

Hierdoor wordt een knop aan uw UI (User Interface) toegevoegd die een venster doet verschijnen met plotopties. De logische sectie is slechts een voorbeeld. U krijgt hiermee enige controle over de plugin voor de plotopties. U kunt hierover meer lezen op de help-pagina van de plugin voor plotopties (een link hiernaar is aanwezig in de help-pagina van alle plugins met de generieke opties).

Vervolgens moet u ervoor zorgen dat de code voor uw plotopties wordt toegevoegd aan de gegenereerde code voor uw plot. Dit doet u door de eigenschappen code.preprocess, code.printout, en code.calculate op te halen uit de ingebedde plugin voor plotopties, en in uw code in te voegen, zoals u kunt zien in het onderstaande voorbeeld.

U ziet hier een .JS-bestand als voorbeeld, dat u kunt gebruiken als sjabloon voor het maken van een plotplugin:

function preprocess () {
    // de "een_of_ander_pakket" is nodig om de plot aan te maken
    echo ("vereist (een_of_ander_pakket)\n");
  }

  function printout (is_voorbeeld) {
    // If "is_voorbeeld"  false/ongedefinieerd is, wordt de volledige code aangemaakt, inclusief kopteksten.
    // If "is_voorbeeld" true is, wordt allen het essentiële aangemaakt.

    if (!is_voorbeeld) {
      echo ('rk.header (' + i18n ("Een voorbeeldplot") + ')\n\n');
      echo ('rk.graph.on ()\n');
    }
    // Alleen de volgende sectie wordt aangemaakt als is_voorbeeld=true

    // onthoud: alles tussen rk.graph.on() en rk.graph.off() moet worden  ingepakt in een try() statement:
    echo ('try ({\n');
    // voeg optie-instellende coderegels in, die moeten worden uitgevoerd voor de werkelijke plotopdrachten.
    // De code zelf  komt uit de ingebedde plugin met plot-opties. printIndentedUnlessEmpty() zorgt voor een mooi afdrukresultaat.
    printIndentedUnlessEmpty ('\t', getString ("plotoptions.code.preprocess"), '', '\n');

    // maak de werkelijke plot. plotoptions.code.printout geeft het deel van de algemene plot opties
    // dat moeten worden toegevoegd aan de plotaanroep zelf.
    echo ('plot (5, 5' + getString ("plotoptions.code.printout") + ')\n');

    // voeg optie-instellende coderegels toe die moeten worden uitgevoerd na de werkelijke plot.
    printIndentedUnlessEmpty ('\t', getString ("plotoptions.code.calculate"), '\n');
    echo ('})'\n);  // Het afsluiten van de try() statement

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