<sect1 id="ekos-extensions">
    <title
>Розширення</title>
    <indexterm>
        <primary
>Інструменти</primary>
        <secondary
>Ekos</secondary>
        <tertiary
>Розширення</tertiary>
    </indexterm>
	<sect2 id="extensions-Introduction">
		<title
>Вступ</title>
	    <para
>Розширення є невеличкими програмами, які можна додавати для взаємодії із Kstars/Ekos/INDI з метою забезпечення роботи додаткових функцій або можливостей. </para>
		<note>
			<para
>Розширення відокремлено від Kstars/Ekos/INDI. Вони не постачаються як частина цього програмного пакунка. У ньому забезпечено лише можливість викликати ці розширення. Вам слід бути обізнаними із вимогами та ризиками використання розширень. </para>
		</note>
	</sect2>
	<sect2 id="extensions-Requirements">
	  <title
>Вимоги</title>
	    <para
>Кожне розширення має складатися із принаймні 2 файлів із необов'язковим третім файлом піктограми. </para>
	      <itemizedlist>
	        <listitem>
	          <para
>Файл програми. Це виконуваний файл, який буде запущено у системі користувача. Користувач, від імені якого запущено KStars, повинен мати права на виконання цього файла. </para>
          </listitem>
          <listitem>
            <para
>Файл налаштувань. Це звичайний текстовий файл, який визначає обов'язкові та додаткові джерела даних для розширення. Він повинен мати таку саму назву, як виконуваний файл розширення, але мати суфікс назви файла .conf. </para>
            <para
>Файл налаштувань обов'язково повинен містити рядок, що починається з <emphasis role="bold"
>minimum_kstars_version=n.n.n</emphasis
>, де n.n.n є найнижчою версією KStars, у якій забезпечено підтримку роботи розширення, наприклад 3.7.3 </para>
            <para
>Крім того (хоча це не є бажаним), у файлі налаштувань може міститися рядок, що починається з <emphasis role="bold"
>runDetached=true</emphasis
>. Якщо такий рядок є, розширення буде запущено незалежно від KStars. Після запуску розширення не зможе передавати дані щодо стану назад до Ekos. Цим слід користуватися, лише якщо розширення мають продовжувати роботу після закриття вікна KStars. Розширення має також надавати власний інтерфейс користувача. </para>
            <para
>Крім того, файл налаштувань може містити будь-які інші параметри, які визначаються автором розширення, та довільний текст. </para>
          </listitem>
          <listitem>
            <para
>Файл піктограми, якщо такий існує, повинен мати таку саму назву, що і виконуваний файл розширення, із додаванням відповідного суфікса назви, що відповідає формату зображення, передбачено підтримку .jpg, .bmp, .gif, .png і .svg. Якщо таку піктограму включено до пакунка розширення, її буде використано у спадному списку вибору розширень. Якщо піктограму не надано, замість неї буде використано типову піктограму. </para>
          </listitem>
        </itemizedlist>
        <para
>Усі файли розширення (виконуваний файл, налаштування та необов'язкова піктограма) має бути скопійовано до придатного до запису з KStars каталогу даних, підкаталог /extensions, наприклад ~/.local/share/kstars/extensions </para>
	    <para
>Наявні розширення, що мають коректний файл налаштувань та мають мінімальну версію KStars не вище поточної встановленої, буде виявлено під час запуску Ekos. Якщо коректних розширень не виявлено, елемент інтерфейсу користувача для розширень не буде показано. Елементи інтерфейсу користувача для розширень — це спадний список, у якому буде показано назву та піктограму кожного виявленого розширення, а також кнопку запуску/зупинення. Якщо розширення не закривається протягом 10 секунд після натискання кнопки зупинення, кнопка активується повторно як кнопка переривання, яка примусово завершить роботу розширення. Одночасно можна використовувати лише одне розширення. </para>
	</sect2>
	<sect2 id="extensions-Development">
    <title
>Розробка</title>
      <para
>Нижче наведено опис додаткових речей для розробників розширень. </para>
        <itemizedlist>
         <listitem>
            <para
>Коди декількох розширень, зокрема приклад каркасу розширення, можна знайти у сховищі <ulink url="https://github.com/LuckyEddie47/kstars_extensions"
>KStars Extension на Github</ulink
> </para>
         </listitem>
         <listitem>
            <para
>Усяке розширення має перевіряти наявність та чинність власного файла налаштувань. Запис файла налаштувань minimum_kstars_version має бути перевірено за внутрішнім еталоном для підтвердження тощо, що файл налаштувань відповідає вимогам розширення. Див. приклад каркасу розширення. </para>
          </listitem>
          <listitem>
            <para
>Версію KStars буде передано до розширення як arg(1) у виклику QProcess. </para>
          </listitem>
          <listitem>
            <para
>Уся взаємодія з KStars/Ekos/INDI має відбуватися за допомогою інтерфейсу DBus. Див. приклад каркасу розширення. Корисними інструментами для вивчення, спостереження та ознайомлення із DBus є <ulink url="https://wiki.gnome.org/Apps/DFeet"
>D-Feet</ulink
> та <ulink url="https://gitlab.freedesktop.org/bustle/bustle"
>Bustle</ulink
> </para>
            <para
>На перший погляд може здатися, що використання системи Qt DBus Adaptors було б набагато легшим, ніж безпосереднє використання інтерфейсів/повідомлень Qt DBus, і KStars надає необхідні визначення xml. Проте зараз інтенсивно використовуються спеціальні типи, визначення яких поєднуються з іншою інформацією у джерелах KStars. Це призводить до появи великого набору файлів із KStars, які потребують включення до розширення, щоб використовувати Adaptors Qt DBus. Сподіваюся, це буде вирішено в майбутньому. </para>
          </listitem>
        </itemizedlist>
	</sect2>
</sect1>
