Capitolo 10. Concetti per l'uso in estensioni specializzate

Per disegnare un grafico nella finestra di output, utilizzare rk.graph.on() direttamente prima di creare il grafico e rk.graph.off(), subito dopo. Questo è simile a ad es. chiamando postscript() e dev.off() in un normale sessione di R.

È importante sottolineare, tuttavia, che è necessario sempre invocare rk.graph.off() dopo aver invocato rk.graph.on(). Altrimenti il ​​file di output sarà lasciato in uno stato incoerente. Per garantire che rk.graph.off() venga realmente invocato, dovreste racchiudere tutti i comandi di R tra le due chiamate nell'istruzione try(). Non ne avete mai sentito parlare? Nessun problema, è facile. Tutto quello che dovete fare è seguire lo schema mostrato nell'esempio, di seguito.

Una funzionalità molto utile per tutti le estensioni che generano un grafico/traccia è fornire un'anteprima che si aggiorna automaticamente. Per farlo, saranno necessarie due cose: aggiungere una casella di controllo <preview> alla propria GUI definizione e modificare il codice generato per l'anteprima.

Aggiungere una casella di controllo <anteprima> è semplice. Basta inserire il seguente comando da qualche parte nella GUI. Si occuperà di tutta la magia dietro le quinte della creazione di un dispositivo di anteprima, aggiornando l'anteprima ogni volta che le impostazioni cambiano, ecc. Esempio:

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

E questo è tutto per la definizione della GUI.

La regolazione del modello JS richiede solo un po' più di lavoro, qui dovrete assicurarvi che venga generata solo il grafico stesso e mostrato in un dispositivo su schermo, anziché indirizzato all'output, cioè nessuna stampa di intestazioni, rk.graphics.on() o chiamate simili. Per aiutarvi in questo, RKWard invocherà le funzioni preprocess(), calculate() e printout() con un parametro aggiuntivo impostato su true, durante la generazione del codice per un'anteprima. (Il parametro viene omesso durante la generazione del codice finale. In javascript questo risulterà false se utilizzato all'interno di un'istruzione if.) Vedere l'esempio, di seguito per il modello tipico che utilizzerete.

In alternativa, se hai bisogno di un controllo maggiore, puoi aggiungere una nuova funzione chiamata preview() al tuo modello JS e generare lì il codice necessario per un'anteprima (probabilmente, almeno in parte, chiamando nuovamente calculate(), ecc.).

Avrete notato che la maggior parte delle estensioni di tracciamento dei grafici in RKWard fornisce una vasta gamma di opzioni generiche ad es. per personalizzare i titoli degli assi o i margini delle figure. Aggiungere queste opzioni alla propria estensione è semplice. Sono fornite da un'estensione integrabile chiamata rkward:: plot_options. Integra questa estensione nell'interfaccia della propria estensione in questo modo:

<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="Opzioni del grafico"/>
                        [...]
                </dialog>
                [...]
        </document>
                

Ciò aggiungerà un pulsante all'interfaccia utente per visualizzare una finestra con le opzioni di stampa. La sezione logica è solo un esempio. Consente un certo controllo sull'estensione delle opzioni del grafico. Maggiori informazioni nella pagina della guida dell'estensione plot_options (collegata dalla pagina della guida di qualsiasi estensione che fornisce le opzioni generiche).

Successivamente è necessario assicurarsi che il codice corrispondente alle opzioni del grafico sia aggiunto al codice generato per il grafico. Per farlo, recuperare le proprietà code.preprocess, code.printout e code.calculate e inserirle nel proprio codice, come mostrato nel esempio, di seguito.

Ecco un esempio di file .JS che si dovrebbe utilizzare come modello, ogni volta che si crea un'estensione con creazione di grafici:

function preprocess () {
    // «unpacchetto» è necessario per creare il grafico
    echo ("require (unpacchetto)\n");
  }

  function printout (is_preview) {
    // Se «is_preview» è impostata a falso, genera il codice completo, incluse le intestazioni.
    // Se «is_preview» è impostata a vero, sarà generata solo la parte essenziale.

    if (!is_preview) {
      echo ('rk.header (' + i18n ("Un grafico di esempio") + ')\n\n');
      echo ('rk.graph.on ()\n');
    }
    // sarà generata solo la seguente sezione per is_preview==true

    // ricorda: qualsiasi cosa tra rk.graph.on() e rk.graph.off() dovrebbe essere inglobata in un'istruzione try():
    echo ('try ({\n');
    // inserisci qualsiasi codice di definizione delle opzioni che dovrebbe essere eseguito prima dei comandi effettivi di tracciamento dei grafici.
    // Il codice stesso è fornito dall'estensione delle opzioni di tracciamento dei grafici. printIndentedUnlessEmpty() si occupa di rendere piacevole la formattazione.
    printIndentedUnlessEmpty ('\t', getString ("plotoptions.code.preprocess"), '', '\n');

    // crea il grafico. plotoptions.code.printout fornisce la parte delle opzioni generiche dei grafici
    // che devono essere aggiunte alla chiamata di tracciamento, stessa.
    echo ('plot (5, 5' + getString ("plotoptions.code.printout") + ')\n');

    // inserisci qualsiasi codice di definizione delle opzioni che dovrebbe essere eseguito dopo il grafico effettivo.
    printIndentedUnlessEmpty ('\t', getString ("plotoptions.code.calculate"), '\n');
    echo ('})'\n);  // la chiusura dell'istruzione try()

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