Capitolo 4. Definizione della GUI

Nel capitolo precedente si è visto come registrare un'estensione con RKWard. L'ingrediente più importante è stato specificare il percorso di un file XML con una descrizione dell'aspetto dell'estensione. In questo capitolo imparerete come creare questo file XML.

Ancora una volta vi guideremo attraverso un esempio. L'esempio è una versione (leggermente semplificata) del test t a due variabili.

<!DOCTYPE rkplugin>
        

Il doctype non è ancora realmente interpretato. Impostarlo comunque a rkplugin.

<document>
        <code file="test_t_due_variabili.js"/>
        

Tutti le estensioni generano del codice. Attualmente l'unico modo per farlo è utilizzare JS, come descritto nel prossimo capitolo. Questo definisce dove cercare il codice JS. Il nome file è relativo alla cartella in cui si trova l'estensione XML.

<help file="test_t_due_variabili.rkh"/>
        

Di solito è una buona idea fornire anche una pagina della guida per la propria estensione. Il nome del file di tale pagina, qui fornito, si riferisce, alla cartella in cui si trova l'estensione XML. La scrittura delle pagine della guida è documentata qui. Se non si fornisce un file della guida, omettere questa riga.

<dialog label="Test t a due variabili">
        

Come è noto, le estensioni possono avere una finestra di dialogo o un'interfaccia guidata o entrambi. Qui iniziamo a definire un'interfaccia di dialogo. L'attributo labelspecifica la didascalia della finestra di dialogo.

<tabbook>
                        <tab label="Impostazioni di base">
        

Gli elementi della GUI possono essere organizzati utilizzando un tabbook. Qui definiamo una scheda come primo elemento nella finestra di dialogo. Utilizzare <tabbook>[...]</tabbook> per definire il tabbook e poi per ciascuna pagina nel tabbook utilizzare <tab>[...]</tab>. L'attributo label nell'elemento <tab> ti consente di specificare una didascalia per quella pagina del tabbook.

<row id="riga_configurazione_principale">
        

I tag <row> e <column> specificano la struttura degli elementi della GUI. Qui si indica che si desidera posizionare alcuni elementi affiancati (da sinistra a destra). L'attributo id non è strettamente necessario, ma sarà utilizzato in seguito, quando si aggiunge un'interfaccia guidata alla nostra estensione. Il primo elemento da posizionare nella riga è:

<varselector id="variabili"/>
        

Utilizzando questo semplice tag si crea un elenco da cui l'utente può selezionare le variabili. È necessario specificare un id per questo elemento, in modo che RKWard sappia come trovarlo.

<column>
        

Successivamente, annidiamo una <column> all'interno della riga. Cioè i seguenti elementi saranno posizionati uno sopra l'altro (dall'alto verso il basso) e tutti saranno a destra del <varselector>.

<varslot types="number" id="x" source="vars" required="true" label="compare"/>
                                                <varslot types="number" id="y" source="vars" required="true" label="against" i18n_context="confronta con"/>
        

Questi elementi sono la controparte del <varselector>. Rappresentano «slot» in cui l'utente può inserire variabili. Noterete che source è impostato sullo stesso valore di id del <varselector>. Ciò significa che i <varslot> prenderanno ciascuno le proprie variabili dal varselector. Anche i <varslot> devono avere un id. Possono avere un'etichetta e possono essere impostati su required. Ciò significa che il pulsante Invia non sarà abilitato finché il <varslot> non conterrà un valore valido. Infine l'attributo type non è ancora interpretato, ma sarà utilizzato per fare in modo che solo i tipi corretti di variabili siano consentiti nel <varslot>.

Nel caso ci si stia chiedendo dell'attributo i18n_context: questo serve a fornire un contesto per aiutare la traduzione corretta della parola «contro», utilizzata come etichetta del <varslot>, ma non influisce direttamente sulla funzionalità dell'estensione. Altre informazioni al riguardo in un capitolo separato.

<radio id="hypothesis" label="ipotesi del test in uso">
                                                        <option value="due.lati" label="Due lati"/>
                                                        <option value="maggiore" label="Il primo è più grande"/>
                                                        <option value="minore" label="Il secondo è più grande"/>
                                                </radio>
        

Qui definisci un gruppo di pulsanti esclusivi <radio>. Il gruppo ha un'etichetta e un id. Ogni <opzione> (pulsante) ha un'etichetta e gli viene assegnato un valore. Questo è il valore che l'elemento <radio> restituirà quando l'opzione è selezionata.

</column>
                                </row>
                        </tab>
        

Ogni tag deve essere chiuso. Abbiamo inserito tutti gli elementi che volevamo (i due <varslots> e il <radio>) nel <column>. Inseriamo tutti gli elementi che vogliamo (il <varselector> e il <column> con quegli elementi) nel <row>. E abbiamo inserito tutti gli elementi che volevamo nella prima pagina del <tabbook>. Non abbiamo ancora finito di definire il <tabbook> (altre pagine a venire), e ovviamente c'è altro in arrivo anche nel <dialog>. Ma questa schermata è fondamentalmente ciò che abbiamo fatto finora:

Notare che non abbiamo specificato i pulsanti Invia, Chiudi ecc. o la vista del codice. Questi elementi sono generati automaticamente. Ma ovviamente dobbiamo ancora definire la seconda pagina del <tabbook>:

<tab label="Opzioni">
                                <checkbox id="varequal" label="assumi varianze uguali" value=", var.equal=TRUE"/>
        

Per impostazione predefinita, gli elementi saranno posizionati dall'alto verso il basso come in una <colonna>. Poiché questo è ciò che vogliamo qui, non dobbiamo dichiarare esplicitamente una disposizione <riga> o <colonna>. Il primo elemento che definiamo è una casella di controllo. Proprio come i <radio><opzione>, la casella di controllo ha un'etichetta e un valore. Il valore è ciò che viene restituito, se la casella di controllo è selezionata. Ovviamente la casella di controllo necessita anche di un id.

<frame label="Intervallo di confidenza" id="frame_conf_int">
        

Ecco ancora un altro elemento di struttura: per segnalare che i due elementi sottostanti sono uniti, tracciamo un <frame> (scatola). Quella cornice può avere una label (didascalia). Poiché la cornice è solo un elemento passivo della struttura, non ha bisogno di un id, ne definiamo ancora uno qui, come faremo riferimento in seguito, quando definiremo un'interfaccia aggiuntiva della procedura

<checkbox id="confint" label="stampa l'intervallo di confidenza" value="1" checked="true"/>
                                        <spinbox type="real" id="conflevel" label="livello di confidenza" min="0" max="1" initial="0.95"/>
                                </frame>
        

All'interno del <frame> inseriamo un altro <checkbox> (utilizzando checked="true", segnaliamo che la casella di selezione dovrebbe essere selezionata per impostazione predefinita) e un <spinbox>. La casella numerica consente all'utente di selezionare un valore compreso tra "min" e "max" con il valore predefinito/iniziale "0.95". L'impostazione di type su "real" segnala che i numeri reali sono accettati al contrario di type=""integer" che accetterebbe solo numeri interi.

</tab>
                </tabbook>
        </dialog>
        

Questo è tutto per la seconda pagina del <tabbook>, tutte le pagine nel <tabbook> e tutti gli elementi nella <dialog>. Abbiamo finito di definire l'aspetto della finestra.

</document>
        

Alla fine chiudiamo il tag <document>, e basta. La GUI è definita. È possibile salvare il file ora. Ma come viene generata la sintassi di R dalle impostazioni della GUI? Ci occuperemo di ciò nel prossimo capitolo. In primo luogo, tuttavia, esamineremo l'aggiunta di un'interfaccia guidata e alcune considerazioni generali.