<chapter id="dcop">
<title
>Scripts in Kstars: de DCOP-interface</title>
<para
>Een van de doelstellingen in &kstars; is het inbouwen van de mogelijkheid om samengestelde handelingen in een script vast te leggen. Hiermee kunt u <quote
>virtuele rondreizen</quote
> in het hemelgewelf ontwerpen, en leraren zullen hiermee demonstraties voor in de klas kunnen maken, waarmee bepaalde astronomische begrippen kunnen worden toegelicht. Het is nu reeds mogelijk om voor &kstars; dit soort scripts te schrijven, hoewel nog niet alle gewenste functies beschikbaar zijn. En ook moeten deze scripts nu nog met de hand worden geschreven, maar in de toekomst zullen we een grafisch hulpmiddel toevoegen voor het bouwen van scripts. In dit hoofdstuk leggen we uit hoe u in &kstars; een script schrijft. </para>
<para
>De KDE-architectuur stelt met de <abbrev
>DCOP</abbrev
>-interface het benodigde raamwerk beschikbaar voor het maken van scripts in programma's. <abbrev
>DCOP</abbrev
> betekent <quote
>Desktop Communication Protocol</quote
> (Bureaubladcommunicatieprotocol). Met behulp van <abbrev
>DCOP</abbrev
> kunnen in &kde; programma's vanuit andere programma's worden bestuurd, of vanuit een terminal, of met behulp van een tekstscript. </para>

<sect1 id="dcop-interface">
<title
>DCOP-functies</title>
<para
>De <abbrev
>DCOP</abbrev
>-interface van &kstars; heeft de volgende functies: <itemizedlist>
<listitem
><para
><function
> lookTowards( const QString richting )</function
>: Richten van de kijkrichting in het schermbeeld in de richting die door het argument "richting" wordt gegeven. Dit kan de naam zijn van een hemelobject, of een van de volgende woorden of afkortingen: zenith (of z), north (n), northeast (ne), east (e), southeast (se), south (s), southwest(sw), west(w), northwest (nw).

("zenith"->zenit, "north"->noord, "northeast"->noordoost, "east"->oost, "southeast"->zuidoost, "south"->zuid, "southwest"->zuidwest, "west"->west, "northwest"->noordwest - dit dient alleen als toelichting, het is duidelijk dat van deze waarden alleen de Engelse namen zullen worden begrepen ... ) </para
></listitem>

<listitem
><para
><function
> setRaDec( double rk, double dec )</function
>: Instellen van de kijkrichting op de opgegeven equatoriale coördinaten

("rk" en "dec" -> rechte klimming en declinatie). </para
></listitem>

<listitem
><para
><function
> setAltAz(double hgte, double az)</function
>: Instellen van de kijkrichting op de opgegeven horizontale coördinaten

("hgte" en "az" -> hoogte en azimut). </para
></listitem>

<listitem
><para
><function
> zoomIn()</function
>: Inzoomen. </para
></listitem>

<listitem
><para
><function
> zoomOut()</function
>: Uitzoomen. </para
></listitem>

<listitem
><para
><function
> defaultZoom()</function
>: Het standaard zoomniveau (=3) herstellen. </para
></listitem>

<listitem
><para
><function
> setLocalTime(int jaar, int mnd, int dag, int hr, int min, int sec)</function
>: De simulatieklok instellen op de opgegeven datum en tijd

("jaar"-> jaar, "mnd"-> maand, "dag"-> dag, "hr"-> uur, "min"-> minuut, "sec"-> seconde). </para
></listitem>

<listitem
><para
><function
> waitFor( double t )</function
>: "t" seconden pauzeren, alvorens verder te gaan met de volgende opdrachten van de script. </para
></listitem>

<listitem
><para
><function
> waitForKey( const QString k )</function
>: De verdere uitvoering van de script stoppen, totdat de opgegeven toets "k" wordt ingedrukt. Momenteel kunt u nog geen gecombineerde toetsaanslagen opgeven (zoals <keycombo action="simul"
>&Ctrl;<keycap
>C</keycap
></keycombo
>); u kunt alleen enkelvoudige toetsaanslagen gebruiken. Om de spatiebalk op te geven typt u <quote
>space</quote
>.

"space" betekent spatie. </para
></listitem>

<listitem
><para
><function
> setTracking( bool volgen )</function
>: Volgen aan of uitschakelen. ("volgen" is een booleaanse variabele, wat betekent dat die alleen de standaardwaarden "true" of "false" kan hebben (wel volgen, of niet volgen)). </para
></listitem>

<listitem
><para
><function
> changeViewOption( const QString optie, const QString waarde )</function
>: Instellen van een weergaveoptie. Er zijn er vele tientallen beschikbaar; in principe kunnen alle opties die in het venster <guilabel
>Weergaveopties</guilabel
> kunnen worden gewijzigd ook hier worden veranderd. Het eerste argument ("optie") is de naam van de optie, (de namen komen uit het configuratiebestand <filename
>kstarsrc</filename
>), en het tweede argument ("waarde") is de gewenste waarde. De argumentontleder is robuust, dus als u per ongeluk verkeerde gegevens invult zullen die op een nette manier worden geweigerd. </para
></listitem>

<listitem
><para
><function
> setGeoLocation( const QString stad, const QString provincie, const QString land )</function
>: De waarnemingslocatie naar de gewenste stad veranderen. Als er geen stad wordt gevonden die met de opgegeven waarden overeenkomt, gebeurt er niets. </para
></listitem>

<listitem
><para
><function
> stop()</function
> [clock]: De simulatieklok stoppen. </para
></listitem>

<listitem
><para
><function
> start()</function
> [clock]: De simulatieklok starten. </para
></listitem>

<listitem
><para
><function
> setScale(float s)</function
> [clock]: Instellen van de snelheid waarmee de simulatieklok loopt. "s"=1.0 correspondeert met de natuurlijke snelheid, "s"=2.0 twee keer zo snel, enzovoorts. </para
></listitem>
</itemizedlist>
</para>
</sect1>

<sect1 id="dcop-test">
<title
>De DCOP-functies testen</title>
<para
>U kunt zeer eenvoudig de DCOP-functies uitproberen met behulp van het programma <application
>kdcop</application
>. Als u <application
>kdcop</application
> uitvoert krijgt u een lijst te zien van alle lopende programma's. Als &kstars; loopt komt die ook voor in de lijst. De meeste van de <application
>DCOP</application
>-functies worden getoond onder de kop <quote
>KStarsInterface</quote
>, maar de klokfuncties staan onder de kop <quote
>clock</quote
>.U kunt een functie uitvoeren door erop te dubbelklikken. Als de functie argumenten nodig heeft zal er een venster worden geopend waarin u de waarden kunt invoeren. </para>
</sect1>

<sect1 id="dcop-script">
<title
>Het schrijven van een DCOP-script</title>
<para
><abbrev
>DCOP</abbrev
>-functies kunnen worden aangeroepen vanaf de commandoregel van UNIX of Linux, deze regels kunnen worden opgenomen in een script. We zullen een voorbeeldscript maken die omschakelt naar equatoriale coördinaten, het beeld op de Maan instelt, een beetje inzoomt, en de kloksnelheid tot 1 uur per seconde vergroot. Na de Maan 20 seconden te hebben gevolgd wordt de klok gestopt en wordt er uitgezoomd. U kunt deze script gebruiken als een voorbeeld voor nieuwe scripts. Eerst wordt de hele script getoond, en daarna de diverse onderdelen ervan uitgelegd. </para>
<para>
<programlisting
>#!/bin/bash
#KStars-script: Volgen van de Maan!
#
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
>Sla dit script op in een bestand. U kunt elke bestandsnaam kiezen, Ik stel voor om een beschrijvende naam te kiezen als <filename
>volgmaan.kstars</filename
>. Typ daarna het volgende in om de script uitvoerbaar te maken: <userinput
><command
>chmod</command
> <option
>a+x</option
> <parameter
>volgmaan.kstars</parameter
> </userinput
>. De script kan dan op elk moment worden uitgevoerd door <userinput
><command
>./volgmaan.kstars</command
></userinput
> te typen in de map waarin het script zich bevindt. Let erop dat de script alleen werkt als &kstars; al loopt. U kunt de opdracht <command
>dcopstart</command
> gebruiken om in een script een nieuwe &kstars; op te starten. </para>
<para
>En nu de uitleg van de script. De bovenste regel laat zien dat het bestand een <command
>BASH</command
>-shellscript is. De volgende twee regels zijn <firstterm
>commentaarregels</firstterm
> (elke regel die begint met een <quote
>#</quote
> is commentaar, en wordt door de shell overgeslagen). In de volgende drie regels worden voor het gemak wat variabelen gedefiniëerd, voor later gebruik. De variabele <varname
>KSTARS</varname
> identificeert het nu lopende &kstars;-programma, wanneer de opdracht <command
>dcopfind</command
> wordt gebruikt. <varname
>MAIN</varname
> en <varname
>CLOCK</varname
> identificeren de beide <abbrev
>DCOP</abbrev
>-interfaces van &kstars;. </para>
<para
>De rest van de script is een lijst van <abbrev
>DCOP</abbrev
>-opdrachten. De eertste stelt de equatoriale coördinaten in door de optie <quote
>UseAltAz</quote
> op <quote
>false</quote
> ("false" -> uit, "true"->aan) in te stellen (ook hier kunt u alle opties die u met <quote
>Weergaveopties wijzigen</quote
> kunt instellen weer vinden door uw configuratiebestand <filename
>kstarsrc</filename
> te bestuderen). De volgende opdracht stelt de kijkrichting in op de Maan en stelt automatisch volgen in. Daarna stellen we het standaard zoomniveau in, om daarna vijf keer in te zoomen. Vervolgens wordt de snelheid van de klok ingesteld op 1 uur (3600 sec) per seconde, en wordt de klok gestart (voor het geval die nog niet liep). De volgende regel stopt de uitvoering van de script gedurende 20 seconden terwijl de Maan wordt gevolgd bij zijn beweging langs de hemel. Tenslotte wordt de klok gestopt en wordt het standaard zoomniveau weer ingesteld. </para>
<para
>We hopen dat u de scriptmogelijkheden van Kstars goed kunt gebruiken. Als u een interessante script maakt willen wij die graag van u ontvangen op ons emailadres <email
>kstars@30doradus.org</email
>, en wellicht kunnen we die op onze webpagina plaatsen. En eventuele ideeën over hoe het maken van scripts zou kunnen worden verbeterd (of welk onderdeel van &kstars; dan ook), kunt u ons laten weten op <email
>kstars-devel@lists.sourceforge.net</email
>, of stuurt u een wensenlijstje naar bugzilla. </para>
</sect1>
</chapter>

