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

<para
>Приложения KDE могут управляться из других приложений, из командной строки или с помощью протокола <abbrev
>DCOP</abbrev
> (Desktop COmmunication Protocol). &kstars; предоставляет набор собственных действий и функций, которые можно вызвать через DCOP. Эти возможности позволяют, например, создавать демонстрации, иллюстрирующие основные концепции астрономии. </para>
<para
>Написание сценариев с использованием DCOP всё таки является программированием, что может отпугнуть тех, у кого нет опыта программирования. Редактор сценариев предоставляет графический интерфейс для конструирования сценариев, использующих возможности &kstars; через DCOP, что сильно упрощает написание сценариев. </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
>На рисунке выше представлен редактор сценариев. Панель слева &mdash; <firstterm
>Текущий сценарий</firstterm
>; там показаны команды, которые вы уже включили в сценарий. Панель справа &mdash; <firstterm
>Функции</firstterm
>; там показан список всех доступных функций и методов. Ниже списка функций расположена небольшая панель, в которой содержится краткое описание функции, выбранной в списке. Панель ниже текущего сценария &mdash; <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
>Moon</quote
> &mdash; Луна) в выпадающий список вручную, или воспользоваться окном <guilabel
>Поиск объекта</guilabel
> нажав кнопку <guibutton
>Объект</guibutton
>. Заметьте, если вы привязали экран к объекту, то автоматически начинается слежение за объектом, таким образом нет необходимости добавлять функцию <firstterm
>setTracking</firstterm
> после lookToward. </para
><para
>Итак, теперь экран центрирован на Луну, следующим шагом мы хотим ускорить время. Для этого используйте функцию <firstterm
>setClockScale</firstterm
>. Добавьте её в сценарий одним из описанных выше методов. После этого на панели аргументов функции появиться окошечко счётчика, с помощью которого вы можете установить требуемую скорость течения времени симуляции. Установите скорость на 3 часа. </para
><para
>Итак, мы привязали экран к Луне и ускорили время. теперь мы просто хотим приостановить исполнение сценария. Добавьте функцию <firstterm
>waitFor</firstterm
> и установите паузу на 20 с, используя панель аргументов функции. </para
><para
>В завершение установим скорость течения времени 1 с. Добавьте ещё один экземпляр setClockScale, и установите значение аргумента &mdash; 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;. Это делается через интерфейс &kstars; INDI DCOP, который предоставляет различные классы функций, подходящие для ваших задач. Функции INDI DCOP можно разделить на пять различных групп. Далее следует обзор этих функций и их аргументов, поддерживаемых в KStars. Рекомендуется прочитать раздел «<link linkend="indi-concepts"
>Общее представление об INDI</link
>», так как мы будем использовать ключевые концепции INDI повсеместно в данном учебном пособии.</para>
  <orderedlist>
    <listitem
><para
>Основные функции устройств (General). Например, функции включения и выключения устройств и так далее.</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
>: указать порт подключения к устройству INDI.</para
></listitem>
	<listitem
><para
><function
>setINDIAction(QString deviceName, QString action)</function
>: выполнить действие на устройстве INDI. Действие может быть любым <emphasis
>элементом свойства-переключателя</emphasis
></para
></listitem>
	<listitem
><para
><function
>waitForINDIAction(QString deviceName, QString action)</function
>: приостановить выполнение сценария, пока действие не возвратит успешное состояние.</para
></listitem>
      </itemizedlist>
    </listitem>
    <listitem
><para
>Функции телескопов (Telescope): функции управления движением телескопа и его состоянием.</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
>Показать установить местонахождение телескопа в виде долготы и широты. Долгота отсчитывается от Гринвича (Великобритания) на восток, хотя широко используются отрицательные долготы для западного полушария, INDI требует использовать значения долготы от 0 до 360 градусов. Поэтому, если у вас отрицательная долгота, просто добавьте к ней 360 градусов и получите требуемое значение для INDI. Например, координаты Калгари (Канада) в &kstars; имеют долготу -114 04 58, широту 51 02 58. Тогда долгота, требуемая INDI, будет 360 - 114.083 = 245.917 градусов.</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
>Функции камеры/CCD (Camera/CCD): функции управления камерой/CCD и получения их состояния.</para>
      <itemizedlist>
	<listitem
><para
><function
>setINDICCDTemp(QString deviceName, int temp)</function
>Показать установить температуру сенсоров CCD в градусах Цельсия.</para
></listitem>
	<listitem
><para
><function
>setINDIFrameType(QString deviceName, QString type)</function
>Показать установить тип кадра CCD. Возможные значения: FRAME_LIGHT, FRAME_BIAS, FRAME_DARK и FRAME_FLAT.</para
></listitem>
	<listitem
><para
><function
>startINDIExposure(QString deviceName, int timeout)</function
>Показать задать экспозицию камеры/CCD в секундах.</para
></listitem>
      </itemizedlist>
    </listitem
>    
   <listitem
><para
>Функции фокусировки (Focuser): функции управления движением и получения сведений от фокусирующего механизма.</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
>Функции фильтра (Filter): функции управления светофильтрами.</para>
      <itemizedlist>
      <listitem
><para
><function
>setINDIFilterNum(QString deviceName, int filter_num)</function
>: установить светофильтр <varname
>filter_num</varname
>. Пользователь может присваивать псевдонимы номерам фильтров в диалоге, открываемом командой <guimenuitem
>Настроить INDI</guimenuitem
> меню  <guimenu
>Устройства</guimenu
> (например, светофильтр 1 &mdash; Красный, светофильтр 2 &mdash; Зелёный и так далее).</para
></listitem>
    </itemizedlist>
    </listitem>
    
  </orderedlist>
  
<para
>Заметьте, имя устройства &mdash; первый аргумент всех функций INDI. Это позволяет не перемешиваться командам к разным устройствам в одном сценарии. Редактор сценариев предоставляет две дополнительные возможности для облегчения написания и редактирования сценариев INDI.</para>
<itemizedlist>
  <listitem
><para
><option
>Добавить waitForINDIAction после любой операции с INDI</option
>Показать если флажок установлен, то после любого действия с INDI редактор сценариев добавит команду <function
>waitForINDIAction()</function
>. Например, если вы добавите функцию <function
>switchINDI()</function
> и эта этот флажок установлен, редактор сценариев добавит «waitForINDIAction CONNECTION» в сценарий сразу после <function
>switchINDI()</function
>. Это приведёт к приостановке выполнения сценария после <function
>switchINDI()</function
>, пока <function
>switchINDI()</function
> не вернёт OK (то есть пока устройство не подключится). Важно помнить, что редактор сценариев не добавит <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 и CCD-камерой Finger Lakes, присоединённой к нему. Наш пример очень прост. Мы повернём телескоп и проследим за Марсом, и сделаем три снимка с экспозицией 10 с через 20 секунд.</para>
<important
><para
>У нас нет средств обратной связи или слежения в интерфейсе DCOP INDI, чтобы узнать состояние выполнения операции (за исключением функции <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
>. Первая функция &mdash; <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
>, с указанной целью &mdash; Марс. И, напоследок, получим снимки с экспозицией 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>

<note>
<para
>Библиотека INDI предоставляет мощные средства создания сценариев, которые позволяют разработчикам писать очень сложные сценарии. За подробностями обратитесь к <ulink url="http://indi.sourceforge.net/manual/book1.html"
>руководству разработчика INDI</ulink
>.</para>
</note>
</sect2>
</sect1>

