path: root/tde-i18n-pt_BR/docs/kdeedu/kstars/dcop.docbook

<chapter id="dcop">
<title
>Scripting o KStars: A Interface DCOP</title>
<para
>Um dos objetivos do &kstars; é fornecer a habilidade de executar comportamentos complexos a partir de um script. Isto permitirá que você crie <quote
>passeios virtuais</quote
> no universo, e possibilitará que professores construam demonstrações em uma aula para ilustrar determinados conceitos de astronomia. Isto já é possível através dos scripts para o &kstars;, apesar de nem todas as funções desejadas estarem incluídas. Além disso, por enquanto não temos um construtor de scripts gráfico, devendo os scripts serem escritos manualmente. Este capítulo explanará como construir scripts para o &kstars;. </para>
<para
>A arquitetura do &kde; fornece o ambiente de trabalho necessário para aplicativos com suporte a scripts através da interface <abbrev
>DCOP</abbrev
>. <abbrev
>DCOP</abbrev
> é uma acrônimo, do inglês, para <quote
>Protocolo de Comunicação de Ambiente</quote
>; através do <abbrev
>DCOP</abbrev
>, aplicativos &kde; podem ser controlados por outros aplicativos, a partir da linha de comando, ou através de um script de texto. NOTA DO TRADUTOR: Observem que os scripts são todos escritos no idioma inglês, não podendo os nomes de funções e argumentos serem traduzidos. </para>

<sect1 id="dcop-interface">
<title
>Funções DCOP</title>
<para
>A Interface <abbrev
>DCOP</abbrev
> do &kstars; inclui as seguintes funções: <itemizedlist>
<listitem
><para
><function
> lookTowards( const QString direction )</function
>: Aponta o foco da tela na direção especificada pelo argumento. O argumento pode ser o nome de qualquer objeto no céu, ou uma das seguintes palavras direcionais ou abreviaturas: zenith (ou z), north (n), northeast (ne), east (e), southeast (se), south (s), southwest(sw), west(w), northwest (nw). </para
></listitem>

<listitem
><para
><function
> setRaDec( double ra, double dec )</function
>: Aponta o foco da tela nas coordenadas equatorias especificadas. </para
></listitem>

<listitem
><para
><function
> setAltAz(double alt, double az)</function
>: Aponta o foco da tela nas coordenadas horizontais especificadas. </para
></listitem>

<listitem
><para
><function
> zoomIn()</function
>: Aumenta o nível de ampliação da tela. </para
></listitem>

<listitem
><para
><function
> zoomOut()</function
>: Diminui o nível de ampliação da tela. </para
></listitem>

<listitem
><para
><function
> defaultZoom()</function
>: Reinicia a tela para o nível de ampliação = 3 (o padrão). </para
></listitem>

<listitem
><para
><function
> setLocalTime(int yr, int mth, int day, int hr, int min, int sec)</function
>: Configura o relógio da simulação para a data e hora especificadas. </para
></listitem>

<listitem
><para
><function
> waitFor( double t )</function
>: Interrompe por t segundos antes de continuar com os comandos subsequentes do script. </para
></listitem>

<listitem
><para
><function
> waitForKey( const QString k )</function
>: Para a execução do script até que o usuário pressione a tecla especificada. Até o momento, você não pode especificar combinações com teclas especiais (como <keycombo action="simul"
>&Ctrl;<keycap
>C</keycap
></keycombo
>); simplesmente use teclas simples. Você pode digitar <quote
>space</quote
> para indicar a barra de espaço. </para
></listitem>

<listitem
><para
><function
> setTracking( bool track )</function
>: Alterna o engajamento do modo de rastreamento. </para
></listitem>

<listitem
><para
><function
> changeViewOption( const QString option, const QString value )</function
>: Ajusta uma opção de visão. Existem dúzias e dúzias de opções disponíveis, basicamente tudo que você pode musar na <guilabel
>Janela Configurar o &kstars;</guilabel
> pode ser mudado aqui também. O primeiro argumento é o nome da opção (os nomes são obtidos a partir do arquivo de configuração <filename
>kstarsrc</filename
>), e o segundo argumento é o valor desejado. A análise do argumento foi feita para ser robusta, logo se você acidentalmente enviar dados ruins, ele simplesmente falhará. </para
></listitem>

<listitem
><para
><function
> setGeoLocation( const QString city, const QString province, const QString country )</function
>: Muda a localização de observação para a cidade especificada. Se nenhuma cidade correspondente ao string do argumento for encontrada, então nada acontecerá. </para
></listitem>

<listitem
><para
><function
> stop()</function
> [clock]: Para o relógio da simulação. </para
></listitem>

<listitem
><para
><function
> start()</function
> [clock]: Inicia o relógio da simulação. </para
></listitem>

<listitem
><para
><function
> setScale(float s)</function
> [clock]: Configura a taxa do relógio da simulação. s=1 corresponde ao tempo real; 2,0 é duas vezes mais rápido que o tempo real, etc. </para
></listitem>
</itemizedlist>
</para>
</sect1>

<sect1 id="dcop-test">
<title
>Testando as Funções DCOP</title>
<para
>Você pode testar as funções DCOP muito facilmente usando o programa <application
>kdcop</application
>. Quando você executar o <application
>kdcop</application
>, você verá uma lista em árvore de todos os programas em execução; se o &kstars; estiver rodando ele será listado. A maioria das funções <abbrev
>DCOP</abbrev
> são listadas sob o cabeçalho <quote
>KStarsInterface</quote
>, mas as funções de relógio estão listadas sob o <quote
>clock</quote
>. Um clique-duplo em qualquer função irá executá-la. Se a função necessita de argumentos, uma janela se abrirá aonde poderá inserir os valores. </para>
</sect1>

<sect1 id="dcop-script">
<title
>Escrevendo um Script DCOP</title>
<para
>Funções <abbrev
>DCOP</abbrev
> podem também ser chamadas a partir da linha de comando do UNIX, e elas podem ser encapsuladas em um script. Nós criaremos um script exemplo que alterna para as coordenadas Equatoriais, aponta a tela para a Lua, amplia um pouco, e acelera o relógio para 1 hora por segundo. Após rastrear a Lua por 20 segundos, o relógio é parado e a tela diminui a ampliação. Você pode usar este script como um modelo para criar novos scripts. Eu listarei todo o script primeiro, e então explanarei suas várias partes. </para>
<para>
<programlisting
>#!/bin/bash
#KStars script: Rastreando a Lua!
#
KSTARS=`dcopfind -a 'kstars*'`
MAIN=KStarsInterface
CLOCK=clock#1
dcop $KSTARS $MAIN  changeViewOption UseAltAz false
dcop $KSTARS $MAIN  lookTowards Moon
dcop $KSTARS $MAIN  defaultZoom
dcop $KSTARS $MAIN  zoomIn
dcop $KSTARS $MAIN  zoomIn
dcop $KSTARS $MAIN  zoomIn
dcop $KSTARS $MAIN  zoomIn
dcop $KSTARS $MAIN  zoomIn
dcop $KSTARS $CLOCK setScale 3600.
dcop $KSTARS $CLOCK start
dcop $KSTARS $MAIN  waitFor  20.
dcop $KSTARS $CLOCK stop
dcop $KSTARS $MAIN  defaultZoom
##
</programlisting>
</para>
<para
>Salve este script para um arquivo. O nome do arquivo pode ser qualquer um que deseje, eu sugiro algo descritivo como <filename
>rastrolua.kstars</filename
>. Então digite o seguinte comando para tornar o script executável: <userinput
><command
>chmod</command
> <option
>a+x</option
> <parameter
>rastrolua.kstars</parameter
> </userinput
>. O script pode então ser executado a qualquer momento digitando <userinput
><command
>./rastrolua.kstars</command
></userinput
> na pasta que contém o script. Observe que o script somente funcionará se uma instância do &kstars; já estiver rodando. Você pode usar o comando <command
>dcopstart</command
> em um script para lançar uma nova instância do &kstars;. </para>
<para
>Agora vamos para a explanação do script. A linha superior identifica o arquivo como um script shell do <command
>BASH</command
>. As duas linhas seguintes são <firstterm
>comentários</firstterm
> (qualquer linha que inicie com o <quote
>#</quote
> é um comentário,e é ignorada pelo shell). As próximas três linhas definem algumas variáveis convenientes que serão usadas mais tarde. A variável <varname
>KSTARS</varname
> identifica o processo do &kstars; atualmente em execução, usando o comando <command
>dcopfind</command
>. <varname
>MAIN</varname
> e <varname
>CLOCK</varname
> identificam as duas interfaces <abbrev
>DCOP</abbrev
> associadas ao &kstars;. </para>
<para
>O lembrete do script é a lista atual de chamadas <abbrev
>DCOP</abbrev
>. O primeiro comando configura a tela para usar as coordenadas Equatoriais configurando a opção <quote
>UseAltAz</quote
> para <quote
>false</quote
> (novamente, você pode ver a lista de todas as opções que o <quote
>changeViewOption</quote
> pode usar examinando seu arquivo de configuração <filename
>kstarrc</filename
>). O próximo comando centraliza a tela na Lua, e automaticamente engaja o rastreamento. Nós então configuramos o nível de ampliação padrão, e então a ampliação em cinco vezes. A seguir, a escala do tempo do relógio é configurada para 1 hora por segundo (3600 segundos é uma hora),e o relógio é iniciado (no caso de não estar rodando). A próxima linha para o script por 20 segundos enquanto nós rastreamos a Lua conforme ela se move no céu. Finalmente, nós paramos o relógio e reiniciamos o nível de ampliação para sua configuração padrão. </para>
<para
>Nós esperamos que você goste das habilidades de script do KStars. Se você criar um script interessante, por favor envie eletronicamente para <email
>kstars@30doradus.org</email
>; nós gostaríamos de ver o que você fez, e talvez colocar alguns scripts em nossa página web. Além disso, se tiver qualquer idéia de como melhorar os recursos de script (ou qualquer parte do &kstars;), informe-nos em <email
>kstars-devel@lists.sourceforge.net</email
> ou envie um pedido de recurso novo para o bugzilla. </para>
</sect1>
</chapter>