path: root/tde-i18n-it/docs/kdeedu/kstars/scriptbuilder.docbook

<sect1 id="tool-scriptbuilder">
<title
>Il Costruttore script</title>
<indexterm
><primary
>Strumenti</primary>
<secondary
>Costruttore script</secondary>
</indexterm>

<para
>Le applicazioni KDE possono essere controllate esternamente da un altro programma, da un prompt di terminale o da uno script di shell, grazie al Protocollo di Comunicazione Desktop (Desktop COmmunication Protocol, <abbrev
>DCOP</abbrev
>). KStars sfrutta questa possibilità per permettere in ogni momento la registrazione e riproduzione di complesse sequenze di eventi. Ciò può essere utile, ad esempio, per creare una dimostrazione didattica che illustri un concetto astronomico. </para>
<para
>Il problema con gli script DCOP è che scriverli è un po' come programmare, impresa che può apparire proibitiva a chi non ha esperienza in materia. Il Costruttore script fornisce un'interfaccia grafica (<abbrev
>GUI</abbrev
>) punta-e-fai-clic per realizzare gli script DCOP di KStars, rendendo molto facile crearne anche di complessi. </para>

<sect2 id="sb-intro">
<title
>Introduzione al Costruttore script</title>

<para
>Prima di spiegare come si usa il Costruttore script, introdurremo brevemente tutti i componenti dell'interfaccia grafica; per maggiori informazioni, utilizza la funzione "Che cos'è questo?". </para>

<screenshot>
<screeninfo
>Il Costruttore Script </screeninfo>
<mediaobject>
  <imageobject>
    <imagedata fileref="scriptbuilder.png" format="PNG"/>
  </imageobject>
  <textobject>
    <phrase
>Costruttore script</phrase>
  </textobject>
</mediaobject>
</screenshot>

<para
>Il Costruttore script è mostrato nell'immagine qui sopra. A sinistra c'è il <firstterm
>riquadro Script corrente</firstterm
> che mostra la lista di comandi inclusi nello script corrente. Il riquadro a destra è il <firstterm
>Browser funzioni</firstterm
>, con la lista di tutte le funzioni disponibili. Sotto il Browser funzioni c'è un pannello dove compare una breve documentazione sulla funzione evidenziata nel riquadro sovrastante. Sotto il riquadro Script corrente c'è il <firstterm
>pannello Argomenti funzione</firstterm
>; quando si seleziona una funzione nel riquadro Script corrente, in questo pannello appare il necessario per specificare il valore degli argomenti eventualmente richiesti. </para
><para
>In cima alla finestra c'è una fila di pulsanti che operano sullo script nel suo insieme. Da sinistra a destra: <guibutton
>Nuovo script</guibutton
>, <guibutton
>Apri script</guibutton
>, <guibutton
>Salva script</guibutton
>, <guibutton
>Salva script con nome...</guibutton
> e <guibutton
>Prova script</guibutton
>. La funzione di questi pulsanti dovrebbe essere ovvia, fatta forse eccezione per l'ultimo. Premendo <guibutton
>Prova script</guibutton
> lo script corrente sarà eseguito nella finestra principale di KStars. Prima di farlo ti consigliamo di spostare la finestra del Costruttore script, in modo che tu possa vedere i risultati. </para
><para
>Al centro della finestra c'è una fila verticale di pulsanti che operano su singole funzioni dello script. Dall'alto in basso: <guibutton
>Aggiungi funzione</guibutton
>, <guibutton
>Elimina funzione</guibutton
>, <guibutton
>Copia funzione</guibutton
>, <guibutton
>Sposta in alto</guibutton
> e <guibutton
>Sposta in basso</guibutton
>. Il pulsante <guibutton
>Aggiungi funzione</guibutton
> aggiunge la funzione selezionata nel Browser all'interno del riquadro Script corrente (puoi anche aggiungere una funzione con un doppio clic su di essa). Gli altri pulsanti operano sulla funzione selezionata nel riquadro Script corrente, con l'effetto di eliminarla, duplicarla o modificarne la posizione all'interno dello script. </para>
</sect2>

<sect2 id="sb-using">
<title
>Utilizzo del Costruttore script</title>
<para
>Per illustrare l'utilizzo del Costruttore script presenteremo un piccolo esempio. Scriveremo uno script che insegue la Luna mentre il tempo scorre a velocità accelerata. </para
><para
>Se vogliamo inseguire la Luna dobbiamo per prima cosa puntarla. La funzione <firstterm
>lookToward</firstterm
> ha precisamente questo scopo. Selezionala nel Browser funzioni e consulta la documentazione visualizzata nel pannello sottostante. Quindi premi il pulsante <guibutton
>Aggiungi funzione</guibutton
> per aggiungere la funzione nel riquadro Script corrente. Il pannello Argomenti funzione conterrà ora una casella chiamata <quote
>Dir</quote
>, che sta per "Direzione". Si tratta della direzione verso cui si vuol puntare il display. La lista contiene solo i punti cardinali, non la Luna o altri oggetti. Puoi inserire <quote
>Luna</quote
> manualmente o utilizzare la finestra <guilabel
>Trova oggetto</guilabel
> per selezionarla dalla lista di oggetti con nome. Nota che, come sempre, centrare un oggetto attiva automaticamente l'inseguimento, così che non c'è bisogno di aggiungere la funzione <firstterm
>setTracking</firstterm
> dopo lookToward. </para
><para
>Ora che abbiamo puntato la Luna vogliamo che il tempo scorra a una velocità superiore al normale. Utilizza allo scopo la funzione <firstterm
>setClockScale</firstterm
>. Aggiungila allo script facendo doppio clic su di essa nel Browser funzioni. Il pannello Argomenti funzione contiene ora il necessario per modificare il passo dell'orologio della simulazione. Porta il passo a tre ore. </para
><para
>Bene, abbiamo puntato la Luna e accelerato lo scorrere del tempo. Ora vogliamo solo che lo script attenda un certo numero di secondi mentre il display insegue la Luna. Aggiungi allo script la funzione <firstterm
>waitFor</firstterm
>, e utilizza il pannello Argomenti funzione per impostare a venti secondi il tempo di attesa. </para
><para
>Per finire, riportiamo il passo dell'orologio al valore normale di un secondo. Aggiungi un'altra istanza di setClockScale, e impostane il valore a un secondo. </para
><para
>Per la verità non abbiamo finito del tutto. Dovremmo assicurarci che il programma stia utilizzando le coordinate equatoriali prima che lo script inizi a inseguire la Luna con passo temporale accelerato. Altrimenti, se il display utilizza coordinate orizzontali, ruoterà assai rapidamente di grandi angoli mentre la Luna sorge e tramonta. Ciò può provocare parecchia confusione, ma lo si può evitare impostando l'opzione di visualizzazione <firstterm
>UseAltAz</firstterm
> a <quote
>false</quote
>. Per modificare una qualsiasi opzione di visualizzazione, utilizza la funzione <firstterm
>changeViewOption</firstterm
>. Aggiungila allo script ed esamina il pannello Argomenti funzione. C'è un pulsante che apre una lista di tutte le opzioni modificabili tramite changeViewOption. Dato che sappiamo di dover utilizzare l'opzione UseAltAz, potremmo semplicemente selezionarla dalla lista. Si tratta tuttavia di una lista piuttosto lunga, e non ci sono spiegazioni per le varie voci. Potrebbe quindi essere più semplice premere il pulsante <guibutton
>Esamina albero</guibutton
>, che aprirà una finestra con una vista ad albero delle opzioni di visualizzazione, divise per argomento. Inoltre ogni voce dispone di una breve spiegazione, ed è indicato il tipo di dati dell'argomento. Possiamo trovare UseAltAz nella categoria <guilabel
>Opzioni mappa celeste</guilabel
>. Selezionala e premi <guibutton
>OK</guibutton
>, ed essa comparirà all'interno del pannello Argomenti funzione. Infine, imposta il suo valore a <quote
>false</quote
> o <quote
>0</quote
>. </para
><para
>Un'altra cosa: cambiare UseAltAz alla fine dello script non serve a granché; dobbiamo modificarlo prima di ogni altra cosa. Perciò assicurati che la funzione sia selezionata nel riquadro Script corrente, e premi il pulsante <guibutton
>Sposta in alto</guibutton
> fino a farla diventare la prima funzione. </para
><para
>Ora che abbiamo terminato lo script dobbiamo salvarlo su disco. Premi il pulsante <guibutton
>Salva script</guibutton
>. Si aprirà una finestra in cui puoi inserire un nome per lo script e uno per il suo autore. Inserisci <quote
>Inseguire la Luna</quote
> come nome, metti il tuo nome come autore e premi <guibutton
>OK</guibutton
>. Apparirà la finestra di dialogo standard "Salva file" di &kde;. Specifica un nome file per lo script e premi <guibutton
>OK</guibutton
> per salvarlo. Nota che, se il nome file non finisce per <quote
>.kstars</quote
>, l'estensione sarà aggiunta automaticamente. Se sei curioso, puoi esaminare lo script con un qualunque editor di testi. </para
><para
>Ora che abbiamo uno script completo possiamo eseguirlo in due modi diversi. È possibile eseguirlo da un prompt di terminale, purché KStars sia in esecuzione. In alternativa, puoi eseguire lo script da KStars tramite la voce <guimenuitem
>Esegui script...</guimenuitem
> nel menu <guimenu
>File</guimenu
>. </para>
</sect2>

<sect2 id="sb-indi">
  <title
>Automazione delle periferiche con INDI</title>
  <para
>La programmazione e l'automazione sono supportate per tutte le periferiche compatibili con <link linkend="what-is-indi"
>INDI</link
>. Puoi coordinare un numero qualsiasi di periferiche per eseguire operazioni complesse tramite il <link linkend="sb-intro"
>Costruttore script</link
> di &kstars;.  Tutto ciò è possibile grazie all'interfaccia DCOP INDI di &kstars;, che fornisce diverse classi di funzioni per soddisfare i tuoi bisogni. Le funzioni DCOP INDI si possono dividere in cinque classi. Segue un elenco delle funzioni e dei loro argomenti come supportati in KStars. Raccomandiamo vivamente di leggere la sezione <link linkend="indi-concepts"
>Concetti di INDI</link
>, dato che utilizzeremo nel seguito quanto vi è spiegato.</para>
  <orderedlist>
    <listitem
><para
>Funzioni generiche di periferica: hanno lo scopo di accendere/spegnere periferiche, e così via...</para>
      <itemizedlist>
	<listitem
><para
><function
>startINDI (QString nomePeriferica, bool usaLocale)</function
>: avvia un servizio INDI in modalità locale o server.</para
></listitem>
	<listitem
><para
><function
>shutdownINDI (QString nomePeriferica)</function
>: arresta un servizio INDI.</para
></listitem>
	<listitem
><para
><function
>switchINDI(QString nomePeriferica, bool accesoSpento)</function
>: connette o disconnette una periferica INDI.</para
></listitem>
	<listitem
><para
><function
>setINDIPort(QString nomePeriferica, QString porta)</function
>: imposta la porta di connessione della periferica.</para
></listitem>
	<listitem
><para
><function
>setINDIAction(QString nomePeriferica, QString azione)</function
>: attiva un'azione INDI. L'azione può essere un <emphasis
>elemento</emphasis
> qualsiasi di una <emphasis
>proprietà interruttore</emphasis
>.</para
></listitem>
	<listitem
><para
><function
>waitForINDIAction(QString nomePeriferica, QString azione)</function
>: arresta l'esecuzione dello script fino a quando la <emphasis
>proprietà</emphasis
> dell'azione specificata restituisce uno stato OK.</para
></listitem>
      </itemizedlist>
    </listitem>
    <listitem
><para
>Funzioni telescopio: servono a controllare il movimento e lo stato del telescopio.</para>
      <itemizedlist>
	<listitem
><para
><function
>setINDIScopeAction(QString nomePeriferica, QString azione)</function
>: imposta la modalità o l'azione del telescopio. Le opzioni disponibili sono SLEW, TRACK, SYNC, PARK e ABORT.</para
></listitem>
	<listitem
><para
><function
>setINDITargetCoord(QString nomePeriferica, double AR, double DEC)</function
>: imposta le coordinate JNow del telescopio ai valori <emphasis
>AR</emphasis
> e <emphasis
>DEC</emphasis
> specificati.</para
></listitem>
	<listitem
><para
><function
>setINDITargetName(QString nomePeriferica, QString nomeOggetto)</function
>: imposta le coordinate JNow del telescopio a quelle di <emphasis
>nomeOggetto</emphasis
>. KStars cercherà l'oggetto nel proprio database e ne utilizzerà le coordinate.</para
></listitem>
	<listitem
><para
><function
>setINDIGeoLocation(QString nomePeriferica, double longitudine, double latitudine)</function
>: imposta la località geografica del telescopio alla latitudine e longitudine specificate. La longitudine è calcolata da Greenwich, Regno Unito, verso est. Tuttavia, sebbene sia comune utilizzare longitudini negative per l'emisfero occidentale, INDI richiede valori di longitudine tra 0 e 360 gradi. Perciò, se hai una longitudine negativa, è sufficiente aggiungere 360 gradi per ottenere il valore che INDI si aspetta. Per esempio, le coordinate di Calgary, Canada, in &kstars; sono longitudine -114 04 58 e latitudine 51 02 58. Perciò a INDI va fornita la longitudine 360 - 114,083 = 245,917 gradi.</para
></listitem>
	<listitem
><para
><function
>setINDIUTC(QString nomePeriferica, QString dataOraUTC)</function
>: imposta la data e l'ora UTC del telescopio in formato ISO 8601. Il formato è AAAA-MM-GGTHH:MM:SS (per esempio 2004-07-12T22:05:32).</para
></listitem>
      </itemizedlist>
    </listitem>
    <listitem
><para
>Funzioni videocamera/CCD: permettono di controllare le proprietà e lo stato della videocamera o del CCD.</para>
      <itemizedlist>
	<listitem
><para
><function
>setINDICCDTemp(QString nomePeriferica, int temp)</function
>: imposta la temperatura del chip CCD in gradi Celsius.</para
></listitem>
	<listitem
><para
><function
>setINDIFrameType(QString nomePeriferica, QString tipo)</function
>: imposta il tipo di frame del CCD. Le opzioni disponibili sono FRAME_LIGHT, FRAME_BIAS, FRAME_DARK e FRAME_FLAT.</para
></listitem>
	<listitem
><para
><function
>startINDIExposure(QString nomePeriferica, int durata)</function
>: avvia l'esposizione del CCD/videocamera per la durata specificata dal parametro omonimo, in secondi.</para
></listitem>
      </itemizedlist>
    </listitem
>    
   <listitem
><para
>Funzioni focheggiatore: servono a controllare il movimento e lo stato del focheggiatore.</para>
      <itemizedlist>
      <listitem
><para
><function
>setINDIFocusSpeed(QString nomePeriferica, QString azione)</function
>: imposta la velocità del focheggiatore. Le opzioni disponibili sono FOCUS_HALT, FOCUS_SLOW, FOCUS_MEDIUM e FOCUS_FAST.</para
></listitem>
      <listitem
><para
><function
>setINDIFocusTimeout(QString nomePeriferica, int durata)</function
>: imposta la durata in secondi di ogni operazione startINDIFocus successiva.</para
></listitem>
      <listitem
><para
><function
>startINDIFocus(QString nomePeriferica, int dirFuoco)</function
>: sposta il focheggiatore verso l'interno (dirFuoco = 0) o l'esterno (dirFuoco = 1). La velocità e durata di questa operazione sono impostate tramite le funzioni <function
>setINDIFocusSpeed()</function
> e <function
>setINDIFocusTimeout()</function
>.</para
></listitem>
    </itemizedlist>
    </listitem>
   <listitem
><para
>Funzioni filtro: servono a controllare la posizione del filtro.</para>
      <itemizedlist>
      <listitem
><para
><function
>setINDIFilterNum(QString nomePeriferica, int num_filtro)</function
>: modifica la posizione del filtro a <varname
>num_filtro</varname
>. L'utente può assegnare nomi ai numeri dei filtri nella finestra <guimenuitem
>Configura INDI</guimenuitem
> nel menu <guimenu
>Periferiche</guimenu
> (per esempio, Filtro 1 = Rosso, Filtro 2 = Verde... eccetera).</para
></listitem>
    </itemizedlist>
    </listitem>
    
  </orderedlist>
  
<para
>Nota che il nome della periferica è il primo argomento di tutte le funzioni INDI. Ciò permette di affiancare nello stesso script più comandi indirizzati a periferiche differenti. Il Costruttore script fornisce due opzioni per facilitare la creazione e la modifica di script INDI:</para>
<itemizedlist>
  <listitem
><para
><option
>Aggiungi WaitForINDIAction dopo ogni azione INDI</option
>: quando questa casella è marcata, il costruttore script aggiungerà automaticamente <function
>waitForINDIAction()</function
> dopo ogni azione che riconosce. Per esempio, se aggiungi la funzione <function
>switchINDI()</function
> e marchi la casella di cui sopra, il costruttore script aggiungerà "waitForINDIAction CONNECTION" nello script subito dopo <function
>switchINDI()</function
>. Ciò avrà l'effetto di arrestare l'esecuzione dello script dopo <function
>switchINDI()</function
>, fino a quando questa funzione non restituirà uno stato OK (il che significa che la connessione ha avuto successo). È molto importante sapere che il costruttore script non può aggiungere automaticamente <function
>waitForINDIAction()</function
> dopo azioni generiche aggiunte tramite la funzione <function
>setINDIAction()</function
>. La ragione è che KStars non può determinare la proprietà genitrice di azioni generiche. Perciò è necessario che tu aggiunga manualmente <function
>waitForINDIAction()</function
> dopo azioni generiche, quando lo desideri.</para>
  </listitem>
  <listitem
><para
><option
>Riutilizza nome periferica INDI</option
>: se marcato, il nome di periferica di tutte le funzioni seguenti è automaticamente impostato all'ultimo nome utilizzato. L'impostazione ha luogo ogni volta che la funzione <function
>startINDI()</function
> viene aggiunta allo script corrente. Si raccomanda di non utilizzare questa opzione lavorando con più di una periferica.</para>
  </listitem>
</itemizedlist>

<para
>Ora siamo pronti per creare uno script dimostrativo che controlli un telescopio LX200 GPS e una camera CCD Finger Lakes. Il nostro obiettivo è semplice: chiederemo al telescopio di puntare e inseguire Marte, e al CCD di effettuare tre esposizioni di dieci secondi, distanziate di venti secondi l'una dall'altra.</para>
<important
><para
>Dato che l'interfaccia DCOP di INDI non dà alcuna informazione sull'avanzamento, valore o stato di operazioni e parametri relativi alle periferiche (fatta eccezione per <function
>waitForINDIAction()</function
>), l'automazione delle periferiche in KStars somiglia a un sistema di controllo a ciclo aperto. In tale sistema non c'è modo di conoscere lo stato di avanzamento del sistema e di correggere gli errori. Di conseguenza, occorre progettare gli script di automazione con molta accortezza. Tutti questi script devono essere sottoposti a una rigorosa fase di test prima di essere impiegati.</para
></important>

<screenshot>
  <screeninfo
>Il Costruttore Script </screeninfo>
  <mediaobject>
    <imageobject>
      <imagedata fileref="indiscript.png" format="PNG"/>
    </imageobject>
    <textobject>
      <phrase
>Costruttore script</phrase>
    </textobject>
  </mediaobject>
</screenshot>

<para
>Lo script dimostrativo è mostrato nell'immagine qui sopra. Nota che abbiamo marcato <option
>"Aggiungi WaitForINDIAction dopo ogni azione INDI"</option
> e smarcato <option
>"Riutilizza nome periferica INDI"</option
>. La prima funzione da aggiungere è <function
>startINDI()</function
>, come mostrato sopra. Vogliamo gestire le nostre periferiche come locali, quindi non cambieremo la modalità mostrata nella finestra degli argomenti. Digitiamo il nome della periferica, cominciando dal telescopio "LX200 GPS". Ripetiamo la stessa operazione per "FLI CCD". La funzione successiva è <function
>waitFor()</function
>. In generale si raccomanda di utilizzare <function
>waitFor()</function
> subito dopo <function
>startINDI()</function
> in modo da mettere lo script in pausa per 1-5 secondi. Ciò assicura che tutte le proprietà siano stabilite e pronte a ricevere comandi. È anche utile per controllare periferiche remote, dato che prelevare e stabilire le varie proprietà può richiedere un po' di tempo. Con la funzione successiva, <function
>switchINDI()</function
>, ci connettiamo a ciascuna periferica.</para>

<para
>Dato che la casella relativa all'opzione <option
>"Aggiungi WaitForINDIAction dopo ogni azione INDI"</option
> è marcata, non dobbiamo aggiungere <function
>waitForINDIAction()</function
> dopo <function
>switchINDI()</function
> per assicurarci che l'esecuzione dello script continui solo dopo che la connessione è avvenuta con successo. Ci penserà automaticamente il costruttore script quando salveremo il programma. Ora impostiamo la modalità del telescopio a inseguimento: fai clic sulla funzione <function
>setINDIScopeAction()</function
> e seleziona TRACK. Nota che questo va fatto <emphasis
>prima</emphasis
> di fornire le coordinate per l'inseguimento. La funzione <function
>setINDIScopeAction()</function
> è fornita per comodità, dato che in questo esempio si limita a chiamare <function
>setINDIAction()</function
> con l'argomento TRACK. Comunque il vantaggio di utilizzare <function
>setINDIScopeAction()</function
> è che KStars può aggiungere automaticamente <function
>waitForINDIAction()</function
> quando richiesto. Questa possibilità non è disponibile per azioni generiche, come spiegato più sopra.</para>

<para
>Il prossimo passo consiste nell'utilizzare la funzione <function
>setINDITargetName()</function
> e impostare il nome a Marte. I passi finali saranno catturare un'immagine con dieci secondi d'esposizione, tramite la funzione <function
>startINDIExposure()</function
>, e aspettare venti secondi, fornendo il valore 20 alla funzione <function
>waitFor()</function
>.</para>

<para
>Possiamo ora salvare il nostro script ed eseguirlo in un altro momento. LO script salvato sarà simile a questo:</para>
<blockquote
><programlisting
>#!/bin/bash
    #Script DCOP per KStars: script dimostrativo
    #di Jasem Mutlaq
    #ultima modifica: gio 6 gen 2005 09:58:26
    #
    KSTARS=`dcopfind -a 'kstars*'`
    MAIN=KStarsInterface
    CLOCK=clock#1
    dcop $KSTARS $MAIN  startINDI "LX200 GPS" true
    dcop $KSTARS $MAIN  startINDI "FLI CCD" true
    dcop $KSTARS $MAIN  waitFor 3
    dcop $KSTARS $MAIN  switchINDI "LX200 GPS" true
    dcop $KSTARS $MAIN  waitForINDIAction "LX200 GPS" CONNECTION
    dcop $KSTARS $MAIN  switchINDI "FLI CCD" true
    dcop $KSTARS $MAIN  waitForINDIAction "FLI CCD" CONNECTION
    dcop $KSTARS $MAIN  setINDIScopeAction "LX200 GPS" TRACK
    dcop $KSTARS $MAIN  waitForINDIAction "LX200 GPS" ON_COORD_SET
    dcop $KSTARS $MAIN  setINDITargetName "LX200 GPS" Mars
    dcop $KSTARS $MAIN  waitForINDIAction "LX200 GPS" EQUATORIAL_EOD_COORD
    dcop $KSTARS $MAIN  startINDIExposure "FLI CCD" 10
    dcop $KSTARS $MAIN  waitForINDIAction "FLI CCD" EXPOSE_DURATION
    dcop $KSTARS $MAIN  waitFor 20
    dcop $KSTARS $MAIN  startINDIExposure "FLI CCD" 10
    dcop $KSTARS $MAIN  waitForINDIAction "FLI CCD" EXPOSE_DURATION
    dcop $KSTARS $MAIN  waitFor 20
    dcop $KSTARS $MAIN  startINDIExposure "FLI CCD" 10
    dcop $KSTARS $MAIN  waitForINDIAction "FLI CCD" EXPOSE_DURATION
</programlisting>
</blockquote>

<note>
<para
>La libreria INDI fornisce validi strumenti per la realizzazione di script, il che permette agli sviluppatori di scrivere script molto complessi. Per avere maggiori dettagli consulta il <ulink url="http://indi.sourceforge.net/manual/book1.html"
>manuale dello sviluppatore di INDI</ulink
>.</para>
</note>
</sect2>
</sect1>