<!-- 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
>uj2@mail.ru</email
></address
></affiliation
><contrib
>Перевод на русский язык</contrib
></othercredit
> <othercredit role="translator"
><firstname
>Алексей</firstname
><surname
>Опарин</surname
><affiliation
><address
><email
>opaleksej@yandex.ru</email
></address
></affiliation
><contrib
>Перевод на русский язык</contrib
></othercredit
><othercredit role="translator"
><firstname
>Олеся</firstname
><surname
>Герасименко</surname
><affiliation
><address
><email
>translation-team@basealt.ru</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
>Если открыть в &kappname; файл исходного кода на языке C++, &Java; или документ &HTML;, для синтаксической разметки будут использоваться одни и те же цвета (несмотря на то, что разные форматы файлов обуславливают выбор разных слов для обозначения элементов текста). Это происходит, потому что в &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;. По умолчанию в неё включены средства подсветки кода &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!OtherContext</userinput
>, чтобы система поднялась на два контекста выше и переключилась на контекст с названием <userinput
>OtherContext</userinput
>. Также возможно переключиться на контекст, который принадлежит другому определению языка, так же, как в правилах <userinput
>IncludeRules</userinput
> (например, <userinput
>SomeContext##JavaScript</userinput
>). Обратите внимание, что это переключение контекста невозможно использовать совместно с <userinput
>#pop</userinput
>: например, <userinput
>#pop!SomeContext##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
> и <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
> определяет место вставки однострочного комментария. По умолчанию однострочный комментарий будет вставлен в начале строки в нулевой позиции. Но если использовать запись <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
><RuleName 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
>SomeContext##JavaScript</userinput
>). Обратите внимание, что это переключение контекста невозможно использовать совместно с <userinput
>#pop</userinput
> (например, запись <userinput
>#pop!SomeContext##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<string>\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; &plasma;</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
> в корневом объекте. Например, если выполняется адаптация существующей схемы, можно добавить URL-адрес исходного репозитория. Наиболее практичным способом комментирования является использование массива строк. </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
>Другие ключи цвета редактора...</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
>Цвет номера текущей строки, отображается у левой границы окна редактирования. Если выбрать цвет, немного отличный от цвета номеров строк, то это поможет визуально выделять текущую строку и не будет отвлекать от другого текста. </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
> (<guilabel
>Обычный текст</guilabel
>): типовой стиль текста для обычного текста и исходного кода без специальной подсветки.</para>
<para
><userinput
>Keyword</userinput
> (<guilabel
>Ключевое слово</guilabel
>): стиль текста для встроенных ключевых слов языка.</para>
<para
><userinput
>Function</userinput
> (<guilabel
>Функция</guilabel
>): стиль текста для определений функций и вызовов функций.</para>
<para
><userinput
>Variable</userinput
> (<guilabel
>Переменая</guilabel
>): стиль текста для переменных, если таковой применим. Например, переменные в 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
> (<guilabel
>Операция</guilabel
>): стиль текста для операторов, таких как <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
> (<guilabel
>Строка</guilabel
>): стиль текста для строк наподобие <quote
><userinput
>hello world</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
> (<guilabel
>Комментарий</guilabel
>): стиль текста для обычных комментариев.</para>
<para
><userinput
>Documentation</userinput
> (<guilabel
>Документация</guilabel
>): стиль текста для комментариев, которые отражают документацию API (например, <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
> (<guilabel
>Предупреждение</guilabel
>): стиль текста для предупреждений (например, ключевого слова <userinput
>@warning</userinput
> в Doxygen).</para>
<para
><userinput
>Alert</userinput
> (<guilabel
>Серьёзное предупреждение</guilabel
>): стиль текста для специальных слов в комментариях, таких как <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
> (<guilabel
>Ошибка</guilabel
>): стиль текста для обозначения подсветки ошибок и неверного синтаксиса.</para>
<para
><userinput
>Others</userinput
> (<guilabel
>Другое</guilabel
>): стиль текста для атрибутов, которые не соответствуют ни одному из других типовых стилей.</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
>Type Modifiers</quote
> и <quote
>Standard Classes</quote
>. В соответствующем файле &XML; <quote
>isocpp.xml</quote
> для определённого атрибута <quote
>Standard Classes</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; &plasma;</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
>Обратите внимание, многие подсветки содержат другие подсветки, представленные группами в списке стилей. Например, многие подсветки импортируют подсветку «Alert», а многие форматы исходного кода — подсветку «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
> and <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
> внедряется как &JSON; в начало документа и имеет следующую форму: <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
> в файлах определения подсветки синтаксических конструкций. Эта запись важна для средств расстановки отступов, которые работают на основе определённых данных о подсветке в документе. Если указан стиль синтаксиса, средством расстановки отступов будет возможно воспользоваться только в том случае, если будет задействовано соответствующее средство подсветки текста. Это позволяет предотвратить <quote
>неопределённое поведение</quote
>, вызванное использованием средства расстановки отступов без необходимой для его работы схемы подсветки. Например, таким образом настроено средство расстановки отступов в файлах <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
> Первым элементом такого массива является глубина отступа, похожая на значение, о котором говорилось ранее. Другой же элемент является абсолютным значением, которое соответствует столбцу <quote
>выравнивания</quote
>. Если это значение превышает значение отступа, то после создания отступа согласно первому параметру к этому отступу будет добавлена разница между ними (в пробелах). В ином случае второе число игнорируется. Одновременное использование символов табуляции и пробелов для расстановки отступов часто называют <quote
>смешанным режимом</quote
>. </para>
<para
>Рассмотрим следующий пример: предположим, что для создания отступов используются символы табуляции и значение ширины табуляции равняется 4. Здесь <tab> — символ табуляции, а '.' — пробел: <programlisting>
1: <tab><tab>foobar("привет",
2: <tab><tab>......."мир");
</programlisting
> При создании отступа для строки 2 функция <function
>indent()</function
> возвращает [8, 15]. В результате два символа табуляции будут вставлены для создания отступа в столбце 8, а затем будет добавлено 7 пробелов для выравнивания по второму параметру, следовательно, строка останется выровненной во время просмотра файла при любой ширине табуляции. </para>
<para
>По умолчанию в пакете &kappname; &kde; поставляются несколько средств расстановки отступов. Код этих средств на языке &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"
>встроенной командной строки</link
> &kappname;. </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 <name>(параметр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; будет показан заданный текст справки. Обязательно <link linkend="dev-scripting-api-i18n"
>выполните перевод строк</link
>. </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 ("myscriptnamehere.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; является текстовым редактором, весь программный интерфейс по возможности основан на курсорах и диапазонах текста. Объект «Cursor» (курсор) является простым кортежем <literal
>(line, column)</literal
> (строка, столбец), который определяет позицию в тексте документа. Объект «Range» (диапазон) — это фрагмент текста от начальной до конечной позиции курсора. Подробное описание программного интерфейса приводится в следующих разделах. </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(другой);</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(строка, столбец)</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
> возвращает диапазон в позиции (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
> возвращает диапазон (<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
> возвращает диапазон с позиции (<replaceable
>начальнаяСтрока</replaceable
>, <replaceable
>начальныйСтолбец</replaceable
>) до позиции (<replaceable
>конечнаяСтрока</replaceable
>, <replaceable
>конечныйСтолбец</replaceable
>). </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>Range(<parameter
>Range <replaceable
>другой</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Конструктор копирования. Возвращает копию диапазона <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
>Возвращает диапазон от (-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
>, если позиция курсора находится в этом диапазоне, в ином случае — <literal
>false</literal
>. </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
>[начальный.столбец, конечный.столбец)</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
>[начальная.строка, конечная.строка)</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
>[начальная.строка, конечная.строка]</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
>[начальный.столбец, конечный.столбец]</literal
>, в ином случае — <literal
>false</literal
>. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>bool Range.onSingleLine();
</synopsis
></term>
<listitem
><para
>Возвращает <literal
>true</literal
>, если диапазон начинается и заканчивается в одной и той же строке, то есть если <replaceable
>Range.начальная.строка == Range.конечная.строка</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(строка, столбец), Cursor(строка, столбец))</literal
></quote
>. </para
></listitem>
</varlistentry
></variablelist>
</sect4>
</sect3>
<sect3 id="dev-scripting-api-global">
<title
>Глобальные функции</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
> предусмотрена встроенная защита от повторного включения одного и того же <replaceable
>файла</replaceable
>. </para>
<para
>Начиная с &kde; 4.10 </para>
</listitem>
</varlistentry
></variablelist>
</sect4>
<sect4 id="dev-scripting-api-debug">
<title
>Отладка</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
>Перевод</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
>Программный интерфейс (API) View</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
>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>
</variablelist>
</para>
</sect3>
<sect3 id="dev-scripting-api-document">
<title
>Программный интерфейс (API) Document</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
>skipWhiteSpaces</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Возвращает <literal
>true</literal
>, если строка с указанным номером начинается с фрагмента текста <replaceable
>текст</replaceable
>, в ином случае — <literal
>false</literal
>. Параметр <replaceable
>skipWhiteSpaces</replaceable
> позволяет указать программе, следует ли игнорировать пробелы в начале строки. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>bool document.endsWith(<parameter
>int <replaceable
>строка</replaceable
></parameter
>, <parameter
>String <replaceable
>текст</replaceable
></parameter
>, <parameter
>bool <replaceable
>skipWhiteSpaces</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Возвращает <literal
>true</literal
>, если строка с указанным номером заканчивается фрагментом текста <replaceable
>текст</replaceable
>, в ином случае — <literal
>false</literal
>. Параметр <replaceable
>skipWhiteSpaces</replaceable
> позволяет указать программе, следует ли игнорировать пробелы в конце строки. </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>bool document.setText(<parameter
>String <replaceable
>текст</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Заменяет всё содержимое документа на указанный текст. </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
>down</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Поиск следующей изменённой строки, начиная со строки <replaceable
>начальнаяСтрока</replaceable
>. Поиск выполняется в направлении «вверх» (к началу документа) или «вниз» (к концу документа), в зависимости от значения параметра <replaceable
>down</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
>, если курсор находится в корректной позиции в тексте. Позиция в тексте является корректной, только если курсор находится в начале, в середине или в конце корректной строки текста. Кроме того, позиция в тексте является некорректной, если курсор находится в заменителе символа Юникода. </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
>Преобразует указанную <quote
>реальную</quote
> позицию курсора в виртуальную позицию курсора, возвращая либо целое значение (int), либо объект «Cursor». </para
></listitem>
</varlistentry>
<varlistentry>
<term
><synopsis
>int document.fromVirtualColumn(<parameter
>int <replaceable
>строка</replaceable
></parameter
>, <parameter
>int <replaceable
>виртуальныйСтолбец</replaceable
></parameter
>);
int document.fromVirtualColumn(<parameter
>Cursor <replaceable
>виртуальныйКурсор</replaceable
></parameter
>);
Cursor document.fromVirtualCursor(<parameter
>Cursor <replaceable
>виртуальныйКурсор</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Преобразует указанную виртуальную позицию курсора в <quote
>реальную</quote
> позицию курсора, возвращая либо целое значение (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>
</variablelist>
</para>
</sect3>
<sect3 id="dev-scripting-api-editor">
<title
>Программный интерфейс (API) редактора</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:47:23 CEST 2024.