Capítol 10. Conceptes per a utilitzar en connectors especialitzats

Per a dibuixar un diagrama a la finestra de sortida, utilitzeu rk.graph.on() directament abans de crear el diagrama, i rk.graph.off(), directament després. Això és similar, p. ex., cridar postscript() i dev.off() en una sessió normal de l'R.

Tanmateix, és important que sempre es cridi rk.graph.off() després de cridar rk.graph.on(). En cas contrari, el fitxer de sortida es deixarà en un estat trencat. Per a assegurar-vos que rk.graph.off() realment sigui cridat, haureu d'ajustar totes les ordres R entre les dues crides en l'expressió try(). Mai ho havíeu escoltat? No us preocupeu, és fàcil. Tot el que heu de fer és seguir el patró mostrat a l'exemple a continuació.

Una característica molt útil per a tots els connectors que generen un diagrama/gràfic és proporcionar una previsualització d'actualització automàtica. Per a fer-ho, necessitareu dues coses: Afegir una casella de selecció <preview> a la definició de la IGU, i ajustar el codi generat per a la vista prèvia.

Afegir una casella de selecció de <preview> és senzill. Col·loqueu el següent en algun lloc de la IGU. S'encarregarà de tota la màgia entre bastidors de crear un dispositiu de vista prèvia, actualitzar la vista prèvia sempre que la configuració hagi canviat, etc. Exemple:

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

I això és per la definició de la IGU.

Ajustar la plantilla JS és només una mica més de feina, aquí haureu d'assegurar-vos que només es genera el diagrama en si, i es mostra en un dispositiu en pantalla, en lloc d'anar dirigit a la sortida. És a dir, sense impressió de capçaleres, rk.graphics.on(), o crides similars. Per a ajudar-vos en això, el RKWard cridarà les funcions preprocess(), calculate() i printout() amb un paràmetre addicional que s'estableix a true en generar codi per a una vista prèvia. (El paràmetre s'omet en generar el codi final. En el javascript això avaluarà false quan s'utilitzi dins d'una sentència if.) Vegeu l'exemple a continuació per al patró típic que utilitzareu.

Alternativament, si necessiteu més control que aquest, podeu afegir una funció nova anomenada preview() a la plantilla JS, i generar el codi requerit per a una vista prèvia, allà (probablement, almenys en part, de nou cridant calculate(), etc.).

Us haureu adonat que la majoria dels connectors de traçat al RKWard proporcionen una àmplia varietat d'opcions genèriques, p. ex., per a personalitzar els títols dels eixos o els marges de les xifres. Afegir aquestes opcions al vostre connector és fàcil. Són proporcionats per un connector incrustable anomenat rkward::plot_options. Incrusteu això a la interfície d'usuari del connector com aquí:

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

Això afegirà un botó a la interfície d'usuari per a obrir una finestra amb les opcions del diagrama. La secció lògica és només un exemple. Permet un cert control sobre el connector d'opcions del diagrama. Llegiu-ne més a la pàgina d'ajuda del connector «plot_options» (enllaçada des de la pàgina d'ajuda de qualsevol connector que proporcioni les opcions genèriques).

A continuació, haureu d'assegurar-vos que el codi corresponent a les opcions del diagrama s'afegeix al codi generat per al diagrama. Per a fer-ho, obteniu les propietats code.preprocess, code.printout, i code.calculate des del connector incrustat d'opcions del diagrama i inseriu-les al codi tal com es mostra a l'exemple a continuació.

Aquest és un exemple de fitxer .JS que hauríeu d'utilitzar com a plantilla, sempre que creeu un connector de traçat:

function preprocess () {
    // the "somepackage" is needed to create the plot
    echo ("require (somepackage)\n");
  }
  
  function printout (is_preview) {
    // If "is_preview" is set to false/undefined, 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');
    }
  }