# Skrypty KStars: Interfejs DCOP

Jednym z celów &kstars; jest umożliwienie odtworzenia skomplikowanych zachowań z plików. Pozwala to na stworzenie wirtualnych szlaków 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;.

Architektura &kde; dostarcza niezbędnego narzędzia służącego do pisania skryptów przez interfejs DCOP. DCOP oznacza Desktop Communication Protocol; czyli protokół komunikacji przez pulpit, przy użyciu DCOP, aplikacje &kde; mogą być kontrolowane z wiersza poleceń lub przez skrypt.

## Funkcje DCOP

Interfejs DCOP &kstars; posiada następujące funkcje:

- `lookTowards( const QString direction )`: 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).

- `setRaDec( double ra, double dec )`: Wskazanie punktu podanego za pomocą współrzędnych równikowych.

- `setAltAz(double alt, double az)`: Wskazanie punktu podanego za pomocą współrzędnych horyzontalnych.

- `zoomIn()`: Zwiększa stopień przybliżenia.

- s`zoomOut()`: Zmniejsza poziom przybliżenia.

- `defaultZoom()`: Przywrócenie przybliżenia na poziomie 3 (domyślnym).

- `setLocalTime(int yr, int mth, int day, int hr, int min, int sec)`: Ustawienie zegara symulatora na określoną datę i godzinę.

- `waitFor( double t )`: Wstrzymanie wykonywania skryptu na t sekund.

- `waitForKey( const QString k )`: Wstrzymanie wykonania skryptu do wciśnięcia przez użytkownika określonego klawisza. Nie można jednak czekać na kombinację klawiszy (takich jak &Ctrl;C); tylko pojedyńcze klawisze. Można wpisać space,by czekać na klawisz spacji.

- `setTracking( bool track )`: Włączenie/wyłączenie trybu śledzenia.

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

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

- `stop()` [clock]: Zatrzymanie zegara symulatora.

- `start()` [clock]: Uruchomienie zegara symulatora.

- `setScale(float s)` [clock]: Ustawienie współczynnika zegara symulatora. s=1.0 oznacza czas rzeczywisty; 2.0 oznacza dwukrotnie szybszy czas, itp.

## Testy funkcji DCOP

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

## Pisanie skryptów DCOP

Funkcje DCOP 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.

    #!/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
    ##

Skrypt należy zapisać. Nazwa może być dowolna; ale sugeruje się jakąś intuicyjną jak `drogaksiezyca.kstars`. By wykonać skrypt należy użyć następujących poleceń: ``chmod` `a+x` `drogaksiezyca.kstars`` . Po tym skrypt może być wywołany w dowolnej chwili poprzez wpisanie ``./drogaksiezyca.kstars`` 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 `dcopstart`.

Wyjaśnienie skryptu. Pierwszy wiersz określa plik jak skrypt powłoki `BASH`. Dwa następne wiersze są komentarzami (każdy wiersz rozpoczynający się od # jest komentarzem; jest teżignorowany przez powłokę). Trzy kolejne wiersze definiują używane później zmienne. Zmienna `KSTARS` określa aktualnie uruchomioną kopię &kstars;, za pomocą polecenia `dcopfind`. `MAIN` oraz `CLOCK` określają dwa interfejsy DCOP związane z &kstars;.

Reszta skryptu jest listą wywołań DCOP. Pierwsze polecenie ustawia wykorzystanie współrzędnych równikowych, poprzez ustawienie UseAltAz na false (lista wszystkich opcji changeViewOption, które mogą być wykorzystane, znajduje się w pliku konfiguracyjnym `kstarsrc`). 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.

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 kstars@30doradus.org; 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 kstars-devel@lists.sourceforge.net lub po wypełnieniu okienka z sugestiami w bugzilli.