Capítulo 4. Definir a GUI

No capítulo anterior você viu como registrar um plugin com o RKWard. O ingrediente mais importante foi especificar o caminho para um arquivo XML com uma descrição de como o plugin realmente se parece. Neste capítulo, você aprenderá como criar este arquivo XML.

Mais uma vez, vamos apresentar um exemplo. O exemplo é uma versão (ligeiramente simplificada) do teste t de duas variáveis.

<!DOCTYPE rkplugin>
        

O doctype não é realmente interpretado. Defina-o como rkplugin, mesmo assim.

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

Todos os plugins geram algum código. Atualmente, a única maneira de fazer isso é usando JS, como detalhado no próximo capítulo. Isso define onde procurar o código JS. O nome do arquivo é relativo ao diretório onde o plugin XML está localizado.

<help file="t_test_duas_vars.rkh"/>
        

Geralmente é uma boa ideia também fornecer uma página de ajuda para o seu plugin. O nome do arquivo dessa página de ajuda é fornecido aqui, relativo ao diretório onde o plugin XML está localizado. A criação de páginas de ajuda está documentada aqui. Se você não fornecer um arquivo de ajuda, omita esta linha.

<dialog label="Teste t com duas variáveis">
        

Como você sabe, os plugins podem ter uma interface de diálogo, uma interface de assistente ou ambas. Aqui, começamos a definir uma interface de diálogo. O atributo label especifica o título do diálogo.

<tabbook>
                        <tab label="Configurações básicas">
        

Os elementos da GUI podem ser organizados usando um catálogo de abas. Aqui, definimos um catálogo de abas como o primeiro elemento da caixa de diálogo. Use <tabbook>[...]</tabbook> para definir o catálogo de abas e, em seguida, para cada página do catálogo de abas, use <tab>[...]</tab>. O atributo label no elemento <tab> permite especificar uma legenda para essa página do catálogo de abas.

<row id="main_settings_row">
        

As tags <row> e <column> especificam o layout dos elementos da GUI. Aqui, você indica que gostaria de colocar alguns elementos lado a lado (da esquerda para a direita). O atributo id não é estritamente necessário, mas o utilizaremos posteriormente, ao adicionar uma interface de assistente ao nosso plugin. O primeiro elemento a ser colocado na linha é:

<varselector id="vars"/>
        

Usando esta tag simples, você cria uma lista da qual o usuário pode selecionar variáveis. Você precisa especificar um id para este elemento, para que o RKWard saiba como encontrá-lo.

<column>
        

Em seguida, aninhamos uma <column> dentro da linha. Ou seja, os elementos seguintes serão colocados uns acima dos outros (de cima para baixo), e todos ficarão à direita do <varselector>.

<varslot types="number" id="x" source="vars" required="true" label="comparar"/>
                                                <varslot types="number" id="y" source="vars" required="true" label="contra" i18n_context="comparar contra"/>
        

Esses elementos são a contraparte do <varselector>. Eles representam “slots” nos quais o usuário pode inserir variáveis. Você notará que o source é definido com o mesmo valor que o id do <varselector >. Isso significa que os <varslot>s obterão suas variáveis ​​do varselector. Os <varslot>s também precisam receber um id. Eles podem ter um label e podem ser definidos como required. Isso significa que o botão Enviar não será habilitado até que o <varslot> contenha um valor válido. Finalmente, o atributo type ainda não foi interpretado, mas será usado para garantir que apenas os tipos corretos de variáveis ​​sejam permitidos no <varslot>.

Caso você esteja se perguntando sobre o atributo i18n_context: Ele serve para fornecer contexto e auxiliar na tradução correta da palavra "against", usada como rótulo do <varslot>, mas não afeta diretamente a funcionalidade do plugin. Mais informações sobre isso em um capítulo separado.

<radio id="hypothesis" label="usar hipótese de teste">
                                                        <option value="two.sided" label="Dois lados"/>
                                                        <option value="greater" label="Primeiro é maior"/>
                                                        <option value="less" label="Segundo é maior"/>
                                                </radio>
        

Aqui, você define um grupo de botões exclusivos <radio>. O grupo possui um label e um id. Cada <option> (botão) possui um label e recebe um value. Este é o valor que o elemento <radio> retornará quando a opção for selecionada.

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

Cada tag precisa ser fechada. Colocamos todos os elementos que queríamos (os dois <varslots> e o <radio>) no <column>. Colocamos todos os elementos que queríamos (o <varselector> e o <column> com esses elementos) no <row>. E colocamos todos os elementos que queríamos na primeira página no <tabbook>. Ainda não terminamos de definir o <tabbook> (mais páginas virão), e é claro que também há mais por vir no <dialog>. Mas esta captura de tela mostra basicamente o que fizemos até agora:

Observe que não especificamos os botões Submit, Close, etc., nem a visualização do código. Esses elementos são gerados automaticamente. Mas, é claro, ainda precisamos definir a segunda página do <tabbook>:

<tab label="Options">
                                <checkbox id="varequal" label="assumir variâncias iguais" value=", var.equal=TRUE"/>
        

Por padrão, os elementos serão dispostos de cima para baixo, como em uma <column>. Como é isso que queremos aqui, não precisamos declarar explicitamente um layout <row> ou <column>. O primeiro elemento que definimos é uma caixa de seleção. Assim como os <radio><option>s, a caixa de seleção tem um label e um value. O value é o que é retornado se a caixa de seleção estiver marcada. Obviamente, a caixa de seleção também precisa de um id.

<frame label="Intervalo de confiança" id="frame_conf_int">
        

Aqui está mais um elemento de layout: Para sinalizar que os dois elementos abaixo pertencem ao mesmo conjunto, desenhamos uma <frame> (caixa). Esse quadro pode ter um label (legenda). Como o quadro é apenas um elemento de layout passivo, ele não precisa de um id, mas ainda assim definimos um aqui, pois nos referiremos a ele mais tarde, ao definir uma interface de assistente adicional.

<checkbox id="confint" label="imprimir intervalo de confidência" value="1" checked="true"/>
                                        <spinbox type="real" id="conflevel" label="nível de confidência" min="0" max="1" initial="0.95"/>
                                </frame>
        

Dentro do <frame>, colocamos outro <checkbox> (usando checked="true", sinalizamos que a caixa de seleção deve estar marcada por padrão) e um <spinbox>. O spinbox permite que o usuário selecione um valor entre "min" e "max", com o valor padrão/inicial "0.95". Definir o parâmetro type como "real" indica que números reais são aceitos em oposição a type="integer", que aceitaria apenas números inteiros.

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

Isso é tudo para a segunda página do <tabbook>, todas as páginas do <tabbook> e todos os elementos do <dialog>. Terminamos de definir a aparência do diálogo.

</document>
        

Finalmente, fechamos a tag <document>, e isso é tudo. A GUI está definida. Você pode salvar o arquivo agora. Mas como a sintaxe R é gerada a partir das configurações da GUI? Abordaremos isso no próximo capítulo. Primeiro, porém, vamos examinar a adição de uma interface de assistente e algumas considerações gerais.