<chapter id="dcop">
<title
>Script per KStars: l'interfaccia DCOP</title>
<para
>Uno degli obiettivi di &kstars; è permettere la riproduzione di complesse sequenze di eventi a partire da uno script. Ciò ti permetterà di creare <quote
>tour virtuali</quote
> del cielo, e darà agli insegnanti un mezzo per realizzare dimostrazioni didattiche che illustrino determinati concetti astronomici. È già possibile scrivere questo tipo di script per &kstars;, abche se non tutte le funzioni progettate sono state incluse. Inoltre, sebbene sia in progetto un'interfaccia grafica per la realizzazione di script, per il momento essi vanno scritti a mano. Questo capitolo spiega come realizzare script per &kstars;. </para>
<para
>L'architettura &kde; fornisce la struttura necessaria per le applicazioni con supporto agli script tramite l'interfaccia <abbrev
>DCOP</abbrev
>. <abbrev
>DCOP</abbrev
> sta per <quote
>Desktop Communication Protocol</quote
> (Protocollo di Comunicazione Desktop); attraverso <abbrev
>DCOP</abbrev
> le applicazioni &kde; possono essere controllate da altre applicazioni, da un prompt di terminale o attraverso uno script di testo. </para>

<sect1 id="dcop-interface">
<title
>Funzioni DCOP</title>
<para
>L'interfaccia <abbrev
>DCOP</abbrev
> di &kstars; include le seguenti funzioni: <itemizedlist>
<listitem
><para
><function
> lookTowards( cost QString direzione)</function
>: punta il display nella direzione specificata dall'argomento. Può trattarsi del nome di un qualsiasi oggetto celeste, o di una delle seguenti parole o abbreviazioni: zenith (o z), per lo zenit, north (n) per il nord, northeast (ne) per il nordest, east (e) per l'est, southeast (se) per il sudest, south (s) per il sud, southwest(sw) per il sudovest, west(w) per l'ovest, northwest (nw) per il nordovest. </para
></listitem>

<listitem
><para
><function
> setRaDec( double ar, double dec )</function
>: centra il display sulle coordinate equatoriali specificate. </para
></listitem>

<listitem
><para
><function
> setAltAz(double alt, double az)</function
>: centra il display sulle coordinate orizzontali specificate. </para
></listitem>

<listitem
><para
><function
> zoomIn()</function
>: aumenta il livello di zoom del display. </para
></listitem>

<listitem
><para
><function
> zoomOut()</function
>: diminuisce il livello di zoom del display. </para
></listitem>

<listitem
><para
><function
> defaultZoom()</function
>: riporta il valore dello zoom a 3 (valore predefinito). </para
></listitem>

<listitem
><para
><function
> setLocalTime(int anno, int mese, int giorno, int ora, int min, int sec)</function
>: imposta l'orologio della simulazione alla data e ora specificate. </para
></listitem>

<listitem
><para
><function
> waitFor( double t )</function
>: attende t secondi prima di continuare con i comandi successivi. </para
></listitem>

<listitem
><para
><function
> waitForKey( cost QString k )</function
>: arresta l'esecuzione dello script fino a quando l'utente non preme il tasto specificato. Attualmente non è possibile specificare una combinazione di tasti (come <keycombo action="simul"
>&Ctrl;<keycap
>C</keycap
></keycombo
>); limitati a usare tasti semplici. Puoi digitare <quote
>space</quote
> per indicare la barra spaziatrice. </para
></listitem>

<listitem
><para
><function
> setTracking( bool track )</function
>: attiva/disattiva l'inseguimento. </para
></listitem>

<listitem
><para
><function
> changeViewOption( cost QString opzione, cost QString valore )</function
>: modifica un'opzione di visualizzazione. Ci sono decine di opzioni disponibili; praticamente tutto ciò che si può cambiare nella finestra <guilabel
>Configura &kstars;</guilabel
> può essere cambiato anche qui. Il primo argomento è il nome dell'opzione (i nomi sono presi dal file di configurazione <filename
>kstarsrc</filename
>), e il secondo è il valore desiderato. L'interprete degli argomenti è stato progettato per essere robusto, quindi dovrebbe arrestarsi senza conseguenze qualora riceva dati non validi. </para
></listitem>

<listitem
><para
><function
> setGeoLocation( cost QString città, cost QString provincia, cost QString nazione )</function
>: imposta la città specificata come località di osservazione. Se non viene trovata alcuna città corrispondente agli argomenti, il comando è ignorato. </para
></listitem>

<listitem
><para
><function
> stop()</function
> [orologio]: arresta l'orologio della simulazione. </para
></listitem>

<listitem
><para
><function
> start()</function
> [orologio]: avvia l'orologio della simulazione. </para
></listitem>

<listitem
><para
><function
> setScale(float s)</function
> [orologio]: imposta il passo dell'orologio della simulazione. s=1.0 corrisponde al tempo reale, 2.0 è due volte più veloce, e così via. </para
></listitem>
</itemizedlist>
</para>
</sect1>

<sect1 id="dcop-test">
<title
>Provare le funzioni DCOP</title>
<para
>Puoi provare le funzioni DCOP con facilità tramite il programma <application
>kdcop</application
>. All'avvio di <application
>kdcop</application
> vedrai una lista ad albero di tutti i programmi in esecuzione, dunque se &kstars; è in esecuzione vi sarà compreso. La maggior parte delle funzioni <abbrev
>DCOP</abbrev
> sono elencate sotto la voce <quote
>KStarsInterface</quote
>, ma le funzioni relative all'orologio si trovano sotto <quote
>clock</quote
>. Fai doppio clic su una funzione per esegurla. Se è richiesto un argomento, comparirà una finestra in cui potrai inserirne il valore. </para>
</sect1>

<sect1 id="dcop-script">
<title
>Scrivere uno script DCOP</title>
<para
>Le funzioni <abbrev
>DCOP</abbrev
> si possono anche invocare dalla riga di comando UNIX, ed è possibile raggrupparle in uno script. Creeremo ora uno script di esempio che passa alle coordinate equatoriali, punta la Luna, aumenta un poco lo zoom e accelera l'orologio a un'ora per secondo. Dopo aver inseguito la Luna per venti secondi, l'orologio viene messo in pausa e lo zoom diminuisce. Puoi utilizzare questo script come modello per crearne di nuovi. Cominceremo col mostrare il listato completo, per poi illustrarne le varie parti. </para>
<para>
<programlisting
>#!/bin/bash
#Script KStars: insegui la Luna!
#
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
>Salva questo script su file. Il nome del file è a piacere, ma suggeriamo qualcosa di descrittivo, del tipo <filename
>inseguiluna.kstars</filename
>. Quindi digita il comando seguente per rendere lo script eseguibile: <userinput
><command
>chmod</command
> <option
>a+x</option
> <parameter
>inseguiluna.kstars</parameter
> </userinput
>. Lo script può ora essere eseguito in qualsiasi momento digitando <userinput
><command
>./inseguiluna.kstars</command
></userinput
> nella cartella che lo contiene. Nota che lo script funziona soltanto se c'è già un'istanza di &kstars; in esecuzione. Puoi utilizzare il comando <command
>dcopstart</command
> in uno script per lanciare una nuova istanza di &kstars;. </para>
<para
>Ora veniamo alla spiegazione dello script. La prima riga identifica il file come uno script di shell <command
>BASH</command
>. Le due righe seguenti sono dei <firstterm
>commenti</firstterm
> (ogni riga che inizia per <quote
>#</quote
> è un commento, e viene ignorata dalla shell). Le tre righe seguenti definiscono alcune variabili che torneranno utili in seguito. La variabile <varname
>KSTARS</varname
> identifica il processo di &kstars; attualmente in esecuzione, tramite il comando <command
>dcopfind</command
>. <varname
>MAIN</varname
> e <varname
>CLOCK</varname
> identificano le due interfacce <abbrev
>DCOP</abbrev
> associate a &kstars;. </para>
<para
>Il resto dello script è la lista vera e propria di chiamate <abbrev
>DCOP</abbrev
>. Il primo comando fa sì che il display utilizzi le coordinate equatoriali, impostando l'opzione <quote
>UseAltAz</quote
> a <quote
>false</quote
> (ribadiamo che puoi vedere una lista di tutte le opzioni utilizzabili da <quote
>changeViewOption</quote
> esaminando il tuo file di configurazione <filename
>kstarsrc</filename
>). Il comando successivo centra il display sulla Luna, e attiva automaticamente l'inseguimento. Impostiamo quindi il livello predefinito di zoom, per poi aumentare l'ingrandimento cinque volte. L'istruzione successiva imposta il passo dell'orologio a un'ora per secondo (3600 secondi fanno un'ora), dopodiché l'orologio viene avviato (casomai non fosse già in funzione). La riga seguente mette lo script in pausa per venti secondi, mentre inseguiamo la Luna nel suo movimento attraverso il cielo. Infine arrestiamo l'orologio e riportiamo lo zoom al valore predefinito. </para>
<para
>Ci auguriamo che tu sfrutti appieno il supporto agli script di KStars. Se hai creato uno script interessante, mandalo a <email
>kstars@30doradus.org</email
>; ci piacerebbe vedere quello che hai fatto, e potremmo anche pubblicare alcuni script sulla nostra pagina web. Inoltre, se hai delle idee su come migliorare il supporto agli script (o qualsiasi altra parte di &kstars;) facci sapere presso <email
>kstars-devel@lists.sourceforge.net</email
> o inoltra una richiesta di funzionalità tramite bugzilla. </para>
</sect1>
</chapter>

