<chapter id="dcop">
<title
>Scripter i KStars: DCOP-grænsefladen</title>
<para
>Et af målene med &kstars; er at kunne udføre komplicerede hændelsesforløb fra et script. Det vil sætte dig i stand til at forevise en <quote
>virtuel tur</quote
> gennem himmelrummet. Og det vil sætte lærere i stand til at illustrere astronomiske fænomener <quote
>levende</quote
> for klassen. Det kan allerede lade sig gøre at lave sådanne scripter til &kstars;, selvom ikke alle de funktioner vi har planlagt er færdige. Og selvom vi i fremtiden vil lave et fint grafisk værktøj til at skrive scripterne med, må du foreløbigt tage til takke med at skrive dem i hånden. Dette kapitel vil hjælpe dig til at skrive scripter til  &kstars;. </para>
<para
>&kde;s arkitektur stiller de nødvendige rammer til rådighed for at integrere scripter i programmerne via grænsefladen <abbrev
>DCOP</abbrev
>. <abbrev
>DCOP</abbrev
> står for <quote
>Desktop Communication Protocol</quote
>. &kde;-programmer kan styres af andre programmer gennem <abbrev
>DCOP</abbrev
> fra en terminalprompt eller fra et tekst-script. </para>

<sect1 id="dcop-interface">
<title
>DCOP-funktioner</title>
<para
>&kstars; <abbrev
>DCOP</abbrev
>-grænseflade indeholder følgende funktioner: <itemizedlist>
<listitem
><para
><function
> lookTowards( const QString direction )</function
>: Drejer stjernekortet i den retning funktionens argument angiver. Det kan være navnet på ethvert objekt på himlen eller et af fælgende retningsord eller forkortelser: zenit (eller z), north (n), northeast (ne), east (e), southeast (se), south (s), southwest(sw), west(w), northwest (nw). </para
></listitem>

<listitem
><para
><function
> setRaDec( double ra, double dec )</function
>: Drejer stjernekortet i retning af de angivne koordinater i ækvatorsystemet. </para
></listitem>

<listitem
><para
><function
> setAltAz(double alt, double az)</function
>: Drejer stjernekortet i retning af de angivne koordinater i horisontsystemet. </para
></listitem>

<listitem
><para
><function
> zoomIn()</function
>: Zoom ind. </para
></listitem>

<listitem
><para
><function
> zoomOut()</function
>: Zoom ud. </para
></listitem>

<listitem
><para
><function
> defaultZoom()</function
>: Zoom til standardniveauet = 3. </para
></listitem>

<listitem
><para
><function
> setLocalTime(int yr, int mth, int day, int hr, int min, int sec)</function
>: Sæt simuleringens ur til den angivne dato og tid. </para
></listitem>

<listitem
><para
><function
> waitFor( double t )</function
>: Hold pause i t sekunder før de næste kommandoer i scriptet udføres. </para
></listitem>

<listitem
><para
><function
> waitForKey( const QString k )</function
>: Stop udførelsen af scriptet indtil brugeren trykker på en bestemt tast. På nuværende tidspunkt kan man kun bruge enkelttaster ikke tastekombinationer (som f.eks. <keycombo action="simul"
>&Ctrl;<keycap
>C</keycap
></keycombo
>). Skriv <quote
>space</quote
> for at bruge mellemrumstasten. </para
></listitem>

<listitem
><para
><function
> setTracking( bool track )</function
>: Slår følgning af et objekt til og fra. </para
></listitem>

<listitem
><para
><function
> changeViewOption( const QString option, const QString value )</function
>: Tilret en visningsindstilling. Der er mange indstillinger der kan tilrettes. Alle indstillinger der kan ændres i vinduet <guilabel
>Indstil &kstars;</guilabel
> kan tilrettes her også. Det første argument er indstillingens navn (navnene tages fra opsætningsfilen <filename
>kstarsrc</filename
>). Det andet argument er den værdi du vil give indstillingen. Argumentbehandlingen er skrevet så den skulle være solid, så hvis du skriver noget forkert skulle den fejle på en pæn måde. </para
></listitem>

<listitem
><para
><function
> setGeoLocation( const QString city, const QString province, const QString country )</function
>: Ændrer det sted himlen ses fra til den angivne by. Hvis den ikke findes i KStars sker der ingenting. </para
></listitem>

<listitem
><para
><function
> stop()</function
> [clock]: Stopper tiden i simuleringen. </para
></listitem>

<listitem
><para
><function
> start()</function
> [clock]: Starter tiden i simuleringen. </para
></listitem>

<listitem
><para
><function
> setScale(float s)</function
> [clock]: Angiver hvor hurtigt tiden skal gå i simuleringen. s=1.0 er normal hastighed, 2.0 er dobbelt hastighed osv. </para
></listitem>
</itemizedlist>
</para>
</sect1>

<sect1 id="dcop-test">
<title
>Test DCOP-funktionerne</title>
<para
>Du kan teste <abbrev
>DCOP</abbrev
>-funktionerne meget nemt med programmet <application
>kdcop</application
>. Når du kører <application
>kdcop</application
> kan du se en trævisning af alle kørende programmer. Hvis &kstars; kører er den med på listen. De fleste af <abbrev
>DCOP</abbrev
>-funktionerne er anført under overskriften <quote
>KStarsInterface</quote
>, men tidsfunktionerne findes under <quote
>clock</quote
>. Dobbeltklik på enhver af funktionerne for at udføre den. Hvis funktionen kræver argumenter vil et vindue blive åbnet hvor du kan skrive værdierne. </para>
</sect1>

<sect1 id="dcop-script">
<title
>Skriv et DCOP-script</title>
<para
><abbrev
>DCOP</abbrev
>-funktionerne kan også kaldes fra en UNIX-kommandolinje, og de kan lægges ind i et script. Vi vil vise et eksempel-script der skifter koordinatsystemet til ækvatorsystemet, drejer stjernekortet så månen er i fokus, zoomer lidt ind, og får uret til at gå en time i sekundet. Du kan bruge dette script som skabelon når du laver dine egne scripter. Jeg vil vise hele scriptet først og derefter forklare de enkelte dele. </para>
<para>
<programlisting
>#!/bin/bash
#KStars script: Følg månen!
#
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
>Gem scriptet som fil. Du kan benytte ethvert filnavn efter eget ønske. Men vi foreslår noget beskrivende som f.eks. <filename
>FølgMånen.kstars</filename
>. Skriv så følgende kommando for at gøre scriptet eksekverbart: <userinput
><command
>chmod</command
> <option
>a+x</option
> <parameter
>FølgMånen.kstars</parameter
> </userinput
>. Scriptet kan så køres ved at stille sig i den mappe hvor scriptet ligger og skrive <userinput
><command
>./FølgMånen.kstars</command
></userinput
>. Bemærk at scriptet kun bliver udført hvis &kstars; allerede er åbnet. Du kan bruge kommandoen <command
>dcopstart</command
> i scriptet hvis et nyt &kstars;-vindue skal åbnes. </para>
<para
>Her følger en forklaring på scriptet. Den øverste linje identificerer scriptet som et <command
>BASH</command
> shell script. De følgende to linjer er <firstterm
>kommentarer</firstterm
> (alle linjer der starter med <quote
>#</quote
> er kommentarer og ignoreres af kommandofortolkeren). De næste tre linjer definerer nogle bekvemme variabler som vil blive brugt senere. <varname
>KSTARS</varname
>-variablen identificerer den kørende &kstars;-proces, vha. <command
>dcopfind</command
>-kommandoen. Variablerne <varname
>MAIN</varname
> og <varname
>CLOCK</varname
> identificerer de to <abbrev
>DCOP</abbrev
>-grænseflader der er tilknyttet &kstars;. </para>
<para
>Resten af scriptet er den egentlige liste af <abbrev
>DCOP</abbrev
>-kald. Den første kommando sætter stjernekortet op til at benytte himmelkoordinatsystemet ækvatorsystemet, ved at sætte <quote
>UseAltAz</quote
> til <quote
>false</quote
> (som sagt kan du se listen over de tilgængelige indstillinger af <quote
>changeViewOption</quote
> i indstillingsfilen <filename
>~/.kde/share/config/kstarsrc</filename
>). Den næste kommando centrerer stjernekortet på Månen, og får stjernekortet til at følge Månen. Zoom-niveauet sættes så der zoomes 4 gange ind. Så sættes urets tidsskala så der går 1 time i sekundet (der er jo 3600 sekunder i en time), og uret startes (hvis det ikke kørte i forvejen). Den næste linje laver en pause på 20 sekunder i scriptet, mens vi følger månens vandring over himlen. Til sidst stoppes tiden og der zoomes ud til normal visning. </para>
<para
>Vi håber du kan bruge scriptmuligheden i &kstars;. Hvis du laver et interessant script må du meget gerne sende det til <email
>kstars@30doradus.org</email
>. Vi vil gerne se hvad du har lavet. Måske vil vi også lægge nogle scripter ud på vores hjemmeside. Vi vil også gerne høre fra dig hvis du har forslag til forbedringer af scriptmuligheden (og/eller resten af &kstars;) på <email
>kstars-devel@lists.sourceforge.net</email
> eller send en ønskeliste via KDE's fejlbehandlingssystem bugzilla. </para>
</sect1>
</chapter>

