<!-- auto-generate scripting documentation (kwrite-devel@kde.org Re: [kate] doc/kate: document most of the new scripts in 4.10) -->
<chapter id="dev">
<chapterinfo>
<authorgroup>
<author
>&TC.Hollingsworth; &TC.Hollingsworth.mail;</author>
<othercredit role="translator"
><firstname
>Юрій</firstname
><surname
>Чорноіван</surname
><affiliation
><address
><email
>yurchor@ukr.net</email
></address
></affiliation
><contrib
>Переклад українською</contrib
></othercredit
>
</authorgroup>
</chapterinfo>
<title
>Розширення можливостей &katepart;</title>
<sect1 id="dev-intro">
<title
>Вступ</title>
<para
>Подібно до всіх компонентів текстових редакторів з широкими можливостями, у &katepart; передбачено певні шляхи до розширення функціональних можливостей компонента. Ви можете <link linkend="dev-scripting"
>створювати прості скрипти, що реалізують додаткові можливості, за допомогою JavaScript</link
>. Нарешті, вдосконаливши ваш екземпляр &katepart;, ви можете <ulink url="https://kate-editor.org/join-us/"
>долучитися до розробників</ulink
> і поділитися вашими удосконаленнями з іншими користувачами!</para>
</sect1>
<sect1 id="highlight">
<title
>Як працювати з підсвічуванням синтаксису</title>
<sect2 id="highlight-overview">
<title
>Огляд</title>
<para
>Підсвічування синтаксису призначено для автоматично показу тексту у різних стилях і кольорах, залежно від призначення відповідного рядка та файла, з якого взято цей рядок. У початковому коді програми, наприклад, оператори керування може бути показано жирним шрифтом, а типи даних і коментарі — кольором, відмінним від кольору решти тексту. За допомогою підсвічування можна значно покращити зручність читання тексту, а отже підвищити ефективність та продуктивність роботи з цим текстом.</para>
<mediaobject>
<imageobject
><imagedata format="PNG" fileref="highlighted.png"/></imageobject>
<textobject
><phrase
>Функція, написана мовою C++, показана з підсвічуванням синтаксису.</phrase
></textobject>
<caption
><para
>Функція, написана мовою C++, показана з підсвічуванням синтаксису.</para>
</caption>
</mediaobject>
<mediaobject>
<imageobject
><imagedata format="PNG" fileref="unhighlighted.png"/></imageobject>
<textobject
><phrase
>Та сама функція, написана мовою C++, без підсвічування.</phrase
></textobject>
<caption
><para
>Та сама функція, написана мовою C++, без підсвічування.</para
></caption>
</mediaobject>
<para
>Ну що, який з двох прикладів зручніше читати?</para>
<para
>У &kappname; передбачено гнучку, придатну для налаштування і потужну систему підсвічування синтаксичних конструкцій, у стандартному пакунку ви знайдете визначення для широкого спектру мов програмування, написання скриптів та розмітки, а також текстових файлів у інших форматах. Окрім того, ви можете створювати власні визначення за допомогою простих файлів &XML;.</para>
<para
>&kappname; автоматично визначатиме належні правила підсвічування синтаксису під час відкриття файла. Дія з визначення відбуватиметься на основі типу &MIME; файла, який визначатиметься за суфіксом назви файла або, якщо у назві немає суфіксу, за вмістом файла. Якщо, на вашу думку, програма зробила неправильний вибір, ви можете вручну вказати правила підсвічування за допомогою пункту меню <menuchoice
><guimenu
>Інструменти</guimenu
> <guisubmenu
>Підсвічування</guisubmenu
></menuchoice
>.</para>
<para
>Гарнітури шрифту та кольори, які буде використано визначенням підсвічування синтаксису, можна налаштувати на вкладці <link linkend="prefcolors-highlighting-text-styles"
>Стилі підсвічування тексту</link
> <link linkend="config-dialog"
>діалогового вікна налаштування</link
>, типами ж &MIME; та суфіксами назв файлів, для яких буде використано таке підсвічування керує вкладка <link linkend="pref-open-save-modes-filetypes"
>Режими та типи файлів</link
>.</para>
<note>
<para
>Підсвічування можна використовувати для покращення візуального сприйняття тексту, але довірятися підсвічуванню під час перевірки коректності синтаксису тексту не слід. Синтаксична розмітка тексту є непростим завданням, складність якого залежить від формату тексту, — у деяких випадках, автори синтаксичних правил вважають успіхом правильний показ 98% тексту, хоча для того, щоб побачити 2% тексту з неправильним підсвічуванням, вам доведеться скористатися не дуже поширеним стилем.</para>
</note>
</sect2>
<sect2 id="katehighlight-system">
<title
>Система підсвічування синтаксису &kappname;</title>
<para
>У цьому розділі ми зосередимося на механізмах, які використовуються для підсвічування синтаксису у &kappname;. Відомості з цього розділу призначено для тих користувачів, яким цікаво дізнатися про роботу системи підсвічування синтаксису, або тих користувачів, які бажають змінити або створити нові визначення підсвічування синтаксису.</para>
<sect3 id="katehighlight-howitworks">
<title
>Як це працює</title>
<para
>Під час відкриття файла однією з перших дій, які виконує редактор &kappname;, є визначення правил підсвічування синтаксису для цього файла. Під час читання тексту з файла або отримання введених вами рядків система підсвічування синтаксису аналізуватиме текст на основі правил підсвічування синтаксису і позначатиме у показаному тексті позиції початку і завершення різних контекстів і стилів.</para>
<para
>Під час введення документа за допомогою клавіатури створений вами текст буде проаналізовано і розмічено на льоту, отже, якщо ви вилучите символ, які система розмітила як початок або завершення певного контексту, стиль сусідніх з поточним фрагментів тексту також змінюватиметься відповідно до зміни контексту.</para>
<para
>Визначення синтаксичних правил, які використовуються у системі підсвічування синтаксису &kappname;, є файлами &XML;, у яких містяться <itemizedlist>
<listitem
><para
>Правила для визначення ролі тексту, впорядковані у контекстні блоки</para
></listitem>
<listitem
><para
>Списки ключових слів</para
></listitem>
<listitem
><para
>Визначення елементів стилю</para
></listitem>
</itemizedlist>
</para>
<para
>Під час аналізу тексту правила визначення контексту застосовуватимуться у порядку, у якому ці правила було визначено у файлі визначень, — якщо початок поточного рядка відповідає певному правилу, буде використано відповідний контекст. Після цього початкову точку у тексті буде пересунуто у завершальну точку застосування визначеного правила і почнеться новий цикл пошуку відповідників правил в межах контексту, встановленого попереднім правилом.</para>
</sect3>
<sect3 id="highlight-system-rules">
<title
>Правила</title>
<para
>Правила визначення є основою системи визначення підсвічування. Кожне правило визначається рядком, символом або <link linkend="regular-expressions"
>формальним виразом</link
>, з яким порівнюватиметься текст документа. Правилом визначаються відомості, які буде використано під час визначення стилю відповідного фрагмента тексту. Правило може перемкнути поточний контекст системи підсвічування або на явно вказаний у правилі контекст або на попередній контекст, який було використано у тексті.</para>
<para
>Правила об’єднуються у контекстні групи. Кожна контекстна група реалізує основні елементи у відповідному форматі файлів, наприклад текстові рядки у лапках або блоки коментарів у файлах кодів програми. За такої структури системи підсвічування можна уникнути потреби у переборі всього набору правил, коли такий перебір не потрібен, а також мати можливість різного трактування деяких послідовностей символів у тексті, залежно від поточного контексту. </para>
<para
>Контексти можуть створюватися і динамічно, таким чином забезпечується використання у правилах особливостей даних документа.</para>
</sect3>
<sect3 id="highlight-context-styles-keywords">
<title
>Контекстні стилі і ключові слова</title>
<para
>У деяких мовах програмування цілі числа обробляються компілятором (програмою, яка перетворює початкові коди програми на бінарний файл програми) у спосіб, відмінний від способу обробки чисел з плаваючою крапкою, також у рядках, взятих у лапки, можуть бути символи зі спеціальним призначенням. У таких випадках було б доцільним виокремити подібні символи, щоб їх простіше було виявити під час читання коду. Отже, навіть якщо ці символи не мають окремого контексту, система підсвічування тексту показати їх так, неначе подібний контекст для них існує, тобто виокремити їх з-поміж навколишнього тексту.</para>
<para
>У визначенні синтаксису може бути довільна кількість стилів, достатня для визначення всіх елементів формату тексту, для якого це визначення було створено.</para>
<para
>У багатьох форматах існують списки слів, які відповідають певному елементу. Наприклад, у мовах програмування керівні команди складають один елемент, назви типів даних — другий, вбудовані функції мови — третій. Система підсвічування синтаксису &kappname; здатна використовувати такі списки для виявлення і позначення слів у тексті з метою підкреслення призначення елементів у текстових форматах.</para>
</sect3>
<sect3 id="kate-highlight-system-default-styles">
<title
>Типові стилі</title>
<para
>Якщо ви відкриєте файл кодів мовою C++, &Java; або документ <acronym
>HTML</acronym
> у &kappname;, ви переконаєтеся у тому, що, хоча формати цих файлів є різними, а отже у них використовуються різні слова для позначень елементів тексту, кольори, які буде використано програмою будуть тими самими. Причиною цього є існування у &kappname; наперед визначеного списку типових стилів, який використовується у окремих визначеннях синтаксису.</para>
<para
>Типові стилі спрощують розпізнавання подібних елементів у різних форматах тексту. Наприклад, коментарі передбачено майже у всіх мовах програмування, написання скриптів або мовах розмітки, отже, якщо їх буде показано у однаковому стилі у всіх форматах мов, вам не потрібно буде зупинятися і розмірковувати над тим, як виглядають коментарі у тексті документа.</para>
<tip>
<para
>Під час створення всіх стилів визначення синтаксису використовують один з типових стилів. У деякій частині визначень синтаксису використовуються додаткові стилі, яких немає серед типових, отже, якщо ви часто працюєте з файлами у таких форматах, доцільно відкрити діалогове вікно налаштування, щоб подивитися, чи не використовуються для певних елементів однакові стилі. Наприклад, існує лише один типовий стиль для рядків, але, оскільки у мові програмування Perl існує два типи рядків, ви можете налаштувати підсвічування для кожного з цих типів трохи по-різному. Огляд всіх <link linkend="kate-highlight-default-styles"
>можливих типових стилів</link
> буде наведено далі.</para>
</tip>
</sect3>
</sect2>
<sect2 id="katehighlight-xml-format">
<title
>Формат &XML; визначення підсвічування</title>
<sect3>
<title
>Огляд</title>
<para
>У &kappname; використовується бібліотека підсвічування синтаксичних конструкцій з &kde-frameworks;. Типово, до бібліотеки підсвічування синтаксичних конструкцій &kappname; включено засоби підсвічування коду &XML;. </para>
<para
>Цей розділ присвячено огляду формату &XML; визначення підсвічування. За допомогою невеличкого прикладу у розділі описано основні компоненти, їх призначення і використання. Далі ми докладно розглянемо правила визначення підсвічування синтаксису.</para>
<para
>Формальне визначення, також відоме як <acronym
>XSD</acronym
>, зберігається у <ulink url="https://commits.kde.org/syntax-highlighting?path=data/schema"
>сховищі підсвічування синтаксису</ulink
> у файлі <filename
>language.xsd</filename
>. </para>
<para
>Нетипові файли <filename class="extension"
>.xml</filename
> підсвічування синтаксису зберігаються у <filename class="directory"
>org.kde.syntax-highlighting/syntax/</filename
> у теці вашого користувача, у підтеці, назву якої можна визначити за допомогою команди <userinput
><command
>qtpaths</command
><option
>--paths GenericDataLocation</option
></userinput
>, зазвичай <filename class="directory"
><envar
>$HOME</envar
>/.local/share/</filename
> і <filename class="directory"
>/usr/share/</filename
>. </para>
<para
>Для пакунків Flatpak і Snap місце зберігання даних є різним для різних програм. У пакунках Flatpak нетипові файли &XML; зберігаються, зазвичай, у <filename class="directory"
><envar
>$HOME</envar
>/.var/app/<replaceable
>назва-пакунка-flatpak</replaceable
>/data/org.kde.syntax-highlighting/syntax/</filename
>, а у пакунках Snap — у <filename class="directory"
><envar
>$HOME</envar
>/snap/<replaceable
>назва-пакунка-snap</replaceable
>/current/.local/share/org.kde.syntax-highlighting/syntax/</filename
>. </para>
<para
>У &Windows; ці файли зберігаються у <filename
>%USERPROFILE%\AppData\Local\org.kde.syntax-highlighting\syntax</filename
>. <replaceable
>%USERPROFILE%</replaceable
> зазвичай є скороченням від <filename
>C:\Users\<replaceable
>користувач</replaceable
></filename
>.</para>
<para
>Загалом, для більшості конфігурацій каталогом нетипових файлів &XML; є такий каталог:</para>
<informaltable>
<tgroup cols="2">
<tbody>
<row>
<entry
>Для окремого користувача:</entry>
<entry
><filename class="directory"
><envar
>$HOME</envar
>/.local/share/org.kde.syntax-highlighting/syntax/</filename
></entry>
</row>
<row>
<entry
>Для усіх користувачів?</entry>
<entry
><filename class="directory"
>/usr/share/org.kde.syntax-highlighting/syntax/</filename
></entry>
</row>
<row>
<entry
>Для пакунків Flatpak:</entry>
<entry
><filename class="directory"
><envar
>$HOME</envar
>/.var/app/<replaceable
>назва-пакунка-flatpak</replaceable
>/data/org.kde.syntax-highlighting/syntax/</filename
></entry>
</row>
<row>
<entry
>Для пакунків Snap:</entry>
<entry
><filename class="directory"
><envar
>$HOME</envar
>/snap/<replaceable
>назва-пакунка-snap</replaceable
>/current/.local/share/org.kde.syntax-highlighting/syntax/</filename
></entry>
</row>
<row>
<entry
>У &Windows;:</entry>
<entry
><filename
>%USERPROFILE%\AppData\Local\org.kde.syntax-highlighting\syntax</filename
></entry>
</row>
</tbody>
</tgroup>
</informaltable>
<para
>Якщо для якоїсь мови існує декілька файлів, буде завантажено файл із найбільшим значенням атрибута <userinput
>version</userinput
> в елементі <userinput
>language</userinput
>.</para>
<variablelist>
<title
>Головні розділи файлів визначення підсвічування &kappname;</title>
<varlistentry>
<term
>Файл підсвічування містить заголовок, у якому встановлюється версія &XML;:</term>
<listitem>
<programlisting
><?xml version="1.0" encoding="UTF-8"?>
</programlisting>
</listitem>
</varlistentry>
<varlistentry>
<term
>Кореневим елементом файла визначення є елемент <userinput
>language</userinput
>. Серед можливих атрибутів:</term>
<listitem>
<para
>Обов’язкові атрибути:</para>
<para
><userinput
>name</userinput
> визначає назву мови. Цю назву буде згодом показано у пунктах меню та діалогових вікнах програми.</para>
<para
><userinput
>section</userinput
> визначає категорію.</para>
<para
><userinput
>extensions</userinput
> визначає суфікси назв файлів, на зразок "*.cpp;*.h"</para>
<para
><userinput
>version</userinput
> визначає поточну модифікацію файла визначень у форматі цілого числа. Кожного разу, коли ви вноситимете зміни до файла визначень правил підсвічування, вам слід збільшувати це число.</para>
<para
><userinput
>kateversion</userinput
> визначає найостаннішу з підтримуваних версій &kappname;.</para>
<para
>Необов’язкові атрибути:</para>
<para
><userinput
>mimetype</userinput
> прив’язує файли на основі типу &MIME;.</para>
<para
><userinput
>casesensitive</userinput
> визначає, чи розрізнятимуться ключові слова за регістром символів, чи ні.</para>
<para
><userinput
>priority</userinput
> потрібно вказати, якщо у іншому файлі визначення підсвічування використовуються ті самі суфікси файлів. Для підсвічування буде використано правила з вищим пріоритетом.</para>
<para
><userinput
>author</userinput
> повинен містити ім’я і адресу електронної пошти автора.</para>
<para
><userinput
>license</userinput
> повинен містити назву ліцензії нового файла підсвічування, зазвичай, MIT.</para>
<para
><userinput
>style</userinput
> має містити дані щодо мови програмування і використовується засобами додавання відступів для атрибута <literal
>required-syntax-style</literal
>.</para>
<para
><userinput
>indenter</userinput
> визначає, який із засобів додавання відступів у рядки буде використано типово. Доступні засоби додавання відступів: <emphasis
>ada, normal, cstyle, cmake, haskell, latex, lilypond, lisp, lua, pascal, python, replicode, ruby</emphasis
> та <emphasis
>xml</emphasis
>.</para>
<para
><userinput
>hidden</userinput
> визначає, чи має бути показано назву підсвічування у меню &kappname;.</para>
<para
>Отже, наступний рядок має виглядати десь так:</para>
<programlisting
><language name="C++" version="1" kateversion="2.4" section="Sources" extensions="*.cpp;*.h" />
</programlisting>
</listitem>
</varlistentry>
<varlistentry>
<term
>Наступним елементом є <userinput
>highlighting</userinput
>, у цьому елементі міститься необов’язковий елемент <userinput
>list</userinput
> і обов’язкові елементи <userinput
>contexts</userinput
> і <userinput
>itemDatas</userinput
>.</term>
<listitem>
<para
>Елементи <userinput
>list</userinput
> містять список ключових слів. У цьому випадку ключовими словами будуть <emphasis
>class</emphasis
> і <emphasis
>const</emphasis
>. У разі потреби ви можете додати довільну кількість списків.</para>
<para
>Починаючи з &kde-frameworks; 5.53, до списку можна включати ключові слова з іншого списку або мови чи файла за допомогою елемента <userinput
>include</userinput
>. Для відокремлення назви списку та назви визначення мови слід використовувати <userinput
>##</userinput
> у той самий спосіб, що і у правилі <userinput
>IncludeRules</userinput
>. Ця можливість є корисною для уникнення дублювання списків ключових слів, якщо вам потрібно включити ключові слова з іншої мови або файла. Наприклад, у списку <emphasis
>othername</emphasis
> міститься ключове слово <emphasis
>str</emphasis
> і усі ключові слова списку <emphasis
>types</emphasis
>, який належить до мови програмування <emphasis
>ISO C++</emphasis
>.</para>
<para
>У елементі <userinput
>contexts</userinput
> містяться всі контексти. Типово, першим контекстом є початок діапазону підсвічування. У контексті <emphasis
>Normal Text</emphasis
> існує два правила: перше визначає список ключових слів з назвою <emphasis
>somename</emphasis
> і правило для визначення лапок і перемикання контексту на контекст <emphasis
>string</emphasis
>. Докладніше правила буде розглянуто у наступній главі.</para>
<para
>Третя частина складається з елемента <userinput
>itemDatas</userinput
>. У цьому елементі містяться всі кольори і гарнітури шрифтів, потрібні для контекстів і правил. У нашому випадку було використано <userinput
>itemData</userinput
> <emphasis
>Normal Text</emphasis
>, <emphasis
>String</emphasis
> і <emphasis
>Keyword</emphasis
>. </para>
<programlisting
><highlighting>
<list name="somename">
<item>class</item>
<item>const</item>
</list>
<list name="othername">
<item>str</item>
<include>types##ISO C++</include>
</list>
<contexts>
<context attribute="Normal Text" lineEndContext="#pop" name="Normal Text" >
<keyword attribute="Keyword" context="#stay" String="somename" />
<keyword attribute="Keyword" context="#stay" String="othername" />
<DetectChar attribute="String" context="string" char="&quot;" />
</context>
<context attribute="String" lineEndContext="#stay" name="string" >
<DetectChar attribute="String" context="#pop" char="&quot;" />
</context>
</contexts>
<itemDatas>
<itemData name="Normal Text" defStyleNum="dsNormal" />
<itemData name="Keyword" defStyleNum="dsKeyword" />
<itemData name="String" defStyleNum="dsString" />
</itemDatas>
</highlighting>
</programlisting>
</listitem>
</varlistentry>
<varlistentry>
<term
>Останньою частиною визначення підсвічування є необов’язковий розділ <userinput
>general</userinput
>. У ньому можуть міститися відомості щодо ключових слів, згортання коду, коментарів, відступів, порожніх рядків та перевірки правопису.</term>
<listitem>
<para
>У розділі <userinput
>comment</userinput
> визначається послідовність символів, за допомогою якої можна додати однорядковий коментар. Крім того, ви можете визначати багаторядкові коментарі за допомогою елемента <emphasis
>multiLine</emphasis
> з додатковим атрибутом <emphasis
>end</emphasis
>. Ці визначення буде використано за виконання користувачем дій <emphasis
>закоментувати/розкоментувати</emphasis
>.</para>
<para
>У розділі <userinput
>keywords</userinput
> визначається те, чи слід враховувати регістр символів у списку ключових слів, чи ні. Інші атрибути буде описано далі за текстом.</para>
<para
>В інших розділах, <userinput
>folding</userinput
>, <userinput
>emptyLines</userinput
> і <userinput
>spellchecking</userinput
>, зазвичай, потреби немає. Пояснення щодо цих розділів наведено нижче.</para>
<programlisting
><general>
<comments>
<comment name="singleLine" start="#"/>
<comment name="multiLine" start="###" end="###" region="CommentFolding"/>
</comments>
<keywords casesensitive="1"/>
<folding indentationsensitive="0"/>
<emptyLines>
<emptyLine regexpr="\s+"/>
<emptyLine regexpr="\s*#.*"/>
</emptyLines>
<spellchecking>
<encoding char="á" string="\'a"/>
<encoding char="à" string="\`a"/>
</spellchecking>
</general>
</language>
</programlisting>
</listitem>
</varlistentry>
</variablelist>
</sect3>
<sect3 id="kate-highlight-sections">
<title
>Докладно про розділи</title>
<para
>У цій частині описано всі доступні атрибути для контекстів, itemDatas, ключових слів, коментарів, згортання коду і відступів.</para>
<variablelist>
<varlistentry>
<term
>Елемент <userinput
>context</userinput
> належить до групи <userinput
>contexts</userinput
>. Цей елемент визначає специфічні для контексту правила, на зразок того, що має трапитися, якщо система підсвічування досягне кінця рядка. Серед можливих атрибутів:</term>
<listitem>
<para
><userinput
>name</userinput
> — назва контексту. За допомогою цієї назви правила визначатимуть контекст, на який слід перемкнутися у випадку виявлення відповідника правила.</para>
<para
><userinput
>lineEndContext</userinput
> визначає контекст, на який має перемкнутися система підсвічування у разі досягнення кінця рядка. Значенням може бути назва іншого контексту, <userinput
>#stay</userinput
> означатиме, що контекст не слід перемикати (тобто нічого не робити), або <userinput
>#pop</userinput
> означатиме, що слід вийти з контексту. Наприклад, можна скористатися значенням <userinput
>#pop#pop#pop</userinput
> для того, щоб система після виходу піднялася на три контексти вище, або навіть <userinput
>#pop#pop!ІншийКонтекст</userinput
>, щоб піднятися на два контексти вище і перемкнутися на контекст з назвою <userinput
>ІншийКонтекст</userinput
>. Також можна перемкнутися на контекст, який належить визначенню іншої мови, так само, як у правилах <userinput
>IncludeRules</userinput
>, наприклад, <userinput
>ЯкийсьКонтекст##JavaScript</userinput
>. Зауважте, що цей перемикач контексту не можна використовувати у поєднанні із <userinput
>#pop</userinput
>. Наприклад, <userinput
>#pop!ЯкийсьКонтекст##JavaScript</userinput
> є некоректним. Перемикачі контексту також описано у розділі <xref linkend="kate-highlight-rules-detailled"/>.</para>
<para
><userinput
>lineEmptyContext</userinput
> визначає контекст, якщо буде знайдено порожній рядок. Номенклатура перемикань контексту є такою самою, як і раніше описано для <emphasis
>lineEndContext</emphasis
>. Типове значення: #stay.</para>
<para
><userinput
>fallthroughContext</userinput
> вказує наступний контекст для перемикання, якщо жодне з правил не є відповідним. Номенклатура перемикань контексту є такою самою, як і раніше описано для <emphasis
>lineEndContext</emphasis
>. Типове значення: #stay.</para>
<para
><userinput
>fallthrough</userinput
> визначає, чи перемикатиметься система підсвічування на контекст, визначений у <userinput
>fallthroughContext</userinput
>, якщо жодне з правил не буде визнано відповідним. Зауважте, що з версії &kde; &frameworks; 5.62 цей атрибут є застарілим. Замість нього слід використовувати <userinput
>fallthroughContext</userinput
>, оскільки якщо вказано атрибут <userinput
>fallthroughContext</userinput
>, неявним чином припускатиметься значення <userinput
>fallthrough</userinput
> рівне <emphasis
>true</emphasis
>. Типове значення: <emphasis
>false</emphasis
>.</para>
<para
><userinput
>noIndentationBasedFolding</userinput
> вимикає згортання на основі відступів у контексті. Якщо згортання на основі відступів не увімкнено, цей атрибут не має сенсу. Цей атрибут визначається у елементі <emphasis
>folding</emphasis
> групи <emphasis
>general</emphasis
>. Типове значення: <emphasis
>false</emphasis
>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term
>Елемент <userinput
>itemData</userinput
> знаходиться у групі <userinput
>itemDatas</userinput
>. За його допомогою визначаються тип шрифту і кольори. Таким чином можна визначати власні типи шрифтів і кольори, але ми рекомендуємо, за можливості, використовувати лише типові стилі так, щоб користувач завжди бачив однакові кольори у файлах різних форматів. Все ж іноді іншого способу не існує, і вам доведеться змінити колір і атрибути шрифту. Обов’язковими атрибутами є name і defStyleNum, інші атрибути є необов’язковими. Серед можливих атрибутів:</term>
<listitem>
<para
><userinput
>name</userinput
> визначає назву itemData. Цю назву буде використано у контекстах і правилах для посилання на itemData у атрибуті <emphasis
>attribute</emphasis
>.</para>
<para
><userinput
>defStyleNum</userinput
> визначає, який тип слід використовувати типово. Докладний перелік можливих типових стилів ви знайдете нижче.</para>
<para
><userinput
>color</userinput
> визначає колір. Можливі формати: '#rrggbb' і '#rgb'.</para>
<para
><userinput
>selColor</userinput
> визначає колір виділеного тексту.</para>
<para
><userinput
>italic</userinput
>, якщо має значення <emphasis
>true</emphasis
>, шрифт буде курсивним.</para>
<para
><userinput
>bold</userinput
>, якщо має значення <emphasis
>true</emphasis
>, шрифт тексту буде напівжирним.</para>
<para
><userinput
>underline</userinput
>: якщо цей атрибут має значення <emphasis
>true</emphasis
>, текст буде підкреслено.</para>
<para
><userinput
>strikeout</userinput
>, якщо цей параметр має значення <emphasis
>true</emphasis
>, текст буде перекреслено.</para>
<para
><userinput
>spellChecking</userinput
>: якщо цей атрибут має значення <emphasis
>true</emphasis
>, правопис тексту буде перевірено.</para>
</listitem>
</varlistentry>
<varlistentry>
<term
>Елемент <userinput
>keywords</userinput
> у групі <userinput
>general</userinput
> визначає властивості ключових слів. Серед можливих атрибутів:</term>
<listitem>
<para
><userinput
>casesensitive</userinput
>, може приймати значення <emphasis
>true</emphasis
> або <emphasis
>false</emphasis
>. Якщо має значення <emphasis
>true</emphasis
>, пошук ключових слів відбуватиметься з врахуванням регістру символів.</para>
<para
><userinput
>weakDeliminator</userinput
> — це список символів, які не є символами відокремлення слів. Наприклад, крапка <userinput
>«.»</userinput
> є символом відокремлення слів. Припустімо тепер, що ключове слово у <userinput
>list</userinput
> містить крапку, тоді це слово буде задіяно, лише якщо ви вкажете крапку серед значень цього аргументу.</para>
<para
><userinput
>additionalDeliminator</userinput
> визначає додаткові символи розмітки.</para>
<para
><userinput
>wordWrapDeliminator</userinput
> визначає символи, після яких можна розривати рядок.</para>
<para
>Типовими символами розмітки і символами відокремлення слів є символи <userinput
>.():!+,-<=>%&*/;?[]^{|}~\</userinput
>, пробіл (<userinput
>' '</userinput
>) і символ табуляції (<userinput
>'\t'</userinput
>).</para>
</listitem>
</varlistentry>
<varlistentry>
<term
>Елемент <userinput
>comment</userinput
> у групі <userinput
>comments</userinput
> визначає властивості коментаря, які буде використано для дій за пунктами меню <menuchoice
><guimenu
>Інструменти</guimenu
> <guimenuitem
>Закоментувати</guimenuitem
></menuchoice
>, <menuchoice
><guimenu
>Інструменти</guimenu
> <guimenuitem
>Розкоментувати</guimenuitem
></menuchoice
> and <menuchoice
><guimenu
>Інструменти</guimenu
><guimenuitem
>Додати або вилучити коментування</guimenuitem
></menuchoice
>. Серед доступних атрибутів:</term>
<listitem>
<para
><userinput
>name</userinput
>: може мати значення <emphasis
>singleLine</emphasis
> або <emphasis
>multiLine</emphasis
>. Якщо буде обрано варіант <emphasis
>multiLine</emphasis
>, слід буде також вказати атрибути <emphasis
>end</emphasis
> і <emphasis
>region</emphasis
>. Якщо ви виберете <emphasis
>singleLine</emphasis
>, ви зможете додати необов'язковий атрибут <emphasis
>position</emphasis
>.</para>
<para
><userinput
>start</userinput
> визначає рядок, який використовується для позначення початку коментаря. У C++ цим рядком для багаторядкових коментарів є "/*". Цей атрибут є обов'язковим для типів <emphasis
>multiLine</emphasis
> і <emphasis
>singleLine</emphasis
>.</para>
<para
><userinput
>end</userinput
> визначає рядок, яким завершуватиметься коментар. У C++ цим рядком буде "*/". Цей атрибути є доступним лише для коментарів типу <emphasis
>multiLine</emphasis
> і є для них обов'язковим.</para>
<para
>Атрибут <userinput
>region</userinput
> повинен мати значення назви придатного для згортання багаторядкового коментаря. Припустімо, що у правилах вказано <emphasis
>beginRegion="Comment"</emphasis
> ... <emphasis
>endRegion="Comment"</emphasis
>, тоді вам слід взяти значення <emphasis
>region="Comment"</emphasis
>. За допомогою цього атрибута можна користуватися дією з розкоментування, навіть якщо було виділено не весь текст багаторядкового коментаря. Потрібно лише, щоб курсор знаходився всередині цього багаторядкового коментаря. Цей атрибут є доступним лише для типу <emphasis
>multiLine</emphasis
>.</para>
<para
><userinput
>position</userinput
> визначає місце вставлення однорядкового коментування. Типово, однорядкове коментування буде вставлено на початку рядка у позиції 0, але якщо ви скористаєтеся записом <emphasis
>position="afterwhitespace"</emphasis
>, коментування буде вставлено праворуч після першого пробільного блоку, перед першим непробільним символом. Ця можливість є корисною для мов, де важливими є відступи у рядках, зокрема Python та YAML. Цей атрибут є необов'язковим, його єдиним можливим значенням є <emphasis
>afterwhitespace</emphasis
>. Цей атрибут є доступним лише для типу <emphasis
>singleLine</emphasis
>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term
>Елемент <userinput
>folding</userinput
> у групі <userinput
>general</userinput
> призначено для визначення властивостей згортання коду. Серед можливих атрибутів:</term>
<listitem>
<para
><userinput
>indentationsensitive</userinput
>: якщо має значення <emphasis
>true</emphasis
>, позначки згортання коду буде додано на основі відступів, так, як це робиться у скриптовій мові Python. Зазвичай, вам не потрібно буде встановлювати цей атрибут, оскільки його типовим значенням є <emphasis
>false</emphasis
>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term
>Елемент <userinput
>emptyLine</userinput
> у групі <userinput
>emptyLines</userinput
> визначає, які з рядків слід вважати порожніми. За його допомогою можна змінити поведінку атрибута <emphasis
>lineEmptyContext</emphasis
> в елементах <userinput
>context</userinput
>. Наявні атрибути:</term>
<listitem>
<para
><userinput
>regexpr</userinput
> визначає формальний вираз, відповідник якого вважатиметься порожнім рядком. Типово, порожні рядки не містять жодних символів, тому цей формальний вираз додає «порожні» рядки, наприклад, якщо ви хочете вважати рядки з пробілів порожніми. Втім, здебільшого, для визначення синтаксису у цьому атрибуті немає потреби.</para>
</listitem>
</varlistentry>
<varlistentry>
<term
>Елемент <userinput
>encoding</userinput
> у групі <userinput
>spellchecking</userinput
> визначає кодування символів для перевірки правопису. Наявні атрибути:</term>
<listitem>
<para
><userinput
>char</userinput
> — кодований символ.</para>
<para
><userinput
>string</userinput
> — послідовність символів, яку буде закодовано як символ <emphasis
>char</emphasis
> при перевірці правопису. Наприклад, якщо виконується обробка коду мовою LaTeX, рядок <userinput
>\"{A}</userinput
> відповідатиме символу <userinput
>Ä</userinput
>.</para>
</listitem>
</varlistentry>
</variablelist>
</sect3>
<sect3 id="kate-highlight-default-styles">
<title
>Можливі типові стилі</title>
<para
>Ви <link linkend="kate-highlight-system-default-styles"
>вже обговорювали</link
> типові стилі у короткому резюме: типовими стилями є наперед визначені набори з гарнітур шрифтів та кольорів.</para>
<variablelist>
<varlistentry>
<term
>Загальні типові стилі:</term>
<listitem>
<para
><userinput
>dsNormal</userinput
>, якщо непотрібне спеціальне підсвічування.</para>
<para
><userinput
>dsKeyword</userinput
>, вбудовані ключові слова мови.</para>
<para
><userinput
>dsFunction</userinput
>, виклики і визначення функцій.</para>
<para
><userinput
>dsVariable</userinput
>, якщо застосовне: назви змінних (наприклад $someVar у PHP/Perl).</para>
<para
><userinput
>dsControlFlow</userinput
>, ключові слова керування обробкою, зокрема if, else, switch, break, return, yield, ...</para>
<para
><userinput
>dsOperator</userinput
>, оператори, зокрема + - * / :: < ></para>
<para
><userinput
>dsBuiltIn</userinput
>, вбудовані функції, класи і об’єкти.</para>
<para
><userinput
>dsExtension</userinput
>, загальні розширення, зокрема класи &Qt; та функції і макроси у C++ та Python.</para>
<para
><userinput
>dsPreprocessor</userinput
>, інструкції препроцесора або визначення макросів.</para>
<para
><userinput
>dsAttribute</userinput
>, анотації, зокрема @override та __declspec(...).</para>
</listitem>
</varlistentry>
<varlistentry>
<term
>Типові стилі, пов’язані із рядками:</term>
<listitem>
<para
><userinput
>dsChar</userinput
>, окремі символи, зокрема 'x'.</para>
<para
><userinput
>dsSpecialChar</userinput
>, символи із спеціальним призначенням у рядках, зокрема символи екранування, замінники або оператори формальних виразів.</para>
<para
><userinput
>dsString</userinput
>, рядки, зокрема "hello world".</para>
<para
><userinput
>dsVerbatimString</userinput
>, буквальні або необроблювані рядки, зокрема «raw \backlash» у Perl, CoffeeScript та командних оболонках, а також r'\raw' у Python.</para>
<para
><userinput
>dsSpecialString</userinput
>, SQL, формальні вирази, документація HERE, математичний режим &latex;...</para>
<para
><userinput
>dsImport</userinput
>, імпорт, включення або потреба у модулях.</para>
</listitem>
</varlistentry>
<varlistentry>
<term
>Пов’язані із числами типові стилі:</term>
<listitem>
<para
><userinput
>dsDataType</userinput
>, вбудовані типи даних, наприклад int, void, u64.</para>
<para
><userinput
>dsDecVal</userinput
>, десяткові значення.</para>
<para
><userinput
>dsBaseN</userinput
>, величини у численні з основою, відмінною від 10.</para>
<para
><userinput
>dsFloat</userinput
>, значення із рухомою крапкою.</para>
<para
><userinput
>dsConstant</userinput
>, вбудовані та визначені користувачем сталі, наприклад PI.</para>
</listitem>
</varlistentry>
<varlistentry>
<term
>Типові стилі, пов’язані із коментаріми та документацією:</term>
<listitem>
<para
><userinput
>dsComment</userinput
>, коментарі.</para>
<para
><userinput
>dsDocumentation</userinput
>, /** Коментарі у документації */ або """docstrings""".</para>
<para
><userinput
>dsAnnotation</userinput
>, команди документації, зокрема @param, @brief.</para>
<para
><userinput
>dsCommentVar</userinput
>, назви змінних, використаних у попередніх командах, зокрема «foobar» у @param foobar.</para>
<para
><userinput
>dsRegionMarker</userinput
>, позначки області, зокрема //BEGIN, //END у коментарях.</para>
</listitem>
</varlistentry>
<varlistentry>
<term
>Інші типові стилі:</term>
<listitem>
<para
><userinput
>dsInformation</userinput
>, нотатки і підказки, наприклад @note у doxygen.</para>
<para
><userinput
>dsWarning</userinput
>, попередження, наприклад @warning у doxygen.</para>
<para
><userinput
>dsAlert</userinput
>, спеціальні слова, наприклад TODO, FIXME, XXXX.</para>
<para
><userinput
>dsError</userinput
>, підсвічування помилок та синтаксичних неточностей.</para>
<para
><userinput
>dsOthers</userinput
>, якщо інше не є застосовним.</para>
</listitem>
</varlistentry>
</variablelist>
</sect3>
</sect2>
<sect2 id="kate-highlight-rules-detailled">
<title
>Правила визначення способу підсвічування</title>
<para
>Цей розділ присвячено опису правил визначення синтаксису.</para>
<para
>Кожне з правил може відповідати нульовій або більшій кількості символів на початку рядка, у якому шукатиметься відповідник правила. Якщо такий відповідник буде знайдено, знайдені символи визначать стиль або <emphasis
>attribute</emphasis
>, вказані за допомогою правила, правило також може надіслати системі запит на зміну поточного контексту.</para>
<para
>Правило виглядає так:</para>
<programlisting
><НазваПравила attribute="(ідентифікатор)" context="(ідентифікатор)" [специфічні для правила атрибути] /></programlisting>
<para
>Значення <emphasis
>attribute</emphasis
> визначає назву стилю, який буде використано для відповідних символів, а значення <emphasis
>context</emphasis
> визначає контекст, який слід використовувати, починаючи з цього місця.</para>
<para
><emphasis
>context</emphasis
> може бути визначено за допомогою:</para>
<itemizedlist>
<listitem>
<para
><emphasis
>Ідентифікатора</emphasis
>, який є назвою іншого контексту.</para>
</listitem>
<listitem>
<para
>Значення <emphasis
>порядку</emphasis
>, яке повідомляє рушієві, чи слід залишатися у поточному контексті (<userinput
>#stay</userinput
>), чи слід повернутися до попереднього контексту, використаного у рядку (<userinput
>#pop</userinput
>).</para>
<para
>Щоб повернутися на декілька рівнів контексту назад, ключове слово #pop можна повторити декілька разів: <userinput
>#pop#pop#pop</userinput
></para>
</listitem>
<listitem>
<para
>Значення <emphasis
>порядку</emphasis
>, після якого вказано знак оклику (<emphasis
>!</emphasis
>), та значення <emphasis
>ідентифікатора</emphasis
>, яке змусить рушій спочатку використати порядок, а потім перемкнутися на інший контекст, наприклад <userinput
>#pop#pop!OtherContext</userinput
>.</para>
</listitem>
<listitem>
<para
><emphasis
>Ідентифікатор</emphasis
>, який є назвою контексту, за яким вказано два символи решітки (<userinput
>##</userinput
>) і ще один <emphasis
>ідентифікатор</emphasis
>, який є назвою визначення мови. Таке іменування є подібним до використаного у правилах <userinput
>IncludeRules</userinput
>. Воно надає вам змогу перемкнутися на контекст, що належить іншому визначення підсвічування синтаксису, наприклад, <userinput
>ЯкийсьКонтекст##JavaScript</userinput
>. Зауважте, що не можна використовувати цей перемикач контексту у поєднанні із <userinput
>#pop</userinput
>. Наприклад, запис <userinput
>#pop!ЯкийсьКонтекст##JavaScript</userinput
> є некоректним.</para>
</listitem>
</itemizedlist>
<para
>Специфічні для правила атрибути можуть бути різними, їх описано у наступних розділах.</para>
<itemizedlist>
<title
>Загальні атрибути</title>
<para
>Всі правила мають перелічені нижче атрибути, їх можна вказувати всюди, де ви побачите напис <userinput
>(загальні атрибути)</userinput
> у списку. Атрибути <emphasis
>attribute</emphasis
> і <emphasis
>context</emphasis
> є обов’язковими атрибутами, всі інші атрибути є необов’язковими. </para>
<listitem>
<para
><emphasis
>attribute</emphasis
>: атрибут, що вказує на визначені <emphasis
>itemData</emphasis
>.</para>
</listitem>
<listitem>
<para
><emphasis
>context</emphasis
>: визначає контекст, на який слід перемкнути систему підсвічування у разі виявлення відповідника правила.</para>
</listitem>
<listitem>
<para
><emphasis
>beginRegion</emphasis
>: почати блок згортання коду. Типове значення: unset.</para>
</listitem>
<listitem>
<para
><emphasis
>endRegion</emphasis
>: закрити блок згортання коду. Типове значення: unset.</para>
</listitem>
<listitem>
<para
><emphasis
>lookAhead</emphasis
>: якщо має значення <emphasis
>true</emphasis
>, система підсвічування не оброблятиме довжину відповідника. Типове значення: <emphasis
>false</emphasis
>.</para>
</listitem>
<listitem>
<para
><emphasis
>firstNonSpace</emphasis
>: відповідність встановлюватиметься, лише якщо рядок є першою відмінною від пробілів послідовністю символів у рядку тексту. Типове значення: <emphasis
>false</emphasis
>.</para>
</listitem>
<listitem>
<para
><emphasis
>column</emphasis
>: збіг буде зареєстровано, якщо збігатиметься рядок. Типове значення: unset.</para>
</listitem>
</itemizedlist>
<itemizedlist>
<title
>Динамічні правила</title>
<para
>Деякі з правил надають змогу встановлювати додатковий атрибут, <userinput
>dynamic</userinput
>, булівського типу з типовим значенням <emphasis
>false</emphasis
>. Якщо атрибут dynamic має значення <emphasis
>true</emphasis
>, у правилі можна використовувати заповнювачі, які позначають текст, знайдений за допомогою правила <emphasis
>формального виразу</emphasis
>, текст буде перемкнуто у поточний контекст у його атрибутах <userinput
>string</userinput
> або <userinput
>char</userinput
>. У атрибуті <userinput
>string</userinput
> заповнювач <replaceable
>%N</replaceable
> (де N — ціле число) буде замінено на відповідний елемент <replaceable
>N</replaceable
> з виклику формального виразу, починаючи з 1. У атрибуті <userinput
>char</userinput
> заповнювач повинен бути числом <replaceable
>N</replaceable
>, його буде замінено на перший символ відповідного елемента <replaceable
>N</replaceable
> з виклику формального виразу. Всі правила, які дозволяють використання цього атрибута, буде позначено написом <emphasis
>(dynamic)</emphasis
>.</para>
<listitem>
<para
><emphasis
>dynamic</emphasis
>: може мати значення <emphasis
>(true|false)</emphasis
>.</para>
</listitem>
</itemizedlist>
<para
><userinput
>Як це працює:</userinput
></para>
<para
>У <link linkend="regular-expressions"
>формальних виразах</link
> правил <userinput
>RegExpr</userinput
> засіб обробки захоплює і запам'ятовує увесь текст у простих круглих дужках — <userinput
>(ШАБЛОН)</userinput
>. Захоплені фрагменти тексту можна використовувати у контексті, до якого перемикається засіб, у правилах із атрибутом <userinput
>dynamic</userinput
> <emphasis
>true</emphasis
> для заміни <replaceable
>%N</replaceable
> (у <emphasis
>String</emphasis
>) або <replaceable
>N</replaceable
> (у <emphasis
>char</emphasis
>).</para>
<para
>Важливо пам'ятати, що фрагмент тексту, який захоплено у правилі <userinput
>RegExpr</userinput
>, зберігається лише у перемкнутому контексті, який вказано за допомогою атрибута <userinput
>context</userinput
> елемента.</para>
<tip>
<itemizedlist>
<listitem>
<para
>Якщо у запам'ятовуванні фрагментів тексту немає потреби для побудови динамічних правил або самого формального виразу, слід використовувати <userinput
>групування без захоплення</userinput
>: <userinput
>(?:ШАБЛОН)</userinput
></para>
<para
>Захоплення груп із <emphasis
>пошуком вперед</emphasis
> і <emphasis
>пошуком назад</emphasis
>, зокрема за допомогою формальних виразів <userinput
>(?=ШАБЛОН)</userinput
>, <userinput
>(?!ШАБЛОН)</userinput
> або <userinput
>(?<=ШАБЛОН)</userinput
>, не відбуватиметься. Щоб дізнатися більше, ознайомтеся з розділом <link linkend="regular-expressions"
>Формальні вирази</link
>.</para>
</listitem>
<listitem>
<para
>Захоплені групи можна використовувати у межах того самого формального виразу за допомогою рядка <replaceable
>\N</replaceable
> замість <replaceable
>%N</replaceable
>. Щоб дізнатися про це більше, ознайомтеся із розділом <link linkend="regex-capturing"
>Збереження знайденого тексту (зворотні посилання)</link
> у главі <link linkend="regular-expressions"
>Формальні вирази</link
>.</para>
</listitem>
</itemizedlist>
</tip>
<para
>Приклад 1:</para>
<para
>У цьому простому прикладі обробник захоплює текст, який відповідає формальному виразу <userinput
>=*</userinput
>, і вставляє його замість <replaceable
>%1</replaceable
> у динамічному правилі. Таким чином можна визначити коментар, який завершується тією самою кількістю символів <userinput
>=</userinput
>, що і починається. Відповідним текстом буде <userinput
>[[ коментар ]]</userinput
>, <userinput
>[=[ коментар ]=]</userinput
> та <userinput
>[=====[ коментар ]=====]</userinput
>.</para>
<para
>Крім того, захоплені дані доступні лише у перемкнутому контексті <emphasis
>Multi-line Comment</emphasis
>.</para>
<programlisting
><context name="Normal" attribute="Normal Text" lineEndContext="#stay">
<RegExpr context="Multi-line Comment" attribute="Comment" String="\[(=*)\[" beginRegion="RegionComment"/>
</context>
<context name="Multi-line Comment" attribute="Comment" lineEndContext="#stay">
<StringDetect context="#pop" attribute="Comment" String="]%1]" dynamic="true" endRegion="RegionComment"/>
</context>
</programlisting>
<para
>Приклад 2:</para>
<para
>У динамічному правилі <replaceable
>%1</replaceable
> відповідає захопленому фрагменту тексту, який відповідає шаблону <userinput
>#+</userinput
>, а <replaceable
>%2</replaceable
> — шаблону <userinput
>&quot;+</userinput
>. Отже, відповідний фрагмент тексту буде таким: <userinput
>#мітка""""у контексті""""#</userinput
>.</para>
<para
>Захопленими даними не можна буде скористатися у інших контекстах, зокрема <emphasis
>OtherContext</emphasis
>, <emphasis
>FindEscapes</emphasis
> або <emphasis
>SomeContext</emphasis
>.</para>
<programlisting
><context name="SomeContext" attribute="Normal Text" lineEndContext="#stay">
<RegExpr context="#pop!NamedString" attribute="String" String="(#+)(?:[\w-]|[^[:ascii:]])(&quot;+)"/>
</context>
<context name="NamedString" attribute="String" lineEndContext="#stay">
<RegExpr context="#pop!OtherContext" attribute="String" String="%2(?:%1)?" dynamic="true"/>
<DetectChar context="FindEscapes" attribute="Escape" char="\"/>
</context>
</programlisting>
<para
>Приклад 3:</para>
<para
>Цей запис відповідає тексту, подібному до такого: <userinput
>Class::function<T>( ... )</userinput
>.</para>
<programlisting
><context name="Normal" attribute="Normal Text" lineEndContext="#stay">
<RegExpr context="FunctionName" lookAhead="true"
String="\b([a-zA-Z_][\w-]*)(::)([a-zA-Z_][\w-]*)(?:&lt;[\w\-\s]*&gt;)?(\()"/>
</context>
<context name="FunctionName" attribute="Normal Text" lineEndContext="#pop">
<StringDetect context="#stay" attribute="Class" String="%1" dynamic="true"/>
<StringDetect context="#stay" attribute="Operator" String="%2" dynamic="true"/>
<StringDetect context="#stay" attribute="Function" String="%3" dynamic="true"/>
<DetectChar context="#pop" attribute="Normal Text" char="4" dynamic="true"/>
</context>
</programlisting>
<itemizedlist>
<title
>Локальні роздільники</title>
<para
>У деяких правилах можна скористатися додатковими атрибутами <userinput
>weakDeliminator</userinput
> і <userinput
>additionalDeliminator</userinput
>, які поєднуються із атрибутами із тією самою назвою теґу <userinput
>keywords</userinput
>. Наприклад, якщо <userinput
>'%'</userinput
> є слабким роздільником <userinput
>keywords</userinput
>, він може стати роздільником слів лише для певного правила, якщо його додати до атрибута <userinput
>additionalDeliminator</userinput
> цього правила. Якщо правило дозволяє ці атрибути, воно містить запис <emphasis
>(локальні роздільники)</emphasis
>.</para>
<listitem>
<para
><emphasis
>weakDeliminator</emphasis
>: список символів, які не є роздільниками слів.</para>
</listitem>
<listitem>
<para
><emphasis
>additionalDeliminator</emphasis
>: визначає додаткові роздільники.</para>
</listitem>
</itemizedlist>
<sect3 id="highlighting-rules-in-detail">
<title
>Докладно про правила</title>
<variablelist>
<varlistentry>
<term
>DetectChar</term>
<listitem>
<para
>Перевірка на рівність одному певному символу. Зазвичай, використовується для пошуку кінця рядків, взятих у лапки.</para>
<programlisting
><DetectChar char="(символ)" (загальні атрибути) (dynamic) /></programlisting>
<para
>Атрибут <userinput
>char</userinput
> визначає символ, з яким відбуватиметься порівняння.</para>
</listitem>
</varlistentry>
<varlistentry>
<term
>Detect2Chars</term>
<listitem>
<para
>Перевірка на рівність двом певним символам у вказаному порядку.</para>
<programlisting
><Detect2Chars char="(символ)" char1="(символ)" (загальні атрибути) /></programlisting>
<para
>Атрибут <userinput
>char</userinput
> визначає перший символ для порівняння, <userinput
>char1</userinput
> — другий.</para>
</listitem>
</varlistentry>
<varlistentry>
<term
>AnyChar</term>
<listitem>
<para
>Перевірка на рівність одному з символів вказаного набору.</para>
<programlisting
><AnyChar String="(рядок)" (загальні атрибути) /></programlisting>
<para
>Атрибут <userinput
>String</userinput
> визначає набір символів.</para>
</listitem>
</varlistentry>
<varlistentry>
<term
>StringDetect</term>
<listitem>
<para
>Перевірка на рівність вказаному рядку.</para>
<programlisting
><StringDetect String="(рядок)" [insensitive="true|false"] (загальні атрибути) (dynamic) /></programlisting>
<para
>Атрибут <userinput
>String</userinput
> визначає рядок для порівняння. Типовим значенням атрибута <userinput
>insensitive</userinput
> є <emphasis
>false</emphasis
>, цей атрибут передається функції порівняння рядків. Якщо значенням атрибута буде <emphasis
>true</emphasis
>, порівняння відбуватиметься без врахування регістру.</para>
</listitem>
</varlistentry>
<varlistentry>
<term
>WordDetect</term>
<listitem>
<para
>Виявити рядок, але з додатковою вимогою щодо меж слів, зокрема крапки, <userinput
>'.'</userinput
>, або пробілу на початку або у кінці слова. Обробка <userinput
>\b<рядок>\b</userinput
> відбувається подібно до формального виразу, але виконується швидше за обробку правила <userinput
>RegExpr</userinput
>.</para>
<programlisting
><WordDetect String="(рядок)" [insensitive="true|false"] (загальні атрибути) (локальні роздільники) /></programlisting>
<para
>Атрибут <userinput
>String</userinput
> визначає рядок для порівняння. Типовим значенням атрибута <userinput
>insensitive</userinput
> є <emphasis
>false</emphasis
>, цей атрибут передається функції порівняння рядків. Якщо значенням атрибута буде <emphasis
>true</emphasis
>, порівняння відбуватиметься без врахування регістру.</para>
<para
>Починаючи з &kate; 3.5 (&kde; 4.5)</para>
</listitem>
</varlistentry>
<varlistentry>
<term
>RegExpr</term>
<listitem>
<para
>Перевірка на збіг з формальним виразом.</para>
<programlisting
><RegExpr String="(рядок)" [insensitive="true|false"] [minimal="true|false"] (загальні атрибути) (dynamic) /></programlisting>
<para
>Атрибут <userinput
>String</userinput
> визначає формальний вираз.</para>
<para
>Типовим значенням атрибута <userinput
>insensitive</userinput
> є <emphasis
>false</emphasis
>, цей атрибут передається рушію пошуку за формальним виразом.</para>
<para
>Типовим значенням атрибута <userinput
>minimal</userinput
> є <emphasis
>false</emphasis
>, цей атрибут буде передано рушієві пошуку за формальним виразом.</para>
<para
>Оскільки пошук відповідників для застосування правила завжди відбувається на початку поточного рядка, формальний вираз, що починається з символу каретки (<literal
>^</literal
>) вказує на те, що пошук відповідника правила слід виконувати лише на початку рядка.</para>
<para
>Щоб дізнатися більше, ознайомтеся з розділом <link linkend="regular-expressions"
>Формальні вирази</link
>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term
>keyword</term>
<listitem>
<para
>Перевірка на рівність ключовому слову з вказаного списку.</para>
<programlisting
><keyword String="(назва списку)" (загальні атрибути) (локальні роздільники) /></programlisting>
<para
>Атрибут <userinput
>String</userinput
> визначає назву списку ключових слів. Список з вказаною назвою має існувати.</para>
<para
>Система підсвічування обробляє правила ключових слів у дуже оптимізований спосіб. Тому абсолютно необхідно, щоб усі ключові слова, які слід знайти, було обмежено визначеними роздільниками, заздалегідь передбаченими (типовими роздільниками) або явно визначеними у властивості <emphasis
>additionalDeliminator</emphasis
> теґу <emphasis
>keywords</emphasis
>.</para>
<para
>Якщо ключове слово, яке слід знайти, має містити символ роздільника, відповідний символ слід додати до властивості <emphasis
>weakDeliminator</emphasis
> теґу <emphasis
>keywords</emphasis
>. Після цього символ втратить властивість роздільності у всіх правилах <emphasis
>keyword</emphasis
>. Також можна скористатися атрибутом <emphasis
>weakDeliminator</emphasis
> теґу <emphasis
>keyword</emphasis
> так, щоб ці конкретні зміни застосовувалися лише до цього конкретного правила.</para>
</listitem>
</varlistentry>
<varlistentry>
<term
>Int</term>
<listitem>
<para
>Виявлення цілого числа (формальний вираз: <userinput
>\b[0-9]+</userinput
>).</para>
<para
><programlisting
><Int (загальні атрибути) (локальні роздільники) /></programlisting
></para>
<para
>У цього правила немає особливих атрибутів.</para>
</listitem>
</varlistentry>
<varlistentry>
<term
>Float</term>
<listitem>
<para
>Виявлення числа із рухомою крапкою (формальний вираз: <userinput
>(\b[0-9]+\.[0-9]*|\.[0-9]+)([eE][-+]?[0-9]+)?</userinput
>).</para>
<para
><programlisting
><Float (загальні атрибути) (локальні роздільники) /></programlisting
></para>
<para
>У цього правила немає особливих атрибутів.</para>
</listitem>
</varlistentry>
<varlistentry>
<term
>HlCOct</term>
<listitem>
<para
>Виявлення вісімкового представлення числа (формальний вираз: <userinput
>\b0[0-7]+</userinput
>).</para>
<para
><programlisting
><HlCOct (загальні атрибути) (локальні роздільники) /></programlisting
></para>
<para
>У цього правила немає особливих атрибутів.</para>
</listitem>
</varlistentry>
<varlistentry>
<term
>HlCHex</term>
<listitem>
<para
>Виявлення шістнадцяткового представлення числа (формальний вираз: <userinput
>\b0[xX][0-9a-fA-F]+</userinput
>).</para>
<para
><programlisting
><HlCHex (загальні атрибути) (локальні роздільники) /></programlisting
></para>
<para
>У цього правила немає особливих атрибутів.</para>
</listitem>
</varlistentry>
<varlistentry>
<term
>HlCStringChar</term>
<listitem>
<para
>Перевірка на відповідність символу керівної послідовності.</para>
<para
><programlisting
><HlCStringChar (загальні атрибути) /></programlisting
></para>
<para
>У цього правила немає особливих атрибутів.</para>
<para
>Перевірка на відповідність символам, які часто використовуються у коді програм, наприклад <userinput
>\n</userinput
> (перехід на новий рядок) або <userinput
>\t</userinput
> (табуляція).</para>
<para
>Пошук буде виконуватися за переліченими далі символами, якщо ці символи стоять одразу за зворотною навскісною рискою (<literal
>\</literal
>): <userinput
>abefnrtv"'?\</userinput
>. Крім того, відповідними вважатимуться шістнадцяткові числа, наприклад <userinput
>\xff</userinput
>, і екрановані вісімкові числа, наприклад <userinput
>\033</userinput
>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term
>HlCChar</term>
<listitem>
<para
>Перевірка на відповідність символу C.</para>
<para
><programlisting
><HlCChar (загальні атрибути) /></programlisting
></para>
<para
>У цього правила немає особливих атрибутів.</para>
<para
>Перевірка на відповідність символам C, взятим у одинарні лапки (Приклад: <userinput
>'c'</userinput
>). Отже, у таких лапках може бути простий символ або екранований символ. Щоб дізнатися про пошук екранованих послідовностей символів, перегляньте пункт для HlCStringChar.</para>
</listitem>
</varlistentry>
<varlistentry>
<term
>RangeDetect</term>
<listitem>
<para
>Перевірка на відповідність рядку з вказаними початковим і кінцевим символами.</para>
<programlisting
><RangeDetect char="(символ)" char1="(символ)" (загальні атрибути) /></programlisting>
<para
><userinput
>char</userinput
> визначає символ, який повинен починати діапазон символів, <userinput
>char1</userinput
> — символ, який має завершувати діапазон.</para>
<para
>Корисно для виявлення, наприклад, невеличких рядків у лапках, але зауважте, що, оскільки рушій підсвічування обробляє за раз лише один рядок, у такий спосіб неможливо знайти рядки у лапках, які розбито між декількома рядками документа.</para>
</listitem>
</varlistentry>
<varlistentry>
<term
>LineContinue</term>
<listitem>
<para
>Перевірка на відповідність вказаному символу наприкінці рядка.</para>
<programlisting
><LineContinue (загальні атрибути) [char="\"] /></programlisting>
<para
>Необов’язковий для встановлення відповідності атрибут <userinput
>char</userinput
>, типовим значенням є символ зворотної риски (<userinput
>'\'</userinput
>). Впроваджено з &kde; 4.13.</para>
<para
>Це правило корисне для перемикання контексту наприкінці рядка. Це потрібно, зокрема, у коді мовами C/C++ для продовження макросів або рядків.</para>
</listitem>
</varlistentry>
<varlistentry>
<term
>IncludeRules</term>
<listitem>
<para
>Включити правила з іншого контексту або мови/файла.</para>
<programlisting
><IncludeRules context="посилання на контекст" [includeAttrib="true|false"] /></programlisting>
<para
>Атрибут <userinput
>context</userinput
> визначає контекст, який слід включити.</para>
<para
>Якщо значенням є простий рядок, у поточний контекст буде включено всі визначені правила, наприклад: <programlisting
><IncludeRules context="anotherContext" /></programlisting
></para>
<para
>Якщо у рядку міститься послідовність символів <userinput
>##</userinput
>, система підсвічування шукатиме контекст у іншому визначенні мови з вказаною назвою. Приклад: <programlisting
><IncludeRules context="String##C++" /></programlisting
> включить контекст <emphasis
>String</emphasis
> з визначення правил підсвічування для <emphasis
>C++</emphasis
>.</para>
<para
>Якщо атрибут <userinput
>includeAttrib</userinput
> матиме значення <emphasis
>true</emphasis
>, атрибут призначення буде змінено на атрибут джерела. Це потрібно для того, щоб, наприклад, виконати коментування, якщо текст, що відповідає знайденому контексту, має інше підсвічування, ніж текст у основному контексті. </para>
</listitem>
</varlistentry>
<varlistentry>
<term
>DetectSpaces</term>
<listitem>
<para
>Пошук пробілів.</para>
<programlisting
><DetectSpaces (загальні атрибути) /></programlisting>
<para
>У цього правила немає особливих атрибутів.</para>
<para
>Цим правилом можна скористатися, якщо вам точно відомо, що перед текстом рядка має бути декілька пробілів, наприклад, на початку рядків з відступом. За допомогою цього правила можна пропустити одразу всі пробіли, замість послідовної перевірки на основі декількох правил, кожне з яких надаватиме змогу відкидати по одному пробілу за один прийом через невідповідність.</para>
</listitem>
</varlistentry>
<varlistentry>
<term
>DetectIdentifier</term>
<listitem>
<para
>Пошук рядків ідентифікаторів (зокрема формальних виразів: <userinput
>[a-zA-Z_][a-zA-Z0-9_]*</userinput
>).</para>
<programlisting
><DetectIdentifier (загальні атрибути) /></programlisting>
<para
>У цього правила немає особливих атрибутів.</para>
<para
>Це правило слід використовувати для пропуску рядка з символів, які складають слова, замість послідовної перевірки на основі декількох правил, кожне з яких надаватиме змогу відкидати по одному символу за один прийом через невідповідність.</para>
</listitem>
</varlistentry>
</variablelist>
</sect3>
<sect3>
<title
>Підказки та поради</title>
<itemizedlist>
<para
>Після того, як ви зрозумієте роботу інструменту перемикання контексту, ви зможете писати власні визначення підсвічування. Але вам завжди слід з обережністю ставитися до вибору правил. Формальні вирази є дуже потужним, але досить повільним у порівнянні з іншими, інструментом. Отже, скористайтесь наведеними нижче підказками. </para>
<listitem>
<para
>Якщо вам потрібно перевірити відповідність лише двом символам, скористайтеся правилом <userinput
>Detect2Chars</userinput
>, замість правила <userinput
>StringDetect</userinput
>. Те саме стосується правила <userinput
>DetectChar</userinput
>.</para>
</listitem>
<listitem>
<para
>Формальними виразами просто користуватися, але часто існує інший, набагато швидший спосіб досягти результату. Припустімо вам потрібно перевірити, чи є символ <userinput
>'#'</userinput
> першим символом рядка. Вирішення на основі формального виразу має виглядати десь так: <programlisting
><RegExpr attribute="Macro" context="macro" String="^\s*#" /></programlisting
> Того самого результату можна досягти набагато швидше за допомогою такого правила: <programlisting
><DetectChar attribute="Macro" context="macro" char="#" firstNonSpace="true" /></programlisting
> Якщо вам потрібно знайти формальний вираз <userinput
>'^#'</userinput
> ви знову ж таки можете скористатися правилом <userinput
>DetectChar</userinput
> з атрибутом <userinput
>column="0"</userinput
>. Відлік значення атрибута <userinput
>column</userinput
> засновано на кількості символів, отже табуляція вважатиметься лише одним символом. </para>
</listitem>
<listitem>
<para
>У правилах <userinput
>RegExpr</userinput
> користуйтеся атрибутом <userinput
>column="0"</userinput
>, якщо буде використано шаблон <userinput
>^ШАБЛОН</userinput
> для встановлення відповідності тексту на початку рядка. У таких спосіб ви пришвидшите обробку, оскільки у засобу обробки не буде потреби у пошуку у решті позицій рядка.</para>
</listitem>
<listitem>
<para
>У формальних виразах користуйтеся групуванням без захоплення — <userinput
>(?:ШАБЛОН)</userinput
>, замість групування із захопленням — <userinput
>(ШАБЛОН)</userinput
>, якщо захоплені дані не буде використано у тому самому формальному виразі або у динамічних правилах. Таким чином, ви уникнете непотрібного зберігання даних.</para>
</listitem>
<listitem>
<para
>Ви можете перемикати контексти без обробки символів тексту. Припустімо, що вам потрібно перемкнути контекст у разі виявлення рядка <userinput
>*/</userinput
>, але також слід обробити цей рядок у наступному контексті. Ви можете скористатися наведеним нижче правилом, у якому атрибут <userinput
>lookAhead</userinput
> призведе до того, що інструмент визначення підсвічування збереже знайдений рядок для обробки у наступному контексті. <programlisting
><Detect2Chars attribute="Comment" context="#pop" char="*" char1="/" lookAhead="true" /></programlisting>
</para>
</listitem>
<listitem>
<para
>Скористайтеся <userinput
>DetectSpaces</userinput
>, якщо вам відома точна кількість пробілів.</para>
</listitem>
<listitem>
<para
>Скористайтеся <userinput
>DetectIdentifier</userinput
> замість формального виразу <userinput
>'[a-zA-Z_]\w*'</userinput
>.</para>
</listitem>
<listitem>
<para
>За можливості, використовуйте типові стилі. Таким чином, ви полегшите користувачеві призвичаювання до середовища.</para>
</listitem>
<listitem>
<para
>Зазирайте до інших файлів &XML;, щоб дізнатися як інші люди реалізують складні правила.</para>
</listitem>
<listitem>
<para
>Ви можете перевірити коректність будь-якого файла &XML; за допомогою команди <command
>validatehl.sh language.xsd mySyntax.xml</command
>. Файли <filename
>validatehl.sh</filename
> і <filename
>language.xsd</filename
> зберігаються у <ulink url="https://commits.kde.org/syntax-highlighting?path=data/schema"
>сховищі бібліотеки підсвічування синтаксичних конструкцій</ulink
>. </para>
</listitem>
<listitem>
<para
>Якщо у вашому файлі часто вживаються складні формальні вирази, ви можете скористатися визначенням <emphasis
>ENTITIES</emphasis
>. Приклад:</para>
<programlisting
><?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE language SYSTEM "language.dtd"
[
<!ENTITY myref "[A-Za-z_:][\w.:_-]*">
]>
</programlisting>
<para
>Після такого визначення ви зможете використовувати <emphasis
>&myref;</emphasis
> замість формального виразу.</para>
</listitem>
</itemizedlist>
</sect3>
</sect2>
</sect1>
<sect1 id="color-themes">
<title
>Робота із темами кольорів</title>
<sect2 id="color-themes-overview">
<title
>Огляд</title>
<para
>Теми кольорів визначають кольори <link linkend="kate-part"
>області редагування тексту</link
> і <link linkend="highlight"
>підсвічування синтаксису</link
>. До теми кольорів включено такі дані: <itemizedlist>
<listitem
><para
>Стиль тексту, який використано для підсвічування синтаксису в <emphasis
>атрибутах типових стилів</emphasis
>. Наприклад, колір тексту і колір позначеного тексту.</para
></listitem>
<listitem
><para
>Тло області редагування тексту, включно із позначенням тексту та поточним рядком.</para
></listitem>
<listitem
><para
>Рамка піктограм для текстової області: тло піктограм, лінія роздільника, номери рядків, позначки перенесення рядків, позначки змінених рядків та згортання коду.</para
></listitem>
<listitem
><para
>Декорації тексту, зокрема позначки пошуку, позначки відступів та табуляцій або пробілів, позначення відповідних дужок та розмітка при перевірці правопису.</para
></listitem>
<listitem
><para
>Закладки і фрагменти.</para
></listitem>
</itemizedlist>
</para>
<para
>Щоб уникнути непорозумінь, це не стосується таких параметрів інтерфейсу: <itemizedlist>
<listitem
><para
>Гарнітури і розміру символів шрифту.</para
></listitem>
<listitem
><para
>Кольорів у програмі для редагування тексту, зокрема на карті смужки гортання, у меню, на панелі вкладок, кольору вікна тощо. У програмах &kde;, зокрема &kate; або &kdevelop;, ці кольори визначаються <userinput
>загальною схемою кольорів Плазми &kde;</userinput
>, яка визначається у <ulink url="help:/kcontrol/colors/"
>модулі «Кольори» програми «Системні параметри»</ulink
>, або у самій програмі, у меню <menuchoice
><guimenu
>Параметри</guimenu
><guisubmenu
>Схема кольорів</guisubmenu
></menuchoice
>. </para
></listitem>
</itemizedlist>
</para>
<mediaobject>
<imageobject
><imagedata format="PNG" fileref="breeze-color-theme-preview.png"/></imageobject>
<textobject
><phrase
>Схеми кольорів <quote
>Світла Breeze</quote
> і <quote
>Темна Breeze</quote
> із підсвічуванням синтаксису <quote
>C++</quote
>.</phrase>
</textobject>
<caption
><para
>Схеми кольорів <quote
>Світла Breeze</quote
> і <quote
>Темна Breeze</quote
> із підсвічуванням синтаксису <quote
>C++</quote
>.</para>
</caption>
</mediaobject>
</sect2>
<sect2 id="color-themes-ksyntaxhighlighting">
<title
>Теми кольорів KSyntaxHighlighting</title>
<para
>Бібліотека <ulink url="https://api.kde.org/frameworks/syntax-highlighting/html/"
>KSyntaxHighlighting</ulink
>, яка є рушієм <link linkend="highlight"
>підсвічування синтаксису</link
> — це бібліотека, яка <userinput
>надає доступ до тем кольорів і керує ними</userinput
>. Вона є частиною &kde; &frameworks;, її використовують текстові редактори &kde;, зокрема <ulink url="https://apps.kde.org/en/kate"
>&kate;</ulink
>, <ulink url="https://apps.kde.org/en/kwrite"
>&kwrite;</ulink
>, <ulink url="https://apps.kde.org/en/kile"
>&kile;</ulink
> та <ulink url="https://apps.kde.org/en/kdevelop"
>&kdevelop;</ulink
>. Ця залежність виглядає так:</para>
<mediaobject>
<imageobject
><imagedata format="PNG" fileref="kf5-ksyntaxhighlighting.png"/></imageobject>
<textobject
><phrase
>Залежність від бібліотек &kde; &frameworks; 5 у текстових редакторах.</phrase
></textobject>
<caption
><para
>Залежність від бібліотек &kde; &frameworks; у текстових редакторах.</para>
</caption>
</mediaobject>
<para
>До KSyntaxHighlighting включено діапазон вбудованих тем, список яких показано на <ulink url="https://kate-editor.org/themes/"
>сторінці <quote
>Теми кольорів</quote
> сайта редактора Kate</ulink
>.</para>
<para
>Бібліотека <ulink url="https://api.kde.org/frameworks/ktexteditor/html/"
>KTextEditor</ulink
>, яка є рушієм текстового редактора, надає у розпорядження користувача інтерфейс для створення та редагування схем кольорів, включно із інструментом для імпортування та експортування тем. Ця бібліотека є найпростішим засобом для створення і редагування тем. Отримати доступ до бібліотеки можна за допомогою <link linkend="config-dialog"
>діалогового вікна <quote
>Налаштувати</quote
></link
> текстового редактора. Докладніше про це у розділі <xref linkend="color-themes-gui"/>.</para>
<mediaobject>
<imageobject
><imagedata format="PNG" fileref="color-themes-gui-breeze-dark-default-text-styles.png"/></imageobject>
<textobject
><phrase
>Графічний інтерфейс для керування темами кольорів у параметрах &kate;.</phrase
></textobject>
<caption
><para
>Графічний інтерфейс для керування темами кольорів у параметрах &kate;.</para>
</caption>
</mediaobject>
<para
>Варто згадати про те, що у текстових редакторах &kde;, зокрема &kate; або &kdevelop;, теми кольорів KSyntaxHighlighting використовують з <ulink url="https://kate-editor.org/post/2020/2020-09-13-kate-color-themes-5.75/"
>&kde; &frameworks; 5.75</ulink
>, випущених 10 жовтня 2020 року. До цієї версії використовували схеми кольорів &kate; (налаштування схеми на основі KConfig), які тепер вважаються застарілими. Втім старі схеми &kate; можна перетворити на схеми кольорів KSyntaxHighlighting. У <ulink url="https://invent.kde.org/frameworks/syntax-highlighting"
>сховищі коду KSyntaxHighlighting</ulink
> для виконання цього завдання є скрипт <userinput
>utils/kateschema_to_theme_converter.py</userinput
> і допоміжна програма <userinput
>utils/schema-converter/</userinput
>. </para>
</sect2>
<sect2 id="color-themes-json">
<title
>Формат &JSON; схем кольорів</title>
<sect3 id="color-themes-json-overview">
<title
>Огляд</title>
<para
>Теми кольорів зберігаються у файлах у форматі &JSON; із суфіксом назви <userinput
>.theme</userinput
>.</para>
<para
>У <ulink url="https://invent.kde.org/frameworks/syntax-highlighting"
>сховищі початкового коду KSyntaxHighlighting</ulink
> файли &JSON; вбудованих тем зберігаються у каталозі <userinput
>data/themes/</userinput
>. Зауважте, що у текстових редакторах вбудовані теми скомпільовано до бібліотеки KSyntaxHighlighting. Тому для доступу до них потрібен початковий код або <link linkend="color-themes-gui-import-export"
>експортування з графічного інтерфейсу для керування темами у KTextEditor</link
>.</para>
<para
>Також можна без проблем додавати нетипові теми, які завантажуватимуться з файлової системи комп'ютера. Налаштовані користувачами теми зберігаються у каталозі <filename class="directory"
>org.kde.syntax-highlighting/themes/</filename
> теки користувача. Визначити розташування теки можна за допомогою команди <userinput
><command
>qtpaths</command
><option
> --paths GenericDataLocation</option
></userinput
>. Типовими теками є <filename class="directory"
><envar
>$HOME</envar
>/.local/share/</filename
> і <filename class="directory"
>/usr/share/</filename
>. </para>
<para
>Для пакунків Flatpak і Snap місце зберігання даних є різним для різних програм. У пакунках Flatpak нетипові файли тем зберігаються, зазвичай, у <filename class="directory"
><envar
>$HOME</envar
>/.var/app/<replaceable
>назва-пакунка-flatpak</replaceable
>/data/org.kde.syntax-highlighting/themes/</filename
>, у пакунках Snap — у <filename class="directory"
><envar
>$HOME</envar
>/snap/<replaceable
>назва-пакунка-snap</replaceable
>/current/.local/share/org.kde.syntax-highlighting/themes/</filename
>. </para>
<para
>У &Windows; ці файли зберігаються у <filename
>%USERPROFILE%\AppData\Local\org.kde.syntax-highlighting\themes</filename
>. <replaceable
>%USERPROFILE%</replaceable
>, зазвичай, є каталогом <filename
>C:\Users\<replaceable
>користувач</replaceable
></filename
>.</para>
<para
>Загалом, для більшості конфігурацій каталогом нетипових тем є такий каталог:</para>
<informaltable>
<tgroup cols="2">
<tbody>
<row>
<entry
>Для окремого користувача:</entry>
<entry
><filename class="directory"
><envar
>$HOME</envar
>/.local/share/org.kde.syntax-highlighting/themes/</filename
></entry>
</row>
<row>
<entry
>Для усіх користувачів?</entry>
<entry
><filename class="directory"
>/usr/share/org.kde.syntax-highlighting/themes/</filename
></entry>
</row>
<row>
<entry
>Для пакунків Flatpak:</entry>
<entry
><filename class="directory"
><envar
>$HOME</envar
>/.var/app/<replaceable
>назва-пакунка-flatpak</replaceable
>/data/org.kde.syntax-highlighting/themes/</filename
></entry>
</row>
<row>
<entry
>Для пакунків Snap:</entry>
<entry
><filename class="directory"
><envar
>$HOME</envar
>/snap/<replaceable
>назва-пакунка-snap</replaceable
>/current/.local/share/org.kde.syntax-highlighting/themes/</filename
></entry>
</row>
<row>
<entry
>У &Windows;:</entry>
<entry
><filename
>%USERPROFILE%\AppData\Local\org.kde.syntax-highlighting\themes</filename
></entry>
</row>
</tbody>
</tgroup>
</informaltable>
<para
>Якщо існує декілька файлів теми із однаковими назвами, буде завантажено файл із найбільшим значенням <userinput
>revision</userinput
>. </para>
</sect3>
<sect3 id="color-themes-json-basic">
<title
>Структура &JSON;</title>
<para
>Структуру файла &JSON; описано на <ulink url="https://www.json.org"
>відповідному сайті</ulink
>. Загалом, файл формату &JSON; складається з таких елементів: <itemizedlist>
<listitem
><para
>Збірки пар ключ-значення, відокремлених комами і згрупованих фігурними дужками <userinput
>{ }</userinput
>. Ці збірки ми називатимемо <quote
>об'єктами</quote
>.</para
></listitem>
<listitem
><para
>Упорядкованих списків значень, відокремлених комами і згрупованих квадратними дужками <userinput
>[ ]</userinput
>, які ми називатимемо <quote
>масивами</quote
>.</para
></listitem
></itemizedlist>
</para>
<para
>У цьому підручнику ми використовуватимемо термінологію <quote
>ключ</quote
>, <quote
>значення</quote
>, <quote
>об'єкт</quote
> і <quote
>масив</quote
>. Якщо ви вперше працюєте із файлами &JSON;, зрозуміти цю термінологію можна з наведених нижче прикладів. </para>
</sect3>
<sect3 id="color-themes-json-root">
<title
>Основні розділи файлів &JSON; теми кольорів</title>
<para
>Кореневий об'єкт файла &JSON; теми кольорів містить такі ключі схеми:</para>
<itemizedlist>
<listitem
><para
><userinput
>metadata</userinput
> — обов'язковий ключ. Значенням є об'єкт із метаданими теми, зокрема назвою, модифікацією та умовами ліцензування.</para>
<para
>Докладний опис наведено у розділі <xref linkend="color-themes-json-metadata"/>.</para>
</listitem>
<listitem
><para
><userinput
>editor-colors</userinput
> — обов'язковий ключ. Значенням є об'єкт із кольорами області редагування тексту, зокрема кольором тла, рамки піктограм та декорування тексту.</para>
<para
>Докладний опис наведено у розділі <xref linkend="color-themes-editor-colors"/>.</para>
</listitem>
<listitem
><para
><userinput
>text-styles</userinput
> — обов'язковий ключ. Значенням є об'єкт із атрибутами <emphasis
>типового стилю тексту</emphasis
> для підсвічування синтаксичних конструкцій. Кожен атрибути визначає власний <emphasis
>колір тексту</emphasis
>, <emphasis
>колір позначеного тексту</emphasis
>, а також, наприклад, те, чи буде шрифт <emphasis
>напівжирним</emphasis
> або <emphasis
>курсивним</emphasis
>. На стилі тексту можна посилатися з <link linkend="kate-highlight-default-styles"
>атрибутів файлів &XML; визначення синтаксису</link
>.</para>
<para
>Докладний опис наведено у розділі <xref linkend="color-themes-text-styles"/>.</para>
</listitem>
<listitem
><para
><userinput
>custom-styles</userinput
> — ключ не є обов'язковим. Визначає стилі тексту для атрибутів специфічних визначень підсвічування. Наприклад, у визначення підсвічування, зокрема для <userinput
>Python</userinput
> або <userinput
>Markdown</userinput
>, ви можете вказати інший стиль тексту, який матиме пріоритет над типовим, який визначено у <userinput
>text-styles</userinput
>.</para>
<para
>Докладний опис наведено у розділі <xref linkend="color-themes-custom-styles"/>.</para>
</listitem>
</itemizedlist>
<para
>У мові &JSON; не передбачено підтримки коментарів. Втім, ви можете скористатися необов'язковим ключем <userinput
>_comments</userinput
> у кореневому об'єкті для запису коментарів. Наприклад, якщо ви адаптуєте наявну тему, ви можете додати адресу сховища початкового матеріалу. Найпрактичнішим способом коментування є використання масиву рядків. </para>
<para
>Нижче наведено приклад файла для теми <quote
>Світла Breeze</quote
>. Ви можете зауважити, що, з метою зменшення розміру прикладу, об'єкти <userinput
>editor-colors</userinput
> і <userinput
>text-styles</userinput
> не містять усіх обов'язкових ключів. Переглянути увесь код <ulink url="https://invent.kde.org/frameworks/syntax-highlighting/-/blob/master/data/themes/breeze-light.theme"
>теми <quote
>Світла Breeze</quote
> можна у сховищі KSyntaxHighlighting</ulink
>. </para>
<programlisting
>{
"_comments": [
"This is a comment.",
"If this theme is an adaptation of another, put the link to the original repository."
],
"metadata": {
"name" : "Breeze Light",
"revision" : 5,
"copyright": [
"SPDX-FileCopyrightText: 2016 Volker Krause <vkrause@kde.org>",
"SPDX-FileCopyrightText: 2016 Dominik Haumann <dhaumann@kde.org>"
],
"license": "SPDX-License-Identifier: MIT"
},
"editor-colors": {
"BackgroundColor" : "#ffffff",
"CodeFolding" : "#94caef",
"BracketMatching" : "#ffff00",
"CurrentLine" : "#f8f7f6",
"IconBorder" : "#f0f0f0",
"IndentationLine" : "#d2d2d2",
"LineNumbers" : "#a0a0a0",
"CurrentLineNumber" : "#1e1e1e",
<replaceable
>The other editor color keys...</replaceable>
},
"text-styles": {
"Normal" : {
"text-color" : "#1f1c1b",
"selected-text-color" : "#ffffff",
"bold" : false,
"italic" : false,
"underline" : false,
"strike-through" : false
},
"Keyword" : {
"text-color" : "#1f1c1b",
"selected-text-color" : "#ffffff",
"bold" : true
},
"Function" : {
"text-color" : "#644a9b",
"selected-text-color" : "#452886"
},
"Variable" : {
"text-color" : "#0057ae",
"selected-text-color" : "#00316e"
},
<replaceable
>Інші ключі стилю тексту...</replaceable>
},
"custom-styles": {
"ISO C++": {
"Data Type": {
"bold": true,
"selected-text-color": "#009183",
"text-color": "#00b5cf"
},
"Keyword": {
"text-color": "#6431b3"
}
},
"YAML": {
"Attribute": {
"selected-text-color": "#00b5cf",
"text-color": "#00b5cf"
}
}
}
}
</programlisting>
</sect3>
<sect3 id="color-themes-json-metadata">
<title
>Метадані</title>
<para
>Об'єкт &JSON; ключа <userinput
>metadata</userinput
> містить відповідні відомості щодо теми. Цей об'єкт має такі ключі: <itemizedlist>
<listitem
><para
><userinput
>name</userinput
> — <emphasis
>рядкове</emphasis
> значення, яке визначає назву мови. Цю назву буде згодом показано у пунктах меню та діалогових вікнах програми. Є обов'язковим.</para
></listitem>
<listitem
><para
><userinput
>revision</userinput
> — <emphasis
>ціле</emphasis
> число, яке визначає поточну модифікацію файла теми. Коли ви оновлюєте файл теми, вам слід збільшувати це число. Ключ є обов'язковим.</para
></listitem>
<listitem
><para
><userinput
>license</userinput
> — <emphasis
>рядок</emphasis
>, який визначає умови ліцензування теми з використанням ідентифікатора <userinput
>SPDX-License-Identifier</userinput
> зі стандартного <ulink url="https://spdx.dev/"
>формату обміну умовами ліцензування SPDX</ulink
>. Ключ є необов'язковим.</para>
<para
>Із повним списком ідентифікаторів умов ліцензування SPDX можна ознайомитися <ulink url="https://spdx.org/licenses/"
>тут</ulink
>.</para
></listitem>
<listitem
><para
><userinput
>copyright</userinput
> — <emphasis
>масив</emphasis
> <emphasis
>рядків</emphasis
>, який визначає авторів теми з використанням ідентифікатора <userinput
>SPDX-FileCopyrightText</userinput
> зі стандартного <ulink url="https://spdx.dev/"
>формату обміну даними щодо умов ліцензування SPDX</ulink
>. Ключ є необов'язковим.</para
></listitem>
</itemizedlist>
</para>
<programlisting
>"metadata": {
"name" : "Breeze Light",
"revision" : 5,
"copyright": [
"SPDX-FileCopyrightText: 2016 Volker Krause <vkrause@kde.org>",
"SPDX-FileCopyrightText: 2016 Dominik Haumann <dhaumann@kde.org>"
],
"license": "SPDX-License-Identifier: MIT"
}
</programlisting>
</sect3>
</sect2>
<sect2 id="color-themes-editing">
<title
>Докладно про кольори</title>
<para
>У цьому розділі наведено докладні відомості щодо усіх доступних атрибутів кольорів і доступних параметрів кольорів.</para>
<sect3 id="color-themes-editor-colors">
<title
>Кольори редактора</title>
<para
>Відповідає кольорам <link linkend="kate-part"
>області редагування тексту</link
>.</para>
<para
>У <link linkend="color-themes-json"
>файлі &JSON; теми</link
> відповідний ключ, <userinput
>editor-colors</userinput
>, має значення <emphasis
>об'єкта</emphasis
>, кожен ключ якого вказує на колір атрибута у текстовому редакторі. Тут <userinput
>усі доступні ключі є обов'язковими</userinput
>. Їхніми значеннями є <userinput
>рядки</userinput
> шістнадцяткових кодів кольорів, наприклад <quote
>#00B5CF</quote
>. </para>
<para
>У <link linkend="color-themes-gui"
>графічному інтерфейсі керування темами KTextEditor</link
> ці атрибути можна змінювати на вкладці <userinput
><guilabel
>Кольори</guilabel
></userinput
>. </para>
<para
>Нижче наведено доступні ключі. Список ключів, які використано у <link linkend="color-themes-json"
>файлі &JSON;</link
>, наведено <emphasis
>напівжирним</emphasis
> шрифтом. У дужках подано назви, які використано у <link linkend="color-themes-gui"
>графічному інтерфейсі</link
>. </para>
<variablelist>
<varlistentry id="variable-prefcolors-colors-text-background">
<term
><guilabel
>Кольори тла редактора</guilabel
></term>
<listitem>
<variablelist>
<varlistentry id="variable-pref-colors-normal-text">
<term
><userinput
>BackgroundColor</userinput
> (<guilabel
>Область тексту</guilabel
>)</term>
<listitem
><para
>Це типовий колір тла для області редагування, він буде домінуючим кольором у області редагування.</para>
<mediaobject>
<imageobject
><imagedata format="PNG" fileref="editor-colors-BackgroundColor.png"/></imageobject>
<caption
><para
></para
></caption>
</mediaobject>
</listitem>
</varlistentry>
<varlistentry id="variable-pref-colors-selected-text">
<term
><userinput
>TextSelection</userinput
> (<guilabel
>Позначений текст</guilabel
>)</term>
<listitem
><para
>Це тло позначеного тексту. </para>
<mediaobject>
<imageobject
><imagedata format="PNG" fileref="editor-colors-TextSelection.png"/></imageobject>
<caption
><para
></para
></caption>
</mediaobject>
</listitem>
</varlistentry>
<varlistentry id="variable-pref-colors-current-line">
<term
><userinput
>CurrentLine</userinput
> (<guilabel
>Поточний рядок</guilabel
>)</term>
<listitem
><para
>Встановлює колір для поточного рядка. Якщо встановити колір, який трошки відрізнятиметься від звичайного кольору тла тексту, вам буде легше фокусуватися на поточному рядку. </para>
<mediaobject>
<imageobject
><imagedata format="PNG" fileref="editor-colors-CurrentLine.png"/></imageobject>
<caption
><para
></para
></caption>
</mediaobject>
</listitem>
</varlistentry>
<varlistentry id="variable-pref-colors-search-highlight">
<term
><userinput
>SearchHighlight</userinput
> (<guilabel
>Підсвічування результатів пошуку</guilabel
>)</term>
<listitem
><para
>Встановлює колір позначення фрагментів тексту, які відповідають критеріям останнього сеансу пошуку. </para>
<mediaobject>
<imageobject
><imagedata format="PNG" fileref="editor-colors-SearchHighlight.png"/></imageobject>
<caption
><para
></para
></caption>
</mediaobject>
</listitem>
</varlistentry>
<varlistentry id="variable-pref-colors-replace-highlight">
<term
><userinput
>ReplaceHighlight</userinput
> (<guilabel
>Підсвічування замін</guilabel
>)</term>
<listitem
><para
>Встановлює колір позначення фрагментів тексту, які відповідають критеріям останнього сеансу заміни.</para>
<mediaobject>
<imageobject
><imagedata format="PNG" fileref="editor-colors-ReplaceHighlight.png"/></imageobject>
<caption
><para
></para
></caption>
</mediaobject>
</listitem>
</varlistentry>
</variablelist>
</listitem>
</varlistentry>
<varlistentry id="variable-prefcolors-colors-icon-border">
<term
><guilabel
>Смужка піктограм</guilabel
></term>
<listitem>
<variablelist>
<varlistentry>
<term
><userinput
>IconBorder</userinput
> (<guilabel
>Область тла</guilabel
>)</term>
<listitem
><para
>Цей колір буде використано для позначок, номерів рядків та рамок поміток згортання у лівій частині області перегляду редактора, якщо їх буде показано. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><userinput
>LineNumbers</userinput
> (<guilabel
>Номери рядків</guilabel
>)</term>
<listitem
><para
>Цей колір буде використано для показу номерів рядків у лівій частині області перегляду, якщо такі номери буде показано.</para
></listitem>
</varlistentry>
<varlistentry>
<term
><userinput
>CurrentLineNumber</userinput
> (<guilabel
>Номер поточного рядка</guilabel
>)</term>
<listitem
><para
>Цей колір буде використано для показу номера поточного рядка, якщо його показано у лівій частині області перегляду. Встановлення трохи іншого значення, порівняно із <quote
>LineNumbers</quote
>, допоможе акцентувати поточний рядок. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><userinput
>Separator</userinput
> (<guilabel
>Роздільник</guilabel
>)</term>
<listitem
><para
>Цей колір буде використано для малювання вертикальної лінії, яка відокремлюватиме рамку піктограм від тла області тексту.</para>
<mediaobject>
<imageobject
><imagedata format="PNG" fileref="editor-colors-IconBorder.png"/></imageobject>
<caption
><para
></para
></caption>
</mediaobject>
</listitem>
</varlistentry>
<varlistentry>
<term
><userinput
>WordWrapMarker</userinput
> (<guilabel
>Позначки перенесення слів</guilabel
>)</term>
<listitem
><para
>Цей колір буде використано для візерунка у лівій частині динамічно перенесених рядків, якщо такі рядки вирівняно вертикально, а також для позначення статичного перенесення слів.</para>
<mediaobject>
<imageobject
><imagedata format="PNG" fileref="editor-colors-WordWrapMarker.png"/></imageobject>
<caption
><para
></para
></caption>
</mediaobject>
</listitem>
</varlistentry>
<varlistentry>
<term
><userinput
>CodeFolding</userinput
> (<guilabel
>Згортання коду</guilabel
>)</term>
<listitem
><para
>Цей колір використовується для підсвічування розділу коду, який буде згорнуто, якщо ви натиснете стрілочку згортання коду у лівій частині документа Щоб дізнатися більше, зверніться до розділу, присвяченого <link linkend="advanced-editing-tools-code-folding"
>згортанню коду</link
>.</para>
<mediaobject>
<imageobject
><imagedata format="PNG" fileref="editor-colors-CodeFolding.png"/></imageobject>
<caption
><para
></para
></caption>
</mediaobject>
</listitem>
</varlistentry>
<varlistentry>
<term
><userinput
>ModifiedLines</userinput
> (<guilabel
>Змінені рядки</guilabel
>)</term>
<listitem
><para
>Встановлює колір, який буде використано для позначення на лівій панелі документа рядків, у які було внесено ще не збережені зміни. Щоб дізнатися більше, зверніться до розділу <xref linkend="kate-part-line-modification"/>.</para
></listitem>
</varlistentry>
<varlistentry>
<term
><userinput
>SavedLines</userinput
> (<guilabel
>Збережені рядки</guilabel
>)</term>
<listitem
><para
>Встановлює колір, який буде використано для позначення на лівій панелі документа рядків, у які було внесено вже збережені зміни. Щоб дізнатися більше, зверніться до розділу <xref linkend="kate-part-line-modification"/>.</para>
<mediaobject>
<imageobject
><imagedata format="PNG" fileref="editor-colors-ModifiedLines.png"/></imageobject>
<caption
><para
></para
></caption>
</mediaobject>
</listitem>
</varlistentry>
</variablelist>
</listitem>
</varlistentry>
<varlistentry id="variable-prefcolors-colors-text-decorations">
<term
><guilabel
>Декорування тексту</guilabel
></term>
<listitem>
<variablelist>
<varlistentry>
<term
><userinput
>SpellChecking</userinput
> (<guilabel
>Рядок з помилкою правопису</guilabel
>)</term>
<listitem
><para
>Встановлює колір позначення помилок правопису.</para>
<mediaobject>
<imageobject
><imagedata format="PNG" fileref="editor-colors-SpellChecking.png"/></imageobject>
<caption
><para
></para
></caption>
</mediaobject>
</listitem>
</varlistentry>
<varlistentry>
<term
><userinput
>TabMarker</userinput
> (<guilabel
>Позначки табуляції та пробілів</guilabel
>)</term>
<listitem
><para
>Цей колір буде використано для показу позначок пробілів, якщо такі позначки увімкнено.</para>
<mediaobject>
<imageobject
><imagedata format="PNG" fileref="editor-colors-TabMarker.png"/></imageobject>
<caption
><para
></para
></caption>
</mediaobject>
</listitem>
</varlistentry>
<varlistentry>
<term
><userinput
>IndentationLine</userinput
> (<guilabel
>Лінія відступу</guilabel
>)</term>
<listitem
><para
>Цей колір використовується для малювання лінії ліворуч від блоків з відступом, якщо <link linkend="appearance-general"
>увімкнено відповідну можливість</link
>.</para>
<mediaobject>
<imageobject
><imagedata format="PNG" fileref="editor-colors-IndentationLine.png"/></imageobject>
<caption
><para
></para
></caption>
</mediaobject>
</listitem>
</varlistentry>
<varlistentry>
<term
><userinput
>BracketMatching</userinput
> (<guilabel
>Підсвічування дужок</guilabel
>)</term>
<listitem
><para
>Цей колір буде використано для показу тла відповідних одна одній дужок. </para>
<mediaobject>
<imageobject
><imagedata format="PNG" fileref="editor-colors-BracketMatching.png"/></imageobject>
<caption
><para
></para
></caption>
</mediaobject>
</listitem>
</varlistentry>
</variablelist>
</listitem>
</varlistentry>
<varlistentry id="variable-prefcolors-colors-marker-colors">
<term
><guilabel
>Кольори позначок</guilabel
></term>
<listitem>
<variablelist>
<varlistentry>
<term
><userinput
>MarkBookmark</userinput
> (<guilabel
>Закладка</guilabel
>)</term>
<listitem
><para
>Встановлює колір, який буде використано для позначення закладок. Зауважте, що цей колір має рівень непрозорості щодо тла у 22% (і у 33% для поточного рядка). Щоб дізнатися більше, зверніться до розділу <xref linkend="kate-part-bookmarks"/>.</para>
<mediaobject>
<imageobject
><imagedata format="PNG" fileref="editor-colors-MarkBookmark.png"/></imageobject>
<caption
><para
></para
></caption>
</mediaobject>
</listitem>
</varlistentry>
<varlistentry>
<term
><userinput
>MarkBreakpointActive</userinput
> (<guilabel
>Активна точка зупинки</guilabel
>)</term>
<listitem
><para
>Цей колір використовується додатком GDB для позначення активної точки зупинки. Зауважте, що цей колір має рівень непрозорості щодо тла. Щоб дізнатися більше, зверніться до <ulink url="help:/kate/kate-application-plugin-gdb.html"
>документації з додатка GDB</ulink
>.</para
></listitem>
</varlistentry>
<varlistentry>
<term
><userinput
>MarkBreakpointReached</userinput
> (<guilabel
>Досягнута точка зупинки</guilabel
>)</term>
<listitem
><para
>Цей колір використовується додатком GDB для позначення точки зупинки, якої було досягнуто під час діагностики. Зауважте, що цей колір має рівень непрозорості щодо тла. Щоб дізнатися більше, зверніться до <ulink url="help:/kate/kate-application-plugin-gdb.html"
>документації з додатка GDB</ulink
>.</para
></listitem>
</varlistentry>
<varlistentry>
<term
><userinput
>MarkBreakpointDisabled</userinput
> (<guilabel
>Вимкнена точка зупинки</guilabel
>)</term>
<listitem
><para
>Цей колір використовується додатком GDB для позначення неактивної точки зупинки. Зауважте, що цей колір має рівень непрозорості щодо тла. Щоб дізнатися більше, зверніться до <ulink url="help:/kate/kate-application-plugin-gdb.html"
>документації з додатка GDB</ulink
>.</para
></listitem>
</varlistentry>
<varlistentry>
<term
><userinput
>MarkExecution</userinput
> (<guilabel
>Виконання</guilabel
>)</term>
<listitem
><para
>Цей колір використовується додатком GDB для позначення рядка коду, який виконується. Зауважте, що цей колір має рівень непрозорості щодо тла. Щоб дізнатися більше, зверніться до <ulink url="help:/kate/kate-application-plugin-gdb.html"
>документації з додатка GDB</ulink
>.</para
></listitem>
</varlistentry>
<varlistentry>
<term
><userinput
>MarkWarning</userinput
> (<guilabel
>Попередження</guilabel
>)</term>
<listitem
><para
>Цей колір використовується додатком збирання для позначення рядка, щодо якого засобом збирання видано попередження. Зауважте, що цей колір має рівень непрозорості щодо тла. Щоб дізнатися більше, зверніться до <ulink url="help:/kate/kate-application-plugin-build.html"
>документації з додатка збирання</ulink
>.</para
></listitem>
</varlistentry>
<varlistentry>
<term
><userinput
>MarkError</userinput
> (<guilabel
>Помилка</guilabel
>)</term>
<listitem
><para
>Цей колір використовується додатком збирання для позначення рядка, щодо якого засобом збирання видано повідомлення про помилку. Зауважте, що цей колір має рівень непрозорості щодо тла. Щоб дізнатися більше, зверніться до <ulink url="help:/kate/kate-application-plugin-build.html"
>документації з додатка збирання</ulink
>.</para
></listitem>
</varlistentry>
</variablelist>
</listitem>
</varlistentry>
<varlistentry id="variable-prefcolors-colors-text-templates-snippets">
<term
><guilabel
>Шаблони і фрагменти тексту</guilabel
></term>
<listitem>
<variablelist>
<varlistentry>
<term
><userinput
>TemplateBackground</userinput
> (<guilabel
>Тло</guilabel
>)</term>
<listitem
><para
>Цей колір використовується додатком фрагментів &kate; для позначення тла фрагмента. Щоб дізнатися більше, ознайомтеся із <ulink url="help:/kate/kate-application-plugin-snippets.html"
>документацією щодо фрагментів &kate;</ulink
>.</para
></listitem>
</varlistentry>
<varlistentry>
<term
><userinput
>TemplatePlaceholder</userinput
> (<guilabel
>Змінний заповнювач</guilabel
>)</term>
<listitem
><para
>Цей колір використовується додатком фрагментів &kate; для позначення замінника, на якому ви можете клацнути з метою внесення змін вручну. Щоб дізнатися більше, зверніться до <ulink url="help:/kate/kate-application-plugin-snippets.html"
>документації з додатка фрагментів &kate;</ulink
>.</para
></listitem>
</varlistentry>
<varlistentry>
<term
><userinput
>TemplateFocusedPlaceholder</userinput
> (<guilabel
>Фокусований змінний заповнювач</guilabel
>)</term>
<listitem
><para
>Цей колір використовується додатком фрагментів &kate; для позначення замінника, який ви редагуєте. Щоб дізнатися більше, зверніться до <ulink url="help:/kate/kate-application-plugin-snippets.html"
>документації з додатка фрагментів &kate;</ulink
>.</para>
<mediaobject>
<imageobject
><imagedata format="PNG" fileref="editor-colors-Template.png"/></imageobject>
<caption
><para
></para
></caption>
</mediaobject>
</listitem>
</varlistentry>
<varlistentry>
<term
><userinput
>TemplateReadOnlyPlaceholder</userinput
> (<guilabel
>Незмінний заповнювач</guilabel
>)</term>
<listitem
><para
>Цей колір використовується додатком фрагментів &kate; для позначення замінника, який не можна змінити вручну, наприклад замінника, який заповнюється автоматично. Щоб дізнатися більше, зверніться до <ulink url="help:/kate/kate-application-plugin-snippets.html"
>документації з додатка фрагментів &kate;</ulink
>.</para>
<mediaobject>
<imageobject
><imagedata format="PNG" fileref="editor-colors-TemplateReadOnlyPlaceholder.png"/></imageobject>
<caption
><para
></para
></caption>
</mediaobject>
</listitem>
</varlistentry>
</variablelist>
</listitem>
</varlistentry>
</variablelist>
</sect3>
<sect3 id="color-themes-text-styles">
<title
>Стилі звичайного тексту</title>
<para
>Стилі звичайного тексту успадковують свої властивості від стилів підсвіченого тексту, що надає редактору можливість показувати текст без великої різниці у шрифтах, наприклад, для тексту коментарів використовується той же стиль у майже всіх форматах тексту, які може підсвічувати KSyntaxHighlighting. </para>
<note>
<para
>На ці стилі тексту можна посилатися з <userinput
>типових стилів</userinput
>, які використовують у файлах &XML; визначення <link linkend="highlight"
>підсвічування синтаксису</link
>. Наприклад, атрибут <quote
>Normal</quote
> є еквівалентним до атрибута <quote
>dsNormal</quote
> у файлах &XML;, а <quote
>DataType</quote
> є еквівалентним до <quote
>dsDataType</quote
>. Див. розділ <xref linkend="kate-highlight-default-styles"/> у документації щодо підсвічування синтаксису. </para>
</note>
<tip>
<para
>Слід вибирати придатні до читання кольори із доброю контрастністю, особливо у поєднанні із <userinput
><link linkend="color-themes-editor-colors"
>кольорами редактора</link
></userinput
>. Див. <xref linkend="color-themes-contrast"/>. </para>
</tip>
<para
>У <link linkend="color-themes-json"
>файлі &JSON;</link
> відповідний ключ <userinput
>text-styles</userinput
> має значення <emphasis
>об'єкта</emphasis
>, кожен ключ якого відповідає назві <emphasis
>типового стилю тексту</emphasis
>. Ключі є еквівалентами ключів, які використовують у визначеннях підсвічування синтаксису. Тут <userinput
>усі доступні ключі стилю тексту є обов'язковими</userinput
>. Список ключів наведено нижче. </para>
<programlisting
>"text-styles": {
"Normal" : {
"text-color" : "#1f1c1b",
"selected-text-color" : "#ffffff",
"bold" : false,
"italic" : false,
"underline" : false,
"strike-through" : false
},
"Keyword" : {
"text-color" : "#1f1c1b",
"selected-text-color" : "#ffffff",
"bold" : true
},
"Function" : {
"text-color" : "#644a9b",
"selected-text-color" : "#452886"
},
<replaceable
>Інші ключі стилю тексту...</replaceable>
}
</programlisting>
<variablelist>
<varlistentry>
<term
>Значенням кожного ключа <emphasis
>типового стилю тексту</emphasis
> є об'єкт &JSON;, у якому задано такі значення, як <emphasis
>color</emphasis
>, <emphasis
>bold</emphasis
>, <emphasis
>italic</emphasis
>. Ось ці ключі: </term>
<listitem>
<para
><userinput
>text-color</userinput
> — <emphasis
>рядкове</emphasis
> значення із шістнадцятковим кодом кольору. Ця пара ключ-значення є обов'язковою.</para>
<para
><userinput
>selected-text-color</userinput
> — колір тексту, коли його позначено. Загалом, те саме значення, що і <quote
>text-color</quote
>. Якщо текст позначено, тло визначається значенням <link linkend="variable-pref-colors-selected-text"
>TextSelection</link
> у <link linkend="color-themes-editor-colors"
>кольорах редактора</link
>, тому вам слід забезпечити добру контрастність та можливість читання на тлі. Значенням є <emphasis
>рядок</emphasis
> із шістнадцятковим кодом кольору. Ця пара ключ-значення є обов'язковою.</para>
<para
><userinput
>bold</userinput
> — <emphasis
>булеве</emphasis
> значення, яке визначає, чи є шрифт тексту напівжирним. Цей ключ є необов'язковим. Типовим значенням є <userinput
>false</userinput
> (ні).</para>
<para
><userinput
>italic</userinput
> — <emphasis
>булеве</emphasis
> значення, яке визначає, чи є шрифт тексту курсивним. Цей ключ є необов'язковим. Типовим значенням є <userinput
>false</userinput
> (ні).</para>
<para
><userinput
>underline</userinput
> — <emphasis
>булеве</emphasis
> значення, яке визначає, чи є текст підкресленим. Цей ключ є необов'язковим. Типовим значенням є <userinput
>false</userinput
> (ні).</para>
<para
><userinput
>strike-through</userinput
> — <emphasis
>булеве</emphasis
> значення, яке визначає, чи є текст перекресленим. Цей ключ є необов'язковим. Типовим значенням є <userinput
>false</userinput
> (ні).</para>
<para
><userinput
>background-color</userinput
> — визначає тло тексту. Використовують, наприклад, у коментарях. Значенням є <emphasis
>рядок</emphasis
> із шістнадцятковим кодом кольору. Цей ключ є необов'язковим. Типовим є текст без будь-якого тла.</para>
<para
><userinput
>selected-background-color</userinput
> — визначає тло позначеного тексту. Значенням є <emphasis
>рядок</emphasis
> із шістнадцятковим кодом кольору. Цей ключ є необов'язковим. Типовим є текст без будь-якого тла.</para>
</listitem>
</varlistentry>
</variablelist>
<para
>У <link linkend="color-themes-gui"
>графічному інтерфейсі для керування темами кольорів KTextEditor</link
> ці атрибути можна змінити на вкладці <userinput
><guilabel
>Стилі звичайного тексту</guilabel
></userinput
>. Для назви у списку стилів буде використано стиль для відповідного запису. Це надасть вам змогу одразу бачити результат застосування стилю. У кожному стилі ви зможете вибрати загальні атрибути, а також кольори тексту і тла. Щоб скинути колір тла, клацніть правою кнопкою миші і скористайтеся контекстним меню.</para>
<para
>Нижче наведено доступні ключі стилю тексту. Список ключів, які використано у <link linkend="color-themes-json"
>файлі &JSON;</link
>, наведено <emphasis
>напівжирним</emphasis
> шрифтом. У дужках подано назви, які використано у <link linkend="color-themes-gui"
>графічному інтерфейсі</link
>, якщо вони є різними.</para>
<variablelist>
<varlistentry>
<term
><guilabel
>Звичайний текст і початковий код</guilabel
></term>
<listitem>
<para
><userinput
>Normal</userinput
> — типовий стиль звичайного тексту і початкового коду без спеціального підсвічування.</para>
<para
><userinput
>Keyword</userinput
> — стиль тексту для вбудованих ключових слів мови.</para>
<para
><userinput
>Function</userinput
> — стиль тексту для визначень і викликів функцій.</para>
<para
><userinput
>Variable</userinput
> — стиль тексту для змінних, якщо такий застосовний. Наприклад, назви змінних у PHP/Perl типово починаються з символу <userinput
>$</userinput
>, тому усі ідентифікатори, які відповідають шаблону <userinput
>$foo</userinput
>, буде підсвічено як змінні.</para>
<para
><userinput
>ControlFlow</userinput
> (<guilabel
>Потік керування</guilabel
>) — стиль тексту для ключових слів потоку керування, зокрема <emphasis
>if</emphasis
>, <emphasis
>then</emphasis
>, <emphasis
>else</emphasis
>, <emphasis
>return</emphasis
>, <emphasis
>switch</emphasis
>, <emphasis
>break</emphasis
>, <emphasis
>yield</emphasis
>, <emphasis
>continue</emphasis
> тощо.</para>
<para
><userinput
>Operator</userinput
> — стиль тексту для операторів, зокрема <userinput
>+</userinput
>, <userinput
>-</userinput
>, <userinput
>*</userinput
>, <userinput
>/</userinput
>, <userinput
>%</userinput
>, тощо.</para>
<para
><userinput
>BuiltIn</userinput
> (<guilabel
>Вбудований блок</guilabel
>) — стиль тексту для вбудованих класів, функцій та об'єктів мови.</para>
<para
><userinput
>Extension</userinput
> (<guilabel
>Розширення</guilabel
>) — стиль тесту для відомих розширень, зокрема класів &Qt;, функцій/макросів у C++ та Python або boost.</para>
<para
><userinput
>Preprocessor</userinput
> (<guilabel
>Попередня обробка</guilabel
>) — стиль тексту для інструкцій препроцесора та визначень макросів.</para>
<para
><userinput
>Attribute</userinput
> (<guilabel
>Атрибут</guilabel
>) — стиль тексту для анотацій або атрибутів функцій чи об'єктів, наприклад <userinput
>@override</userinput
> у Java або <userinput
>__declspec(...)</userinput
> і <userinput
>__attribute__((...))</userinput
> у C++.</para>
</listitem>
</varlistentry>
<varlistentry>
<term
><guilabel
>Числа, типи і сталі</guilabel
></term>
<listitem>
<para
><userinput
>DataType</userinput
> (<guilabel
>Тип даних</guilabel
>) — стиль тексту для вбудованих типів даних, зокрема <emphasis
>int</emphasis
>, <emphasis
>char</emphasis
>, <emphasis
>float</emphasis
>, <emphasis
>void</emphasis
>, <emphasis
>u64</emphasis
> тощо.</para>
<para
><userinput
>DecVal</userinput
> (<guilabel
>Десяткове/Значення</guilabel
>) — стиль тексту для десяткових значень.</para>
<para
><userinput
>BaseN</userinput
> (<guilabel
>Ціле у системі числення з основою N</guilabel
>) — стиль тексту для чисел в записі із основою числення, відмінною від 10.</para>
<para
><userinput
>Float</userinput
> (<guilabel
>З рухомою крапкою</guilabel
>) — стиль тексту для чисел із рухомою крапкою.</para>
<para
><userinput
>Constant</userinput
> (<guilabel
>Стала</guilabel
>) — стиль тексту для сталих мови програмування або визначених користувачем сталих, наприклад <emphasis
>True</emphasis
>, <emphasis
>False</emphasis
>, <emphasis
>None</emphasis
> у Python або <emphasis
>nullptr</emphasis
> у C/C++; або математичних стали, зокрема <emphasis
>PI</emphasis
>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term
><guilabel
>Рядки і символи</guilabel
></term>
<listitem>
<para
><userinput
>Char</userinput
> (<guilabel
>Символ</guilabel
>) — стиль тексту для окремих символів, зокрема <userinput
>'x'</userinput
>.</para>
<para
><userinput
>SpecialChar</userinput
> (<guilabel
>Спеціальний символ</guilabel
>) — стиль тексту для екранованих символів у рядках, наприклад <quote
><userinput
>hello\n</userinput
></quote
>, та інших символів зі спеціальним значенням у рядках, зокрема символів-замінників та операторів формальних виразів.</para>
<para
><userinput
>String</userinput
> — стиль тексту для рядків, подібних до <quote
><userinput
>привіт, світе</userinput
></quote
>.</para>
<para
><userinput
>VerbatimString</userinput
> (<guilabel
>Рядок буквально</guilabel
>) — стиль тексту для буквальних або необроблених рядків, зокрема <userinput
>'raw \backlash'</userinput
> у Perl, CoffeeScript та командних оболонках, а також <userinput
>r'\raw'</userinput
> у Python або рядків, подібних до документації HERE.</para>
<para
><userinput
>SpecialString</userinput
> (<guilabel
>Спеціальний рядок</guilabel
>) — стиль тексту для спеціальних рядків, зокрема формальних виразів у ECMAScript, коду у рівняннях &latex;, коду SQL тощо.</para>
<para
><userinput
>Import</userinput
> (<guilabel
>Імпортування, модулі, включення</guilabel
>) — стиль тексту для включень, імпортувань, модулів та пакунків &latex;.</para>
</listitem>
</varlistentry>
<varlistentry>
<term
><guilabel
>Коментарі і документація</guilabel
></term>
<listitem>
<para
><userinput
>Comment</userinput
> — стиль тексту для звичайних коментарів.</para>
<para
><userinput
>Documentation</userinput
> (<guilabel
>Документація</guilabel
>) — стиль тексту для коментарів, які відповідають за документацію з програмного інтерфейсу, зокрема <userinput
>/** коментарів doxygen */</userinput
> або <userinput
>"""рядків_документації"""</userinput
>.</para>
<para
><userinput
>Annotation</userinput
> (<guilabel
>Анотація</guilabel
>) — стиль тексту для анотацій у коментарях або командах документування, зокрема <userinput
>@param</userinput
> у Doxygen або JavaDoc.</para>
<para
><userinput
>CommentVar</userinput
> (<guilabel
>Змінна коментаря</guilabel
>) — стиль тексту, який відповідає назвам змінних у наведених вище командах у коментарі, зокрема <userinput
>foobar</userinput
> у <quote
><userinput
>@param foobar</userinput
></quote
> для коду Doxygen або JavaDoc.</para>
<para
><userinput
>RegionMarker</userinput
> (<guilabel
>Позначка ділянки</guilabel
>) — стиль тексту для позначок ділянки, яка типово визначається командами <userinput
>//BEGIN</userinput
> і <userinput
>//END</userinput
> у коментарях.</para>
<para
><userinput
>Information</userinput
> (<guilabel
>Інформація</guilabel
>) — стиль тексту для відомостей, нотаток і підказок, зокрема ключового слова <userinput
>@note</userinput
> у Doxygen.</para>
<para
><userinput
>Warning</userinput
> — стиль тексту для попереджень, зокрема ключового слова <userinput
>@warning</userinput
> у Doxygen.</para>
<para
><userinput
>Alert</userinput
> — стиль тексту для спеціальних слів у коментарях, зокрема <userinput
>TODO</userinput
>, <userinput
>FIXME</userinput
>, <userinput
>XXXX</userinput
> та <userinput
>WARNING</userinput
>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term
><guilabel
>Різне</guilabel
></term>
<listitem>
<para
><userinput
>Error</userinput
> — стиль тексту для позначення підсвічування помилок та помилкових синтаксичних конструкцій.</para>
<para
><userinput
>Others</userinput
> — стиль тексту для атрибутів, які не можна віднести до жодного із інших типових стилів.</para>
</listitem>
</varlistentry>
</variablelist>
</sect3>
<sect3 id="color-themes-custom-styles">
<title
>Стилі тексту нетипового підсвічування</title>
<para
>Тут ви можете встановити стилі тексту для специфічного визначення синтаксису, перевизначивши <userinput
>стиль звичайного тексту</userinput
>, який описано у <link linkend="color-themes-text-styles"
>попередньому розділі</link
>. </para>
<para
>У <link linkend="color-themes-json"
>файл &JSON; теми</link
> цей ключ відповідає ключу <userinput
>custom-styles</userinput
>, чиїм значенням є <emphasis
>об'єкт</emphasis
>, кожен ключ підлеглої схеми якого відповідає <userinput
>назві визначення підсвічування синтаксису</userinput
>. Його значенням <emphasis
>об'єкт</emphasis
>, кожен ключ якого відповідає <userinput
>назві атрибутів стилю</userinput
>, яку визначено <link linkend="kate-highlight-sections"
>елементах <userinput
>itemData</userinput
></link
> файла &XML; підсвічування синтаксису, і відповідне значення є підлеглим об'єктом із ключами <emphasis
>text-color</emphasis
>, <emphasis
>selected-text-color</emphasis
>, <emphasis
>bold</emphasis
>, <emphasis
>italic</emphasis
>, <emphasis
>underline</emphasis
>, <emphasis
>strike-through</emphasis
>, <emphasis
>background-color</emphasis
> і <emphasis
>selected-background-color</emphasis
>, який визначено у <link linkend="color-themes-text-styles"
>попередньому розділі</link
>. Усі ці значення є необов'язковими, оскільки, якщо їх не вказано, буде використано стиль, який визначено у <userinput
>text-styles</userinput
>. </para>
<para
>Наприклад, у цьому фрагменті коду визначення підсвічування синтаксису <quote
>ISO C++</quote
> містить спеціальний стиль тексту для атрибутів <quote
>Модифікатори типу</quote
> і <quote
>Стандартні класи</quote
>. У відповідному файлі &XML;, <quote
>isocpp.xml</quote
>, визначений атрибут <quote
>Стандартні класи</quote
> використовує типовий стиль <userinput
>BuiltIn</userinput
> (або dsBuiltIn). У цьому атрибуті буде перезаписано лише одне значення — <userinput
>text-color</userinput
> — новим кольором <quote
>#6431b3</quote
>. </para>
<programlisting
>"custom-styles": {
"ISO C++": {
"Standard Classes": {
"text-color": "#6431b3"
},
"Type Modifiers": {
"bold": true,
"selected-text-color": "#009183",
"text-color": "#00b5cf"
}
}
}
</programlisting>
<note>
<itemizedlist>
<listitem>
<para
>Вам слід зробити так, щоб ці стилі тексту було пов'язано із назвами атрибутів у файлах &XML; підсвічування синтаксису. Якщо буде оновлено файл XML, а деякі атрибути буде перейменовано або вилучено, нетиповий стиль, який визначено у темі, стане незастосовним.</para>
</listitem>
<listitem>
<para
>Визначення підсвічування синтаксичних конструкцій часто включають інші визначення. Наприклад, визначення підсвічування <quote
>QML</quote
> включає визначення підсвічування <quote
>JavaScript</quote
>, оскільки вони містять спільні функціональні можливості підсвічування.</para>
</listitem>
</itemizedlist>
</note>
<para
>У <link linkend="color-themes-gui"
>графічному інтерфейсі для керування темами KTextEditor</link
> ці атрибути можна змінити на вкладці <userinput
><guilabel
>Стилі підсвіченого тексту</guilabel
></userinput
>. Типово, редактор попередньо вибирає підсвічування для поточного документа. Ви зауважите, що багато визначень підсвічувань місять інші визначення підсвічувань, що позначається групами у списку стилів. Наприклад, у більшості визначень підсвічувань імпортують підсвічування <quote
>Alert</quote
>, а багато визначень підсвічувань програмного коду імпортують підсвічування <quote
>Doxygen</quote
>. </para>
</sect3>
</sect2>
<sect2 id="color-themes-gui">
<title
>Графічний інтерфейс тем кольорів</title>
<para
>Найпростішим способом створення і редагування тем кольорів є використання графічного інтерфейсу — <link linkend="config-dialog"
>діалогового вікна <quote
>Налаштувати</quote
></link
>, яке надається <ulink url="https://api.kde.org/frameworks/ktexteditor/html/"
>KTextEditor</ulink
>. Щоб отримати до нього доступ, скористайтеся пунктом меню <menuchoice
><guimenu
>Параметри</guimenu
> <guimenuitem
>Налаштувати <replaceable
>назва_програми</replaceable
>...</guimenuitem
></menuchoice
> у вікні вашого текстового редактора. У відповідь буде відкрито діалогове вікно <guilabel
>Налаштувати</guilabel
>. У цьому діалоговому вікні вам слід вибрати сторінку <guilabel
>Теми кольорів</guilabel
> на бічній панелі. </para>
<mediaobject>
<imageobject
><imagedata format="PNG" fileref="color-themes-gui-default-text-styles.png"/></imageobject>
<textobject
><phrase
>Діалогове вікно параметрів &kate; для керування темою кольорів.</phrase
></textobject>
<caption
><para
>Діалогове вікно параметрів &kate; для керування темою кольорів.</para>
</caption>
</mediaobject>
<para
>За допомогою цього <link linkend="config-dialog"
>діалогового вікна</link
> ви можете налаштувати усі кольори будь-якої теми, а також створити або скопіювати тему, вилучити тему, експортувати тему до файла <userinput
>.theme</userinput
> у <link linkend="color-themes-json"
>форматі &JSON;</link
> або імпортувати тему із зовнішніх файлів <userinput
>.theme</userinput
>. У кожній темі передбачено параметри для кольорів і стилів тексту. </para>
<para
>Типово, вносити зміни до вбудованих тем не можна. Для внесення змін вам слід скопіювати типову тему і змінити її назву.</para>
<para
>Щоб встановити остаточну тему у вашому текстовому редакторі, вам слід вибрати тему за допомогою розташованого у нижній частині вікна спадного списку із міткою <guilabel
>Типова тема для <replaceable
>назва_програми</replaceable
></guilabel
> і натиснути кнопку <guibutton
>Застосувати</guibutton
> або <guibutton
>Гаразд</guibutton
>. Типово, активним є варіант <userinput
><guilabel
>Автоматичний вибір</guilabel
></userinput
>. Використання цього варіанта призводить до вибору теми кольорів, яка найкраще пасує до <emphasis
>схеми кольорів Плазми &kde;</emphasis
> для редагування тексту. Зазвичай, вибір здійснюється між <quote
>Світлою Breeze</quote
> і <quote
>Темною Breeze</quote
>. Вибір залежить від того, світлою чи темною є схема кольорів середовища. </para>
<tip>
<para
>Ви можете змінити загальну схему кольорів &kde; за допомогою <ulink url="help:/kcontrol/colors/"
>модуля <quote
>Кольори</quote
> програми «Системні параметри»</ulink
>. Ви також можете змінити її у деяких програмах, зокрема &kate; та &kdevelop;, окремо. Для цього скористатися пунктом меню <menuchoice
><guimenu
>Параметри</guimenu
><guisubmenu
>Схема кольорів</guisubmenu
></menuchoice
>. </para>
</tip>
<sect3 id="color-themes-gui-new-theme">
<title
>Створити тему</title>
<para
>Щоб створити тему, спочатку слід скопіювати наявну тему. Виберіть наявну тему, якою ви хочете скористатися як основою, наприклад <quote
>Світу Breeze</quote
> або <quote
>Темну Breeze</quote
>, і натисніть кнопку <guibutton
>Копіювати</guibutton
>. Потім впишіть у показане поле назви назву нової теми. </para>
<para
>Якщо ви хочете внести зміни до вбудованої теми або теми, призначеної лише для читання, вам слід спочатку скопіювати тему, вказавши для копії іншу назву.</para>
</sect3>
<sect3 id="color-themes-gui-import-export">
<title
>Імпортування або експортування файлів &JSON; тем</title>
<para
>Ви можете експортувати вибрану тему (включно із вбудованими) до <link linkend="color-themes-json"
>файла &JSON;</link
> із суфіксом назви <userinput
>.theme</userinput
> за допомогою кнопки <guibutton
>Експортувати</guibutton
>. У відповідь на натискання кнопки програма відкриє діалогове вікно для збереження файла. Щоб додати тему кольорів із зовнішнього <link linkend="color-themes-json"
>файла &JSON;</link
>, просто натисніть кнопку <guibutton
>Імпортувати</guibutton
> і виберіть за допомогою діалогового вікна навігації файловою системою файл <userinput
>.theme</userinput
>. </para>
<tip>
<itemizedlist>
<listitem>
<para
>Як ми вже <link linkend="color-themes-json-overview"
>згадували вище</link
>, налаштовані користувачами теми зберігаються у каталозі <filename class="directory"
>org.kde.syntax-highlighting/themes/</filename
>. Коли ви копіюєте або створюєте тему, вона автоматично з'являється у цьому каталозі. Крім того, імпортування або додавання теми є еквівалентним до копіювання зовнішнього файла <userinput
>.theme</userinput
> до цього каталогу. KSyntaxHighlighting автоматично вибирає файли тем кольорів з вказаного каталогу.</para>
</listitem>
<listitem>
<para
>Якщо ви хочете оприлюднити створену вами тему, важливо перевірити коректність об'єкта <link linkend="color-themes-json-metadata"
>metadata</link
> у <link linkend="color-themes-json"
>файлі &JSON;</link
>, додавши до нього відповідні умови ліцензування та вказавши відповідний номер модифікації.</para>
</listitem>
</itemizedlist>
</tip>
</sect3>
<sect3 id="color-themes-gui-editing">
<title
>Редагування тем кольорів</title>
<sect4 id="prefcolors-colors">
<title
>Кольори</title>
<para
>Тут можна коригувати кольори області редагування тексту. Докладніший опис параметрів наведено у розділі <xref linkend="color-themes-editor-colors"/>.</para>
</sect4>
<sect4 id="prefcolors-normal-text-styles">
<title
>Стилі звичайного тексту</title>
<para
>Стилі звичайного тексту успадковують свої властивості від стилів підсвіченого тексту, що надає редактору можливість показувати текст без великої різниці у шрифтах, наприклад, для тексту коментарів використовується той же стиль у майже всіх форматах тексту, які може підсвічувати KSyntaxHighlighting.</para>
<para
>Під час підготовки до показу назви стилю у списку стилів буде використано стиль, назву якого ви бачитимете, отже під час налаштування стилю вам легше буде знайти потрібний пункт у списку. </para>
<para
>Для кожного стилю ви можете обрати загальні атрибути, а також колір тексту і тла. Щоб повернути колір тла до початкового значення, наведіть на цього вказівник миші і клацніть правою кнопкою миші, щоб викликати відповідне контекстне меню.</para>
<para
>Докладний опис атрибутів цієї області наведено у розділі <xref linkend="color-themes-text-styles"/>.</para>
</sect4>
<sect4 id="prefcolors-highlighting-text-styles">
<title
>Стилі підсвіченого тексту</title>
<para
>Тут ви можете змінити стилі тексту, які використовуватимуться певним типом підсвічування. У редакторі буде попередньо обрано колір, який використовується у вашому поточному документі. Щоб працювати з іншим стилем підсвічування, виберіть якого зі спадного списку <guilabel
>Підсвічування</guilabel
>, розташованому над списком стилів. </para>
<para
>Під час підготовки до показу назви стилю у списку стилів буде використано стиль, назву якого ви бачитимете, отже під час налаштування стилю вам легше буде знайти потрібний пункт у списку. </para>
<para
>У кожному стилі ви можете обрати загальні атрибути, а також кольори тексту та тла. Щоб повернути колір тла до початкового значення, наведіть на цього вказівник миші і клацніть правою кнопкою миші, щоб викликати відповідне контекстне меню. Крім того, ви зможете порівнювати стиль з типовим стилем, що використовується для елемента, і встановлювати його або не робити цього.</para>
<para
>Ви побачите, що багато стилів підсвічування містять інші стилі підсвічування, які у списку стилів зібрано у групи. Наприклад, більшість стилів підсвічування імпортують стиль підсвічування «Увага», а багато з форматів підсвічування коду — підсвічування «Doxygen». Зміна кольорів у таких групах, впливатиме на стилі, лише якщо її було використано у форматі підсвічування, який ви редагуєте. </para>
</sect4>
</sect3>
</sect2>
<sect2 id="color-themes-tips-and-tricks">
<title
>Підказки та поради</title>
<sect3 id="color-themes-contrast">
<title
>Контрастність кольорів тексту</title>
<para
>Важливим аспектом роботи із темами кольорів є вибір контрастного кольору тексту, який зробить простішим читання, особливо у поєднанні із кольором тла.</para>
<para
>Для пошук контрастних кольорів можна скористатися програмою <userinput
>Kontrast</userinput
>. Ця програма повідомить вам, чи є комбінації кольорів тексту і тла придатними до читання і доступними для користувачів. Тому ця програма є чудовим інструментом для створення тем кольорів.</para>
<para
>Ви можете встановити <userinput
>Kontrast</userinput
> з <ulink url="https://apps.kde.org/en/kontrast"
>сайта програм &kde;</ulink
> або з <ulink url="https://flathub.org/apps/details/org.kde.kontrast"
>пакунка Flatpak на Flathub</ulink
> (лише у GNU/Linux).</para>
<para
>Подібні функціональні можливості реалізовано у програмі GNOME <userinput
>Contrast</userinput
>. Встановити цю програму можна за допомогою <ulink url="https://flathub.org/apps/details/org.gnome.design.Contrast"
>пакунка Flatpak з Flathub</ulink
> (лише у GNU/Linux).</para>
</sect3>
<sect3 id="color-themes-tips-and-tricks-consistency">
<title
>Пропозиції щодо однорідності підсвічування синтаксису</title>
<para
>До KSyntaxHighlighting включено <ulink url="https://kate-editor.org/syntax/"
>понад 300 визначень підсвічування синтаксичних конструкцій</ulink
>, тому було б дуже добре, аби ви переконалися, що нова тема виглядає добре для усіх визначень підсвічувань синтаксичних конструкцій. У вбудованих темах кольорів використано наведені нижче принципи, якими ми рекомендуємо (не обов'язково) користуватися для досягнення належного показу для усіх визначень підсвічувань синтаксичних конструкцій:</para>
<itemizedlist>
<listitem
><para
>Користуйтеся напівжирним шрифтом для <link linkend="color-themes-text-styles"
>стилів тексту</link
> <quote
>Keyword</quote
> і <quote
>ControlFlow</quote
>.</para
></listitem>
<listitem
><para
>Не використовуйте кольору тла у <link linkend="color-themes-text-styles"
>стилі тексту</link
>, окрім <quote
>Alert</quote
> і <quote
>RegionMarker</quote
>.</para
></listitem>
</itemizedlist>
<para
>Більшість визначень підсвічувань синтаксичних конструкцій добре виглядають у типових темах <quote
>Світла Breeze</quote
> та <quote
>Темна Breeze</quote
>. Тому іншим способом забезпечення сумісності із визначеннями є використання подібних кольорів у <link linkend="color-themes-text-styles"
>стилях тексту</link
>, зокрема <emphasis
>зеленого</emphasis
> для <quote
>Preprocessor</quote
> та <quote
>Others</quote
>, <emphasis
>синього</emphasis
> для <quote
>DataType</quote
> і <quote
>Attribute</quote
> або <emphasis
>пурпурового</emphasis
> для <quote
>Function</quote
>.</para>
<para
>Зауважте, що ці рекомендації не є обов'язковими для створення і оприлюднення теми.</para>
</sect3>
</sect2>
</sect1>
<sect1 id="dev-scripting">
<title
>Створення скриптів мовою JavaScript</title>
<para
>Можливості компонента редактора &kappname; можна дуже просто розширити за допомогою написання скриптів. Для написання скриптів слід використовувати мову ECMAScript (широко відому як JavaScript). У &kappname; передбачено підтримку двох типів скриптів: скрипти встановлення відступів та скрипти командного рядка. </para>
<sect2 id="dev-scripting-indentation">
<title
>Скрипти додавання відступів</title>
<para
>Скрипти встановлення відступів, які також будемо називати інструментами відступів, автоматично встановлюють відступи у тексті під час його введення. Наприклад, після натискання клавіші &Enter; програма зазвичай збільшує відступ у наступному рядку. </para>
<para
>У наступних розділах наведено покрокові настанови щодо створення основи простого інструменту відступів. На першому кроці вам слід створити файл <filename
>*.js</filename
> з назвою, наприклад, <filename
>javascript.js</filename
> у локальній домашній теці <filename
>$<envar
>XDG_DATA_HOME</envar
>/katepart5/script/indentation</filename
>. Тут змінна середовища <envar
>XDG_DATA_HOME</envar
> типово має значення <filename
>~/.local</filename
> або <filename
>~/.local/share</filename
>. </para>
<para
>У &Windows; ці файли зберігаються у <filename
>%USERPROFILE%\AppData\Local\katepart5\script\indentation</filename
>. <replaceable
>%USERPROFILE%</replaceable
> зазвичай є скороченням для <filename
>C:\\Users\\<replaceable
>користувач</replaceable
></filename
>.</para>
<sect3 id="dev-scripting-indentation-header">
<title
>Заголовок скрипту додавання відступів</title>
<para
>Заголовок файла <filename
>javascript.js</filename
> подається у межах закоментованого блоку і має таку форму <programlisting>
var katescript = {
"name": "JavaScript",
"author": "Example Name <example.name@some.address.org>",
"license": "BSD License",
"revision": 1,
"kate-version": "5.1",
"required-syntax-style": "javascript",
"indent-languages": ["javascript"],
"priority": 0,
}; // kate-script-header, must be at the start of the file without comments
</programlisting
> Нижче ми зупинимося докладніше на кожному з записів заголовка. <itemizedlist>
<listitem
><para
><literal
>name</literal
> [обов’язковий запис]: це назва інструменту відступів, яку буде показано у меню <menuchoice
><guimenu
>Інструменти</guimenu
><guimenuitem
>Відступ</guimenuitem
></menuchoice
> і діалогових вікнах налаштування. </para
></listitem>
<listitem
><para
><literal
>author</literal
> [необов’язковий запис]: ім’я автора та дані щодо способу встановлення з ним зв’язку. </para
></listitem>
<listitem
><para
><literal
>license</literal
> [необов’язковий запис]: скорочена форма умов ліцензування, зокрема BSD або LGPLv3. </para
></listitem>
<listitem
><para
><literal
>revision</literal
> [обов’язковий запис]: версія скрипту. Внесення змін до коду скрипту має призводити до збільшення його версії. </para
></listitem>
<listitem
><para
><literal
>kate-version</literal
> [обов’язковий запис]: мінімальне значення версії &kappname;, у якій працюватиме скрипт. </para
></listitem>
<listitem
><para
><literal
>required-syntax-style</literal
> [необов’язковий запис]: потрібний вам стиль синтаксису, який відповідає вказаному значенням <literal
>style</literal
> у файлах визначення підсвічування синтаксичних конструкцій. Цей запис є важливим для інструментів відступів, які працюють на основі певних даних щодо підсвічування у документі. Якщо буде вказано стиль синтаксичних конструкцій, інструментом відступів можна буде скористатися, лише якщо буде задіяно відповідний інструмент підсвічування тексту. Таким чином можна запобігти «невизначеній поведінці», спричиненій використанням інструменту відступів без потрібної для його роботи схеми підсвічування. Наприклад, у такий спосіб налаштовано інструмент відступів Ruby у файлах <filename
>ruby.js</filename
> і <filename
>ruby.xml</filename
>. </para
></listitem>
<listitem
><para
><literal
>indent-languages</literal
> [необов’язковий запис]: масив JSON стилів синтаксичних конструкцій, які може обробляти інструмент відступів, наприклад <literal
>["c++", "java"</literal
>. </para
></listitem>
<listitem
><para
><literal
>priority</literal
> [необов’язковий запис]: якщо якомусь файлу з визначеним підсвічуванням синтаксичних конструкцій відповідає декілька інструментів відступів, за допомогою цього запису буде встановлено пріоритет застосування інструменту відступів. </para
></listitem>
</itemizedlist>
</para>
</sect3>
<sect3 id="dev-scripting-indentation-body">
<title
>Код інструменту відступів</title>
<para
>Тепер, озброєні знаннями про формат заголовка, ви можете перейти до вивчення того, як же працює сам скрипт встановлення відступів. Основа подібного скрипту виглядає так: <programlisting>
// вимагаємо бібліотек JS katepart, наприклад range.js, якщо використовується Range
require ("range.js");
triggerCharacters = "{}/:;";
function indent(line, indentWidth, ch)
{
//скрипт буде викликано під час обробки символу нового рядка (ch == '\n') і всіх символів, вказаних у
// загальній змінній triggerCharacters. Під час використання пункту меню <menuchoice
><guimenu
>Інструменти</guimenu
><guimenuitem
>Форматований відступ</guimenuitem
></menuchoice>
// змінна ch матиме порожнє значення, тобто ch == ''.
//
// див. також розділ «Інтерфейс (API) роботи зі скриптами»
return -2;
}
</programlisting
> У функції <function
>indent()</function
> передбачено три параметри: <itemizedlist
> <listitem
><para
><literal
>line</literal
>: рядок, у якому слід встановити відступ</para
></listitem
> <listitem
><para
><literal
>indentWidth</literal
>: ширина відступу у пробілах</para
></listitem
> <listitem
><para
><literal
>ch</literal
>: символ нового рядка (<literal
>ch == '\n'</literal
>), символ перемикання, вказаний за допомогою <literal
>triggerCharacters</literal
> або порожній рядок, якщо користувачем було обрано пункт меню <menuchoice
><guimenu
>Інструменти</guimenu
> <guimenuitem
>Форматований відступ</guimenuitem
></menuchoice
>.</para
></listitem
> </itemizedlist
> Значення, повернуте функцією <function
>indent()</function
>, визначатиме спосіб встановлення відступу у рядку. Якщо буде повернуто ціле число, його обробку буде виконано за такими варіантами: <itemizedlist
> <listitem
><para
>повернуто значення <literal
>-2</literal
>: нічого не робити</para
></listitem
> <listitem
><para
>повернуто значення <literal
>-1</literal
>: зберегти відступ (його буде визначено на основі попереднього непорожнього рядка)</para
></listitem
> <listitem
><para
>повернуто значення <literal
> 0</literal
>: числа >= 0 визначають глибину відступу у пробілах</para
></listitem
> </itemizedlist
> Крім того, може бути повернуто масив з двох елементів: <itemizedlist
> <listitem
><para
><literal
>повернуто [ відступ, вирівнювання ];</literal
></para
></listitem
> </itemizedlist
> Першим елементом такого масиву є глибина відступу, подібна на значення, про яке ми говорили раніше. Інший же елемент є абсолютним значенням, що відповідає стовпчику «вирівнювання». Якщо це значення буде більшим за значення відступу, до відступу після додавання відступу, визначеного першим параметром, буде додано різницю між цими значенням. Якщо ж значення другого параметра буде меншим за відступ, його буде проігноровано. Одночасне використання для встановлення відступів пробілів і символів табуляції часто називають «мішаним режимом». </para>
<para
>Розглянемо такий приклад: для встановлення відступів використовується символ табуляції, а ширину відступу визначено як 4 пробіли. У нашому прикладі, <таб> — це символ табуляції, а «.» — пробіл: <programlisting>
1: <таб><таб>foobar("привіт",
2: <таб><таб>......."світе");
</programlisting
> Під час встановлення відступу для рядка 2 функція <function
>indent()</function
> повертає значення [8, 15]. У результаті буде додано два символи табуляції для встановлення відступу до стовпчика 8, а потім буде додано 7 пробілів для вирівнювання за другим параметром, більшим за перший, отже рядок залишатиметься вирівняним під час перегляду файла за будь-якої встановленої ширити відступу табуляції. </para>
<para
>У типовому пакунку KDE для &kappname; передбачено декілька інструментів відступів. Код цих інструментів мовою JavaScript зберігається у каталозі <filename
>$<envar
>XDG_DATA_DIRS</envar
>/katepart5/script/indentation</filename
>.</para>
<para
>У &Windows; ці файли зберігаються у <filename
>%USERPROFILE%\AppData\Local\katepart5\script\indentation</filename
>. <replaceable
>%USERPROFILE%</replaceable
> зазвичай є скороченням для <filename
>C:\\Users\\<replaceable
>користувач</replaceable
></filename
>. </para>
<para
>Під час розробки скрипту встановлення відступів корисним буває перезавантаження скриптів для перевірки коректності поведінки під час встановлення відступів. Замість перезапуску програми достатньо просто перейти до командного рядка і виконати команду <command
>reload-scripts</command
>. </para>
<para
>Якщо вами було створено якийсь корисний скрипт, ви зробити його вашим власним внеском до проєкту розробки &kappname;. Будь ласка, повідомте про вашу розробку у <ulink url="mailto:kwrite-devel@kde.org"
>списку листування програми</ulink
>. </para>
</sect3>
</sect2>
<sect2 id="dev-scripting-command-line">
<title
>Скрипти командного рядка</title>
<para
>Оскільки всі користувачі мають різні потреби, у &kappname; передбачено підтримку невеличких допоміжних інструментів для пришвидшення роботи з фрагментами тексту за допомогою <link linkend="advanced-editing-tools-commandline"
>вбудованого командного рядка</link
>. Наприклад, команду <command
>sort</command
> (впорядкувати) реалізовано саме за допомогою такого інструменту або скрипту. У цьому розділі ви знайдете пояснення щодо способу створення файлів <filename
>*.js</filename
>, які допоможуть вам розширити можливості &kappname; додаванням допоміжних скриптів. </para>
<para
>Скрипти командного рядка зберігаються у одній теці зі скриптами встановлення відступів. Отже на першому кроці вам слід створити файл <filename
>*.js</filename
> з назвою <filename
>myutils.js</filename
> у локальній домашній теці <filename
>$<envar
>XDG_DATA_HOME</envar
>/katepart5/script/commands</filename
>. Тут змінна середовища <envar
>XDG_DATA_HOME</envar
> типово має значення <filename
>~/.local</filename
> або <filename
>~/.local/share</filename
>.</para>
<para
>У &Windows; ці файли зберігаються у <filename
>%USERPROFILE%\AppData\Local\katepart5\script\commands</filename
>. <replaceable
>%USERPROFILE%</replaceable
> зазвичай є скороченням для <filename
>C:\\Users\\<replaceable
>користувач</replaceable
></filename
>. </para>
<sect3 id="dev-scripting-command-line-header">
<title
>Заголовок скрипту командного рядка</title>
<para
>Заголовок кожного скрипту командної оболонки має бути вбудовано до JSON на початку скрипту так: <programlisting>
var katescript = {
"author": "Example Name <example.name@some.address.org>",
"license": "LGPLv2+",
"revision": 1,
"kate-version": "5.1",
"functions": ["sort", "moveLinesDown"],
"actions": [
{ "function": "sort",
"name": "Sort Selected Text",
"category": "Editing",
"interactive": "false"
},
{ "function": "moveLinesDown",
"name": "Move Lines Down",
"category": "Editing",
"shortcut": "Ctrl+Shift+Down",
"interactive": "false"
}
]
}; // kate-script-header, must be at the start of the file without comments
</programlisting
> Тепер про кожен із записів докладніше: <itemizedlist>
<listitem
><para
><literal
>author</literal
> [необов’язковий запис]: ім’я автора та дані щодо способу встановлення з ним зв’язку.</para
></listitem>
<listitem
><para
><literal
>license</literal
> [необов’язковий запис]: скорочена форма умов ліцензування, зокрема BSD або LGPLv2.</para
></listitem>
<listitem
><para
><literal
>revision</literal
> [обов’язковий запис]: версія скрипту. Внесення змін до коду скрипту має призводити до збільшення його версії.</para
></listitem>
<listitem
><para
><literal
>kate-version</literal
> [обов’язковий запис]: мінімальне значення версії &kappname;, у якій працюватиме скрипт.</para
></listitem>
<listitem
><para
><literal
>functions</literal
> [обов’язковий запис]: масив JSON команд скрипту.</para
></listitem>
<listitem
><para
><literal
>actions</literal
> [необов’язковий запис]: масив JSON об’єктів JSON, який визначає пункти дій, які буде показано у меню програми. Докладніший опис наведено у розділі щодо <link linkend="advanced-editing-tools-commandline"
>призначення клавіатурних скорочень</link
>.</para
></listitem>
</itemizedlist>
</para>
<para
>Оскільки значення <literal
>functions</literal
> є масивом JSON, окремий скрипт може містити довільну кількість команд для командного рядка. Доступ до кожної із функцій можна оримати за допомогою <link linkend="advanced-editing-tools-commandline"
>вбудованого командного рядка &kappname;</link
>. </para>
</sect3>
<sect3 id="dev-scripting-command-line-body">
<title
>Код скрипту командного рядка</title>
<para
>Всі оголошені у заголовку функції має бути реалізовано у тілі скрипту. Наприклад, у файлі скрипту з наведеного вище прикладу слід реалізувати дві функції, <command
>sort</command
> і <command
>moveLinesDown</command
>. Всі функції має бути записано відповідно до таких синтаксичних правил: <programlisting
>// вимагаємо бібліотек JS katepart, наприклад range.js, якщо використовується Range
require ("range.js");
function <назва>(параметр1, параметр2, ...)
{
// ...реалізація, див. також: Інтерфейс (API) роботи зі скриптами
}
</programlisting>
</para>
<para
>Параметри у командному рядку передаються функції як <parameter
>параметр1</parameter
>, <parameter
>параметр2</parameter
> тощо. Щоб надати користувачам можливість ознайомлюватися з документацією щодо команди, просто реалізуйте функцію '<function
>help</function
>' у такий спосіб: <programlisting>
function help(cmd)
{
if (cmd == "sort") {
return i18n("Sort the selected text.");
} else if (cmd == "...") {
// ...
}
}
</programlisting
>Після цього виконання команди <command
>help sort</command
> у командному рядку призведе до виклику відповідної функції довідки (help) з параметром <parameter
>cmd</parameter
> встановленим у назву вказаної команди, тобто, у нашому прикладі, <parameter
>cmd == "sort"</parameter
>. У відповідь на команду &kappname; покаже користувачеві визначений вами текст довідки. </para>
<para
>Під час розробки скрипту командного рядка корисним буває перезавантаження скриптів для перевірки коректності поведінки під час встановлення відступів. Замість перезапуску програми достатньо просто перейти до командного рядка і виконати команду <command
>reload-scripts</command
>. </para>
<sect4 id="dev-scripting-command-line-shortcuts">
<title
>Призначення клавіатурних скорочень</title>
<para
>Для створення скриптів, доступ до яких можна буде отримувати з меню програми та за допомогою клавіатурних скорочень, скрипт повинен мати надавати відповідний заголовок. У наведеному вище прикладі, обидві функції <literal
>sort</literal
> та <literal
>moveLinesDown</literal
> показують відповідні пункти меню через таку частину заголовка скрипту: <programlisting>
var katescript = {
...
"actions": [
{ "function": "sort",
"name": "Sort Selected Text",
"icon": "",
"category": "Editing",
"interactive": "false"
},
{ "function": "moveLinesDown",
"name": "Move Lines Down",
"icon": "",
"category": "Editing",
"shortcut": "Ctrl+Shift+Down",
"interactive": "false"
}
]
};
</programlisting
> Поля для однієї дії є такими: <itemizedlist>
<listitem
><para
><literal
>function</literal
> [обов’язкове поле]: пункт функції, який має бути показано у меню <menuchoice
><guimenu
>Інструменти</guimenu
> <guisubmenu
>Скрипти</guisubmenu
></menuchoice
>.</para
></listitem>
<listitem
><para
><literal
>name</literal
> [необов’язковий запис]: текст пункту, який буде показано у меню скриптів.</para
></listitem>
<listitem
><para
><literal
>icon</literal
> [необов’язковий запис]: піктограма, яку буде показано поряд з текстом пункту меню. Можна використовувати назву будь-якої з піктограм KDE.</para
></listitem>
<listitem
><para
><literal
>category</literal
> [необов’язковий запис]: якщо буде вказано категорію, пункт скрипту буде додано у підменю.</para
></listitem>
<listitem
><para
><literal
>shortcut</literal
> [необов’язковий запис]: клавіатурне скорочення, вказане за допомогою цього значення буде типовим. Приклад: <literal
>Ctrl+Alt+t</literal
>. Докладніше про можливі скорочення можна дізнатися з <ulink url="https://doc.qt.io/qt-5/qt.html#Key-enum"
>документації до &Qt;</ulink
>.</para
></listitem>
<listitem
><para
><literal
>interactive</literal
> [необов’язковий]: якщо для роботи скрипту потрібні дані, введені користувачем, встановіть значення <literal
>true</literal
>.</para
></listitem>
</itemizedlist>
</para>
<para
>Якщо вами було створено якийсь корисний скрипт, ви зробити його вашим власним внеском до проєкту розробки &kappname;. Будь ласка, повідомте про вашу розробку у <ulink url="mailto:kwrite-devel@kde.org"
>списку листування програми</ulink
>. </para>
</sect4>
</sect3>
</sect2>
<sect2 id="dev-scripting-api">
<title
>Інтерфейс (API) роботи зі скриптами</title>
<para
>Програмним інтерфейсом роботи зі скриптами, основи якого викладено тут, можна користуватися у будь-яких скриптах, зокрема скриптах роботи з відступами та командному рядку програми. Класи <classname
>Cursor</classname
> і <classname
>Range</classname
> визначаються бібліотечними файлами у <filename
>$<envar
>XDG_DATA_DIRS</envar
>/katepart5/libraries</filename
>. Якщо вам потрібно ними скористатися у певному скрипті для використання якихось із функцій <classname
>Document</classname
> або <classname
>View</classname
>, будь ласка, включіть до скрипту потрібну вам бібліотеку такою командою: <programlisting
>// вимагаємо бібліотек JS katepart, наприклад range.js, якщо використовується Range
require ("range.js");
</programlisting>
</para>
<para
>Щоб розширити стандартний програмний інтерфейс (API) для роботи зі скриптами власними функціями і прототипами просто створіть файл у локальній теці файлів налаштування KDE, <filename
>$<envar
>XDG_DATA_HOME</envar
>/katepart5/libraries</filename
>, і включіть його до вашого скрипту за допомогою такого коду: <programlisting
>require ("vashscript.js");
</programlisting>
</para>
<para
>У &Windows; ці файли зберігаються у <filename
>%USERPROFILE%\AppData\Local\katepart5\libraries</filename
>. <replaceable
>%USERPROFILE%</replaceable
> зазвичай є скороченням для <filename
>C:\\Users\\<replaceable
>користувач</replaceable
></filename
>.</para>
<para
>Рекомендованим способом розширення можливостей прототипів, зокрема <classname
>Cursor</classname
> або <classname
>Range</classname
>, <emphasis
>не</emphasis
> є внесення змін до загальних файлів <filename
>*.js</filename
>. Для цього вам краще внести зміи до прототипу <classname
>Cursor</classname
> у JavaScript після команди включення <filename
>cursor.js</filename
> до вашого скрипту за допомогою <literal
>require</literal
>. </para>
<sect3 id="dev-scripting-api-prototypes">
<title
>Курсори і діапазони</title>
<para
>Оскільки &kappname; є текстовим редактором, весь програмний інтерфейс (API) за можливості засновано на курсорах та діапазонах тексту. Об’єкт Cursor (курсор) є простим кортежем <literal
>(line, column)</literal
> (рядок, стовпчик), що визначає позицію у тексті документа. Об’єкт Range (діапазон) це фрагмент тексту від початкової позиції курсора до кінцевої позиції курсора. Докладніше про програмний інтерфейс (API) ми поговоримо у наступних розділах. </para>
<sect4 id="dev-scripting-api-cursors">
<title
>Прототип Cursor (курсор)</title>
<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>
<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>
<varlistentry>
<term
><synopsis
>Cursor(<parameter
>Cursor <replaceable
>інший</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Конструктор копіювання. Повертає копію курсора <replaceable
>інший</replaceable
>. </para>
<para
>Приклад: <function
>var copy = new Cursor(other);</function
> </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>Cursor Cursor.clone();
</synopsis
></term>
<listitem
><para
>Повертає клон курсора.</para>
<para
>Приклад: <function
>var clone = cursor.clone();</function
> </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>Cursor.setPosition(<parameter
>int <replaceable
>рядок</replaceable
></parameter
>, <parameter
>int <replaceable
>позиція</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Встановлює курсор у місце вказане параметрами <replaceable
>рядок</replaceable
> і <replaceable
>позиція</replaceable
>.</para>
<para
>Актуальна версія: KDE 4.11 </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>bool Cursor.isValid();
</synopsis
></term>
<listitem
><para
>Перевіряє, чи є курсор коректним. Курсор вважається некоректним, якщо значення його позицій у рядку і/або стовпчику дорівнюють <literal
>-1</literal
>. </para>
<para
>Приклад: <function
>var valid = cursor.isValid();</function
> </para
></listitem>
</varlistentry>
<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>
<varlistentry>
<term
><synopsis
>int Cursor.compareTo(<parameter
>Cursor <replaceable
>інший</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Порівнює поточний курсор з курсором <replaceable
>інший</replaceable
>. Повертає <itemizedlist>
<listitem
><para
><literal
>-1</literal
>, якщо поточний курсор розташовано перед курсором <replaceable
>інший</replaceable
>,</para
></listitem>
<listitem
><para
><literal
>0</literal
>, якщо курсори у однакових позиціях і</para
></listitem>
<listitem
><para
><literal
>+1</literal
>, якщо поточний курсор розташовано після курсора <replaceable
>інший</replaceable
>.</para
></listitem>
</itemizedlist>
</para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>bool Cursor.equals(<parameter
>Cursor <replaceable
>інший</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Повертає <literal
>true</literal
>, якщо цей курсор і курсор <replaceable
>інший</replaceable
> є однаковими. Якщо це не так, повертає <literal
>false</literal
>. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>String Cursor.toString();
</synopsis
></term>
<listitem
><para
>Повертає об’єкт курсора як рядок у формі <quote
><literal
>Cursor(line, column)</literal
></quote
>. </para
></listitem>
</varlistentry
></variablelist>
</sect4>
<sect4 id="dev-scripting-api-ranges">
<title
>Прототип Range (діапазон)</title>
<variablelist
><varlistentry>
<term
><synopsis
>Range();
</synopsis
></term>
<listitem
><para
>Конструктор. Виклик <literal
>new Range()</literal
> повертає Range (діапазон) у (0, 0) - (0, 0). </para
></listitem>
</varlistentry>
<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 (діапазон)(<replaceable
>початок</replaceable
>, <replaceable
>кінець</replaceable
>). </para
></listitem>
</varlistentry>
<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>
<varlistentry>
<term
><synopsis
>Range(<parameter
>Range <replaceable
>інший</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Конструктор копіювання. Повертає копію Range <replaceable
>інший</replaceable
>. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>Range Range.clone();
</synopsis
></term>
<listitem
><para
>Повертає клон діапазону. </para>
<para
>Приклад: <function
>var clone = range.clone();</function
> </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>bool Range.isEmpty();
</synopsis
></term>
<listitem
><para
>Повертає <literal
>true</literal
>, якщо початкова і кінцева позиції курсора є рівними. </para>
<para
>Приклад: <function
>var empty = range.isEmpty();</function
> </para>
<para
>Актуальна версія: KDE 4.11 </para
></listitem>
</varlistentry>
<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>
<varlistentry>
<term
><synopsis
>Range Range.invalid();
</synopsis
></term>
<listitem
><para
>Повертає Range (діапазон) від (-1, -1) до (-1, -1). </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>bool Range.contains(<parameter
>Cursor <replaceable
>курсор</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Повертає <literal
>true</literal
>, якщо позиція курсора міститься у діапазоні, у іншому випадку повертає <constant
>false</constant
>. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>bool Range.contains(<parameter
>Range <replaceable
>інший</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Повертає <literal
>true</literal
>, якщо поточний діапазон містить діапазон <replaceable
>інший</replaceable
>. Якщо це не так, повертає <literal
>false</literal
>. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>bool Range.containsColumn(<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>
<varlistentry>
<term
><synopsis
>bool Range.containsLine(<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>
<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>
<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>
<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>
<varlistentry>
<term
><synopsis
>bool Range.onSingleLine();
</synopsis
></term>
<listitem
><para
>Повертає <literal
>true</literal
>, якщо діапазон починається і завершується на тому самому рядку, тобто якщо <replaceable
>Range.start.line == Range.end.line</replaceable
>. </para>
<para
>Актуальна версія: KDE 4.9 </para
></listitem>
</varlistentry>
<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>
<varlistentry>
<term
><synopsis
>String Range.toString();
</synopsis
></term>
<listitem
><para
>Повертає діапазон у форматі <quote
><literal
>Range(Cursor(line, column), Cursor(line, column))</literal
></quote
>. </para
></listitem>
</varlistentry
></variablelist>
</sect4>
</sect3>
<sect3 id="dev-scripting-api-global">
<title
>Загальні функції (Global Functions)</title>
<para
>У цьому розділі наведено всі загальні функції.</para>
<sect4 id="dev-scripting-api-includes">
<title
>Читання і включення файлів</title>
<variablelist
><varlistentry>
<term
><synopsis
>String read(<parameter
>String <replaceable
>назва файла</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Виконає пошук файла з назвою <replaceable
>назва файла</replaceable
> у каталозі <literal
>katepart5/script/files</literal
> і поверне його вміст як рядок. </para
></listitem>
</varlistentry
></variablelist>
<variablelist
><varlistentry>
<term
><synopsis
>void require(<parameter
>String <replaceable
>назва файла</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Виконає пошук файла з назвою <replaceable
>назва файла</replaceable
> у каталозі <literal
>katepart5/script/libraries</literal
> і обробить його код. У <literal
>require</literal
> передбачено вбудований захист від повторного включення одного і того самого файла. </para>
<para
>Актуальна версія: KDE 4.10 </para>
</listitem>
</varlistentry
></variablelist>
</sect4>
<sect4 id="dev-scripting-api-debug">
<title
>Налагоджування (Debugging)</title>
<variablelist
><varlistentry>
<term
><synopsis
>void debug(<parameter
>String <replaceable
>текст</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Виводить <replaceable
>текст</replaceable
> до <literal
>stdout</literal
> у консоль, з якої запущено програму. </para
></listitem>
</varlistentry
></variablelist>
</sect4>
<sect4 id="dev-scripting-api-i18n">
<title
>Переклад (Translation)</title>
<para
>Повноцінна локалізація стане можливою лише за використання декількох функцій, призначених для перекладу рядків у скриптах, а саме <literal
>i18n</literal
>, <literal
>i18nc</literal
>, <literal
>i18np</literal
> і <literal
>i18ncp</literal
>. Робота цих функцій подібна до роботи <ulink url="https://techbase.kde.org/Development/Tutorials/Localization/i18n"
>функцій перекладу рядків у KDE</ulink
>. </para>
<para
>За допомогою функцій перекладу і системи перекладу KDE вбудовані у скрипт рядки повідомлень може бути перекладено мовою інтерфейсу програми. Рядки у скриптах, які є частиною офіційної збірки &kappname; буде автоматично видобуто і подано для перекладу командами перекладачів KDE. Іншими словами, якщо ви є розробником основної гілки &kappname;, ви не маєте перейматися видобуванням повідомлень і їхнім перекладом. Втім, слід зауважити, що переклад працюватиме лише у межах інфраструктури &kde;, тобто переклад нових рядків скриптів, розроблених поза межами &kde;, неможливий. Тому вам варто надіслати вашу роботу до основної гілки розробки &kate;, щоб уможливити належний переклад. </para>
<variablelist
><varlistentry>
<term
><synopsis
>void i18n(<parameter
>String <replaceable
>текст</replaceable
></parameter
>, <replaceable
>параметр1</replaceable
>, ...);
</synopsis
></term>
<listitem
><para
>Перекладає <replaceable
>текст</replaceable
> мовою, використаною у інтерфейсі програми. Параметри <replaceable
>параметр1</replaceable
>, ... є необов’язковими. Вони є замінниками рядків <literal
>%1</literal
>, <literal
>%2</literal
> тощо.</para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>void i18nc(<parameter
>String <replaceable
>контекст</replaceable
></parameter
>, <parameter
>String <replaceable
>текст</replaceable
></parameter
>, <replaceable
>параметр1</replaceable
>, ...);
</synopsis
></term>
<listitem
><para
>Перекладає <replaceable
>текст</replaceable
> мовою, використаною у інтерфейсі програми. Крім того, перекладачі зможуть побачити рядок <replaceable
>контекст</replaceable
>. За допомогою контексту перекладачам буде простіше правильно перекласти рядок. Параметри <replaceable
>параметр1</replaceable
>, ... є необов’язковими. Вони є замінниками рядків <literal
>%1</literal
>, <literal
>%2</literal
> тощо.</para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>void i18np(<parameter
>String <replaceable
>однина</replaceable
></parameter
>, <parameter
>String <replaceable
>множина</replaceable
></parameter
>, <parameter
>int <replaceable
>кількість</replaceable
></parameter
>, <replaceable
>параметр1</replaceable
>, ...);
</synopsis
></term>
<listitem
><para
>Перекладає <replaceable
>однину</replaceable
> або <replaceable
>множину</replaceable
> повідомлення мовою, використаною у інтерфейсі програми залежно від вказаного значення <replaceable
>кількість</replaceable
>. Параметри <replaceable
>параметр1</replaceable
>, ... є необов’язковими. Вони є замінниками рядків <literal
>%1</literal
>, <literal
>%2</literal
> тощо.</para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>void i18ncp(<parameter
>String <replaceable
>контекст</replaceable
></parameter
>, <parameter
>String <replaceable
>однина</replaceable
></parameter
>, <parameter
>String <replaceable
>множина</replaceable
></parameter
>, <parameter
>int <replaceable
>кількість</replaceable
></parameter
>, <replaceable
>параметр1</replaceable
>, ...);
</synopsis
></term>
<listitem
><para
>Перекладає <replaceable
>однину</replaceable
> або <replaceable
>множину</replaceable
> повідомлення мовою, використаною у інтерфейсі програми залежно від вказаного значення <replaceable
>кількість</replaceable
>. Крім того, перекладачі зможуть побачити рядок <replaceable
>контекст</replaceable
>. За допомогою контексту перекладачам буде простіше правильно перекласти рядок. Параметри <replaceable
>параметр1</replaceable
>, ... є необов’язковими. Вони є замінниками рядків <literal
>%1</literal
>, <literal
>%2</literal
> тощо.</para
></listitem>
</varlistentry
></variablelist>
</sect4>
</sect3>
<sect3 id="dev-scripting-api-view">
<title
>Програмний інтерфейс <classname
>View</classname
></title>
<para
>Яким би чином не було запущено скрипт, він завжди користуватиметься загальною змінною <quote
><literal
>view</literal
></quote
>, що відповідає поточній активній панелі перегляду. Нижче наведено список всіх типових функцій об’єкта View. <variablelist>
<varlistentry>
<term
><synopsis
><function
>void view.copy()</function
>
</synopsis
></term>
<listitem>
<para
>Копіювати позначений фрагмент, якщо щось позначено. Якщо нічого не позначено, копіювати поточний рядок, якщо позначено пункт налаштувань <userinput
>[ ] Копіювати/Вирізати поточний рядок, якщо нічого не позначено</userinput
>.</para>
<para
>Актуальна версія: &kde-frameworks; 5.79</para>
</listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
><function
>void view.cut()</function
>
</synopsis
></term>
<listitem>
<para
>Вирізати позначений фрагмент, якщо щось позначено. Якщо нічого не позначено, вирізати поточний рядок, якщо позначено пункт налаштувань <userinput
>[ ] Копіювати/Вирізати поточний рядок, якщо нічого не позначено</userinput
>.</para>
<para
>Актуальна версія: &kde-frameworks; 5.79</para>
</listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
><function
>void view.paste()</function
>
</synopsis
></term>
<listitem>
<para
>Вставити вміст буфера обміну даними.</para>
<para
>Актуальна версія: &kde-frameworks; 5.79</para>
</listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
><function
>Cursor view.cursorPosition()</function
>
</synopsis
></term>
<listitem
><para
>Повертає поточну позицію курсора у області перегляду.</para
></listitem>
</varlistentry>
<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
>Встановлює для поточного курсора позицію, вказану напряму (рядок, стовпчик), або позицію вказаного курсора. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>Cursor view.virtualCursorPosition();
</synopsis
></term>
<listitem
><para
>Повертає позицію віртуального курсора. Всі символи табуляцій буде враховано за допомогою відповідної кількості пробілів, яка залежатиме від поточної ширини табуляції. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>void view.setVirtualCursorPosition(<parameter
>int <replaceable
>рядок</replaceable
></parameter
>, <parameter
>int <replaceable
>стовпчик</replaceable
></parameter
>);
void view.setVirtualCursorPosition(<parameter
>Cursor <replaceable
>курсор</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Встановлює для віртуального курсора позицію, вказану напряму (рядок, стовпчик), або позицію вказаного курсора. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>String view.selectedText();
</synopsis
></term>
<listitem
><para
>Повертає позначений фрагмент тексту. Якщо жодного фрагменту не позначено, повертає порожній рядок. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>bool view.hasSelection();
</synopsis
></term>
<listitem
><para
>Повертає <literal
>true</literal
>, якщо у області перегляду позначено фрагмент тексту, інакше повертає <literal
>false</literal
>. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>Range view.selection();
</synopsis
></term>
<listitem
><para
>Повертає діапазон позначеного фрагменту тексту. Якщо жодного фрагменту не позначено, буде повернуто некоректний діапазон. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>void view.setSelection(<parameter
>Range <replaceable
>діапазон</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Встановлює позначення тексту за вказаним діапазоном. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>void view.removeSelectedText();
</synopsis
></term>
<listitem
><para
>Вилучає позначений текст. Якщо у області перегляду не було позначено жодного тексту, ніяких дій виконано не буде. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>void view.selectAll();
</synopsis
></term>
<listitem
><para
>Позначає весь текст у документі. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>void view.clearSelection();
</synopsis
></term>
<listitem
><para
>Знімає позначення фрагменту тексту, не вилучаючи сам текст. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>void view.setBlockSelection(bool on);
</synopsis
></term>
<listitem
><para
>Вмикає або вимикає режим позначення блоку. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>bool view.blockSelection();
</synopsis
></term>
<listitem
><para
>Повертає <literal
>true</literal
>, якщо увімкнено режим позначення блоку, інакше повертає <literal
>false</literal
>. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>void view.align(<parameter
>Range <replaceable
>діапазон</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Належним чином повторно встановити відступи рядків у вказаному діапазоні <replaceable
>діапазон</replaceable
> за поточними параметрами відступів. </para>
</listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>void view.alignOn(<parameter
>Range <replaceable
>діапазон</replaceable
></parameter
>, <parameter
>String <replaceable
>взірець</replaceable
> = ""</parameter
>);
</synopsis
></term>
<listitem
><para
>Вирівнює рядки у діапазоні <replaceable
>діапазон</replaceable
> у позиції, яку задано формальним виразом <replaceable
>взірець</replaceable
>. Якщо буде вказано порожній <replaceable
>взірець</replaceable
>, вирівнювання типово відбудеться за першим непорожнім символом. Якщо у взірці буде вказано блок захоплення, вирівнювання відбудеться за захопленим блоком. </para>
<para
><emphasis
>Приклади:</emphasis
></para>
<para
><literal
>view.alignOn(document.documentRange(), '-');</literal
> вставить пробіли до першого <literal
>-</literal
> у кожному з рядків для вирівнювання усіх дефісів за вказаною позицією.</para>
<para
><literal
>view.alignOn(document.documentRange(), ':\\s+(.)');</literal
> вставить пробіли до першого непорожнього символу, який стоїть після двокрапки, для вирівнювання усіх таких символів за однаковою позицією.</para>
</listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>object view.executeCommand(<parameter
>String <replaceable
>команда</replaceable
></parameter
>,
<parameter
>String <replaceable
>аргументи</replaceable
></parameter
>,
<parameter
>Range <replaceable
>діапазон</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Виконує <link linkend="advanced-editing-tools-commandline"
>команду</link
> <replaceable
>команда</replaceable
> із додатковими аргументами <replaceable
>аргументи</replaceable
> і необов'язковим діапазоном <replaceable
>діапазон</replaceable
>. Повернутий об'єкт <replaceable
>object</replaceable
> є булевою властивістю <replaceable
>object.ok</replaceable
>, яка вказує на те, чи було успішним виконання команди <replaceable
>команда</replaceable
>. Якщо сталася помилка, у рядку <replaceable
>object.status</replaceable
> міститиметься повідомлення про помилку. </para>
<para
>Актуальна версія: &kde-frameworks; 5.50</para>
</listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>Range view.searchText(<parameter
>Range <replaceable
>діапазон</replaceable
></parameter
>,
<parameter
>String <replaceable
>взірець</replaceable
></parameter
>,
<parameter
>bool <replaceable
>назад</replaceable
> = false</parameter
>);
</synopsis
></term>
<listitem
><para
>Шукати перше включення <replaceable
>взірця</replaceable
> у <replaceable
>діапазоні</replaceable
> і повернути знайдений діапазон. Пошук буде виконано у зворотному напрямку, якщо для додаткового булевого параметра <replaceable
>назад</replaceable
> буде встановлено значення <literal
>true</literal
>. </para>
<para
>Повернутий діапазон буде некоректним (див. Range.isValid()), якщо <replaceable
>взірець</replaceable
> не буде знайдено у <replaceable
>діапазоні</replaceable
>. </para>
<para
>Актуальна версія: &kde-frameworks; 5.97</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</sect3>
<sect3 id="dev-scripting-api-document">
<title
>Програмний інтерфейс (API) <classname
>Document</classname
></title>
<para
>Яким би чином не було запущено скрипт, він завжди користуватиметься загальною змінною <quote
><literal
>document</literal
></quote
>, що відповідає поточній активній панелі перегляду. Нижче наведено список всіх типових функцій об’єкта Document. <variablelist>
<varlistentry>
<term
><synopsis
>String document.fileName();
</synopsis
></term>
<listitem
><para
>Повертає назву файла документа або порожній рядок для незбережених буферів з текстом. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>String document.url();
</synopsis
></term>
<listitem
><para
>Повертає адресу URL документа повністю або порожній рядок для незбережених буферів з текстом. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>String document.mimeType();
</synopsis
></term>
<listitem
><para
>Повертає тип &MIME; документа або тип &MIME; <literal
>application/octet-stream</literal
>, якщо відповідного типу &MIME; встановити не вдасться. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>String document.encoding();
</synopsis
></term>
<listitem
><para
>Повертає поточне кодування символів, яке буде використано для збереження даних файла. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>String document.highlightingMode();
</synopsis
></term>
<listitem
><para
>Повертає загальний режим підсвічування, використаний у всьому документі. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>String document.highlightingModeAt(<parameter
>Cursor <replaceable
>позиція</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Повертає режим підсвічування, використаний за вказаною позицією у тексті. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>Array document.embeddedHighlightingModes();
</synopsis
></term>
<listitem
><para
>Повертає масив режимів підсвічування, вбудованих до поточного документа. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>bool document.isModified();
</synopsis
></term>
<listitem
><para
>Повертає <literal
>true</literal
>, якщо у документі є незбережені зміни, інакше повертає <literal
>false</literal
>. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>String document.text();
</synopsis
></term>
<listitem
><para
>Повертає увесь вміст документа у формі єдиного рядка тексту. Розриви рядків буде позначено символом розриву рядка <quote
><literal
>\n</literal
></quote
>. </para
></listitem>
</varlistentry>
<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>
<varlistentry>
<term
><synopsis
>String document.line(<parameter
>int <replaceable
>рядок</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Повертає рядок за його номером у тексті. Якщо вказаний номер не належатиме до діапазону номерів рядків документа, буде повернуто порожній рядок. </para
></listitem>
</varlistentry>
<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>
<varlistentry>
<term>
<synopsis
>Range document.wordRangeAt(<parameter
>int <replaceable
>рядок</replaceable
></parameter
>, <parameter
>int <replaceable
>стовпчик</replaceable
></parameter
>);
Range document.wordRangeAt(<parameter
>Cursor <replaceable
>курсор</replaceable
></parameter
>);
</synopsis>
</term>
<listitem
><para
>Повертає діапазон слова за вказаним розташуванням курсора. Повернуте значення діапазону буде некоректним (див. Range.isValid()), якщо текст розташовано за кінцем рядка. Якщо за вказаним розташуванням курсора не буде слова, функцією буде повернуто порожній діапазон. </para>
<para
>Актуальна версія: KDE 4.9 </para>
</listitem>
</varlistentry>
<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>
<varlistentry>
<term
><synopsis
>String document.firstChar(<parameter
>int <replaceable
>рядок</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Повертає перший символ вказаного рядка <replaceable
>рядок</replaceable
>, який не є пробілом. Першим символом рядка вважається символ у стовпчику 0. Якщо рядок є порожнім або складається лише з пробілів, функція повертає порожній рядок. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>String document.lastChar(<parameter
>int <replaceable
>рядок</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Повертає останній символ вказаного рядка <replaceable
>рядок</replaceable
>, який не є пробілом. Якщо рядок є порожнім або складається лише з пробілів, функція повертає порожній рядок. </para
></listitem>
</varlistentry>
<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>
<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
>, якщо вказаний <replaceable
>текст</replaceable
> розташовано за відповідною позицією курсора. Якщо це не так, повертає <literal
>false</literal
>. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>bool document.startsWith(<parameter
>int <replaceable
>рядок</replaceable
></parameter
>, <parameter
>String <replaceable
>текст</replaceable
></parameter
>, <parameter
>bool <replaceable
>пропускатиПробіли</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Повертає <literal
>true</literal
>, якщо рядок з вказаним номером починається з фрагмента тексту <replaceable
>текст</replaceable
>. Якщо це не так, повертає <literal
>false</literal
>. За допомогою параметра <replaceable
>пропускатиПробіли</replaceable
> можна вказати програмі, чи слід ігнорувати пробіли. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>bool document.endsWith(<parameter
>int <replaceable
>рядок</replaceable
></parameter
>, <parameter
>String <replaceable
>текст</replaceable
></parameter
>, <parameter
>bool <replaceable
>пропускатиПробіли</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Повертає <literal
>true</literal
>, якщо рядок з вказаним номером завершується фрагментом тексту <replaceable
>текст</replaceable
>. Якщо це не так, повертає <literal
>false</literal
>. За допомогою параметра <replaceable
>пропускатиПробіли</replaceable
> можна вказати програмі, чи слід ігнорувати пробіли. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>bool document.setText(<parameter
>String <replaceable
>текст</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Замінює весь вміст документа на <parameter
>текст</parameter
>. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>bool document.clear();
</synopsis
></term>
<listitem
><para
>Вилучає з документа весь текст. </para
></listitem>
</varlistentry>
<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>
<varlistentry>
<term
><synopsis
>bool document.insertText(<parameter
>int <replaceable
>рядок</replaceable
></parameter
>, <parameter
>int <replaceable
>стовпчик</replaceable
></parameter
>, <parameter
>String <replaceable
>текст</replaceable
></parameter
>);
bool document.insertText(<parameter
>Cursor <replaceable
>курсор</replaceable
></parameter
>, <parameter
>String <replaceable
>текст</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Вставляє фрагмент тексту <replaceable
>текст</replaceable
> у вказану позицію курсора. Повертає <literal
>true</literal
> у разі успіху або <literal
>false</literal
>, якщо документ відкрито у режимі лише для читання. </para
></listitem>
</varlistentry>
<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>
<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>
<varlistentry>
<term
><synopsis
>bool document.removeLine(<parameter
>int <replaceable
>рядок</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Вилучає рядок з вказаним номером. Повертає <literal
>true</literal
> у разі успіху або <literal
>false</literal
>, якщо документ відкрито у режимі лише для читання або рядка з вказаним номером у документі немає. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>bool document.wrapLine(<parameter
>int <replaceable
>рядок</replaceable
></parameter
>, <parameter
>int <replaceable
>стовпчик</replaceable
></parameter
>);
bool document.wrapLine(<parameter
>Cursor <replaceable
>курсор</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Обрізає рядок з вказаним номером за вказаним розташуванням курсора. Повертає <literal
>true</literal
> у разі успіху. У інших випадках повертає <literal
>false</literal
> (наприклад, якщо номер рядка < 0). </para>
<para
>Актуальна версія: KDE 4.9 </para>
</listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>void document.joinLines(<parameter
>int <replaceable
>початковийРядок</replaceable
></parameter
>, <parameter
>int <replaceable
>кінцевийРядок</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Об’єднує рядки у діапазоні від<replaceable
>початковийРядок</replaceable
> до <replaceable
>кінцевийРядок</replaceable
>. Послідовні рядки тексту завжди відокремлюються одинарним пробілом. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>int document.lines();
</synopsis
></term>
<listitem
><para
>Повертає кількість рядків у документі. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>bool document.isLineModified(<parameter
>int <replaceable
>рядок</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Повертає <literal
>true</literal
>, якщо у рядку <replaceable
>рядок</replaceable
> зараз містяться незбережені дані. </para>
<para
>Актуальна версія: &kde; 5.0 </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>bool document.isLineSaved(<parameter
>int <replaceable
>рядок</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Повертає <literal
>true</literal
>, якщо <replaceable
>рядок</replaceable
> було змінено, після чого документ було збережено. Інакше кажучи, у рядку вже не міститься незбережених даних. </para>
<para
>Актуальна версія: &kde; 5.0 </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>bool document.isLineTouched(<parameter
>int <replaceable
>рядок</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Повертає <literal
>true</literal
>, якщо у рядку <replaceable
>рядок</replaceable
> зараз містяться незбережені дані або його вміст було раніше змінено. </para>
<para
>Актуальна версія: &kde; 5.0 </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>bool document.findTouchedLine(<parameter
>int <replaceable
>початковийРядок</replaceable
></parameter
>, <parameter
>bool <replaceable
>напрямок</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Шукати наступний змінений рядок, починаючи з рядка <replaceable
>початковийРядок</replaceable
>. Пошук виконується у напрямку кінця або початку документа залежно від напрямку пошуку, визначеного параметром <replaceable
>напрям</replaceable
>. </para>
<para
>Актуальна версія: &kde; 5.0 </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>int document.length();
</synopsis
></term>
<listitem
><para
>Повертає кількість символів у документі. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>int document.lineLength(<parameter
>int <replaceable
>рядок</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Повертає довжину рядка з номером <replaceable
>рядок</replaceable
>. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>void document.editBegin();
</synopsis
></term>
<listitem
><para
>Започатковує групу редагування для впорядкування операцій зі скасування або повторення дій. Не забувайте, що викликати <function
>editEnd()</function
> слід саме стільки разів, скільки разів було викликано <function
>editBegin()</function
>. Виклики <function
>editBegin()</function
> використовують вбудований лічильник, отже їх може бути вкладено один у оден. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>void document.editEnd();
</synopsis
></term>
<listitem
><para
>Завершує групу редагування. Останній виклик <function
>editEnd()</function
> (тобто відповідник першого виклику <function
>editBegin()</function
>) завершує крок з редагування. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>int document.firstColumn(<parameter
>int <replaceable
>рядок</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Повертає перший відмінний від пробілу стовпчик у вказаному за допомогою параметра номера, <replaceable
>рядок</replaceable
>, рядку. Якщо у рядку будуть лише пробіли, функція поверне значення <literal
>-1</literal
>. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>int document.lastColumn(<parameter
>int <replaceable
>рядок</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Повертає останній відмінний від пробілу стовпчик у вказаному за допомогою параметра номера, <replaceable
>рядок</replaceable
>, рядку. Якщо у рядку будуть лише пробіли, функція поверне значення <literal
>-1</literal
>. </para
></listitem>
</varlistentry>
<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>
<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>
<varlistentry>
<term
><synopsis
>int document.prevNonEmptyLine(<parameter
>int <replaceable
>рядок</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Повертає наступний непорожній рядок, що містить символи, відмінні від пробілів. Пошук відбуватиметься у напрямку початку документа. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>int document.nextNonEmptyLine(<parameter
>int <replaceable
>рядок</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Повертає наступний непорожній рядок, що містить символи, відмінні від пробілів. Пошук відбуватиметься у напрямку кінця документа. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>bool document.isInWord(<parameter
>String <replaceable
>символ</replaceable
></parameter
>, <parameter
>int <replaceable
>атрибут</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Повертає <literal
>true</literal
>, якщо вказаний <replaceable
>символ</replaceable
> з вказаним параметром <replaceable
>атрибут</replaceable
> може бути частиною слова. Якщо це не так, повертає <literal
>false</literal
>. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>bool document.canBreakAt(<parameter
>String <replaceable
>символ</replaceable
></parameter
>, <parameter
>int <replaceable
>атрибут</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Повертає <literal
>true</literal
>, якщо вказаний <replaceable
>символ</replaceable
> з вказаним параметром <replaceable
>атрибут</replaceable
> може бути використано для розбиття рядка. Якщо це не так, повертає <literal
>false</literal
>. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>bool document.canComment(<parameter
>int <replaceable
>атрибутПочатку</replaceable
></parameter
>, <parameter
>int <replaceable
>атрибутКінця</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Повертає <literal
>true</literal
>, якщо діапазон тексту, початок і кінець якого визначаються на основі вказаних атрибутів, можна закоментувати. Якщо це не так, повертає <literal
>false</literal
>. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>String document.commentMarker(<parameter
>int <replaceable
>атрибут</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Повертає позначку коментаря для окремого рядка коментарів з вказаним параметром <replaceable
>атрибут</replaceable
>. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>String document.commentStart(<parameter
>int <replaceable
>атрибут</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Повертає позначку, якою має розпочинатися багаторядковий коментар для вказаного значення параметра <replaceable
>атрибут</replaceable
>. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>String document.commentEnd(<parameter
>int <replaceable
>атрибут</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Повертає позначку, якою має розпочинатися багаторядковий коментар для вказаного значення параметра <replaceable
>атрибут</replaceable
>. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>Range document.documentRange();
</synopsis
></term>
<listitem
><para
>Повертає діапазон всього документа. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>Cursor documentEnd();
</synopsis
></term>
<listitem
><para
>Повертає курсор, розташований у останній позиції останнього рядка у документі. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>bool isValidTextPosition(<parameter
>int <replaceable
>рядок</replaceable
></parameter
>, <parameter
>int <replaceable
>позиція</replaceable
></parameter
>);
bool isValidTextPosition(<parameter
>Cursor <replaceable
>курсор</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Повертає <literal
>true</literal
>, якщо вказану позицію курсора розташовано у коректній позиції у тексті. Позиція у тексті є коректною, лише якщо її розташовано на початку, у середині або у кінці коректного рядка тексту. Крім того, текстова позиція є некоректною, якщо її розташовано посередині замінника символу Unicode. </para
><para
>Актуальна версія: &kde; 5.0 </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>int document.attribute(<parameter
>int <replaceable
>рядок</replaceable
></parameter
>, <parameter
>int <replaceable
>стовпчик</replaceable
></parameter
>);
int document.attribute(<parameter
>Cursor <replaceable
>курсор</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Повертає атрибут за вказаною позицією курсора. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>bool document.isAttribute(<parameter
>int <replaceable
>рядок</replaceable
></parameter
>, <parameter
>int <replaceable
>стовпчик</replaceable
></parameter
>, <parameter
>int <replaceable
>атрибут</replaceable
></parameter
>);
bool document.isAttribute(<parameter
>Cursor <replaceable
>курсор</replaceable
></parameter
>, <parameter
>int <replaceable
>атрибут</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Повертає <literal
>true</literal
>, якщо атрибут за вказаною позицією курсора дорівнює значенню параметра <replaceable
>атрибут</replaceable
>. Якщо це не так, повертає <literal
>false</literal
>. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>String document.attributeName(<parameter
>int <replaceable
>рядок</replaceable
></parameter
>, <parameter
>int <replaceable
>стовпчик</replaceable
></parameter
>);
String document.attributeName(<parameter
>Cursor <replaceable
>курсор</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Повертає назву атрибута придатну до читання. Ця назва відповідає назві <literal
>itemData</literal
> у файлах підсвічування синтаксичних конструкцій. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>bool document.isAttributeName(<parameter
>int <replaceable
>рядок</replaceable
></parameter
>, <parameter
>int <replaceable
>стовпчик</replaceable
></parameter
>, <parameter
>String <replaceable
>назва</replaceable
></parameter
>);
bool document.isAttributeName(<parameter
>Cursor <replaceable
>курсор</replaceable
></parameter
>, <parameter
>String <replaceable
>назва</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Повертає <literal
>true</literal
>, якщо назва атрибута у певній позиції курсора відповідає вказаному значенню параметра <replaceable
>назва</replaceable
>. Якщо це не так, повертає <literal
>false</literal
>. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>String document.variable(<parameter
>String <replaceable
>ключ</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Повертає значення вказаної змінної документа <replaceable
>ключ</replaceable
>. Якщо змінної з вказаною назвою у документі не існує, повертає порожній рядок. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>void document.setVariable(<parameter
>String <replaceable
>ключ</replaceable
></parameter
>, <parameter
>String <replaceable
>значення</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Встановлює значення відповідної змінної документа <replaceable
>ключ</replaceable
>. </para>
<para
>Див. також <link linkend="config-variables"
>змінні документа Kate</link
> </para>
<para
>Актуальна версія: KDE 4.8 </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>int document.firstVirtualColumn(<parameter
>int <replaceable
>рядок</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Повертає віртуальний стовпчик першого відмінного від пробілу символу у вказаному рядку або <literal
>-1</literal
>, якщо рядок є порожнім або містить лише символи пробілів. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>int document.lastVirtualColumn(<parameter
>int <replaceable
>рядок</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Повертає віртуальний стовпчик останнього відмінного від пробілу символу у вказаному рядку або <literal
>-1</literal
>, якщо рядок є порожнім або містить лише символи пробілів. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>int document.toVirtualColumn(<parameter
>int <replaceable
>рядок</replaceable
></parameter
>, <parameter
>int <replaceable
>стовпчик</replaceable
></parameter
>);
int document.toVirtualColumn(<parameter
>Cursor <replaceable
>курсор</replaceable
></parameter
>);
Cursor document.toVirtualCursor(<parameter
>Cursor <replaceable
>курсор</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Перетворює вказану «реальну» позицію курсора на віртуальну позицію курсора, повертає або ціле значення (int), або об’єкт Cursor. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>int document.fromVirtualColumn(<parameter
>int <replaceable
>line</replaceable
></parameter
>, <parameter
>int <replaceable
>virtualColumn</replaceable
></parameter
>);
int document.fromVirtualColumn(<parameter
>Cursor <replaceable
>virtualCursor</replaceable
></parameter
>);
Cursor document.fromVirtualCursor(<parameter
>Cursor <replaceable
>віртуальнийКурсор</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Перетворює вказану віртуальну позицію курсора на «реальну» позицію курсора, повертає або ціле значення (int), або об’єкт Cursor. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>Cursor document.anchor(<parameter
>int <replaceable
>рядок</replaceable
></parameter
>, <parameter
>int <replaceable
>стовпчик</replaceable
></parameter
>, <parameter
>Char <replaceable
>символ</replaceable
></parameter
>);
Cursor document.anchor(<parameter
>Cursor <replaceable
>курсор</replaceable
></parameter
>, <parameter
>Char <replaceable
>символ</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Виконує пошук у напрямку початку документа, починаючи від вказаної позиції курсора, вказаного символу. Наприклад, якщо функції буде передано символ «(», функція поверне позицію початкової дужки «(». Відповідність дужок не враховуватиметься, тобто інші «(...)» буде проігноровано. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>Cursor document.rfind(<parameter
>int <replaceable
>рядок</replaceable
></parameter
>, <parameter
>int <replaceable
>стовпчик</replaceable
></parameter
>, <parameter
>String <replaceable
>текст</replaceable
></parameter
>, <parameter
>int <replaceable
>атрибут</replaceable
> = -1</parameter
>);
Cursor document.rfind(<parameter
>Cursor <replaceable
>курсор</replaceable
></parameter
>, <parameter
>String <replaceable
>текст</replaceable
></parameter
>, <parameter
>int <replaceable
>атрибут</replaceable
> = -1</parameter
>);
</synopsis
></term>
<listitem
><para
>Виконує пошук у напрямку початку документа вказаного фрагмента тексту з відповідним значенням параметра <replaceable
>атрибут</replaceable
>. Параметр <replaceable
>атрибут</replaceable
> буде проігноровано, якщо він матиме значення <literal
>-1</literal
>. Функція поверне значення некоректного курсора, якщо фрагмент тексту знайти не вдасться. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>int document.defStyleNum(<parameter
>int <replaceable
>рядок</replaceable
></parameter
>, <parameter
>int <replaceable
>стовпчик</replaceable
></parameter
>);
int document.defStyleNum(<parameter
>Cursor <replaceable
>курсор</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Повертає типовий стиль курсора, використаний за вказаною позицією у тексті. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>bool document.isCode(<parameter
>int <replaceable
>рядок</replaceable
></parameter
>, <parameter
>int <replaceable
>стовпчик</replaceable
></parameter
>);
bool document.isCode(<parameter
>Cursor <replaceable
>курсор</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Повертає <literal
>true</literal
>, якщо атрибут за вказаною позицією курсора не дорівнює жодному зі значень стилів: <literal
>dsComment</literal
>, <literal
>dsString</literal
>, <literal
>dsRegionMarker</literal
>, <literal
>dsChar</literal
>, <literal
>dsOthers</literal
>. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>bool document.isComment(<parameter
>int <replaceable
>рядок</replaceable
></parameter
>, <parameter
>int <replaceable
>стовпчик</replaceable
></parameter
>);
bool document.isComment(<parameter
>Cursor <replaceable
>курсор</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Повертає <literal
>true</literal
>, якщо значенням атрибута символу у позиції курсора є <literal
>dsComment</literal
>. Якщо це не так, повертає <literal
>false</literal
>. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>bool document.isString(<parameter
>int <replaceable
>рядок</replaceable
></parameter
>, <parameter
>int <replaceable
>стовпчик</replaceable
></parameter
>);
bool document.isString(<parameter
>Cursor <replaceable
>курсор</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Повертає <literal
>true</literal
>, якщо значенням атрибута символу у позиції курсора є <literal
>dsString</literal
>. Якщо це не так, повертає <literal
>false</literal
>. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>bool document.isRegionMarker(<parameter
>int <replaceable
>рядок</replaceable
></parameter
>, <parameter
>int <replaceable
>стовпчик</replaceable
></parameter
>);
bool document.isRegionMarker(<parameter
>Cursor <replaceable
>курсор</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Повертає <literal
>true</literal
>, якщо значенням атрибута символу у позиції курсора є <literal
>dsRegionMarker</literal
>. Якщо це не так, повертає <literal
>false</literal
>. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>bool document.isChar(<parameter
>int <replaceable
>рядок</replaceable
></parameter
>, <parameter
>int <replaceable
>стовпчик</replaceable
></parameter
>);
bool document.isChar(<parameter
>Cursor <replaceable
>курсор</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Повертає <literal
>true</literal
>, якщо значенням атрибута символу у позиції курсора є <literal
>dsChar</literal
>. Якщо це не так, повертає <literal
>false</literal
>. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>bool document.isOthers(<parameter
>int <replaceable
>рядок</replaceable
></parameter
>, <parameter
>int <replaceable
>стовпчик</replaceable
></parameter
>);
bool document.isOthers(<parameter
>Cursor <replaceable
>курсор</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Повертає <literal
>true</literal
>, якщо значенням атрибута символу у позиції курсора є <literal
>dsOthers</literal
>. Якщо це не так, повертає <literal
>false</literal
>. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>void document.indent(<parameter
>Range <replaceable
>діапазон</replaceable
></parameter
>, <parameter
>int <replaceable
>зміна</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Встановити відступи у всіх рядка у діапазоні <replaceable
>діапазон</replaceable
> на <replaceable
>зміна</replaceable
> табуляцій або <replaceable
>зміна</replaceable
> разів на <literal
>tabSize</literal
> пробілів, залежно від визначених користувачем параметрів. Значення <replaceable
>зміна</replaceable
> може бути від'ємним. </para
></listitem>
</varlistentry>
</variablelist>
</para>
</sect3>
<sect3 id="dev-scripting-api-editor">
<title
>Програмний інтерфейс редактора</title>
<para
>Окрім програмного інтерфейсу документа та області перегляду, існує і загальний програмний інтерфейс редактора, який надає доступ до загальних функцій керування редактором за допомогою скриптів. <variablelist>
<varlistentry>
<term
><synopsis
>String editor.clipboardText();
</synopsis
></term>
<listitem
><para
>Повертає текст, який зберігається у загальному буфері обміну даними. </para>
<para
>Актуальна версія: &kde-frameworks; 5.50</para>
</listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>String editor.clipboardHistory();
</synopsis
></term>
<listitem
><para
>Редактор зберігає журнал буфера обміну даними, який містить до 10 записів. Ця функція повертає усі записи, які зараз перебувають у журналі буфера обміну даними. </para>
<para
>Актуальна версія: &kde-frameworks; 5.50</para>
</listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>void editor.setClipboardText(<parameter
>String <replaceable
>текст</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Встановлює для вмісту буфера обміну даними значення <replaceable
>текст</replaceable
>. Запис <replaceable
>текст</replaceable
> буде додано до журналу буфера обміну даними. </para>
<para
>Актуальна версія: &kde-frameworks; 5.50</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</sect3>
</sect2>
</sect1>
</chapter>
Generated by dwww version 1.15 on Sun Jun 30 00:51:24 CEST 2024.