<chapter id="dcop">
<title
>Skrypty KStars: Interfejs DCOP</title>
<para
>Jednym z celów &kstars; jest umożliwienie odtworzenia skomplikowanych zachowań z plików. Pozwala to na stworzenie <quote
>wirtualnych szlaków</quote
> na niebie i umożliwia nauczycielom konstruowanie zajęć ilustrujących koncepcje astronomiczne. Dostępna jest już możliwość pisania takich skryptów dla &kstars; pomimo, że nie wszystkie potrzebne funkcje są dostępne. Dopóki nie jest dostępne narzędzie programowe do budowy skryptów bazujące na interfejsie GUI, skrypty muszą być pisane ręcznie. Ten rozdział wyjaśnia jak napisać skrypt dla &kstars;. </para>
<para
>Architektura &kde; dostarcza niezbędnego narzędzia służącego do pisania skryptów przez interfejs <abbrev
>DCOP</abbrev
>. <abbrev
>DCOP</abbrev
> oznacza <quote
>Desktop Communication Protocol</quote
>; czyli protokół komunikacji przez pulpit, przy użyciu <abbrev
>DCOP</abbrev
>, aplikacje &kde; mogą być kontrolowane z wiersza poleceń lub przez skrypt. </para>

<sect1 id="dcop-interface">
<title
>Funkcje DCOP</title>
<para
>Interfejs <abbrev
>DCOP</abbrev
> &kstars; posiada następujące funkcje: <itemizedlist>
<listitem
><para
><function
> lookTowards( const QString direction )</function
>: Argument wskazuje punkt który będzie przybliżany. Może być to nazwa dowolnego obiektu na niebie, lub jeden z następujących wyrazów lub skrótów kierunków: zenith (lub z, zenit), north (n, północ), northeast (ne, północny wschód), east (e, wschód), southeast (se, południowy wschód), south (s, południe), southwest (sw, południowy zachód), west (w, zachód), northwest (nw, północny zachód). </para
></listitem>

<listitem
><para
><function
> setRaDec( double ra, double dec )</function
>: Wskazanie punktu podanego za pomocą współrzędnych równikowych. </para
></listitem>

<listitem
><para
><function
> setAltAz(double alt, double az)</function
>: Wskazanie punktu podanego za pomocą współrzędnych horyzontalnych. </para
></listitem>

<listitem
><para
><function
> zoomIn()</function
>: Zwiększa stopień przybliżenia. </para
></listitem>

<listitem
><para
>s<function
> zoomOut()</function
>: Zmniejsza poziom przybliżenia. </para
></listitem>

<listitem
><para
><function
> defaultZoom()</function
>: Przywrócenie przybliżenia na poziomie 3 (domyślnym). </para
></listitem>

<listitem
><para
><function
> setLocalTime(int yr, int mth, int day, int hr, int min, int sec)</function
>: Ustawienie zegara symulatora na określoną datę i godzinę. </para
></listitem>

<listitem
><para
><function
> waitFor( double t )</function
>: Wstrzymanie wykonywania skryptu na t sekund. </para
></listitem>

<listitem
><para
><function
> waitForKey( const QString k )</function
>: Wstrzymanie wykonania skryptu do wciśnięcia przez użytkownika określonego klawisza. Nie można jednak czekać na kombinację klawiszy (takich jak <keycombo action="simul"
>&Ctrl;<keycap
>C</keycap
></keycombo
>); tylko pojedyńcze klawisze. Można wpisać <quote
>space</quote
>,by czekać na klawisz spacji. </para
></listitem>

<listitem
><para
><function
> setTracking( bool track )</function
>: Włączenie/wyłączenie trybu śledzenia. </para
></listitem>

<listitem
><para
><function
> changeViewOption( const QString option, const QString value )</function
>: Regulacja widoku. Dostępnych jest wiele opcji; wszystkich ustawień można dokonać w oknie <guilabel
>Konfiguracja: &kstars;</guilabel
>. Pierwszym argumentem jest nazwa opcji (nazwy są wzięte z pliku konfiguracyjnego <filename
>kstarsrc</filename
>), drugim argumentem jest żądana wartość. Parser argumentu jest dosyć ścisły, zatem wprowadzenie złego argumentu powoduje błąd. </para
></listitem>

<listitem
><para
><function
> setGeoLocation( const QString city, const QString province, const QString country )</function
>: Zmiana miejsca obserwacji na podaną lokalizację. Jeżeli podane jako argument miasto nie zostanie znalezione, nie zostanie wykonana żadna czynność. </para
></listitem>

<listitem
><para
><function
> stop()</function
> [clock]: Zatrzymanie zegara symulatora. </para
></listitem>

<listitem
><para
><function
> start()</function
> [clock]: Uruchomienie zegara symulatora. </para
></listitem>

<listitem
><para
><function
> setScale(float s)</function
> [clock]: Ustawienie współczynnika zegara symulatora. s=1.0 oznacza czas rzeczywisty; 2.0 oznacza dwukrotnie szybszy czas, itp. </para
></listitem>
</itemizedlist>
</para>
</sect1>

<sect1 id="dcop-test">
<title
>Testy funkcji DCOP</title>
<para
>Działanie funkcji DCOP można łatwo zaobserwować przy użyciu programu <application
>kdcop</application
>. Uruchamiając <application
>kdcop</application
>, widzimy listę drzewiastą wszystkich uruchomionych programów; jeżeli uruchomiony jest program &kstars; będzie on oczywiście wyświetlony. Większość funkcji <abbrev
>DCOP</abbrev
> jest wymienionych w nagłówku <quote
>KStarsInterface</quote
>, natomiast funkcje zegara są wymienione w <quote
>zegarze</quote
>. Podwójne kliknięcie na wybranej funkcji uruchamia ją. Jeżeli funkcja wymaga argumentu, pojawi się okno w którym można je wprowadzić. </para>
</sect1>

<sect1 id="dcop-script">
<title
>Pisanie skryptów DCOP</title>
<para
>Funkcje <abbrev
>DCOP</abbrev
> mogą być wywoływane z wiersza poleceń UNIX-a, jak również umieszczone w skrypcie. Utworzymy przykładowy skrypt zamieniający współrzędne równikowe, ustawiający wskaźnik wyświetlacza na Księżyc, przybliżający lekko a także przyspiesza zegar do 1 godziny na sekundę. Po śledzeniu Księżyca przez 20 sekund zegar jest zatrzymywany a obraz oddalany. Skryptu można używać jako wzorca do tworzenia kolejnych. Najpierw zostanie przytoczony cały skrypt a później objaśnione poszczególne jego części. </para>
<para>
<programlisting
>#!/bin/bash
#KStars script: Track the Moon!
#
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
>Skrypt należy zapisać. Nazwa może być dowolna; ale sugeruje się jakąś intuicyjną jak <filename
>drogaksiezyca.kstars</filename
>. By wykonać skrypt należy użyć następujących poleceń: <userinput
><command
>chmod</command
> <option
>a+x</option
> <parameter
>drogaksiezyca.kstars</parameter
> </userinput
>. Po tym skrypt może być wywołany w dowolnej chwili poprzez wpisanie <userinput
><command
>./drogaksiezyca.kstars</command
></userinput
> w folderze zawierającym skrypt. Skrypt zostanie wykonany jedynie wtedy, gdy uruchomiony jest już program &kstars;. Do uruchomienia nowej instancji &kstars; w skrypcie można użyć polecenia <command
>dcopstart</command
>. </para>
<para
>Wyjaśnienie skryptu. Pierwszy wiersz określa plik jak skrypt powłoki <command
>BASH</command
>. Dwa następne wiersze są <firstterm
>komentarzami</firstterm
> (każdy wiersz rozpoczynający się od <quote
>#</quote
> jest komentarzem; jest teżignorowany przez powłokę). Trzy kolejne wiersze definiują używane później zmienne. Zmienna <varname
>KSTARS</varname
> określa aktualnie uruchomioną kopię &kstars;, za pomocą polecenia <command
>dcopfind</command
>. <varname
>MAIN</varname
> oraz <varname
>CLOCK</varname
> określają dwa interfejsy <abbrev
>DCOP</abbrev
> związane z &kstars;. </para>
<para
>Reszta skryptu jest listą wywołań <abbrev
>DCOP</abbrev
>. Pierwsze polecenie ustawia wykorzystanie współrzędnych równikowych, poprzez ustawienie <quote
>UseAltAz</quote
> na <quote
>false</quote
> (lista wszystkich opcji <quote
>changeViewOption</quote
>, które mogą być wykorzystane, znajduje się w pliku konfiguracyjnym <filename
>kstarsrc</filename
>). Następny wiersz wyśrodkowuje wyświetlacz na Księżycu i uruchamia śledzenie. Następnie zostaje ustawiony domyślny poziom przybliżenia, a następnie przyliżenie zostaje zwiększone 5 krotnie. Dalej skala czasu zegara zostaje ustawiona na 1 godzinę na sekundę (3600 sekund na godzinę), a także zostaje uruchomiony zegar (pod warunkiem, że wcześniej nie był uruchomiony). Kolejny wiersz zatrzymuje wykonanie skryptu na 20 sekund, podczas gdy Księżyc jest dalej śledzony na niebie. Następnie zostaje zatrzymany zegar, a przybliżenie ustawione na poziom domyślny. </para>
<para
>Mamy nadzieję, że podobają się Państwu możliwości skryptów KStars. Jeżeli napiszą Państwo jakiś interesujący skrypt bardzo prosimy o przysłanie go na adres <email
>kstars@30doradus.org</email
>; z przyjemnością obejrzymy efekty Państwa pracy i być może umieścimy na naszej stronie internetowej. Czekamy także na wszelkie sugestie jak ulepszyć możliwości skryptów (bądź dowolnej innej części &kstars;), pod adresem <email
>kstars-devel@lists.sourceforge.net</email
> lub po wypełnieniu okienka z sugestiami w bugzilli. </para>
</sect1>
</chapter>

