<sect1 id="tool-scriptbuilder">
<title
>A Ferramenta de Construção de 'Scripts'</title>
<indexterm
><primary
>Ferramentas</primary>
<secondary
>Construtor de Programas</secondary>
</indexterm>

<para
>KDE applications can be controlled externally from another program, from a console prompt, or from a shell script using the Inter-process communication protocol (<abbrev
>DCOP</abbrev
>). KStars takes advantage of this feature to allow rather complex behaviors to be scripted and played back at any time. This can be used, for example, to create a classroom demo to illustrate an astronomical concept. </para>
<para
>The problem with DBus scripts is, writing them is a bit like programming, and can seem a daunting task to those who do not have programming experience. The Script Builder Tool provides a <abbrev
>GUI</abbrev
> point-and-click interface for constructing KStars DCOP scripts, making it very easy to create complex scripts. </para>

<sect2 id="sb-intro">
<title
>Introdução ao Construtor de Programas</title>

<para
>Antes de explicar como usar o Construtor de 'Scripts', será dada uma introdução muito breve a todos os componentes <abbrev
>GUI</abbrev
>; para mais informações, use a função de "O Que É Isto?". </para>

<screenshot>
<screeninfo
>A Ferramenta de Construção de 'Scripts' </screeninfo>
<mediaobject>
  <imageobject>
    <imagedata fileref="scriptbuilder.png" format="PNG"/>
  </imageobject>
  <textobject>
    <phrase
>Ferramenta de Construção de 'Scripts'</phrase>
  </textobject>
</mediaobject>
</screenshot>

<para
>O Construtor de 'Scripts' é apresentado na imagem acima. A área à esquerda é a do <firstterm
>'Script' Actual</firstterm
>; ela mostra a lista dos comandos que compõem o 'script' em elaboração. A zona da direita é o <firstterm
>Navegador de Funções</firstterm
>; ela mostra uma lista com todas as funções de 'scripts' disponíveis. Por baixo do Navegador de Funções, existe um pequeno painel que irá mostrar uma documentação curta sobre a função seleccionada no Navegador de Funções. O painel por baixo do 'Script' Actual é o <firstterm
>painel dos Argumentos da Função</firstterm
>; quando for seleccionada uma função no 'Script Actual', este painel irá conter os itens para indicar os valores dos argumentos que a função seleccionada necessita. </para
><para
>Along the top of the window, there is a row of buttons which operate on the script as a whole. From left to right, they are: <guibutton
>New Script</guibutton
>, <guibutton
>Open Script</guibutton
>, <guibutton
>Save Script</guibutton
>, <guibutton
>Save Script As...</guibutton
>, and <guibutton
>Test Script</guibutton
>. The function of these buttons should be obvious, except perhaps the last button. Pressing <guibutton
>Test Script</guibutton
> will attempt to run the current script in the main KStars window. You should move the Script Builder window out of the way before pressing this, so you can see the results. </para
><para
>No centro da janela, existe uma coluna de botões que operam em funções individuais do 'script'. De cima para baixo, estas são: <guibutton
>Adicionar Função</guibutton
>, <guibutton
>Remover Função</guibutton
>, <guibutton
>Copiar Função</guibutton
>, <guibutton
>Subir</guibutton
> e <guibutton
>Descer</guibutton
>. O <guibutton
>Adicionar Função</guibutton
> adiciona a função seleccionada de momento no Navegador de Funções na zona do 'Script' Actual (você poderá também adicionar uma função se fizer duplo-click nela). O resto dos botões lidam com a função seleccionada no 'Script Actual', removendo-a, duplicando-a ou mudando a sua posição no 'script' actual. </para>
</sect2>

<sect2 id="sb-using">
<title
>Utilizar o Construtor de 'Scripts'</title>
<para
>Para ilustrar a utilização do Construtor de 'Scripts', iremos apresentar um pequeno exemplo de tutorial onde iremos criar um 'script' que segue a Lua enquanto o relógio anda a uma velocidade acelerada. </para
><para
>Se vamos seguir a Lua, teremos de apontar a visualização para ela em primeiro lugar. A função <firstterm
>lookToward</firstterm
> é usada para isso. Seleccione esta função no Navegador de Funções, tendo em atenção a documentação que é mostrada no painel por baixo do Navegador. Carregue no botão <guibutton
>Adicionar Função</guibutton
> para adicionar esta função à área do 'Script Actual'. O painel dos Argumentos da Função irá conter agora uma lista chamada <quote
>dir</quote
>, que é uma abreviatura de 'direction' (direcção). Esta a direcção para a qual a visualização deverá ser apontada. A lista contém apenas os pontos cardeais, não a Lua ou outros objectos quaisquer. Você poderá então escrever <quote
>Lua</quote
> na opção manualmente, ou carregar no botão <guibutton
>Objecto</guibutton
> para usar a janela de <guilabel
>Procurar um Objecto</guilabel
> para seleccionar a Lua da lista de objectos identificados. Repare que, como de costume, o foco num objecto activa automaticamente o modo de seguimento do objecto, por isso não há necessidade de adicionar a função <firstterm
>setTracking</firstterm
> depois do 'lookToward'. </para
><para
>Agora que já tratámos de apontar para a Lua, queremos fazer o tempo passar a uma velocidade acelerada. Use a função <firstterm
>setClockScale</firstterm
> para isso. Adicione-a ao 'script' fazendo duplo-click nela no Navegador de Funções. O painel de Argumentos da Função contém um selector para indicar a iteração temporal desejada para o relógio da simulação. Mude essa iteração para 3 horas. </para
><para
>OK, já apontámos para a Lua e acelerámos o relógio. Agora só queremos que o 'script' espere durante vários segundos enquanto a visualização persegue a Lua. Adicione a função <firstterm
>waitFor</firstterm
> ao 'script' e use o painel de Argumentos da Função para indicar que deverá esperar 20 segundos antes de continuar. </para
><para
>Para terminar, vamos repor a iteração temporal do relógio para o valor normal de 1 segundo. Adicione outra instância do 'setClockScale', e coloque o seu valor a 1 s. </para
><para
>De facto, ainda não terminámos realmente. Temos provavelmente que nos certificar a visualização está a usar coordenadas Equatoriais antes de o 'script' seguir a Lua com uma iteração temporal acelerada. Caso contrário, se a visualização estiver a usar coordenadas Horizontais, ela irá rodar muito depressa, com ângulos grandes, à medida que a Lua nasce e se põe. Isto poderá ser muito confuso, e é evitado se usar a opção de visualização <firstterm
>UseAltAz</firstterm
> igual a <quote
>false</quote
>. Para mudar uma opção de visualização qualquer, use a função <firstterm
>changeViewOption</firstterm
>. Adicione esta função ao 'script' e analise o painel dos Argumentos da Função. Existe uma lista que contém todas as opções de visualização que poderão ser ajustadas com o 'changeViewOption'. Dado que sabemos que queremos usar a opção UseAltAz, poderemos simplesmente seleccioná-la na lista. Contudo, a lista é muito grande, e não existe nenhuma explicação para que é que serve cada item. Por isso poderá ser mais fácil carregar no botão <guibutton
>Árvore de Navegação</guibutton
>, o qual irá abrir uma janela que contém uma árvore com todas as opções de visualização, organizadas por tópico. Para além disso, cada item tem uma breve explicação do que é que a opção faz e o tipo de dados do valor da opção. A opção UseAltAz encontra-se sob a categoria <guilabel
>Opções do mapa do céu</guilabel
>. Basta seleccionar este item e carregar em <guibutton
>OK</guibutton
>, para que fique seleccionado na lista do painel dos Argumentos da Função. Finalmente, coloque o seu valor a <quote
>false</quote
> ou a <quote
>0</quote
>. </para
><para
>Um passo mais: a alteração do 'UseAltAz' no fim do 'script' não nos faz nada bem; precisamos que isto seja alterado antes que algo de mau aconteça. Por isso, certifique-se que esta função é seleccionada na janela do 'Script Actual' e carregue no botão <guibutton
>Subir</guibutton
> até que seja a primeira função. </para
><para
>Agora que terminámos o 'script', deveremos gravá-lo em disco. Carregue no botão <guibutton
>Gravar 'Script'</guibutton
>. Isto irá abrir em primeiro lugar uma janela onde poderá indicar um nome para o 'script' e preencher o seu nome como autor. Indique como nome <quote
>Seguir a Lua</quote
> e o seu nome como autor, carregando depois em <guibutton
>OK</guibutton
>. De seguida, você irá ver a janela normal de Gravar um Ficheiro do &kde;. Indique o nome do ficheiro do 'script' e carregue em <guibutton
>OK</guibutton
> para gravar o código. Repare que, se o seu ficheiro não terminar em <quote
>.kstars</quote
>, este sufixo será adicionado automaticamente. Se você for curioso, poderá examinar o ficheiro do 'script' com um editor de texto qualquer. </para
><para
>Now that we have a completed script, we can run it in a couple of ways. From a console prompt, you can simply execute the script as long as an instance of KStars is currently running. Alternatively, you can execute the script from within KStars using the <guimenuitem
>Run Script</guimenuitem
> item in the <guimenu
>File</guimenu
> menu. </para>
</sect2>
</sect1>

