Capítulo 10. Conceitos para uso em plugins especializados

Para desenhar um gráfico na janela de saída, use rk.graph.on() imediatamente antes de criar o gráfico e rk.graph.off() imediatamente depois. Isso é semelhante a, por exemplo, chamar postscript() e dev.off() em uma sessão R regular.

É importante ressaltar, no entanto, que você deve sempre chamar rk.graph.off() após chamar rk.graph.on(). Caso contrário, o arquivo de saída ficará corrompido. Para garantir que rk.graph.off() seja realmente chamado, você deve envolver todos os comandos R entre as duas chamadas em uma instrução try(). Nunca ouviu falar disso? Não se preocupe, é fácil. Tudo o que você precisa fazer é seguir o padrão mostrado no exemplo, abaixo.

Um recurso muito útil para todos os plugins que geram um gráfico é fornecer uma pré-visualização com atualização automática. Para isso, você precisará de duas coisas: Adicionar uma caixa de seleção <preview> à sua definição GUI e ajustar o código gerado para a pré-visualização.

Adicionar uma caixa de seleção <preview> é simples. Basta colocar o seguinte em algum lugar da sua GUI. Isso cuidará de toda a mágica nos bastidores da criação de um dispositivo de visualização, atualizando a visualização sempre que as configurações forem alteradas, etc. Exemplo:

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

E isso conclui a definição da GUI.

Ajustar o modelo JS requer apenas um pouco mais de trabalho. Aqui, você precisará garantir que somente o próprio gráfico seja gerado e exibido em um dispositivo na tela, em vez de ser direcionado para a saída. Ou seja, sem impressão de cabeçalhos, rk.graphics.on() ou chamadas semelhantes. Para auxiliar você nisso, o RKWard chamará as funções preprocess(), calculate() e printout() com um parâmetro adicional definido como true ao gerar o código para uma pré-visualização. (O parâmetro é omitido ao gerar o código final. Em JavaScript, isso será avaliado como false quando usado dentro de uma instrução if.) Veja o exemplo abaixo para o padrão típico que você usará.

Alternativamente, caso precise de mais controle do que isso, você pode adicionar uma nova função chamada preview() ao seu modelo JS e gerar o código necessário para uma pré-visualização ali (provavelmente, pelo menos em parte, chamando novamente calculate(), etc).

Você deve ter notado que a maioria dos plugins de plotagem no RKWard oferece uma ampla gama de opções genéricas como, por exemplo, personalizar títulos de eixos ou margens de figuras. Adicionar essas opções ao seu plugin é fácil. Elas são fornecidas por um plugin incorporável chamado rkward::plot_options. Incorpore-o na interface do seu plugin desta forma:

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

Isso adicionará um botão à sua interface de usuário para abrir uma janela com opções de plotagem. A seção de lógica é apenas um exemplo. Ela permite algum controle sobre o plugin de opções de plotagem. Leia mais na página de ajuda do plugin plot_options (link disponível na página de ajuda de qualquer plugin que forneça as opções genéricas).

Em seguida, você precisa garantir que o código correspondente às suas opções de plotagem seja adicionado ao código gerado para o seu gráfico. Para fazer isso, obtenha as propriedades code.preprocess, code.printout e code.calculate do plugin de opções de plotagem incorporado e insira-as em seu código, conforme mostrado no exemplo, abaixo.

Aqui está um exemplo de arquivo .JS que você deve usar como modelo sempre que criar um plugin de plotagem:

function preprocess () {
    // o "algumpacote" é necessário para criar o gráfico
    echo ("require (algumpacote)\n");
  }
  
  function printout (is_preview) {
    // Se "is_preview" é definido para false/undefined, ele gera o código completo, incluindo headers.
    // Se "is_preview" é definido para true, somente o essencial será gerado.

    if (!is_preview) {
      echo ('rk.header (' + i18n ("An example plot") + ')\n\n');
      echo ('rk.graph.on ()\n');
    }
    // somente a seção a seguir será gerada para is_preview==true

    // lembre-se: tudo entre between rk.graph.on() e rk.graph.off() deve ser circundado dentro de uma declaração try():
    echo ('try ({\n');
    // insira qualquer código de opção-configuração que deve ser executado antes dos comandos de plotagem.
    // O código em si é fornecido para incorporar o plugin de opções de gráfico. printIndentedUnlessEmpty() takes care of pretty formatting.
    printIndentedUnlessEmpty ('\t', getString ("plotoptions.code.preprocess"), '', '\n');

    // cria de fato o gráfico. plotoptions.code.printout fornece a parte das opções genéricas do gráfico
    // que deve ser adicionado à chamada de plotagem em si.
    echo ('plot (5, 5' + getString ("plotoptions.code.printout") + ')\n');

    // insere qualquer código de configuração-opção que deve ser executado após a plotagem em si.
    printIndentedUnlessEmpty ('\t', getString ("plotoptions.code.calculate"), '\n');
    echo ('})'\n);  // the closure of the try() statement

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