<sect1 id="tool-scriptbuilder">
<title
>Редактор сценариев</title>
<indexterm
><primary
>Инструменты</primary>
<secondary
>Редактор сценариев</secondary>
</indexterm>

<para
>Приложения KDE могут управляться из других приложений, из командной строки, или с помощью Коммуникационного Протокола Рабочего Стола (Desktop COmmunication Protocol -- <abbrev
>DCOP</abbrev
>). &kstars; предоставляет набор расширений, позволяющих лучше контролировать изображение с помощью сценариев. Эти возможности позволяют, например, создавать демонстрации иллюстрирующие основные концепции астрономии. </para>
<para
>Написание DCOP скриптов все-таки является программированием, что может отпугнуть тех, у кого нет опыта программирования. Редактор сценариев предоставляет графический интерфейс (<abbrev
>GUI</abbrev
>) для конструирования DCOP сценариев &kstars;, что сильно упрощает написание сценариев. </para>

<sect2 id="sb-intro">
<title
>Введение в редактор сценариев</title>

<para
>Перед тем как подробно описывать как пользоваться редактором сценариев, прочтите небольшое вступление обо всех компонентах графического интерфейса. Для более подробной информации воспользуйтесь функцией "справка". </para>

<screenshot>
<screeninfo
>Редактор сценариев </screeninfo>
<mediaobject>
  <imageobject>
    <imagedata fileref="scriptbuilder.png" format="PNG"/>
  </imageobject>
  <textobject>
    <phrase
>Редактор сценариев</phrase>
  </textobject>
</mediaobject>
</screenshot>

<para
>На рисунке ниже представлен редактор сценариев. Панель слева -- <firstterm
>Текущий скрипт</firstterm
>;там показаны команды, которые вы уже включили в сценарий. Панель справа -- <firstterm
>Браузер функции</firstterm
>; там показан список всех доступных функций. Ниже браузера функций расположена небольшая панель, в которой содержится краткое описание функции выбранной в браузере. Панель ниже текущего скрипта -- <firstterm
>Аргументы функций</firstterm
>; где вы можете изменить аргументы функции выделенной в текущем скрипте. </para
><para
>Вверху расположен ряд кнопок, которые оперируют со сценарием как с целым: это (слева на право) <guibutton
>Создать скрипт</guibutton
>, <guibutton
>Открыть скрипт</guibutton
>, <guibutton
>Сохранить скрипт</guibutton
>, <guibutton
>Сохранить скрипт как...</guibutton
>, и <guibutton
>Тестировать скрипт</guibutton
>. Значение этих кнопок очевидны, за исключением, может быть, последней. Нажав на кнопку <guibutton
>Тестировать скрипт</guibutton
> вы запустите его в главном окне &kstars;. Отодвиньте окно Редактора сценариев в сторону, перед тем как нажимать эту кнопку, чтобы увидеть результат выполнения сценария. </para
><para
>В центре окна расположены кнопки, которые работают с отдельными функциями сценария. Это (сверху вниз): <guibutton
>Добавить функцию</guibutton
>, <guibutton
>Удалить функцию</guibutton
>, <guibutton
>Копировать функцию</guibutton
>, <guibutton
>Выше</guibutton
>, и <guibutton
>Ниже</guibutton
>. <guibutton
>Добавить функцию</guibutton
> -- добавляет выделенную в браузере функцию в текущий сценарий (вы также можете добавить функцию дважды щёлкнув на её названии мышью). Остальные кнопки оперируют с функциями выделенными в текущем сценарии, т.е. позволяют удалять их, копировать, изменять их положение. </para>
</sect2>

<sect2 id="sb-using">
<title
>Использование Редактора сценариев</title>
<para
>В качестве иллюстрации использования редактора сценариев, мы приведём небольшой пример, где сделаем скрипт, который покажет след Луны, пока часы симуляции идут в ускоренном режиме. </para
><para
>Прежде чем нарисовать след Луны, нужно привязать к ней экран. Для этого используем функцию <firstterm
>lookToward</firstterm
>. выделите эту функцию в списке справа, и обратите внимание, что описание этой функции появилось в панели ниже. Нажмите кнопку <guibutton
>Добавить функцию</guibutton
> , чтобы добавить функцию к текущему сценарию. Теперь в панели Аргументы функцийпоявился выпадающий список <quote
>направление</quote
>, где вы можете выбрать направление, на которое будет привязан экран. В выпадающем списке содержаться только направления света, но нет объектов, таких как, например, Луна. Вы можете ввести имя объекта (<quote
>Луна</quote
>) в выпадающий список вручную, или воспользоваться окном <guilabel
>Поиск объекта</guilabel
> нажав кнопку <guibutton
>Объект</guibutton
>. Заметьте, если вы привязали экран к объекту, то автоматически начинается слежение за объектом, таким образом нет необходимости добавлять функцию <firstterm
>setTracking</firstterm
> перед lookToward. </para
><para
>Итак, теперь экран центрирован на Луну, следующим шагом мы хотим ускорить время. Для этого используйте функцию <firstterm
>setClockScale</firstterm
>. Добавьте её в сценарий, одним из описанных выше методов. После этого на панели Аргументы функций появиться окошечко счётчика, с помощью которого вы можете установить требуемую скорость течения времени симуляции. Установите скорость на 3 часа. </para
><para
>Итак, мы привязали экран к Луне и ускорили время. теперь мы просто хотим приостановить исполнение сценария. Добавьте функцию <firstterm
>waitFor</firstterm
> и установите паузу на 20с., используя панель Аргументов функций. </para
><para
>В завершение, установим скорость течения времени 1с. Добавьте ещё один экземпляр setClockScale, и установите значение аргумента - 1с. </para
><para
>Однако, в приведённом сценарии есть один недостаток. Мы должны сперва убедиться, что для отрисовки используются Экваториальные координаты, прежде чем начнём следить за Луной. Если используются Горизонтальные координаты, то на экране вы увидите очень быстрое вращение небесной сферы. Чтобы этого не произошло, установите параметр вида <firstterm
>UseAltAz</firstterm
> в <quote
>false</quote
>. Чтобы изменить какой-либо параметр вида, используйте функцию <firstterm
>changeViewOption</firstterm
>. Добавьте эту функцию к сценарию, и обратите внимание на панель аргументов функций. Здесь есть выпадающий список, содержащий все параметры вида. Так как мы точно знаем название опции, то мы можем просто выбрать её из списка. Если вы не знаете название необходимой опции, нажмите на кнопку <guibutton
>Просмотреть дерево</guibutton
>, чтобы открыть окно, которое показывает опции по разделам. Кроме того, рядом с каждой опцией содержится краткое описание, за что она отвечает, и тип аргументов и их предельные значения. Так опцию UseAltAz мы найдём в разделе <guilabel
>Настройка звёздного неба</guilabel
>. Выберите опцию и нажмите кнопку <guibutton
>OK</guibutton
>, после этого опция будет выбрана в выпадающем списке в панели аргументов функций. Наконец в поле Значение, наберите <quote
>false</quote
> или <quote
>0</quote
>. </para
><para
>Ещё один шаг: изменение опции UseAltAz в конце сценария не принесёт желаемого результат; мы должны изменить эту опцию в начале сценария. Для этого убедитесь что выделена нужная функция в панели текущий скрипт, и нажимайте кнопку <guibutton
>Выше</guibutton
>, до тех пор, пока функция не окажется вверху. </para
><para
>Теперь, когда сценарий написан, нужно сохранить его на диск. Для этого нажмите кнопку <guibutton
>Сохранить скрипт</guibutton
>. Сперва откроется окно, где вам предложат ввести название сценария и ваше имя, как имя автора. Для примера, в качестве названия сценария введите <quote
>Слежение за луной</quote
>, и своё имя в поле автор, и нажмите <guibutton
>OK</guibutton
>. После этого откроется стандартный диалог &kde; Сохранить файл. Введите название файла, и нажмите <guibutton
>OK</guibutton
>, чтобы сохранить сценарий. Заметьте, что если имя файла НЕ оканчивается <quote
>.kstars</quote
>, то этот суффикс будет добавлен автоматически. Если вы чувствуете себя опытным пользователем, вы можете отредактировать сценарий вручную, с помощью любого текстового редактора. </para
><para
>Готовый сценарий, можно запустить множеством способов. Из командной строки можно запустить только если &kstars; уже запущен. Также вы можете запустить сценарий из &kstars; с помощью пункта <guimenuitem
>Запустить сценарий</guimenuitem
>, меню <guimenuitem
>Файл</guimenuitem
>. </para>
</sect2>

<sect2 id="sb-indi">
  <title
>Управление устройствами с помощью INDI</title>
  <para
>Автоматизация управления доступна для всех устройств совместимых с протоколом <link linkend="what-is-indi"
>INDI</link
>. Вы можете координировать работу любого количества устройств с помощью <link linkend="sb-intro"
>Генератора сценариев</link
> &kstars;. Управление можно улучшить, используя интерфейс INDI DCOP, который предоставляет различные функции для решения ваших задач. Функции INDI DCOP можно разбить на четыре класса. Далее следует обзор функций и их аргументов, поддерживаемых &kstars; Перед использованием, мы рекомендуем сперва познакомиться с <link linkend="indi-concepts"
>Концепцией INDI</link
>.</para>
  <orderedlist>
    <listitem
><para
>Основные функции устройств (Generic Device Functions): например функции включения/выключения устройств и т.п. ...</para>
      <itemizedlist>
	<listitem
><para
><function
>startINDI (QString deviceName, bool useLocal)</function
> : Устанавливает INDI сервис, как локальный для данного компьютера или как сервер.</para
></listitem>
	<listitem
><para
><function
>shutdownINDI (QString deviceName)</function
> : Останавливает INDI сервис. </para
></listitem>
	<listitem
><para
><function
>switchINDI(QString deviceName, bool turnOn)</function
> : Подключает, или отключает устройство (работающее по протоколу) INDI.</para
></listitem>
	<listitem
><para
><function
>setINDIPort(QString deviceName, QString port)</function
> : Устанавливает порт подключения устройства.</para
></listitem>
	<listitem
><para
><function
>setINDIAction(QString deviceName, QString action)</function
> : Выполняет действие INDI. Действие может быть - <emphasis
>element</emphasis
> или <emphasis
>switch property</emphasis
></para
></listitem>
	<listitem
><para
><function
>waitForINDIAction(QString deviceName, QString action)</function
> : Приостановить выполнение сценария, пока <emphasis
>свойство</emphasis
> действия не вернёт успешный статус завершения.</para
></listitem>
      </itemizedlist>
    </listitem>
    <listitem
><para
>Функции телескопов (Telescope Functions): функции управления движением телескопа и его состоянием.</para>
      <itemizedlist>
	<listitem
><para
><function
>setINDIScopeAction(QString deviceName, QString action)</function
> : Установить режим, или действие телескопа. возможные значения - SLEW, TRACK, SYNC, PARK, и ABORT.</para
></listitem>
	<listitem
><para
><function
>setINDITargetCoord(QString deviceName, double RA, double DEC)</function
> : установить координаты "цели" телескопа.</para
></listitem>
	<listitem
><para
><function
>setINDITargetName(QString deviceName, QString objectName)</function
> : Установить координаты "цели" по имени <emphasis
>objectName</emphasis
>. &kstars; ищет имя объекта в своей базе данных, и автоматически задаёт значения склонения и восхождения, если они есть в базе данных..</para
></listitem>
	<listitem
><para
><function
>setINDIGeoLocation(QString deviceName, double longitude, double latitude)</function
> : Устанавливает географическое положение телескопа: долготу и широту. Долгота устанавливается в нотации "E of N". На пример,долгота города Calgary, Canada в &kstars;: -114 04 58 - широта: 51 02 58. Необходимо преобразовывать <emphasis
>только</emphasis
> отрицательные значения долготы. Чтобы преобразовать долготы в  "E of N" нотацию, мы должны прибавить к абсолютному значению долготы прибавить 180 градусов. Так, в нашем примере, долгота INDI = 114 04 08 + 180 00 00 = 294 04 08 "E of N".</para
></listitem>
	<listitem
><para
><function
>setINDIUTC(QString ddeviceName, QString UTCDateTime)</function
> : Установить для телескопа UTC дату и время в вормате ISO 8601, т.е. в формате ГГГГ-ММ-ДДTЧЧ:MM:СС (например 2004-07-12T22:05:32).</para
></listitem>
      </itemizedlist>
    </listitem>
    <listitem
><para
>Функции фокусировки (Focuser Functions): функции управляющие фокусировкой телескопа и статусом фокусировки.</para>
      <itemizedlist>
      <listitem
><para
><function
>setINDIFocusSpeed(QString deviceName, QString action)</function
> : Установить скорость фокусирующего механизма. Допустимые значения FOCUS_HALT, FOCUS_SLOW, FOCUS_MEDIUM, и FOCUS_FAST.</para
></listitem>
      <listitem
><para
><function
>setINDIFocusTimeout(QString deviceName, int timeout)</function
> : Установить максимальную длительность любых операций выполняемых после в результате вызова функции startINDIFocus.</para
></listitem>
      <listitem
><para
><function
>startINDIFocus(QString deviceName, int focusDir)</function
> : Фокусировать на короткое расстояние (focusDir = 0) или на бесконечность (focusDir = 1). Скорость и время устанавливаются функциями <function
>setINDIFocusSpeed()</function
> и <function
>setINDIFocusTimeout()</function
>.</para
></listitem>
    </itemizedlist>
    </listitem>
    <listitem
><para
>Функции камеры/ПЗС (Camera/CCD Functions) :функции управляющие камерой/ПЗС и их состоянием.</para>
      <itemizedlist>
	<listitem
><para
><function
>setINDICCDTemp(QString deviceName, int temp)</function
> : Установить температуру ПЗС сенсоров, в градусах Цельсия.</para
></listitem>
	<listitem
><para
><function
>setINDIFrameType(QString deviceName, QString type)</function
> : Установить тип кадра ПЗС. Возможные значения: FRAME_LIGHT, FRAME_BIAS, FRAME_DARK, и FRAME_FLAT.</para
></listitem>
	<listitem
><para
><function
>startINDIExposure(QString deviceName, int timeout)</function
> : Начать экспозицию ПЗС/Камеры, время (<emphasis
>timeout</emphasis
>) в секундах.</para
></listitem>
      </itemizedlist>
    </listitem>
  </orderedlist>
  
<para
>Заметьте, что имя устройства - первый аргумент всех функций INDI. Это позволяет не перемешиваться командам к разным устройствам в одном сценарии. Редактор сценариев две возможности для облегчения написания и редактирования сценариев INDI.</para>
<itemizedlist>
  <listitem
><para
><option
>Добавить waitForINDIAction после каждого действия INDI</option
> : Если эта опция выбрана, то после любого действия Редактор сценариев добавит команду <function
>waitForINDIAction()</function
>. Например, если вы добавите функцию <function
>switchINDI()</function
>и эта опция была отмечена, редактор сценариев добавит "waitForINDIAction CONNECTION" в сценарий сразу после <function
>switchINDI()</function
>. Это приведёт к приостановке выполнения сценария после <function
>switchINDI()</function
>, покаl <function
>switchINDI()</function
> не вернёт OK (&ie; пока устройство не подключится). Важно знать, что редактор сценариев не добавит <function
>waitForINDIAction()</function
> для действий, добавленных с помощью <function
>setINDIAction()</function
>, так как &kstars; не сможет определить родительское свойство таких действий. Поэтому, вы должны вручную добавить <function
>waitForINDIAction()</function
> после этих действий, если требуется.</para>
  </listitem>
  <listitem
><para
><option
>Повторное использование имён INDI</option
> : Когда эта опция выбрана, то во всех последующих функциях, будет использоваться последнее введённое имя устройства. Новое имя устанавливается с помощью <function
>startINDI()</function
>. Если вы работаете с несколькими устройствами, то рекомендуется выключать эту опцию.</para>
  </listitem>
</itemizedlist>

<para
>Теперь мы можем создать пример сценария, который будет управлять телескопом LX200 GPS, и ПЗС камерой Finger Lakes, присоединённой к нему. Наш пример очень прост. Мы повернём телескоп и проследим за Марсом, и сделаем три снимка с экспозицией 10с через 20с каждый.</para>
<important
><para
>У нас нет средств обратной связи или слежения в INDI DCOP интерфейсе, чтобы узнать степень выполнения операции (за исключением функции <function
>waitForINDIAction()</function
>), поэтому мы должны постоянно следить за устройством. Так как мы не можем следить за возникновением ошибок, и исправлять их "на лету", мы должны писать сценарий с перестраховкой. Все сценарии должны тщательно проверяться, перед их использованием.</para
></important>

<screenshot>
  <screeninfo
>Редактор сценариев </screeninfo>
  <mediaobject>
    <imageobject>
      <imagedata fileref="indiscript.png" format="PNG"/>
    </imageobject>
    <textobject>
      <phrase
>Редактор сценариев</phrase>
    </textobject>
  </mediaobject>
</screenshot>

<para
>Пример сценария приведён выше. Обратите внимание, что отмечена опция <option
>Добавить waitForINDIAction после каждого действия INDI</option
> и не отмечена <option
>Повторное использование имён INDI</option
>. Первая функция - <function
>startINDI()</function
>. Мы запускаем наше устройство локально, поэтому нет необходимости менять режим сервиса в окне аргументов функций. Мы вводим имена устройств, начиная с телескопа "LX200 GPS", потом повторяем тоже и для ПЗС матрицы - "FLI CCD".После этого стоит функция <function
>waitFor()</function
>. Рекомендуется использовать функцию <function
>waitFor()</function
> непосредственно после <function
>startINDI()</function
>, чтобы приостановить выполнение сценария на 1-5с. Это сделано для того, чтобы быть уверенными, что внутренние переменные настроены так как надо, и устройства готовы для получения команд. Также это необходимо для управления удалёнными устройствами, так как связь ними может быть затруднена. Далее следует функция <function
>switchINDI()</function
>, чтобы соединиться с устройствами.</para>

<para
>Так как опция <option
>Добавить waitForINDIAction после каждого действия INDI</option
> отмечена, то нет необходимости добавлять <function
>waitForINDIAction()</function
> после <function
>switchINDI()</function
>, чтобы убедиться в выполнении команды, потому что редактор сценариев сделает это автоматически при сохранении файла. Далее запустим слежение телескопа, добавив <function
>setINDIScopeAction()</function
> с аргументом TRACK. Заметьте, что мы переводим телескоп в режим слежения <emphasis
>перед</emphasis
> указанием координат. Функция <function
>setINDIScopeAction()</function
> применена здесь для большего удобства, можно было воспользоваться функцией <function
>setINDIAction()</function
> с ключевым словом TRACK. Тем не менее, благодаря использования <function
>setINDIScopeAction()</function
> &kstars; автоматически добавит функцию <function
>waitForINDIAction()</function
>. </para>

<para
>Далее мы используем функцию <function
>setINDITargetName()</function
>, с "целью" - Марс. И, напоследок, получим снимки с экспозицией 10с, используя <function
>startINDIExposure()</function
>, с паузой в 20с между снимками используя <function
>waitFor()</function
> со значением аргумента 20.</para>

<para
>Теперь сохраним сценарий, чтобы использовать его в дальнейшем. Сохранённый сценарий должен выглядеть примерно так:</para>
<blockquote
><programlisting
>#!/bin/bash
    #KStars DCOP script: Demo Script
    #by Jasem Mutlaq
    #last modified: Thu Jan 6 2005 09:58:26
    #
    KSTARS=`dcopfind -a 'kstars*'`
    MAIN=KStarsInterface
    CLOCK=clock#1
    dcop $KSTARS $MAIN  startINDI "LX200 GPS" true
    dcop $KSTARS $MAIN  startINDI "FLI CCD" true
    dcop $KSTARS $MAIN  waitFor 3
    dcop $KSTARS $MAIN  switchINDI "LX200 GPS" true
    dcop $KSTARS $MAIN  waitForINDIAction "LX200 GPS" CONNECTION
    dcop $KSTARS $MAIN  switchINDI "FLI CCD" true
    dcop $KSTARS $MAIN  waitForINDIAction "FLI CCD" CONNECTION
    dcop $KSTARS $MAIN  setINDIScopeAction "LX200 GPS" TRACK
    dcop $KSTARS $MAIN  waitForINDIAction "LX200 GPS" ON_COORD_SET
    dcop $KSTARS $MAIN  setINDITargetName "LX200 GPS" Mars
    dcop $KSTARS $MAIN  waitForINDIAction "LX200 GPS" EQUATORIAL_EOD_COORD
    dcop $KSTARS $MAIN  startINDIExposure "FLI CCD" 10
    dcop $KSTARS $MAIN  waitForINDIAction "FLI CCD" EXPOSE_DURATION
    dcop $KSTARS $MAIN  waitFor 20
    dcop $KSTARS $MAIN  startINDIExposure "FLI CCD" 10
    dcop $KSTARS $MAIN  waitForINDIAction "FLI CCD" EXPOSE_DURATION 
    dcop $KSTARS $MAIN  waitFor 20
    dcop $KSTARS $MAIN  startINDIExposure "FLI CCD" 10
    dcop $KSTARS $MAIN  waitForINDIAction "FLI CCD" EXPOSE_DURATION
</programlisting>
</blockquote>
</sect2>
</sect1>