<chapter id="dcop">
<title
>KStars fernsteuern: Die DCOP-Schnittstelle</title>
<para
>Eines der Ziele von &kstars; ist es, schwierigere Verhaltensweisen mit Skripten erneut aufzurufen. Dies erlaubt Ihnen, <quote
>virtuelle Führungen</quote
> des Himmels durchzuführen und erlaubt es Lehrern, Klassenzimmervorführungen zu erstellen, die bestimmte astronomische Konzepte darstellen. Es ist schon möglich, solche Skripte für &kstars; zu schreiben, obwohl noch nicht alle Funktionen beinhaltet sind. Vielleicht wird es bald einen oberflächenbasierten Skriptbaukasten geben, zur Zeit müssen die Skripte jedoch per Hand geschrieben werden. Dieses Kapitel beschreibt, wie Sie &kstars;-Skripte schreiben können. </para>
<para
>Die &kde;-Architektur biete das nötige Grundgerüst für Skriptanwendungen über die Schnittstelle namens <abbrev
>DCOP</abbrev
>. <abbrev
>DCOP</abbrev
> steht für <quote
>Desktop Communication Protocol</quote
>; durch <abbrev
>DCOP</abbrev
> können &kde;-Anwendungen von anderen Anwendungen, einer Kommandozeile oder durch ein Textskript gesteuert werden. </para>

<sect1 id="dcop-interface">
<title
>DCOP-Funktionen</title>
<para
>Die &kstars; <abbrev
>DCOP</abbrev
>-Schnittstelle enthält folgende Funktionen: <itemizedlist>
<listitem
><para
><function
> lookTowards( const QString richtung )</function
>: Richtet die Anzeigenmitte auf die Richtung aus, die durch das Argument angegeben wird. Das kann der Name jedes Objektes im Himmel sein oder einer der folgenden direktionalen Begriffe oder Abkürzungen: "zenith" (Zenit) (oder "z"), "north" (Nord) (oder "n"), "northeast" (Nordost) (oder "ne"), "east" (Osten) (oder ("e"), "southeast" (Südosten) (oder "se"), "south" (Süden) (oder "s"), "southwest" (Südwest) (oder "sw"), "west" (Westen) (oder "w") oder "northwest" (Nordwest) (oder "nw"). </para
></listitem>

<listitem
><para
><function
> setRaDec( double ra, double dec )</function
>: Fokussiert die Anzeige auf die angegebenen äquatorialen Koordinaten. </para
></listitem>

<listitem
><para
><function
> setAltAz(double alt, double az)</function
>: Fokussiert die Anzeige auf die angegebenen horizontalen Koordinaten. </para
></listitem>

<listitem
><para
><function
> zoomIn()</function
>: Vergrößert die Anzeige. </para
></listitem>

<listitem
><para
><function
> zoomOut()</function
>: Verkleinert die Anzeige </para
></listitem>

<listitem
><para
><function
> zoomOut()</function
>:  Setzt die Anzeige auf die Vergrößerungsstufe 3 (der Standard). </para
></listitem>

<listitem
><para
><function
> setLocalTime(int jahr, int monat, int tag, int std, int min, int sek)</function
>: Setzt die Simulationsuhr auf das angegebene Datum und Zeit. </para
></listitem>

<listitem
><para
><function
> waitFor( double t )</function
>: Pausiert für t Sekunden bevor mit den weiteren Skriptbefehlen fortgefahren wird. </para
></listitem>

<listitem
><para
><function
> waitForKey( const QString k )</function
>: Hält die Skriptausführung solange an, bis der Benutzer die angegebene Taste drückt. An diesem Punkt können Sie keine Tastenkombinationen angeben (wie etwa <keycombo action="simul"
>&Strg;<keycap
>C</keycap
></keycombo
>). Nur einfache Tasten sind erlaubt. Sie können <quote
>space</quote
> (engl. für Leertaste) eingeben, um die Leertaste zu bezeichnen. </para
></listitem>

<listitem
><para
><function
> setTracking( bool track )</function
>: Kontrolliert, ob die Verfolgungsfunktion eingeschaltet ist. </para
></listitem>

<listitem
><para
><function
> changeViewOption( const QString option, const QString value )</function
>: Passt eine Anzeigeeinstellung an. Es gibt Dutzende dieser Einstellungen, praktisch alles, was Sie im Fenster <guilabel
>&kstars; einrichten</guilabel
> verändern können. Das erste Argument ist der Name der Einstellung (Die Namen sind aus der Einstellungsdatei <filename
>kstarsrc</filename
> entnommen) und das zweite Argument ist der gewünschte Wert. Der Argumentleser ist sehr robust, also wenn Sie falsche Daten angeben, sollte er sich achtbar aus der Affäre ziehen. </para
></listitem>

<listitem
><para
><function
> setGeoLocation( const QString city, const QString province, const QString country )</function
>: Ändert den Beobachtungsort in die angegebene Stadt. Wenn keine Stadt mit dem Namen des Arguments gefunden wird, passiert nichts. </para
></listitem>

<listitem
><para
><function
> stop()</function
> [Uhr]: Hält die Simulationsuhr an. </para
></listitem>

<listitem
><para
><function
> start()</function
> [Uhr]: Startet die Simulationsuhr. </para
></listitem>

<listitem
><para
><function
> setScale(float s)</function
> [Uhr]: Setzt den Zeitschritt der Simulationsuhr: s = 1.0 entspricht der Realzeit, 2.0 ist zweimal so schnell, wie die Realzeit. </para
></listitem>
</itemizedlist>
</para>
</sect1>

<sect1 id="dcop-test">
<title
>DCOP-Funktionen testen</title>
<para
>Sie können die DCOP-Funktionen recht einfach ausprobieren, wenn Sie das Programm <application
>kdcop</application
> benutzen. Wenn Sie <application
>kdcop</application
> starten, sehen Sie eine Baumliste aller laufenden Programme; wenn &kstars; läuft, ist es aufgelistet. Viele der <abbrev
>DCOP</abbrev
>-Funktionen werden unter der Überschrift <quote
>KStarsInterface</quote
> aufgeführt, aber die Uhrzeitfunktionen werden unter<quote
>Uhr</quote
> aufgelistet. Doppelklicken Sie auf eine Funktion, um sie auszuführen. Wenn die Funktion Argumente erwartet, wird sich ein Fenster öffnen, in das Sie die Werte eingeben können. </para>
</sect1>

<sect1 id="dcop-script">
<title
>Schreiben eines DCOP-Skriptes</title>
<para
><abbrev
>DCOP</abbrev
>-Funktionen können auch von der UNIX-Kommandozeile aus aufgerufen werden und können in ein Skript verpackt werden. Wir werden ein Beispielskript erstellen, das auf äquatoriale Koordinaten umschaltet, die Ansicht auf dem Mond zentriert, etwas vergrößert und die Uhr auf eine Stunde pro Sekunde beschleunigt. Nachdem der Mond für 20 Sekunden verfolgt wird, wird die Uhr pausiert und die Anzeige verkleinert. Sie können dieses Skript als eine Art Beispieldatei für das Erstellen neuer Skripte verwenden. Ich werde das Skript zunächst hier aufführen und dann seine verschiedenen Teile erklären. </para>
<para>
<programlisting
>#!/bin/bash
#KStars Skript: Verfolgt den Mond
#
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
>Speichern Sie dieses Skript in eine Datei. Der Dateiname kann ein beliebiger sein. Ich empfehle etwas beschreibendes wie <filename
>trackmoon.kstars</filename
>. Dann geben Sie folgenden Befehl ein, um das Skript ausführbar zu machen: <userinput
><command
>chmod</command
> <option
>a+x</option
> <parameter
>trackmoon.kstars</parameter
> </userinput
>. Das Skript kann dann zu jeder Zeit mit der Eingabe <userinput
><command
>./trackmoon.kstars</command
></userinput
> im Verzeichnis, das das Skript enthält, ausgeführt werden. Beachten Sie, dass das Skript nur dann funktioniert, wenn &kstars; schon läuft. Sie können den Befehl <command
>dcopstart</command
> benutzen, um eine neue Instanz von &kstars; zu starten. </para>
<para
>Nun zur Erklärung des Skriptes. Die Kopfzeile identifiziert die Datei als <command
>BASH</command
> Shellskript. Die folgenden zwei Zeilen sind <firstterm
>Kommentare</firstterm
> (jede Zeile, die mit einem <quote
>#</quote
> beginnt ist ein Kommentar und wird ignoriert). Die nächsten drei Zeilen definieren einige Variablen, die später benutzt werden. Die Variable <varname
>KSTARS</varname
> identifiziert den aktuell laufenden &kstars;-Prozess, mit dem Befehl <command
>dcopfind</command
>. <varname
>MAIN</varname
> und <varname
>CLOCK</varname
> bezeichnen die zwei <abbrev
>DCOP</abbrev
>-Schnittstellen, die mit &kstars; verknüpft sind. </para>
<para
>Der Rest des Skriptes ist die tatsächliche Liste der <abbrev
>DCOP</abbrev
>-Aufrufe. Der erste Befehl setzt die Anzeige auf äquatoriale Koordinaten, indem die Einstellung <quote
>UseAltAz</quote
> auf <quote
>false</quote
> gesetzt wird. (Sie können eine Liste aller Optionen, die <quote
>changeViewOption</quote
> kennt, erhalten, wenn Sie in die Datei <filename
>kstarsrc</filename
> schauen). Der nächste Befehl zentriert die Ansicht auf dem Mond und schaltet die Verfolgung an. Dann setzen wir die normale Vergrößerungsstufe und vergrößern fünf Mal. Dann setzen wir die Zeitschritteinheit auf 1 Stunde pro Sekunde (3600 Sekunden sind eine Stunde) und starten die Uhr (falls sie noch nicht gelaufen ist). Die nächste Zeile pausiert das Skript für 20 Sekunden, während wir den Mond verfolgen, der über den Himmel zieht. Letztendlich stoppen wir die Uhr und setzen die Vergrößerungsstufe auf den normalen Wert. </para>
<para
>Wir hoffen, Sie mögen die Skriptmöglichkeiten von KStars. Falls Sie ein interessantes Skript erstellt haben, bitte schicken Sie es an <email
>kstars@30doradus.org</email
>, wir würden gerne sehen, was Sie erstellt haben und vielleicht einige Skripte auf der Webseite veröffentlichen. Wenn Sie Ideen zu Verbesserung der Skriptingmöglichkeiten haben (oder zu irgendeinem anderen Teil von &kstars;) lassen Sie es uns wissen unter <email
>kstars-devel@lists.sourceforge.net</email
> oder berichten Sie Probleme oder Wünsche an http://bugs.kde.org. </para>
</sect1>
</chapter>

