<chapter id="dcop">
<title>Skriptid ja KStars: DCOP liides</title>
<para>&kstars;i üks eesmärke on pakkuda võimalust kasutada ka kõige keerulisemaid võimalusi skripti vahendusel. See lubab luua <quote>virtuaalretki</quote> taevakaardil ning aitab õpetajatel koolitöös illustreerida mõningaid astronoomilisi põhimõtteid ning üldse juttu ja teksti köitvamaks muuta. Juba praegu on võimalik &kstars;is selliseid skripte kasutada, kuigi veel ei saa pruukida kõiki funktsioone, mida me tahaksime pakkuda. Meil on küll graafiline skriptide loomise abivahend, kuid siiski tuleb skriptid ise veel käsitsi kirjutada. Käesolev peatükk selgitabki, kuidas &kstars;i skripte kirja panna. </para>
<para>&kde; arhitektuur pakub skripte tarvitavatele rakendustele vajaliku raamistiku <abbrev>DCOP</abbrev> liidese näol. <abbrev>DCOP</abbrev> tähendab <quote>töölaua kommunikatsiooniprotokolli</quote> (inglise keeles Desktop COmmunication Protocol) ning just <abbrev>DCOP</abbrev> võimaldabki &kde; rakendusi juhtida teistest rakendustest, käsurealt või tekstiskripti abil. </para>

<sect1 id="dcop-interface">
<title>DCOP funktsioonid</title>
<para>&kstars;i <abbrev>DCOP</abbrev> kiides kasutab järgmisi funktsioone: <itemizedlist>
<listitem><para><function> lookTowards( const TQString suund )</function>: tsentreerib vaate argumendiga määratud punkti. Selleks võib olla suvalise taevakeha nimi või mõni järgmistest sõnadest või lühenditest: zenith (või z) seniidi tähistusena, north (n) põhjakaare, northeast (ne) kirde, east (e) ida, southeast (se) kagu, south (s), southwest (sw) edela, west (w) lääne ja northwest (nw) loode tähistusena. </para></listitem>

<listitem><para><function> setRaDec( double OT, double kääne )</function>: tsentreerib vaate määratud ekvaatorilistele koordinaatidele. </para></listitem>

<listitem><para><function> setAltAz(double h, double a)</function>: tsentreerib vaate määratud horisondiliste koordinaatidele. </para></listitem>

<listitem><para><function> zoomIn()</function>: suurendab vaate suurendust. </para></listitem>

<listitem><para><function> zoomOut()</function>: vähendab vaate suurendust. </para></listitem>

<listitem><para><function> defaultZoom()</function>: taastab vaikesuurenduse = 3. </para></listitem>

<listitem><para><function> setLocalTime(int aasta, int kuu, int päev, int tund, int min, int sek)</function>: seab simulatsioonikella määratud kuupäevale ja ajale. </para></listitem>

<listitem><para><function> waitFor( double t )</function>: paus t sekundit enne järgneva skriptikäsu rakendamist. </para></listitem>

<listitem><para><function> waitForKey( const TQString klahv )</function>: skripti rakendamine peatatakse, kuni kasutaja vajutab määratud klahvi. Praegu ei saa määrata klahvikombinatsioone (näiteks <keycombo action="simul">&Ctrl;<keycap>C</keycap></keycombo>), vaid ainult üksikklahve. Tühikuklahvi jaoks tuleb kirjutada <quote>space</quote>. </para></listitem>

<listitem><para><function> setTracking( bool track )</function>: jälgimisrežiimi näitamise lülitamine. </para></listitem>

<listitem><para><function> changeViewOption( const TQString võimalus, const TQString väärtus )</function>: vaatevõimaluse määramine. Kasutada saab kümneid võimalusi, sisuliselt kõike, mida saab seadistada &kstars;i <guilabel>vaateseadistuste aknas</guilabel>. Esimene argument ongi võimalus (vastav nimi võetakse seadistustefailist <filename>kstarsrc</filename>), teine soovitud väärtus. Argumentide parser on püütud teha võimalikult <quote>lollikindel</quote>, nii et kui kirjutad midagi kogemata valesti, siis see lihtsalt ei rakendu. </para></listitem>

<listitem><para><function> setGeoLocation( const TQString linn, const TQString provints/maakond, const TQString riik )</function>: võimalus määrata vaatluskohaks mingi konkreetne linn. Kui argumendis määratud linna andmebaasist ei leita, ei tee see käsk midagi. </para></listitem>

<listitem><para><function> stop()</function> [clock]: seiskab simulatsioonikella. </para></listitem>

<listitem><para><function> start()</function> [clock]: käivitab simulatsioonikella. </para></listitem>

<listitem><para><function> setScale(float s)</function> [clock]: määrab simulatsioonikella ajasammu. s=1.0 vastab reaalajale, 2.0 on kaks korda kiirem reaalajast jne. </para></listitem>
</itemizedlist>
</para>
</sect1>

<sect1 id="dcop-test">
<title>DCOP funktsioonide testimine</title>
<para>DCOP funktsioone saab hõlpsast testida rakenduse <application>kdcop</application> abil. Kui <application>kdcop</application> käivitada, näeb puukujulises nimekirjas kõiki töötavaid rakendusi ja kui &kstars; peaks töötama, on ta samuti seal kirjas. Enamik <abbrev>DCOP</abbrev> funktsioone on kirjas <quote>KStarsInterface</quote> päises, kuid kellafunktsioonid on ära toodud <quote>clock</quote> all. Suvalise funktsiooni käivitamiseks tee sellel topeltklõps. Kui funktsioon eeldab argumente, ilmub aken, kuhu need saab sisestada. </para>
</sect1>

<sect1 id="dcop-script">
<title>DCOP skripti kirjutamine</title>
<para><abbrev>DCOP</abbrev> funktsioone saab välja kutsuda ka UNIX-i käsurealt ning neid on võimalik skripti kaasata. Me näitame siin üht näidisskripti, mis lülitab sisse ekvaatorilised koordinaadid, tsentreerib vaate Kuule, suurendab veidi ning paneb kella käima kiirusega üks tund sekundis. Seda skripti saab kasutada mallina meelepäraste skriptide loomisel. Kõigepealt siis skript ning seejärel seletus. </para>
<para>
<programlisting>#!/bin/bash
#KStars script: Jälgi Kuud!
#
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>Salvesta skript failina. Nimi võib olla milline tahes, mina soovitaksin anda nimeks midagi kirjeldavat, näiteks <filename>kuuvaatlus.kstars</filename>. Skripti muutmiseks käivitatavaks anna järgmine käsk: <userinput><command>chmod</command> <option>a+x</option> <parameter>kuuvaatlus.kstars</parameter> </userinput>. Nüüd saab skripti käivitada käsuga <userinput><command>./kuuvaatlus.kstars</command></userinput> kataloogis, kus skript asub. Arvesta, et skript toimib ainult siis, kui KStars eelnevalt töötab. Uue &kstars;i akna avamiseks võib skriptis kasutada käsku <command>dcopstart</command>. </para>
<para>Nüüd siis selgitused skripti juurde. Ülemine rida tuvastab faili <command>BASH</command>i shelliskriptina. Järgmised kaks rida on <firstterm>kommentaarid</firstterm> (kommentaarid on kõik read, mille alguses seisab <quote>#</quote>, ning shell jätab need arvesse võtmata). Järgmised kolm rida määravad mõningad muutujad, mida hiljem kasutatakse. Muutuja <varname>KSTARS</varname> tuvastab töötava &kstars;i protsessi, kasutades selleks käsku <command>dcopfind</command>. Muutujad <varname>MAIN</varname> ja<varname>CLOCK</varname> tuvastavad kaks &kstars;iga seotud <abbrev>DCOP</abbrev> liidest. </para>
<para>Ülejäänud osa skriptist kujutabki endast tegelike <abbrev>DCOP</abbrev> väljakutsete loetelu. Esimene rida määrab ekvaatoriliste koordinaatide kasutamise, määrates võimaluse <quote>UseAltAz</quote> (ehk siis kõrguse ja asimuudi kasutamise) väärtuseks <quote>false</quote> ehk <quote>väär</quote> (kõiki võimalusi, mida kasutab <quote>changeViewOptions</quote> ehk vaateseadistuste dialoog, näeb seadistustefailis <filename>kstarsrc</filename>). Järgmine käsk tsentreerib vaate Kuule ja lülitab sisse selle jälgimise. Seejärel kehtestatakse vaikesuurendus ja suurendatakse seda viis korda. Siis määratakse kell käima kiirusega üks tund sekundis (3600 sekundit on ju üks tund) ning kell käivitatakse. Järgmine rida peatab skripti 20 sekundiks, mille kestel saab jälgida üle taevalaotuse kulgevat Kuud. Lõpuks peatatakse kell ning taastatakse vaikesuurendus. </para>
<para>Me loodame, et KStarsi skriptivõimalused pakuvad sulle suurt naudingut ja lubavad luua huvitavaid lahendusi. Kui oled loonud mõne huvipakkuva skripti, võid sellest teada anda ka meiliaadressil <email>kstars@30doradus.org</email>, sest meile meeldiks teada saada, mida teevad meie kasutajad, ja võimaluse korral ka skripte oma veebileheküljel avaldada. Kui sul aga on mingeid mõtteid, kuidas skriptidesse (või üldse mis tahes &kstars;i töö osasse) puutuvat parandada, anna sellest teada aadressil <email>kstars-devel@lists.sourceforge.net</email> või esita oma soov Bugzilla vahendusel. </para>
</sect1>
</chapter>

