<chapter id="id_scripting">
<title
>Написання скриптів</title>

<sect1 id="id_scripting_kile">
<title
>Написання скриптів для &kile;</title>

<para
>Можливості з роботи зі скриптами у &kile; надають змогу виконувати код мовою <ulink url="http://uk.wikipedia.org/wiki/ECMAScript"
>ECMAScript</ulink
>, широко відомою під назвою &javascript;. Знайти підручники щодо об’єктів (змінних), функцій та властивостей, які підтримуються &javascript; доволі просто.</para>

<para
>Підтримку роботи зі скриптами можна увімкнути за допомогою діалогового вікна налаштування &kile;: <menuchoice
><guimenu
>Параметри</guimenu
><guisubmenu
>Налаштувати Kile...</guisubmenu
> <guimenuitem
>Kile</guimenuitem
><guilabel
>Запис скриптів</guilabel
></menuchoice
>. <screenshot>
	<screeninfo
>Вмикання або вимикання підтримки скриптів</screeninfo>
	<mediaobject>
	<imageobject>
	<imagedata fileref="scripting-support.png" format="PNG"/>
	</imageobject>
	<textobject>
		<phrase
>Вмикання або вимикання підтримки скриптів</phrase>
	</textobject>
	</mediaobject>
</screenshot>
</para>

<para
>Якщо увімкнено роботу зі скриптами, на бічній панелі буде показано панель скриптів, за допомогою якої можна керувати скриптами: <screenshot>
	<screeninfo
>Панель скриптів на бічній панелі</screeninfo>
	<mediaobject>
	<imageobject>
	<imagedata fileref="scripting-panel.png" format="PNG"/>
	</imageobject>
	<textobject>
		<phrase
>Панель скриптів на бічній панелі</phrase>
	</textobject>
	</mediaobject>
</screenshot>
</para>

<para
>На цьому віджеті буде розміщено шість піктограм, за допомогою яких можна виконувати різні завдання: <itemizedlist>
<listitem
><para
>Запустити вказаний скрипт.</para
></listitem>
<listitem
><para
>Створити новий скрипт.</para
></listitem>
<listitem
><para
>Відкрити позначений скрипт у редакторі.</para
></listitem>
<listitem
><para
>Налаштувати клавіатурне скорочення для позначеного скрипту.</para
></listitem>
<listitem
><para
>Вилучити призначене клавіатурне скорочення.</para
></listitem>
<listitem
><para
>Оновити список доступних скриптів на основі даних з каталогу <filename
>$<envar
>KDEDIR</envar
>/share/apps/kile/scripts/</filename
>.</para
></listitem>
</itemizedlist>
</para>

</sect1>

<sect1 id="id_execute_script">
<title
>Виконання скрипту</title>

<para
>Виконати скрипт можна у три різних способи:</para>

<procedure>
<step
><para
>Вибрати потрібний скрипт і натиснути кнопку <guilabel
>Виконати</guilabel
>, розташовану у лівій частині віджета керування скриптами.</para>
<screenshot>
	<screeninfo
>Керування скриптами: кнопка виконання</screeninfo>
	<mediaobject>
	<imageobject>
	<imagedata fileref="scripting-execbutton.png" format="PNG"/>
	</imageobject>
	<textobject>
		<phrase
>Керування скриптами: кнопка виконання</phrase>
	</textobject>
	</mediaobject>
</screenshot>
</step>

<step
><para
>Скористатися клавіатурним скороченням.</para>
<screenshot>
	<screeninfo
>Керування скриптами: клавіатурне скорочення</screeninfo>
	<mediaobject>
	<imageobject>
	<imagedata fileref="scripting-shortcut.png" format="PNG"/>
	</imageobject>
	<textobject>
		<phrase
>Керування скриптами: клавіатурне скорочення</phrase>
	</textobject>
	</mediaobject>
</screenshot>
<para
>Ви можете пов’язати зі скриптом певне клавіатурне скорочення за допомогою кнопки <guilabel
>Налаштувати</guilabel
> панелі керування скриптами.</para>
<screenshot>
	<screeninfo
>Робота зі скриптами: вікно налаштування клавіатурного скорочення</screeninfo>
	<mediaobject>
	<imageobject>
	<imagedata fileref="scripting-configure.png" format="PNG"/>
	</imageobject>
	<textobject>
		<phrase
>Робота зі скриптами: вікно налаштування клавіатурного скорочення</phrase>
	</textobject>
	</mediaobject>
</screenshot>
</step>

<step
><para
>Використовувати послідовність символів у редакторі. Скрипт буде виконано, якщо вами буде введено відповідну послідовність символів у вікні редактора.</para>
<screenshot>
	<screeninfo
>Робота зі скриптами: послідовність символів у редакторі</screeninfo>
	<mediaobject>
	<imageobject>
	<imagedata fileref="scripting-keysequence1.png" format="PNG"/>
	</imageobject>
	<textobject>
		<phrase
>Робота зі скриптами: послідовність символів у редакторі</phrase>
	</textobject>
	</mediaobject>
</screenshot>
<para
>Цей метод можна розширити для реалізації додаткових можливостей доповнення коду. Припустімо, ви написали скрипт, який просто додає команду &latex; <userinput
>\textbf{}</userinput
> до поточного документа.</para>

<programlisting
>document.insertText("\\textbf{%C}");
</programlisting>

<para
>Тепер, якщо ви введете призначену послідовність символів, <userinput
>bfx</userinput
> у ваш текстовий документ, цю послідовність символів буде вилучено, а скрипт буде виконано. Скрипт вставить до тексту <userinput
>\textbf{}</userinput
> і розташує курсор між дужками.</para>
<screenshot>
	<screeninfo
>Робота зі скриптами: введення послідовності символів у вікні редактора</screeninfo>
	<mediaobject>
	<imageobject>
	<imagedata fileref="scripting-keysequence2.png" format="PNG"/>
	</imageobject>
	<textobject>
		<phrase
>Робота зі скриптами: введення послідовності символів у вікні редактора</phrase>
	</textobject>
	</mediaobject>
</screenshot>
<para
>Зручний і потужний спосіб доповнення коду.</para>
</step>
</procedure>

</sect1>

<sect1 id="id_scripting_api">
<title
>Довідка з програмного інтерфейсу</title>

<para
>Доступ до програмного інтерфейсу роботи зі скриптами (API), описаний у цьому розділі, можна отримати з будь-якого скрипту. До завантаження вмісту скрипту &kile; додає декілька прототипів та функцій до контексту роботи зі скриптами. Цей зручний програмний інтерфейс містить деякі прототипи, зокрема текстові курсори та визначення діапазонів тексту. Відповідін файли розташовано у теці <filename
>KILE_APP_DIR/script-plugins/</filename
>.</para>

<para
>Скрипти &kile; трохи відрізняються від скриптів <ulink url="http://kate-editor.org"
>&kate;</ulink
>. Останні мають іншу побудову, оскільки їх можна запускати з командного рядка. Але ви можете отримати доступ до всіх функцій програмного інтерфейсу &kate; з програмного інтерфейсу &kile;, отже портування коду &javascript; з &kate; до &kile; має бути доволі простим. Оскільки &kile; має дуже широкі можливості з редагування &latex;, його власний програмний інтерфейс надає доступ до набагато ширших можливостей, ніж інтерфейс &kate;.</para>

<para
><emphasis
>Зауваження:</emphasis
> опис викликів програмного інтерфейсу, які також доступні у &kate; було запозичено з документації до &kate;.</para>


<sect2 id="id_scripting_api_global">
<title
>Загальні функції (Global Functions)</title>

<para
>У цьому розділі наведено загальні функції.</para>

<variablelist
><varlistentry>
<term
><synopsis
>void debug(<parameter
>String <replaceable
>текст</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Виводить <parameter
>текст</parameter
> до <literal
>stdout</literal
> у консоль, з якої запущено програму. Виведений текст має інше розфарбування, щоб його було простіше відрізнити від діагностичних повідомлень. </para
></listitem>
</varlistentry
></variablelist>

</sect2>


<sect2 id="id_scripting_api_cursor">
<title
>Прототип Cursor (курсор)</title>

<para
>Оскільки &kile; є текстовим редактором, весь програмний інтерфейс засновано на роботі з курсором і діапазонами. Тип Cursor є простим кортежем <literal
>(line, column)</literal
> (рядок, позиція), який відповідає певній позиції у тексті документа.</para>

<variablelist
><varlistentry>
<term
><synopsis
>Cursor();
</synopsis
></term>
<listitem
><para
>Конструктор. Повертає об’єкт Cursor (курсор) у позиції <literal
>(0, 0)</literal
>. </para
><para
>Приклад: <function
>var cursor = new Cursor();</function
></para>
</listitem>
</varlistentry
></variablelist>

<variablelist
><varlistentry>
<term
><synopsis
>Cursor(<parameter
>int <replaceable
>рядок</replaceable
></parameter
>, <parameter
>int <replaceable
>стовпчик</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Конструктор Повертає об’єкт Cursor (курсор) у позиції (рядок, стовпчик). </para
><para
>Приклад: <function
>var cursor = new Cursor(3,42);</function
> </para
></listitem>
</varlistentry
></variablelist>

<variablelist
><varlistentry>
<term
><synopsis
>Cursor(<parameter
>Cursor <replaceable
>інший</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Конструктор копіювання Повертає копію курсора <parameter
>інший</parameter
>. </para
><para
>Приклад: <function
>var copy = new Cursor(other);</function
> </para
></listitem>
</varlistentry
></variablelist>

<variablelist
><varlistentry>
<term
><synopsis
>Cursor Cursor.clone();
</synopsis
></term>
<listitem
><para
>Повертає клон курсора. </para
><para
>Приклад: <function
>var clone = cursor.clone();</function
> </para
></listitem>
</varlistentry
></variablelist>

<variablelist
><varlistentry>
<term
><synopsis
>bool Cursor.isValid();
</synopsis
></term>
<listitem
><para
>Перевіряє, чи є курсор коректним. Курсор вважається некоректним, якщо значення його позицій у рядку і/або стовпчику дорівнюють <literal
>-1</literal
>. </para
><para
>Приклад: <function
>var valid = cursor.isValid();</function
> </para
></listitem>
</varlistentry
></variablelist>

<variablelist
><varlistentry>
<term
><synopsis
>Cursor Cursor.invalid();
</synopsis
></term>
<listitem
><para
>Повертає новий некоректний курсор, розташований у позиції <literal
>(-1,-1)</literal
>. </para
><para
>Приклад: <function
>var invalidCursor = cursor.invalid();</function
> </para
></listitem>
</varlistentry
></variablelist>

<variablelist
><varlistentry>
<term
><synopsis
>int Cursor.compareTo(<parameter
>Cursor <replaceable
>інший</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Порівнює поточний курсор з курсором <parameter
>інший</parameter
>. Повертає <itemizedlist>
<listitem
><para
><literal
>-1</literal
>, якщо поточний курсор розташовано перед курсором <parameter
>інший</parameter
>,</para
></listitem>
<listitem
><para
><literal
>0</literal
>, якщо курсори у однакових позиціях і</para
></listitem>
<listitem
><para
><literal
>+1</literal
>, якщо поточний курсор розташовано після курсора <parameter
>інший</parameter
>.</para
></listitem>
</itemizedlist>
</para
></listitem>
</varlistentry
></variablelist>

<variablelist
><varlistentry>
<term
><synopsis
>bool Cursor.equals(<parameter
>Cursor <replaceable
>інший</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Повертає <literal
>true</literal
>, якщо цей курсор і курсор <parameter
>інший</parameter
> є однаковими. Якщо це не так, повертає <literal
>false</literal
>. </para
></listitem>
</varlistentry
></variablelist>

<variablelist
><varlistentry>
<term
><synopsis
>String Cursor.toString();
</synopsis
></term>
<listitem
><para
>Повертає об’єкт курсора як рядок у формі <literal
>Cursor(line, column)</literal
>. </para
></listitem>
</varlistentry
></variablelist>

</sect2>


<sect2 id="id_scripting_api_range">
<title
>Прототип Range (діапазон)</title>

<para
>Оскільки &kate; є текстовим редактором, весь програмний інтерфейс (API) за можливості засновано на курсорах та діапазонах тексту Об’єкт Cursor (курсор) є простим кортежем <literal
>(line, column)</literal
> (рядок, стовпчик), що визначає позицію у тексті документа. Об’єкт Range (діапазон) це фрагмент тексту від початкової позиції курсора до кінцевої позиції курсора.</para>

<variablelist
><varlistentry>
<term
><synopsis
>Range();
</synopsis
></term>
<listitem
><para
>Конструктор: виклик <literal
>new Range()</literal
> повертає Range (діапазон) у <literal
>(0, 0) - (0, 0)</literal
>. </para
></listitem>
</varlistentry
></variablelist>

<variablelist
><varlistentry>
<term
><synopsis
>Range(<parameter
>Cursor <replaceable
>початок</replaceable
></parameter
>, <parameter
>Cursor <replaceable
>кінець</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Конструктор Виклик функції <literal
>new Range(<replaceable
>початок</replaceable
>, <replaceable
>кінець</replaceable
>)</literal
> повертає Range (діапазон)(<parameter
>початок</parameter
>, <parameter
>кінець</parameter
>). </para
></listitem>
</varlistentry
></variablelist>

<variablelist
><varlistentry>
<term
><synopsis
>Range(<parameter
>int <replaceable
>початковийРядок</replaceable
></parameter
>, <parameter
>int <replaceable
>початковийСтовпчик</replaceable
></parameter
>, <parameter
>int <replaceable
>кінцевийРядок</replaceable
></parameter
>, <parameter
>int <replaceable
>кінцевийСтовпчик</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Конструктор Виклик функції <literal
>new Range(<replaceable
>початковийРядок</replaceable
>, <replaceable
>початковийСтовпчик</replaceable
>, <replaceable
>кінцевийРядок</replaceable
>, <replaceable
>кінцевийСтовпчик</replaceable
>)</literal
> повертає Range (діапазон) від позиції (<replaceable
>початковийРядок</replaceable
>, <replaceable
>початковийСтовпчик</replaceable
>) до позиції (<replaceable
>кінцевийРядок</replaceable
>, <replaceable
>кінцевийСтовпчик</replaceable
>). </para
></listitem>
</varlistentry
></variablelist>

<variablelist
><varlistentry>
<term
><synopsis
>Range(<parameter
>Range <replaceable
>інший</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Конструктор копіювання. Повертає копію Range <literal
>інший</literal
>. </para
></listitem>
</varlistentry
></variablelist>

<variablelist
><varlistentry>
<term
><synopsis
>Range Range.clone();
</synopsis
></term>
<listitem
><para
>Повертає клон діапазону. </para
><para
>Приклад: <function
>var clone = range.clone();</function
> </para
></listitem>
</varlistentry
></variablelist>

<variablelist
><varlistentry>
<term
><synopsis
>bool Range.isValid();
</synopsis
></term>
<listitem
><para
>Повертає <literal
>true</literal
>, якщо початкова і кінцева позиції курсора є коректними. Якщо це не так, повертає <literal
>false</literal
>. </para
><para
>Приклад: <function
>var valid = range.isValid();</function
> </para
></listitem>
</varlistentry
></variablelist>

<variablelist
><varlistentry>
<term
><synopsis
>bool Range.invalid();
</synopsis
></term>
<listitem
><para
>Повертає Range (діапазон) від (-1,-1) до (-1,-1). </para
></listitem>
</varlistentry
></variablelist>

<variablelist
><varlistentry>
<term
><synopsis
>bool Range.contains(<parameter
>Cursor <replaceable
>курсор</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Повертає <literal
>true</literal
>, якщо позиція курсора міститься у діапазоні, у іншому випадку повертає <constant
>false</constant
>. </para
></listitem>
</varlistentry
></variablelist>

<variablelist
><varlistentry>
<term
><synopsis
>bool Range.contains(<parameter
>Range <replaceable
>інший</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Повертає <literal
>true</literal
>, якщо поточний діапазон містить діапазон <parameter
>інший</parameter
>. Якщо це не так, повертає <literal
>false</literal
>. </para
></listitem>
</varlistentry
></variablelist>

<variablelist
><varlistentry>
<term
><synopsis
>bool Range.containsColumn(<parameter
>int <replaceable
>стовпчик</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Повертає <literal
>true</literal
>, якщо <parameter
>стовпчик</parameter
> належить напіввідкритому інтервалу <literal
>[start.column, end.column)</literal
>. Якщо це не так, повертає <literal
>false</literal
>. </para
></listitem>
</varlistentry
></variablelist>

<variablelist
><varlistentry>
<term
><synopsis
>bool Range.containsLine(<parameter
>int <replaceable
>рядок</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Повертає <literal
>true</literal
>, якщо <parameter
>рядок</parameter
> належить до напіввідкритого інтервалу <literal
>[start.line, end.line)</literal
>. Якщо це не так, повертає <literal
>false</literal
>. </para
></listitem>
</varlistentry
></variablelist>

<variablelist
><varlistentry>
<term
><synopsis
>bool Range.overlaps(<parameter
>Range <replaceable
>інший</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Повертає <literal
>true</literal
>, якщо поточний діапазон і діапазон <replaceable
>інший</replaceable
> мають ненульовий перетин. Якщо це не так, повертає <literal
>false</literal
>. </para
></listitem>
</varlistentry
></variablelist>

<variablelist
><varlistentry>
<term
><synopsis
>bool Range.overlapsLine(<parameter
>int <replaceable
>рядок</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Повертає <literal
>true</literal
>, якщо <replaceable
>рядок</replaceable
> належить до інтервалу <literal
>[start.line, end.line]</literal
>. Якщо це не так, повертає <literal
>false</literal
>. </para
></listitem>
</varlistentry
></variablelist>

<variablelist
><varlistentry>
<term
><synopsis
>bool Range.overlapsColumn(<parameter
>int <replaceable
>стовпчик</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Повертає <literal
>true</literal
>, якщо <replaceable
>стовпчик</replaceable
> належить інтервалу <literal
>[start.column, end.column]</literal
>. Якщо це не так, повертає <literal
>false</literal
>. </para
></listitem>
</varlistentry
></variablelist>

<variablelist
><varlistentry>
<term
><synopsis
>bool Range.equals(<parameter
>Range <replaceable
>інший</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Повертає <literal
>true</literal
>, якщо поточний діапазон і діапазон <replaceable
>інший</replaceable
> тотожні. Якщо це не так, повертає <literal
>false</literal
>. </para
></listitem>
</varlistentry
></variablelist>

<variablelist
><varlistentry>
<term
><synopsis
>String Range.toString();
</synopsis
></term>
<listitem
><para
>Повертає діапазон у форматі <literal
>Range(Cursor(line, column), Cursor(line, column))</literal
>. </para
></listitem>
</varlistentry
></variablelist>

</sect2>


<sect2 id="id_scripting_api_view">
<title
>Програмний інтерфейс <classname
>View</classname
></title>

<para
>Під час виконання кожного скрипту використовується загальний об’єкт (змінна) <userinput
>view</userinput
>, яка відповідає поточній активній панелі редактора. Всі функції <literal
>view</literal
> працюють з розташуваннями курсора або позначеним фрагментом тексту. Нижче наведено список всіх доступних функцій <userinput
>view</userinput
>.</para>

<variablelist
><varlistentry>
<term
><synopsis
>void view.backspace();
</synopsis
></term>
<listitem
><para
>Програмний еквівалент натискання клавіші Backspace. </para
></listitem>
</varlistentry
></variablelist>

<variablelist
><varlistentry>
<term
><synopsis
>Cursor view.cursorPosition();
</synopsis
></term>
<listitem
><para
>Повертає поточну позицію курсора у області перегляду. </para
></listitem>
</varlistentry
></variablelist>

<variablelist
><varlistentry>
<term
><synopsis
>void view.setCursorPosition(<parameter
>int <replaceable
>рядок</replaceable
></parameter
>, <parameter
>int <replaceable
>стовпчик</replaceable
></parameter
>);
void view.setCursorPosition(<parameter
>Cursor <replaceable
>курсор</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Встановлює для поточного курсора позицію, вказану напряму (<parameter
>рядок</parameter
>, <parameter
>стовпчик</parameter
>), або позицію вказаного <parameter
>курсора</parameter
>. </para
></listitem>
</varlistentry
></variablelist>

<variablelist
><varlistentry>
<term
><synopsis
>void view.cursorLeft();
</synopsis
></term>
<listitem
><para
>Пересуває курсор на одну позицію назад текстом. </para
></listitem>
</varlistentry
></variablelist>

<variablelist
><varlistentry>
<term
><synopsis
>void view.cursorRight();
</synopsis
></term>
<listitem
><para
>Пересуває курсор на одну позицію вперед текстом. </para
></listitem>
</varlistentry
></variablelist>

<variablelist
><varlistentry>
<term
><synopsis
>void view.cursorUp();
</synopsis
></term>
<listitem
><para
>Пересуває курсор у документі на один рядок вгору. </para
></listitem>
</varlistentry
></variablelist>

<variablelist
><varlistentry>
<term
><synopsis
>void view.cursorDown();
</synopsis
></term>
<listitem
><para
>Пересуває курсор у документі на один рядок вниз. </para
></listitem>
</varlistentry
></variablelist>

<variablelist
><varlistentry>
<term
><synopsis
>int view.cursorLine();
</synopsis
></term>
<listitem
><para
>Повертає номер рядка, у якому зараз перебуває курсор. </para
></listitem>
</varlistentry
></variablelist>

<variablelist
><varlistentry>
<term
><synopsis
>int view.cursorColumn();
</synopsis
></term>
<listitem
><para
>Повертає номер позиції у рядку, у якій зараз перебуває курсор. </para
></listitem>
</varlistentry
></variablelist>

<variablelist
><varlistentry>
<term
><synopsis
>void view.setCursorLine(<parameter
>int <replaceable
>рядок</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Переводить курсор у вказаний <parameter
>рядок</parameter
>. </para
></listitem>
</varlistentry
></variablelist>

<variablelist
><varlistentry>
<term
><synopsis
>void view.setCursorColumn(<parameter
>int <replaceable
>стовпчик</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Переводить курсор у вказану позицію у рядку <parameter
>стовпчик</parameter
>. </para
></listitem>
</varlistentry
></variablelist>

<variablelist
><varlistentry>
<term
><synopsis
>Cursor view.virtualCursorPosition();
</synopsis
></term>
<listitem
><para
>Отримати поточну <emphasis
>віртуальну</emphasis
> позицію курсора. <emphasis
>Віртуальна</emphasis
> означає, що символи табуляції вважаються <emphasis
>декількома</emphasis
> символами, відповідно до налаштувань, визначених користувачем (наприклад, один символ табуляції може відповідати 8 пробілам). За допомогою віртуальної позиції курсора можна отримати доступ до видимих користувачеві значень поточного розташування курсора. </para
></listitem>
</varlistentry
></variablelist>

<variablelist
><varlistentry>
<term
><synopsis
>bool view.hasSelection();
</synopsis
></term>
<listitem
><para
>Повертає <literal
>true</literal
>, якщо у області перегляду позначено фрагмент тексту, інакше повертає <literal
>false</literal
>. </para
></listitem>
</varlistentry
></variablelist>

<variablelist
><varlistentry>
<term
><synopsis
>String view.selectedText();
</synopsis
></term>
<listitem
><para
>Повертає позначений фрагмент тексту. Якщо жодного фрагменту не позначено, повертає порожній рядок. </para
></listitem>
</varlistentry
></variablelist>

<variablelist
><varlistentry>
<term
><synopsis
>Range view.selectionRange();
</synopsis
></term>
<listitem
><para
>Повертає діапазон позначеного фрагменту тексту. Якщо жодного фрагменту не позначено, буде повернуто некоректний діапазон. </para
></listitem>
</varlistentry
></variablelist>

<variablelist
><varlistentry>
<term
><synopsis
>void view.setSelection(<parameter
>Range <replaceable
>діапазон</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Встановлює позначення тексту за вказаним <parameter
>діапазоном</parameter
>. </para
></listitem>
</varlistentry
></variablelist>

<variablelist
><varlistentry>
<term
><synopsis
>void view.selectAll();
</synopsis
></term>
<listitem
><para
>Позначає весь текст у документі. </para
></listitem>
</varlistentry
></variablelist>

<variablelist
><varlistentry>
<term
><synopsis
>void view.clearSelection();
</synopsis
></term>
<listitem
><para
>Знімає позначення фрагменту тексту, не вилучаючи сам текст. </para
></listitem>
</varlistentry
></variablelist>

<variablelist
><varlistentry>
<term
><synopsis
>void view.removeSelectedText();
</synopsis
></term>
<listitem
><para
>Вилучає позначений текст. Якщо у області перегляду не було позначено жодного тексту, ніяких дій виконано не буде. </para
></listitem>
</varlistentry
></variablelist>

<variablelist
><varlistentry>
<term
><synopsis
>void view.selectLine();
</synopsis
></term>
<listitem
><para
>Позначає текст у поточному рядку. </para
></listitem>
</varlistentry
></variablelist>

<variablelist
><varlistentry>
<term
><synopsis
>void view.selectLine(<parameter
>int <replaceable
>рядок</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Позначає текст у вказаному <parameter
>рядку</parameter
>. </para
></listitem>
</varlistentry
></variablelist>

<variablelist
><varlistentry>
<term
><synopsis
>void view.selectLines(<parameter
>int <replaceable
>з</replaceable
></parameter
>, <parameter
>int <replaceable
>до</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Позначає весь текст з рядка <parameter
>з</parameter
> до рядка <parameter
>до</parameter
>. </para
></listitem>
</varlistentry
></variablelist>

<variablelist
><varlistentry>
<term
><synopsis
>void view.selectWord();
</synopsis
></term>
<listitem
><para
>Позначає поточне слово. Якщо у поточній позиції курсора немає ніяких слів, нічого не позначається. </para
></listitem>
</varlistentry
></variablelist>

<variablelist
><varlistentry>
<term
><synopsis
>void view.selectLatexCommand();
</synopsis
></term>
<listitem
><para
>Позначає поточну команду &latex;. Якщо у позиції курсора немає ніяких команд, нічого не позначається. </para
></listitem>
</varlistentry
></variablelist>

<variablelist
><varlistentry>
<term
><synopsis
>void view.selectEnvironment(<parameter
>bool <replaceable
>всередині = false</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Позначає весь текст у поточному середовищі &latex;. Якщо параметр <parameter
>всередині</parameter
> має значення <literal
>false</literal
>, буде позначено текст середовища разом з зовнішніми командами визначення &latex;, <userinput
>\begin{...}...\end{...}</userinput
>. Якщо ж це не так, буде позначено текст без команд визначення. Якщо функції не буде передано параметра, вважатиметься, що значенням параметра <parameter
>всередині</parameter
> є <literal
>false</literal
>. </para
></listitem>
</varlistentry
></variablelist>

<variablelist
><varlistentry>
<term
><synopsis
>void view.selectTexgroup(<parameter
>bool <replaceable
>всередині = true</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Позначає поточну групу &latex;. Якщо параметр <parameter
>всередині</parameter
> має значення <literal
>true</literal
>, буде позначено групу TeX без зовнішніх дужок. Якщо не буде вказано ніякого значення параметра<parameter
>всередині</parameter
>, вважатиметься, що параметр має значення <literal
>true</literal
>. </para
></listitem>
</varlistentry
></variablelist>

<variablelist
><varlistentry>
<term
><synopsis
>void view.selectMathgroup();
</synopsis
></term>
<listitem
><para
>Позначає текст поточної формульної групи. </para
></listitem>
</varlistentry
></variablelist>

<variablelist
><varlistentry>
<term
><synopsis
>void view.selectParagraph(bool всіРядки = true);
</synopsis
></term>
<listitem
><para
>Позначає весь текст у поточному абзаці &latex;. Якщо параметр <parameter
>всіРядки</parameter
> має значення <literal
>true</literal
>, до позначення буде включено перший і останній рядки абзацу повністю (разом з символом кінця рядка). Якщо для параметра буде визначено значення <literal
>false</literal
>, до позначеного фрагмента буде включено лише непробільні символи. </para
></listitem>
</varlistentry
></variablelist>

</sect2>


<sect2 id="id_scripting_api_document">
<title
>Програмний інтерфейс (API) <classname
>Document</classname
></title>

<para
>Під час виконання кожного скрипту використовується загальний об’єкт (змінна) <userinput
>document</userinput
>, що відповідає поточному активному документу. Нижче наведено список всіх доступних функцій <userinput
>document</userinput
>.</para>

<variablelist
><varlistentry>
<term
><synopsis
>void document.insertText(<parameter
>String <replaceable
>текст</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Вставляє <parameter
>текст</parameter
> у поточну позицію курсора. </para
></listitem>
</varlistentry
></variablelist>

<variablelist
><varlistentry>
<term
><synopsis
>void document.insertText(<parameter
>int <replaceable
>рядок</replaceable
></parameter
>, <parameter
>int <replaceable
>стовпчик</replaceable
></parameter
>, <parameter
>String <replaceable
>текст</replaceable
></parameter
>);
void document.insertText(<parameter
>Cursor <replaceable
>курсор</replaceable
></parameter
>, <parameter
>String <replaceable
>текст</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Вставляє <parameter
>текст</parameter
> у вказану позицію курсора. </para
></listitem>
</varlistentry
></variablelist>

<variablelist
><varlistentry>
<term
><synopsis
>bool document.removeText(<parameter
>int <replaceable
>зРядка</replaceable
></parameter
>, <parameter
>int <replaceable
>зіСтовпчика</replaceable
></parameter
>, <parameter
>int <replaceable
>доРядка</replaceable
></parameter
>, <parameter
>int <replaceable
>доСтовпчика</replaceable
></parameter
>);
bool document.removeText(<parameter
>Cursor <replaceable
>з</replaceable
></parameter
>, <parameter
>Cursor <replaceable
>до</replaceable
></parameter
>);
bool document.removeText(<parameter
>Range <replaceable
>діапазон</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Вилучає текст у вказаному діапазоні. Повертає <literal
>true</literal
> у разі успіху або <literal
>false</literal
>, якщо документ відкрито у режимі лише для читання. </para
></listitem>
</varlistentry
></variablelist>

<variablelist
><varlistentry>
<term
><synopsis
>bool document.replaceText(<parameter
>Range <replaceable
>діапазон</replaceable
></parameter
>, <parameter
>String <replaceable
>текст</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Замінити текст у вказаному діапазоні вказаним текстом. </para
></listitem>
</varlistentry
></variablelist>

<variablelist
><varlistentry>
<term
><synopsis
>int document.lines();
</synopsis
></term>
<listitem
><para
>Повертає кількість рядків у документі. </para
></listitem>
</varlistentry
></variablelist>

<variablelist
><varlistentry>
<term
><synopsis
>int document.length();
</synopsis
></term>
<listitem
><para
>Повертає кількість символів у документі. </para
></listitem>
</varlistentry
></variablelist>

<variablelist
><varlistentry>
<term
><synopsis
>Range document.documentRange();
</synopsis
></term>
<listitem
><para
>Повертає діапазон всього документа. </para
></listitem>
</varlistentry
></variablelist>

<variablelist
><varlistentry>
<term
><synopsis
>Cursor document.documentEnd();
</synopsis
></term>
<listitem
><para
>Повертає поточну позицію кінця документа. </para
></listitem>
</varlistentry
></variablelist>

<variablelist
><varlistentry>
<term
><synopsis
>String document.text();
</synopsis
></term>
<listitem
><para
>Повертає увесь вміст документа у формі єдиного рядка тексту. Розриви рядків буде позначено символом розриву рядка, <literal
>\n</literal
>. </para
></listitem>
</varlistentry
></variablelist>

<variablelist
><varlistentry>
<term
><synopsis
>String document.text(<parameter
>int <replaceable
>зРядка</replaceable
></parameter
>, <parameter
>int <replaceable
>зіСтовпчика</replaceable
></parameter
>, <parameter
>int <replaceable
>доРядка</replaceable
></parameter
>, <parameter
>int <replaceable
>доСтовпчика</replaceable
></parameter
>);
String document.text(<parameter
>Cursor <replaceable
>з</replaceable
></parameter
>, <parameter
>Cursor <replaceable
>до</replaceable
></parameter
>);
String document.text(<parameter
>Range <replaceable
>діапазон</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Повертає фрагмент тексту у вказаному діапазоні. Для того, щоб код було легше читати, ми рекомендуємо вам використовувати засновану на об’єктах Cursor і Range версію функції. </para
></listitem>
</varlistentry
></variablelist>

<variablelist
><varlistentry>
<term
><synopsis
>bool document.setText(<parameter
>String <replaceable
>текст</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Замінює весь вміст документа на <parameter
>текст</parameter
>. </para
></listitem>
</varlistentry
></variablelist>

<variablelist
><varlistentry>
<term
><synopsis
>bool document.clear();
</synopsis
></term>
<listitem
><para
>Вилучає з документа весь текст. </para
></listitem>
</varlistentry
></variablelist>

<variablelist
><varlistentry>
<term
><synopsis
>String document.line();
</synopsis
></term>
<listitem
><para
>Повертає поточний рядок у форматі String. </para
></listitem>
</varlistentry
></variablelist>

<variablelist
><varlistentry>
<term
><synopsis
>String document.line(<parameter
>int <replaceable
>рядок</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Повертає рядок за його номером у тексті. Якщо вказаний номер не належатиме до діапазону номерів рядків документа, буде повернуто порожній рядок. </para
></listitem>
</varlistentry
></variablelist>

<variablelist
><varlistentry>
<term
><synopsis
>int document.lineLength();
</synopsis
></term>
<listitem
><para
>Повертає довжину поточного рядка. </para
></listitem>
</varlistentry
></variablelist>

<variablelist
><varlistentry>
<term
><synopsis
>int document.lineLength(<parameter
>int <replaceable
>рядок</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Повертає довжину рядка з номером <parameter
>рядок</parameter
>. </para
></listitem>
</varlistentry
></variablelist>

<variablelist
><varlistentry>
<term
><synopsis
>bool document.insertLine(<parameter
>String <replaceable
>рядок</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Вставляє поточний фрагмент тексту до рядка з вказаним номером. Повертає <literal
>true</literal
> у разі успіху або <literal
>false</literal
>, якщо документ відкрито у режимі лише для читання або рядка з вказаним номером у документі немає. </para
></listitem>
</varlistentry
></variablelist>

<variablelist
><varlistentry>
<term
><synopsis
>bool document.insertLine(<parameter
>int <replaceable
>рядок</replaceable
></parameter
>, <parameter
>String <replaceable
>текст</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Вставляє вказаний фрагмент тексту до рядка з вказаним номером. Повертає <literal
>true</literal
> у разі успіху або <literal
>false</literal
>, якщо документ відкрито у режимі лише для читання або рядка з вказаним номером у документі немає. </para
></listitem>
</varlistentry
></variablelist>

<variablelist
><varlistentry>
<term
><synopsis
>bool document.removeLine();
</synopsis
></term>
<listitem
><para
>Вилучає текст поточного рядка. Повертає <literal
>true</literal
> у разі успіху або <literal
>false</literal
>, якщо документ відкрито у режимі лише для читання. </para
></listitem>
</varlistentry
></variablelist>

<variablelist
><varlistentry>
<term
><synopsis
>bool document.removeLine(<parameter
>int <replaceable
>рядок</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Вилучає рядок з вказаним номером. Повертає <literal
>true</literal
> у разі успіху або <literal
>false</literal
>, якщо документ відкрито у режимі лише для читання або рядка з вказаним номером у документі немає. </para
></listitem>
</varlistentry
></variablelist>

<variablelist
><varlistentry>
<term
><synopsis
>bool document.replaceLine(<parameter
>String <replaceable
>текст</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Замінити текст поточного рядка вказаним текстом. </para
></listitem>
</varlistentry
></variablelist>

<variablelist
><varlistentry>
<term
><synopsis
>bool document.replaceLine(<parameter
>int <replaceable
>рядок</replaceable
></parameter
>, <parameter
>String <replaceable
>текст</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Замінити текст у вказаному рядку вказаним текстом. </para
></listitem>
</varlistentry
></variablelist>

<variablelist
><varlistentry>
<term
><synopsis
>bool document.truncateLine();
</synopsis
></term>
<listitem
><para
>Обрізає поточний рядок на вказаному стовпчику або позиції курсора. Повертає <literal
>true</literal
> у разі успіху або <literal
>false</literal
>, якщо рядка з вказаним номером у документі немає. </para
></listitem>
</varlistentry
></variablelist>

<variablelist
><varlistentry>
<term
><synopsis
>bool document.truncate(<parameter
>int <replaceable
>рядок</replaceable
></parameter
>, <parameter
>int <replaceable
>стовпчик</replaceable
></parameter
>);
bool document.truncate(<parameter
>Cursor <replaceable
>курсор</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Обрізає рядок з вказаним номером на вказаному стовпчику або позиції курсора. Повертає <literal
>true</literal
> у разі успіху або <literal
>false</literal
>, якщо рядка з вказаним номером у документі немає. </para
></listitem>
</varlistentry
></variablelist>

<variablelist
><varlistentry>
<term
><synopsis
>String document.word();
</synopsis
></term>
<listitem
><para
>Повертає слово у поточній позиції курсора. Якщо у поточній позиції немає слів, повернутий рядок буде порожнім. </para
></listitem>
</varlistentry
></variablelist>

<variablelist
><varlistentry>
<term
><synopsis
>String document.wordAt(<parameter
>int <replaceable
>рядок</replaceable
></parameter
>, <parameter
>int <replaceable
>стовпчик</replaceable
></parameter
>);
String document.wordAt(<parameter
>Cursor <replaceable
>курсор</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Повертає слово у вказаній позиції курсора. Якщо у поточній позиції немає слів, повернутий рядок буде порожнім. </para
></listitem>
</varlistentry
></variablelist>

<variablelist
><varlistentry>
<term
><synopsis
>Range document.wordRange();
</synopsis
></term>
<listitem
><para
>Повертає діапазон слова у поточній позиції курсора. Якщо у поточній позиції курсора немає жодних слів, буде повернуто значення <literal
>Range.invalid()</literal
>. Перевірку на коректність можна виконати за допомогою функції <literal
>Range.isValid()</literal
>. </para
></listitem>
</varlistentry
></variablelist>

<variablelist
><varlistentry>
<term
><synopsis
>String document.latexCommand();
</synopsis
></term>
<listitem
><para
>Повертає команду &latex; у поточній позиції курсора. Якщо у поточній позиції немає команд, повернутий рядок буде порожнім. </para
></listitem>
</varlistentry
></variablelist>

<variablelist
><varlistentry>
<term
><synopsis
>String document.latexCommandAt(<parameter
>int <replaceable
>рядок</replaceable
></parameter
>, <parameter
>int <replaceable
>стовпчик</replaceable
></parameter
>);
String document.latexCommandAt(<parameter
>Cursor <replaceable
>курсор</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Повертає команду &latex; у вказаній позиції курсора. Якщо у поточній позиції немає команд, повернутий рядок буде порожнім. </para
></listitem>
</varlistentry
></variablelist>

<variablelist
><varlistentry>
<term
><synopsis
>Range document.latexCommandRange();
</synopsis
></term>
<listitem
><para
>Повертає діапазон команди &latex; у поточній позиції курсора. Якщо у поточній позиції курсора немає жодних команд &latex;, буде повернуто значення <literal
>Range.invalid()</literal
>. Перевірку на коректність можна виконати за допомогою функції <literal
>Range.isValid()</literal
>. </para
></listitem>
</varlistentry
></variablelist>

<variablelist
><varlistentry>
<term
><synopsis
>String document.charAt(<parameter
>int <replaceable
>рядок</replaceable
></parameter
>, <parameter
>int <replaceable
>стовпчик</replaceable
></parameter
>);
String document.charAt(<parameter
>Cursor <replaceable
>курсор</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Повертає символ за вказаною позицією курсора. </para
></listitem>
</varlistentry
></variablelist>

<variablelist
><varlistentry>
<term
><synopsis
>String document.firstChar(<parameter
>int <replaceable
>рядок</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Повертає перший символ вказаного рядка <parameter
>рядок</parameter
>, який не є пробілом. Першим символом рядка вважається символ у стовпчику 0. Якщо рядок є порожнім або складається лише з пробілів, функція повертає порожній рядок. </para
></listitem>
</varlistentry
></variablelist>

<variablelist
><varlistentry>
<term
><synopsis
>String document.lastChar(<parameter
>int <replaceable
>рядок</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Повертає останній символ вказаного рядка <parameter
>рядок</parameter
>, який не є пробілом. Якщо рядок є порожнім або складається лише з пробілів, функція повертає порожній рядок. </para
></listitem>
</varlistentry
></variablelist>

<variablelist
><varlistentry>
<term
><synopsis
>bool document.isSpace(<parameter
>int <replaceable
>рядок</replaceable
></parameter
>, <parameter
>int <replaceable
>стовпчик</replaceable
></parameter
>);
bool document.isSpace(<parameter
>Cursor <replaceable
>курсор</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Повертає <literal
>true</literal
>, якщо символ у вказаній позиції курсора є пробілом. Якщо це не так, повертає <literal
>false</literal
>. </para
></listitem>
</varlistentry
></variablelist>

<variablelist
><varlistentry>
<term
><synopsis
>void document.insertBullet();
</synopsis
></term>
<listitem
><para
>Вставити <emphasis
>позначку</emphasis
> &kile;. Між такими позначками доволі просто пересуватися. Крім того, позначку буде позначено, отже її буде автоматично вилучено, щойно користувач введе першу літеру замінника цієї позначки у документі. </para
></listitem>
</varlistentry
></variablelist>

<variablelist
><varlistentry>
<term
><synopsis
>void document.nextBullet();
</synopsis
></term>
<listitem
><para
>Перейти до наступної позначки у тексті, якщо така є. </para
></listitem>
</varlistentry
></variablelist>

<variablelist
><varlistentry>
<term
><synopsis
>void document.previousBullet();
</synopsis
></term>
<listitem
><para
>Перейти до попередньої позначки у тексті, якщо така є. </para
></listitem>
</varlistentry
></variablelist>

<variablelist
><varlistentry>
<term
><synopsis
>bool document.hasEnvironment();
</synopsis
></term>
<listitem
><para
>Повертає <literal
>true</literal
>, якщо було знайдено зовнішнє середовище &latex;. Якщо середовища не було знайдено, повертає <literal
>false</literal
>. </para
></listitem>
</varlistentry
></variablelist>

<variablelist
><varlistentry>
<term
><synopsis
>String document.environment(<parameter
>bool <replaceable
>всередині = false</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Повертає весь текст зовнішнього середовища &latex;. Якщо для параметра <parameter
>всередині</parameter
> встановлено значення <literal
>false</literal
>, до тексту середовища буде включено зовнішні команди визначення &latex;, <userinput
>\begin{...}...\end{...}</userinput
>. У протилежному випадку буде повернуто текст без команд визначення. Якщо ніякого значення параметру не буде передано, вважатиметься, що <parameter
>всередині</parameter
> має значення <literal
>false</literal
>. Якщо середовища не буде знайдено, повернутий рядок буде порожнім. </para
></listitem>
</varlistentry
></variablelist>

<variablelist
><varlistentry>
<term
><synopsis
>Range document.environmentRange(<parameter
>bool <replaceable
>всередині = false</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Повертає весь текст зовнішнього середовища &latex;. Якщо для параметра <parameter
>всередині</parameter
> встановлено значення <literal
>false</literal
>, до тексту середовища буде включено зовнішні команди визначення &latex;, <userinput
>\begin{...}...\end{...}</userinput
>. У протилежному випадку буде повернуто текст без команд визначення. Якщо ніякого значення параметру не буде передано, вважатиметься, що <parameter
>всередині</parameter
> має значення <literal
>false</literal
>. Якщо середовища не буде знайдено, буде повернуто <literal
>Range.invalid()</literal
>. Перевірити це можна за допомогою функції <literal
>Range.isValid()</literal
>. </para
></listitem>
</varlistentry
></variablelist>

<variablelist
><varlistentry>
<term
><synopsis
>String document.environmentName();
</synopsis
></term>
<listitem
><para
>Повертає назву зовнішнього середовища &latex; або порожній рядок. </para
></listitem>
</varlistentry
></variablelist>

<variablelist
><varlistentry>
<term
><synopsis
>void document.removeEnvironment(<parameter
>bool <replaceable
>всередині = false</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Вилучає текст у зовнішньому середовищі &latex;. Якщо параметр <parameter
>всередині</parameter
> має значення <literal
>true</literal
>, буде вилучено текст середовища разом з зовнішніми командами визначення &latex;, <userinput
>\begin{...}...\end{...}</userinput
>. Якщо ж це не так, буде вилучено текст без команд визначення. Якщо функції не буде передано параметра, вважатиметься, що значенням параметра <parameter
>всередині</parameter
> є <literal
>false</literal
>. </para
></listitem>
</varlistentry
></variablelist>

<variablelist
><varlistentry>
<term
><synopsis
>void document.closeEnvironment();
</synopsis
></term>
<listitem
><para
>Вставити команду завершення середовища, якщо у поточній позиції курсора було виявлено незавершене середовище &latex;. </para
></listitem>
</varlistentry
></variablelist>

<variablelist
><varlistentry>
<term
><synopsis
>void document.closeAllEnvironments();
</synopsis
></term>
<listitem
><para
>Вставити команди завершення всіх незавершених середовищ &latex;, які буде виявлено у поточній позиції курсора. </para
></listitem>
</varlistentry
></variablelist>

<variablelist
><varlistentry>
<term
><synopsis
>bool document.hasTexgroup();
</synopsis
></term>
<listitem
><para
>Повертає <literal
>true</literal
>, якщо у поточній позиції курсора було виявлено зовнішню групу &latex;. Якщо такої групи не було виявлено, повертає <literal
>false</literal
>. </para
></listitem>
</varlistentry
></variablelist>

<variablelist
><varlistentry>
<term
><synopsis
>String document.texgroup(<parameter
>bool <replaceable
>всередині = true</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Повертає весь текст зовнішньої групи &latex;. Якщо для параметра <parameter
>всередині</parameter
> встановлено значення <literal
>false</literal
>, до тексту середовища буде включено зовнішні дужки, <userinput
>{...}</userinput
>. У протилежному випадку буде повернуто текст без команд визначення. Якщо ніякого значення параметру не буде передано, вважатиметься, що <parameter
>всередині</parameter
> має значення <literal
>false</literal
>. Якщо групи &latex; не буде знайдено, повернутий рядок буде порожнім. </para
></listitem>
</varlistentry
></variablelist>

<variablelist
><varlistentry>
<term
><synopsis
>Range document.texgroupRange(<parameter
>bool <replaceable
>всередині = true</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Повертає весь текст зовнішньої групи &latex; Якщо для параметра <parameter
>всередині</parameter
> встановлено значення <literal
>false</literal
>, до тексту середовища буде включено зовнішні дужки, <userinput
>{...}</userinput
> У протилежному випадку буде повернуто текст без дужок. Якщо ніякого значення параметру не буде передано, вважатиметься, що <parameter
>всередині</parameter
> має значення <literal
>false</literal
>. Якщо групи не буде знайдено, буде повернуто <literal
>Range.invalid()</literal
>. Перевірити це можна за допомогою функції <literal
>Range.isValid()</literal
>. </para
></listitem>
</varlistentry
></variablelist>

<variablelist
><varlistentry>
<term
><synopsis
>void document.removeTexgroup(<parameter
>bool <replaceable
>всередині = true</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Вилучає текст у зовнішній групі &latex; Якщо параметр <parameter
>всередині</parameter
> має значення <literal
>true</literal
>, буде вилучено текст групи &latex; з зовнішніми дужками, <userinput
>{...}</userinput
>. Якщо ж це не так, буде вилучено текст без дужок. Якщо функції не буде передано параметра, вважатиметься, що значенням параметра <parameter
>всередині</parameter
> є <literal
>false</literal
>. </para
></listitem>
</varlistentry
></variablelist>

<variablelist
><varlistentry>
<term
><synopsis
>bool document.hasMathgroup();
</synopsis
></term>
<listitem
><para
>Повертає <literal
>true</literal
>, якщо у поточній позиції курсора було виявлено зовнішню формульну групу &latex;. Якщо такої групи не було виявлено, повертає <literal
>false</literal
>. </para
></listitem>
</varlistentry
></variablelist>

<variablelist
><varlistentry>
<term
><synopsis
>String document.mathgroup();
</synopsis
></term>
<listitem
><para
>Повертає текст зовнішньої формульної групи &latex;. Повернутий рядок буде порожнім, якщо у поточній позиції курсора не вдасться виявити зовнішньої формульної групи &latex;. </para
></listitem>
</varlistentry
></variablelist>

<variablelist
><varlistentry>
<term
><synopsis
>Range document.mathgroupRange();
</synopsis
></term>
<listitem
><para
>Повертає діапазон зовнішньої формульної групи &latex; у поточній позиції курсора. Якщо у поточній позиції курсора немає формульних груп, буде повернуто значення <literal
>Range.invalid()</literal
>. Перевірку на коректність можна виконати за допомогою функції <literal
>Range.isValid()</literal
>. </para
></listitem>
</varlistentry
></variablelist>

<variablelist
><varlistentry>
<term
><synopsis
>void document.removeMathgroup();
</synopsis
></term>
<listitem
><para
>Вилучити текст зовнішньої формульної групи &latex;. </para
></listitem>
</varlistentry
></variablelist>

<variablelist
><varlistentry>
<term
><synopsis
>String document.paragraph();
</synopsis
></term>
<listitem
><para
>Повернути текст поточного абзацу &latex;. </para
></listitem>
</varlistentry
></variablelist>

<variablelist
><varlistentry>
<term
><synopsis
>Range document.paragraphRange();
</synopsis
></term>
<listitem
><para
>Повернути діапазон зовнішнього параграфа &latex;. </para
></listitem>
</varlistentry
></variablelist>

<variablelist
><varlistentry>
<term
><synopsis
>void document.removeParagraph();
</synopsis
></term>
<listitem
><para
>Вилучити текст поточного параграфа &latex;. </para
></listitem>
</varlistentry
></variablelist>

<variablelist
><varlistentry>
<term
><synopsis
>bool document.matchesAt(<parameter
>int <replaceable
>рядок</replaceable
></parameter
>, <parameter
>int <replaceable
>стовпчик</replaceable
></parameter
>, <parameter
>String <replaceable
>текст</replaceable
></parameter
>);
bool document.matchesAt(<parameter
>Cursor <replaceable
>курсор</replaceable
></parameter
>, <parameter
>String <replaceable
>текст</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Повертає <literal
>true</literal
>, якщо вказаний <parameter
>текст</parameter
> розташовано за відповідною позицією курсора. Якщо це не так, повертає <literal
>false</literal
>. </para
></listitem>
</varlistentry
></variablelist>

<variablelist
><varlistentry>
<term
><synopsis
>bool document.startsWith(<parameter
>int <replaceable
>рядок</replaceable
></parameter
>, <parameter
>String <replaceable
>шаблон</replaceable
></parameter
>, <parameter
>bool <replaceable
>пропускатиПробіли = true</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Повертає <literal
>true</literal
>, якщо рядок починається з шаблону <parameter
>шаблон</parameter
>, інакше повертає <literal
>false</literal
>. За допомогою аргументу <parameter
>пропускатиПробіли</parameter
> можна керувати тим, чи буде пропущено початкові пробіли. </para
></listitem>
</varlistentry
></variablelist>

<variablelist
><varlistentry>
<term
><synopsis
>bool document.endsWith(<parameter
>int <replaceable
>рядок</replaceable
></parameter
>, <parameter
>String <replaceable
>шаблон</replaceable
></parameter
>, <parameter
>bool <replaceable
>пропускатиПробіли = true</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Повертає <literal
>true</literal
>, якщо рядок з вказаним номером завершується фрагментом тексту <parameter
>шаблон</parameter
>. Якщо це не так, повертає <literal
>false</literal
>. За допомогою параметра <parameter
>пропускатиПробіли</parameter
> можна вказати програмі, чи слід ігнорувати пробіли. </para
></listitem>
</varlistentry
></variablelist>

<variablelist
><varlistentry>
<term
><synopsis
>int document.firstColumn(<parameter
>int <replaceable
>рядок</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Повертає перший відмінний від пробілу стовпчик у вказаному за допомогою параметра номера, <parameter
>
>рядок</parameter
>, рядку. Якщо у рядку будуть лише пробіли, функція поверне значення <literal
>-1</literal
>. </para
></listitem>
</varlistentry
></variablelist>

<variablelist
><varlistentry>
<term
><synopsis
>int document.lastColumn(<parameter
>int <replaceable
>рядок</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Повертає останній відмінний від пробілу стовпчик у вказаному за допомогою параметра номера, <parameter
>рядок</parameter
>, рядку. Якщо у рядку будуть лише пробіли, функція поверне значення <literal
>-1</literal
>. </para
></listitem>
</varlistentry
></variablelist>

<variablelist
><varlistentry>
<term
><synopsis
>int document.prevNonSpaceColumn(<parameter
>int <replaceable
>рядок</replaceable
></parameter
>, <parameter
>int <replaceable
>стовпчик</replaceable
></parameter
>);
int document.prevNonSpaceColumn(<parameter
>Cursor <replaceable
>курсор</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Повертає номер стовпчика з символом, відмінним від пробілу. Пошук буде виконано у напрямку початку документа, починаючи з вказаної позиції курсора. </para
></listitem>
</varlistentry
></variablelist>

<variablelist
><varlistentry>
<term
><synopsis
>int document.nextNonSpaceColumn(<parameter
>int <replaceable
>рядок</replaceable
></parameter
>, <parameter
>int <replaceable
>стовпчик</replaceable
></parameter
>);
int document.nextNonSpaceColumn(<parameter
>Cursor <replaceable
>курсор</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Повертає номер стовпчика з символом, відмінним від пробілу. Пошук буде виконано у напрямку кінця документа, починаючи з вказаної позиції курсора. </para
></listitem>
</varlistentry
></variablelist>

<variablelist
><varlistentry>
<term
><synopsis
>int document.prevNonEmptyLine(<parameter
>int <replaceable
>рядок</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Повертає наступний непорожній рядок, що містить символи, відмінні від пробілів. Пошук відбуватиметься у напрямку початку документа. </para
></listitem>
</varlistentry
></variablelist>

<variablelist
><varlistentry>
<term
><synopsis
>int document.nextNonEmptyLine(<parameter
>int <replaceable
>рядок</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Повертає наступний непорожній рядок, що містить символи, відмінні від пробілів. Пошук відбуватиметься у напрямку кінця документа. </para
></listitem>
</varlistentry
></variablelist>

<variablelist
><varlistentry>
<term
><synopsis
>void document.gotoBeginEnv();
</synopsis
></term>
<listitem
><para
>Перейти до початку зовнішнього середовища &latex;. </para
></listitem>
</varlistentry
></variablelist>

<variablelist
><varlistentry>
<term
><synopsis
>void document.gotoEndEnv();
</synopsis
></term>
<listitem
><para
>Перейти до кінця зовнішнього середовища &latex;. </para
></listitem>
</varlistentry
></variablelist>

<variablelist
><varlistentry>
<term
><synopsis
>void document.gotoBeginTexgroup();
</synopsis
></term>
<listitem
><para
>Перейти до початку зовнішньої групи &latex;. </para
></listitem>
</varlistentry
></variablelist>

<variablelist
><varlistentry>
<term
><synopsis
>void document.gotoEndTexgroup();
</synopsis
></term>
<listitem
><para
>Перейти до кінця зовнішньої групи &latex;. </para
></listitem>
</varlistentry
></variablelist>

<variablelist
><varlistentry>
<term
><synopsis
>void document.gotoNextParagraph();
</synopsis
></term>
<listitem
><para
>Перейти до наступного параграфа &latex;. </para
></listitem>
</varlistentry
></variablelist>

<variablelist
><varlistentry>
<term
><synopsis
>void document.gotoPrevParagraph();
</synopsis
></term>
<listitem
><para
>Перейти до попереднього параграфа &latex;. </para
></listitem>
</varlistentry
></variablelist>

<variablelist
><varlistentry>
<term
><synopsis
>void document.gotoNextSectioning();
</synopsis
></term>
<listitem
><para
>Перейти до наступного розділу &latex;. </para
></listitem>
</varlistentry
></variablelist>

<variablelist
><varlistentry>
<term
><synopsis
>void document.gotoPrevSectioning();
</synopsis
></term>
<listitem
><para
>Перейти до попереднього розділу &latex;. </para
></listitem>
</varlistentry
></variablelist>

<variablelist
><varlistentry>
<term
><synopsis
>void document.gotoLine(<parameter
>int <replaceable
>рядок</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Перейти до вказаного <literal
>рядка</literal
>. </para
></listitem>
</varlistentry
></variablelist>

<variablelist
><varlistentry>
<term
><synopsis
>void document.insertChapter();
</synopsis
></term>
<listitem
><para
>Вставити команду <userinput
>\chapter</userinput
> (див. також <literal
>document.insertSection()</literal
>). </para
></listitem>
</varlistentry
></variablelist>

<variablelist
><varlistentry>
<term
><synopsis
>void document.insertSection();
</synopsis
></term>
<listitem
><para
>Вставити команду <userinput
>\section</userinput
>. Подібно до ситуації, коли вибрано пункт меню <menuchoice
><guimenu
>LaTeX</guimenu
><guisubmenu
>Розділи</guisubmenu
><guimenuitem
>section</guimenuitem
></menuchoice
>, буде відкрито діалогове вікно, за допомогою якого ви зможете вибрати заголовок та мітку для команди початку розділу. <screenshot>
	<screeninfo
>Діалогове вікно: вставлення команди початку розділу</screeninfo>
	<mediaobject>
	<imageobject>
	<imagedata fileref="dialog-insertsection.png" format="PNG"/>
	</imageobject>
	<textobject>
		<phrase
>Діалогове вікно: вставлення команди початку розділу</phrase>
	</textobject>
	</mediaobject>
</screenshot>
</para
></listitem>
</varlistentry
></variablelist>

<variablelist
><varlistentry>
<term
><synopsis
>void document.insertSubsection();
</synopsis
></term>
<listitem
><para
>Вставити команду <userinput
>\subsection</userinput
> (див. також <literal
>document.insertSection()</literal
>). </para
></listitem>
</varlistentry
></variablelist>

<variablelist
><varlistentry>
<term
><synopsis
>void document.insertSubsubsection();
</synopsis
></term>
<listitem
><para
>Вставити команду <userinput
>\subsubsection</userinput
> (див. також <literal
>document.insertSection()</literal
>). </para
></listitem>
</varlistentry
></variablelist>

<variablelist
><varlistentry>
<term
><synopsis
>void document.insertParagraph();
</synopsis
></term>
<listitem
><para
>Вставити команду <userinput
>\paragraph</userinput
> (див. також <literal
>document.insertSection()</literal
>). </para
></listitem>
</varlistentry
></variablelist>

<variablelist
><varlistentry>
<term
><synopsis
>void document.insertSubparagraph();
</synopsis
></term>
<listitem
><para
>Вставити команду <userinput
>\subparagraph</userinput
> (див. також <literal
>document.insertSection()</literal
>). </para
></listitem>
</varlistentry
></variablelist>

<variablelist
><varlistentry>
<term
><synopsis
>void document.insertLabel();
</synopsis
></term>
<listitem
><para
>Вставити команду <userinput
>\label</userinput
>. </para
></listitem>
</varlistentry
></variablelist>

<variablelist
><varlistentry>
<term
><synopsis
>void document.insertReference();
</synopsis
></term>
<listitem
><para
>Вставити команду <userinput
>\ref</userinput
>. Подібно до ситуації, коли вибрано пункт меню <menuchoice
><guimenu
>&latex;</guimenu
><guisubmenu
>Розділи</guisubmenu
><guimenuitem
>ref</guimenuitem
></menuchoice
>, буде відкрито діалогове вікно, за допомогою якого ви зможете вибрати у спадному списку одну з вже встановлених міток. <screenshot>
	<screeninfo
>Діалогове вікно: вставляння команди посилання</screeninfo>
	<mediaobject>
	<imageobject>
	<imagedata fileref="dialog-insertreference.png" format="PNG"/>
	</imageobject>
	<textobject>
		<phrase
>Діалогове вікно: вставляння команди посилання</phrase>
	</textobject>
	</mediaobject>
</screenshot>
</para
></listitem>
</varlistentry
></variablelist>

<variablelist
><varlistentry>
<term
><synopsis
>void document.insertPageref();
</synopsis
></term>
<listitem
><para
>Вставити команду <userinput
>\pageref</userinput
> (див. також <literal
>document.insertReference()</literal
>). </para
></listitem>
</varlistentry
></variablelist>


<variablelist
><varlistentry>
<term
><synopsis
>void document.insertCitation();
</synopsis
></term>
<listitem
><para
>Вставити команду <userinput
>\cite</userinput
>. </para
></listitem>
</varlistentry
></variablelist>

<variablelist
><varlistentry>
<term
><synopsis
>void document.insertIndex();
</synopsis
></term>
<listitem
><para
>Вставити команду <userinput
>\index</userinput
>. </para
></listitem>
</varlistentry
></variablelist>

<variablelist
><varlistentry>
<term
><synopsis
>void document.insertFootnote();
</synopsis
></term>
<listitem
><para
>Вставити команду <userinput
>\footnote</userinput
>. </para
></listitem>
</varlistentry
></variablelist>

<variablelist
><varlistentry>
<term
><synopsis
>void document.comment();
</synopsis
></term>
<listitem
><para
>Вставити позначку коментування. Позначений фрагмент тексту або поточний рядок буде закоментовано. </para
></listitem>
</varlistentry
></variablelist>

<variablelist
><varlistentry>
<term
><synopsis
>void document.uncomment();
</synopsis
></term>
<listitem
><para
>Зняти позначку коментаря з позначеного фрагмента тексту або поточного рядка. </para
></listitem>
</varlistentry
></variablelist>

<variablelist
><varlistentry>
<term
><synopsis
>void document.uppercase();
</synopsis
></term>
<listitem
><para
>Переводить вибраний текст або літеру, розташовану одразу за курсором у верхній регістр. </para
></listitem>
</varlistentry
></variablelist>

<variablelist
><varlistentry>
<term
><synopsis
>void document.lowercase();
</synopsis
></term>
<listitem
><para
>Переводить вибраний текст або літеру, розташовану одразу за курсором у нижній регістр. </para
></listitem>
</varlistentry
></variablelist>

<variablelist
><varlistentry>
<term
><synopsis
>void document.capitalize();
</synopsis
></term>
<listitem
><para
>Переводить першу літеру позначеного фрагмента тексту або поточного слова у верхній регістр. </para
></listitem>
</varlistentry
></variablelist>

<variablelist
><varlistentry>
<term
><synopsis
>void document.joinLines();
</synopsis
></term>
<listitem
><para
>Об’єднує рядки поточного позначеного фрагмента тексту. Послідовні рядки тексту завжди відокремлюються одинарним пробілом. </para
></listitem>
</varlistentry
></variablelist>

<variablelist
><varlistentry>
<term
><synopsis
>void document.insertIntelligentNewline();
</synopsis
></term>
<listitem
><para
>Вставити кмітливий новий рядок (див. <xref linkend="editing_smartnewline" role="select: title pageabbrv"/>). </para
></listitem>
</varlistentry
></variablelist>

<variablelist
><varlistentry>
<term
><synopsis
>void document.insertIntelligentTabulator();
</synopsis
></term>
<listitem
><para
>Вставити кмітливу табуляцію (див. <xref linkend="editing_tabulator" role="select: title pageabbrv"/>). </para
></listitem>
</varlistentry
></variablelist>

<variablelist
><varlistentry>
<term
><synopsis
>void document.editBegin();
</synopsis
></term>
<listitem
><para
>Започатковує групу редагування для впорядкування операцій зі скасування або повторення дій. Не забувайте, що викликати <function
>editEnd()</function
> слід саме стільки разів, скільки разів було викликано <function
>editBegin()</function
>. Виклики <function
>editBegin()</function
> використовують вбудований лічильник, отже їх може бути вкладено один у оден. </para
></listitem>
</varlistentry
></variablelist>

<variablelist
><varlistentry>
<term
><synopsis
>void document.editEnd();
</synopsis
></term>
<listitem
><para
>Завершує групу редагування. Останній виклик <function
>editEnd()</function
> (тобто відповідник першого виклику <function
>editBegin()</function
>) завершує крок з редагування. </para
></listitem>
</varlistentry
></variablelist>

<variablelist
><varlistentry>
<term
><synopsis
>StringList document.labelList();
</synopsis
></term>
<listitem
><para
>Повертає всі визначені мітки у форматі <literal
>StringList</literal
>, який у &javascript; можна використовувати як масив з рядків. </para
></listitem>
</varlistentry
></variablelist>

<variablelist
><varlistentry>
<term
><synopsis
>StringList document.bibitemList();
</synopsis
></term>
<listitem
><para
>Повертає всі визначені пункти списку літератури у форматі <literal
>StringList</literal
>, який у &javascript; можна використовувати як масив з рядків. </para
></listitem>
</varlistentry
></variablelist>

<variablelist
><varlistentry>
<term
><synopsis
>void document.refreshStructure();
</synopsis
></term>
<listitem
><para
>Оновити дані панелі структури (див. <xref linkend="navigating" role="select: title pageabbrv"/>). </para
></listitem>
</varlistentry
></variablelist>

</sect2>


<sect2 id="id_scripting_api_kile">
<title
>Програмний інтерфейс &kile;</title>

<para
>Для обробки високорівневої взаємодії зі сторонніми чинниками, зокрема вхідними повідомленнями і діалоговими інтерфейсами, використовується загальний об’єкт (змінна) <userinput
>kile</userinput
>. Відповідні виклики програмного інтерфейсу поділено на підоб’єкти для структуризації цієї частини програмного інтерфейсу роботи зі скриптами. З точки зору концепції, <userinput
>kile</userinput
> чимось подібний до об’єкта <userinput
>window</userinput
> у програмному інтерфейсі переглядачів сторінок інтернету. <itemizedlist>
<listitem
><para
><literal
>kile.alert</literal
>: панелі повідомлень</para
></listitem>
<listitem
><para
><literal
>kile.input</literal
>: отримати введені користувачем дані</para
></listitem>
<listitem
><para
><literal
>kile.wizard</literal
>: викликати один з майстрів &kile;</para
></listitem>
<listitem
><para
><literal
>kile.script</literal
>: отримати дані щодо запущеного скрипту</para
></listitem>
<listitem
><para
><literal
>kile.file</literal
>: виконати дії над файлами, зокрема читання або запис.</para
></listitem>
</itemizedlist>
</para>


<sect3 id="id_scripting_api_kile_alert">
<title
>Попередження</title>

<variablelist
><varlistentry>
<term
><synopsis
>void kile.alert.information(<parameter
>String <replaceable
>текст</replaceable
></parameter
>, <parameter
>String <replaceable
>підпис</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Показати діалогове вікно <emphasis
>Інформація</emphasis
>. <parameter
>текст</parameter
> — рядок повідомлення, а <parameter
>підпис</parameter
> — заголовок вікна повідомлення. Типовим заголовком є назва скрипту. </para
></listitem>
</varlistentry
></variablelist>

<variablelist
><varlistentry>
<term
><synopsis
>void kile.alert.sorry(<parameter
>String <replaceable
>текст</replaceable
></parameter
>, <parameter
>String <replaceable
>підпис</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Показати діалогове вікно <emphasis
>Вибачте</emphasis
>. <parameter
>текст</parameter
> — рядок повідомлення, а <parameter
>підпис</parameter
> — заголовок вікна повідомлення. Типовим заголовком є назва скрипту. </para
></listitem>
</varlistentry
></variablelist>

<variablelist
><varlistentry>
<term
><synopsis
>void kile.alert.error(<parameter
>String <replaceable
>текст</replaceable
></parameter
>, <parameter
>String <replaceable
>підпис</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Показати діалогове вікно <emphasis
>Помилка</emphasis
>. <parameter
>текст</parameter
> — рядок повідомлення, а <parameter
>підпис</parameter
> — заголовок вікна повідомлення. Типовим заголовком є назва скрипту. </para
></listitem>
</varlistentry
></variablelist>

<variablelist
><varlistentry>
<term
><synopsis
>String kile.alert.question(<parameter
>String <replaceable
>текст</replaceable
></parameter
>, <parameter
>String <replaceable
>підпис</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Показати діалогове вікно <emphasis
>Питання</emphasis
>. <parameter
>текст</parameter
> — рядок повідомлення, а <parameter
>підпис</parameter
> — заголовок вікна повідомлення. Типовим заголовком є назва скрипту. Повернутий рядок міститиме <literal
>yes</literal
> (так) або <literal
>no</literal
> (ні). </para
></listitem>
</varlistentry
></variablelist>

<variablelist
><varlistentry>
<term
><synopsis
>String kile.alert.warning(<parameter
>String <replaceable
>текст</replaceable
></parameter
>, <parameter
>String <replaceable
>підпис</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Показати просте діалогове вікно <emphasis
>Попередження</emphasis
>. <parameter
>текст</parameter
> — рядок повідомлення, а <parameter
>підпис</parameter
> — заголовок вікна повідомлення. Типовим заголовком є назва скрипту. Повернутий рядок міститиме <literal
>continue</literal
> (продовжити) або <literal
>cancel</literal
> (скасувати). </para
></listitem>
</varlistentry
></variablelist>
</sect3>


<sect3 id="id_scripting_api_kile_input">
<title
>Введення</title>

<variablelist
><varlistentry>
<term
><synopsis
>String kile.input.getListboxItem(<parameter
>String <replaceable
>підпис</replaceable
></parameter
>, <parameter
>String <replaceable
>мітка</replaceable
></parameter
>, <parameter
>StringList <replaceable
>список</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Функція, за допомогою якої користувач може вибрати якийсь пункт зі списку у форматі панелі списку варіантів. <parameter
>підпис</parameter
> — текст, який буде показано у заголовку, <parameter
>мітка</parameter
> — текст, який буде показано як пояснювальний до списку, а <parameter
>list</parameter
> — список рядків, які буде вставлено до списку. </para
></listitem>
</varlistentry
></variablelist>

<variablelist
><varlistentry>
<term
><synopsis
>String kile.input.getComboboxItem(<parameter
>String <replaceable
>підпис</replaceable
></parameter
>, <parameter
>String <replaceable
>мітка</replaceable
></parameter
>, <parameter
>StringList <replaceable
>список</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Функція, за допомогою якої користувач може вибрати якийсь пункт зі спадного списку. <parameter
>підпис</parameter
> — текст, який буде показано у заголовку, <parameter
>мітка</parameter
> — текст, який буде показано як пояснювальний до списку, а <parameter
>list</parameter
> — список рядків, які буде вставлено до списку. </para
></listitem>
</varlistentry
></variablelist>

<variablelist
><varlistentry>
<term
><synopsis
>String kile.input.getText(<parameter
>String <replaceable
>підпис</replaceable
></parameter
>, <parameter
>String <replaceable
>мітка</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Функція, призначена для отримання рядка від користувача. <parameter
>підпис</parameter
> — текст, який буде показано на смужці заголовка вікна, а <parameter
>мітка</parameter
> — пояснювальний текст до рядка для введення тексту. </para
></listitem>
</varlistentry
></variablelist>

<variablelist
><varlistentry>
<term
><synopsis
>String kile.input.getLatexCommand(<parameter
>String <replaceable
>підпис</replaceable
></parameter
>, <parameter
>String <replaceable
>мітка</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Функція, призначена для отримання команди &latex; від користувача. Це означає, що прийматимуться лише латинські літери верхнього і нижнього регістрів. <parameter
>підпис</parameter
> — текст, який буде показано на смужці заголовка вікна, а <parameter
>мітка</parameter
> — пояснювальний текст до рядка для введення тексту. </para
></listitem>
</varlistentry
></variablelist>

<variablelist
><varlistentry>
<term
><synopsis
>int kile.input.getInteger(<parameter
>String <replaceable
>підпис</replaceable
></parameter
>, <parameter
>String <replaceable
>мітка</replaceable
></parameter
>, <parameter
>int <replaceable
>мінімум = INT_MIN</replaceable
></parameter
>, <parameter
>int <replaceable
>максимум = INT_MAX</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Функція, призначена для отримання цілого числа від користувача. <parameter
>підпис</parameter
> — текст, який буде показано на смужці заголовка вікна, а <parameter
>мітка</parameter
> — пояснювальний текст до рядка для введення тексту. <parameter
>мінімум</parameter
> і <parameter
>максимум</parameter
> є найменшим і найбільшим значеннями, які може ввести користувач. Типовими значеннями є <literal
>INT_MIN</literal
> і <literal
>INT_MAX</literal
>. </para
></listitem>
</varlistentry
></variablelist>

<variablelist
><varlistentry>
<term
><synopsis
>int kile.input.getPosInteger(<parameter
>String <replaceable
>підпис</replaceable
></parameter
>, <parameter
>String <replaceable
>мітка</replaceable
></parameter
>, <parameter
>int <replaceable
>мінімум = 1</replaceable
></parameter
>, <parameter
>int <replaceable
>максимум = INT_MAX</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Функція, призначена для отримання додатного цілого числа від користувача. <parameter
>підпис</parameter
> — текст, який буде показано на смужці заголовка вікна, а <parameter
>мітка</parameter
> — пояснювальний текст до рядка для введення тексту. <parameter
>мінімум</parameter
> і <parameter
>максимум</parameter
> є найменшим і найбільшим значеннями, які може ввести користувач. Типовими значеннями є <literal
>1</literal
> і <literal
>INT_MAX</literal
>. </para
></listitem>
</varlistentry
></variablelist>
</sect3>


<sect3 id="id_scripting_api_kile_wizard">
<title
>Майстер</title>

<variablelist
><varlistentry>
<term
><synopsis
>void kile.wizard.tabular();
</synopsis
></term>
<listitem
><para
>Викликає <emphasis
>Майстер створення таблиць</emphasis
>, який допомагає у створенні середовищ tabular (див. <xref linkend="wizard_array" role="select: title pageabbrv"/>). </para
></listitem>
</varlistentry
></variablelist>

<variablelist
><varlistentry>
<term
><synopsis
>void kile.wizard.array();
</synopsis
></term>
<listitem
><para
>Викликає <emphasis
>Майстер створення масивів</emphasis
>, який допомагає у створенні середовищ типу array (див. <xref linkend="wizard_array" role="select: title pageabbrv"/>). </para
></listitem>
</varlistentry
></variablelist>

<variablelist
><varlistentry>
<term
><synopsis
>void kile.wizard.tabbing();
</synopsis
></term>
<listitem
><para
>Викликає <emphasis
>Майстер створення табуляцій</emphasis
>, який допомагає у створенні середовищ типу tabbing (див. <xref linkend="wizard_array" role="select: title pageabbrv"/>). </para
></listitem>
</varlistentry
></variablelist>

<variablelist
><varlistentry>
<term
><synopsis
>void kile.wizard.floatEnvironment();
</synopsis
></term>
<listitem
><para
>Викликає <emphasis
>Майстер створення плаваючих об’єктів</emphasis
>, який допомагає у створенні рухомих елементів набору документа (див. <xref linkend="wizard_float" role="select: title pageabbrv"/>). </para
></listitem>
</varlistentry
></variablelist>

<variablelist
><varlistentry>
<term
><synopsis
>void kile.wizard.mathEnvironment();
</synopsis
></term>
<listitem
><para
>Викликає <emphasis
>Майстер створення формул</emphasis
>, який полегшує створення середовищ формул (див. <xref linkend="wizard_math" role="select: title pageabbrv"/>). </para
></listitem>
</varlistentry
></variablelist>

<variablelist
><varlistentry>
<term
><synopsis
>void kile.wizard.postscript();
</synopsis
></term>
<listitem
><para
>Викликає <emphasis
>Майстер інструментів Postscript</emphasis
>, який обробку та перевпорядковування документів Postscript (див. <xref linkend="wizard_postscript" role="select: title pageabbrv"/>). </para
></listitem>
</varlistentry
></variablelist>
</sect3>


<sect3 id="id_scripting_api_kile_script">
<title
>Скрипт</title>

<variablelist
><varlistentry>
<term
><synopsis
>String kile.script.name();
</synopsis
></term>
<listitem
><para
>Повертає основу назви запущеного скрипту (без шляху та суфікса назви). </para
></listitem>
</varlistentry
></variablelist>

<variablelist
><varlistentry>
<term
><synopsis
>String kile.script.caption();
</synopsis
></term>
<listitem
><para
>Повертає рядок, яким можна скористатися для створення заголовків вікон попереджень. Виглядає це так: <userinput
>Script: scriptname.js</userinput
>. </para
></listitem>
</varlistentry
></variablelist>
</sect3>


<sect3 id="id_scripting_api_kile_file">
<title
>Файл</title>

<variablelist
><varlistentry>
<term
><synopsis
>Object kile.file.read(<parameter
>String <replaceable
>назва_файла</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Читати вміст текстового файла. Використовується так: </para
><para
>Приклад: <function
>var res = kile.file.read("шлях/до/файл.txt");</function
> </para
><para
>Повертає значення <userinput
>res</userinput
> як об’єкт (краще сказати, карту) з трьома властивостями: </para
><para>
<itemizedlist>
<listitem
><para
><guilabel
>status:</guilabel
> дає код стану дії. Можливі значення: 0 (без помилок), 1 (помилка доступу) або 2 (доступ заборонено). Отже, якщо не сталося помилок, значенням <userinput
>res.status</userinput
> або <userinput
>res["status"]</userinput
> буде 0.</para
></listitem>
<listitem
><para
><guilabel
>result:</guilabel
> містить текст відповідного файла.</para
></listitem>
<listitem
><para
><guilabel
>message:</guilabel
> містить повідомлення про помилку, якщо така сталася.</para
></listitem>
</itemizedlist>
</para
></listitem>
</varlistentry
></variablelist>

<variablelist
><varlistentry>
<term
><synopsis
>Object kile.file.read();
</synopsis
></term>
<listitem
><para
>Подібний до <literal
>read(назва_файла)</literal
>, але назву файла вказувати непотрібно. Замість цього, буде відкрито діалогове вікно для вибору файла, дані якого слід прочитати. </para
></listitem>
</varlistentry
></variablelist>

<variablelist
><varlistentry>
<term
><synopsis
>Object kile.file.write(<parameter
>String <replaceable
>назва файла</replaceable
></parameter
>, <parameter
>String <replaceable
>текст</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Записати вказаний текст до файла. Має використовуватися так: </para
><para
>Приклад: <function
>var res = kile.file.write("шлях/до/file.txt","Якийсь фрагмент тексту...");</function
> </para
><para
>Повернутим значенням <userinput
>res</userinput
> є об’єкт (або, краще сказати, карта) з двома властивостями: <literal
>status</literal
> і <literal
>message</literal
> (докладніше про властивості див. <literal
>read()</literal
>). </para
></listitem>
</varlistentry
></variablelist>

<variablelist
><varlistentry>
<term
><synopsis
>Object kile.file.write(<parameter
>String <replaceable
>текст</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Подібний до <literal
>write(назва_файла,текст)</literal
>, але назва файла не передається. Замість цього відкривається діалогове вікно для вибору назви файла. </para
></listitem>
</varlistentry
></variablelist>

<variablelist
><varlistentry>
<term
><synopsis
>String kile.file.getOpenFileName(<parameter
>String <replaceable
>початковийКаталог</replaceable
></parameter
>, <parameter
>String <replaceable
>фільтр</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Створює модальний діалог вибору файла і повертає вибрану назву файла або порожній рядок, якщо назву файла не було вибрано. Зауважте, що у разі використання цього методу користувач має вибрати назву вже створеного файла. </para
><para
>Параметри: </para
><para>
<itemizedlist>
<listitem
><para
><guilabel
>початковийКаталог:</guilabel
> початковий каталог діалогового вікна відкриття.</para
></listitem>
<listitem
><para
><guilabel
>фільтр:</guilabel
> загальний шаблон оболонки або фільтр за типом MIME, який визначає, які файли слід показувати. Дані щодо цього параметра можна знайти у документації з KFileDialog.</para
></listitem>
</itemizedlist>
</para
><para
>Обидва параметри є необов’язковими. Якщо не буде вказано параметр <literal
>фільтр</literal
>, буде показано всі файли. Якщо, крім того, не буде вказано параметр <literal
>початковийКаталог</literal
>, початковим каталогом у діалоговому вікні буде каталог поточного документа. </para
></listitem>
</varlistentry
></variablelist>

<variablelist
><varlistentry>
<term
><synopsis
>String kile.file.getSaveFileName(<parameter
>String <replaceable
>початковийКаталог</replaceable
></parameter
>, <parameter
>String <replaceable
>фільтр</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Створює модальний діалог вибору файла і повертає вибрану назву файла або порожній рядок, якщо назву файла не було вибрано. Зауважте, що у разі використання цього методу користувач не повинен обов’язково вибирати назву вже створеного файла. Опис параметрів можна знайти у поясненнях щодо <literal
>getOpenFileName()</literal
>. </para
></listitem>
</varlistentry
></variablelist>

</sect3>

</sect2>

</sect1>


<sect1 id="id_scripting_examples">
<title
>Приклади</title>

<para
>Наведені нижче приклади можуть допомогти вам у ознайомленні зі способами використання програмного інтерфейсу роботи зі скриптами. Ці приклади, а також інші корисні дані можна знайти у каталозі даних &kile;: <filename
>KILE_APP_DIR/scripts/</filename
>. У кожному скрипті міститься короткий опис його призначення.</para>

<sect2 id="id_scripting_example1">
<title
>Приклад 1: заміна назви середовища</title>

<para
>Замінимо зовнішнє середовище &latex; якимось іншим, зберігаючи розташування курсора. За допомогою нашого скрипту, наприклад, можна буде замінити <userinput
>\begin{abc}...\end{abc}</userinput
> на <userinput
>\begin{xyz}...\end{xyz}</userinput
>.</para>

<programlisting
>var range = document.environmentRange(false);
if ( range.isValid() ) {
        var envname = kile.input.getLatexCommand("Введіть назву середовища","Нова назва середовища:");
        if ( envname != '' ) {
                replaceEnvCommand(envname,range);
        }
}
else {
        kile.alert.sorry("Не виявлено зовнішнього середовища LaTeX.");
}

function replaceEnvCommand(newEnv,r)
{
        var c = view.cursorPosition();

        var envname = document.environmentName();

        if ( envname != "" ) {
                var beginRange = new Range(r.start,new Cursor(r.start.line,r.start.column+8+envname.length));
                var endRange = new Range(new Cursor(r.end.line,r.end.column-6-envname.length),r.end);

                document.editBegin();
                document.replaceText(endRange,"\\end{"+newEnv+"}");
                document.replaceText(beginRange,"\\begin{"+newEnv+"}");
                document.editEnd();
        }
}
</programlisting>
</sect2>

<sect2 id="id_scripting_example2">
<title
>Приклад 2: заміна команди визначення шрифту &latex;</title>

<para
>Замінимо зовнішню команду визначення шрифту &latex; якоюсь іншою командою визначення шрифту (курсор має бути розташовано у якійсь групі TeX), зберігаючи розташування курсора. За допомогою нашого скрипту, наприклад, можна буде замінити <userinput
>\textbf{abc}</userinput
> на <userinput
>\textit{abc}</userinput
>.</para>

<programlisting
>var fontCommands = new Array("\\textbf","\\textit","\\textsl","\\texttt",
                             "\\textsc","\\textrm","\\textsf","\\emph");

var range = document.texgroupRange(false);
if ( range.isValid() ) {
        replaceFontCommand(range);
}
else {
        kile.alert.sorry("Не виявлено зовнішньої групи TeX.");
}

function replaceFontCommand(r)
{
        var c = view.cursorPosition();

        document.editBegin();
        view.setCursorPosition(r.start);
        var cmd = document.latexCommand();
        var index = fontCommands.indexOf(cmd);
        if ( index 
>= 0 ) {
                var cmdRange = document.latexCommandRange();
                if ( cmdRange.isValid() ) {
                        var newcommand = kile.input.getListboxItem("Вибір",
                                                    "Виберіть команду шрифту:",buildCmdList(cmd));
                        if ( newcommand != "" ) {
                                document.replaceText(cmdRange,newcommand);
                                c.column = c.column - (cmd.length - newcommand.length);
                        }
                }
/                view.setCursorPosition(c);
        }
        else {
                kile.alert.sorry("Не виявлено зовнішньої команди визначення шрифту.");
        }
        document.editEnd();
}

function buildCmdList(current)
{
        var result = new Array();
        for ( i=0; i&lt;fontCommands.length; ++i ) {
                if ( fontCommands[i] != current ) {
                        result.push(fontCommands[i]);
                }
        }
        return result;
}
</programlisting>

</sect2>

<sect2 id="id_scripting_example3">
<title
>Приклад 3: створення обгортки позначеного фрагмента тексту</title>

<para
>Вмістити позначений фрагмент тексту у параметр команди TeX без зміни розташування курсора. <userinput
>abc</userinput
>, наприклад, буде замінено на <userinput
>\texcommand{abc}</userinput
>.</para>

<programlisting
>var range = view.selectionRange();

if ( range.isValid() ) {
        var cmd = kile.input.getLatexCommand("Вибір","Виберіть зовнішню команду LaTeX:");
        if ( cmd != "" ) {
                surroundTexCommand("\\"+cmd,range);
        }
}
else {
        kile.alert.sorry("Нічого не позначено.");
}

function surroundTexCommand(cmd,r)
{
        var c = view.cursorPosition();

        document.editBegin();
        view.clearSelection();
        document.insertText(r.end,"}");
        document.insertText(r.start,cmd+"{");

        c.column = c.column + cmd.length + 2;
        view.setCursorPosition(c);
        document.editEnd();
}
</programlisting>
</sect2>

</sect1>

</chapter>
