http://docs.kde.org/
Пред.Расширение функциональных возможностей KatePartСлед.

Написание сценариев JavaScript

Функциональность компонента редактирования KatePart можно расширить с помощью написания сценариев. Для этого используется язык ECMAScript (широко известен как JavaScript). KatePart поддерживает два вида сценариев: сценарии расстановки отступов и сценарии командной строки. Функциональные возможности, похожие на сценарии командной строки, также доступны в подключаемом модуле фрагментов.

Сценарии расстановки отступов

Сценарии расстановки отступов — также их называют средствами расстановки отступов — выполняют автоматическую расстановку отступов в исходном коде по мере набора текста. Например, после нажатия клавиши Enter программа обычно увеличивает отступ в следующей строке.

В следующих разделах приведены пошаговые инструкции по созданию основы простого средства расстановки отступов. На первом этапе следует создать файл *.js с названием, например, javascript.js в локальной домашней папке $XDG_DATA_HOME/katepart5/script/indentation. Здесь переменная среды XDG_DATA_HOME обычно имеет значение ~/.local или ~/.local/share.

В Windows® эти файлы расположены в каталоге %USERPROFILE%\AppData\Local\katepart5\script\indentation. %USERPROFILE% обычно имеет значение C:\\Users\\пользователь.

Заголовок сценария расстановки отступов

Заголовок файла javascript.js внедряется как JSON в начало документа и имеет следующую форму: 

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

Далее приводится подробное описание каждой из записей заголовка:

  • name [обязательная запись]: название средства расстановки отступов, которое будет показано в меню Сервис → Расстановка отступов и диалоге настройки.

  • author [необязательная запись]: имя и контактные данные автора.

  • license [необязательная запись]: краткая форма условий лицензирования, например BSD или LGPLv3.

  • revision [обязательная запись]: версия сценария. Не забывайте увеличивать номер версии при каждом внесении изменений в файл.

  • kate-version [обязательная запись]: минимальное значение версии KatePart, необходимой для работы сценария.

  • required-syntax-style [необязательная запись]: нужный стиль синтаксиса, который соответствует указанному значению style в файлах определения подсветки синтаксических конструкций. Эта запись важна для средств расстановки отступов, которые работают на основе определённых данных о подсветке в документе. Если указан стиль синтаксиса, средство расстановки отступов доступно только тогда, когда задействовано соответствующее средство подсветки текста. Это позволяет предотвратить «неопределённое поведение», вызванное использованием средства расстановки отступов без необходимой для его работы схемы подсветки. Например, таким образом настроено средство расстановки отступов в файлах ruby.js и ruby.xml.

  • indent-languages [необязательная запись]: массив JSON стилей синтаксических конструкций, которые может обрабатывать средство расстановки отступов, например: ["c++", "java"].

  • priority [необязательная запись]: если какому-либо файлу с определённой подсветкой соответствуют несколько средств расстановки отступов, значение приоритета определяет, какое средство расстановки отступов будет использоваться по умолчанию.

Исходный код средства расстановки отступов

Выше был рассмотрен формат заголовка. Теперь можно перейти к изучению того, как же работает сам сценарий расстановки отступов. Основа подобного сценария выглядит так: 

// необходимые библиотеки JS katepart, например range.js, если используется Range
require ("range.js");

triggerCharacters = "{}/:;";
function indent(line, indentWidth, ch)
{
    // сценарий будет вызываться при обработке каждого символа новой строки (ch == '\n') и всех символов, указанных в
    // глобальной переменной triggerCharacters. При выборе пункта меню Сервис → Форматированный отступ
    // переменная ch будет иметь пустое значение, то есть ch == ''.
    //
    // смотрите также раздел: «Программный интерфейс (API) работы со сценариями»
    return -2;
}

В функции indent() предусмотрено три параметра:

  • line: строка, в которой следует установить отступ

  • indentWidth: ширина отступа (в пробелах)

  • ch: символ новой строки (ch == '\n'), символ переключения, указанный в triggerCharacters, или пустая строка, если пользователем был выбран пункт меню Сервис → Форматированный отступ.

Значение, возвращённое функцией indent(), определяет способ установки отступа в строке. Если возвращённое функцией значение является простым целым числом, оно обрабатывается следующим образом:

  • возвращено значение -2: ничего не делать

  • возвращено значение -1: сохранить отступ (он будет определён на основе предыдущей непустой строки)

  • возвращено значение 0: числа >= 0 определяют глубину отступа в пробелах

Либо может быть возвращён массив из двух элементов:

  • return [ indent, align ];

Первым элементом такого массива является глубина отступа, похожая на значение, о котором говорилось ранее. Другой же элемент является абсолютным значением, которое соответствует столбцу «выравнивания». Если это значение превышает значение отступа, то после создания отступа согласно первому параметру к этому отступу будет добавлена разница между ними (в пробелах). В ином случае второе число игнорируется. Одновременное использование символов табуляции и пробелов для расстановки отступов часто называют «смешанным режимом».

Рассмотрим следующий пример: предположим, что для создания отступов используются символы табуляции и значение ширины табуляции равняется 4. Здесь <tab> — символ табуляции, а '.' — пробел: 

1: <tab><tab>foobar("привет",
2: <tab><tab>……."мир");

При создании отступа для строки 2 функция indent() возвращает [8, 15]. В результате два символа табуляции будут вставлены для создания отступа в столбце 8, а затем будет добавлено 7 пробелов для выравнивания по второму параметру, следовательно, строка останется выровненной во время просмотра файла при любой ширине табуляции.

По умолчанию в пакете KatePart KDE поставляются несколько средств расстановки отступов. Код этих средств на языке JavaScript расположен в каталоге $XDG_DATA_DIRS/katepart5/script/indentation.

В Windows® эти файлы расположены в каталоге %USERPROFILE%\AppData\Local\katepart5\script\indentation. %USERPROFILE% обычно имеет значение C:\\Users\\пользователь.

При разработке средства расстановки отступов сценарии требуется перезагружать для проверки корректности поведения во время установки отступов. Вместо перезапуска приложения достаточно просто перейти в командную строку и выполнить команду reload-scripts.

Чтобы поделиться созданным полезным сценарием с разработчиками KatePart, отправьте запрос на слияние изменений в соответствующий проект на GitLab.

Сценарии командной строки

Примечание

Функциональные возможности, похожие на сценарии командной строки, также доступны в подключаемом модуле фрагментов. С этим модулем начать разработку будет проще (особенно в том случае, когда нужны небольшие пользовательские сценарии).

Поскольку у всех пользователей разные потребности, в KatePart предусмотрена поддержка небольших вспомогательных инструментов для ускорения работы с фрагментами текста с помощью встроенной командной строки. Например, команда sort (упорядочить) реализована именно с помощью такого инструмента. В этом разделе содержится описание способа создания файлов *.js, которые позволят расширить возможности KatePart путём добавления вспомогательных сценариев.

Сценарии командной строки расположены в той же папке, что и сценарии расстановки отступов. Поэтому на первом этапе следует создать файл *.js с именем myutils.js в локальной домашней папке $XDG_DATA_HOME/katepart5/script/commands. Здесь переменная среды XDG_DATA_HOME обычно имеет значение ~/.local или ~/.local/share.

В Windows® эти файлы расположены в каталоге %USERPROFILE%\AppData\Local\katepart5\script\commands. %USERPROFILE% обычно имеет значение C:\\Users\\пользователь.

Заголовок сценария командной строки

Заголовок каждого сценария командной строки встраивается в JSON в начале сценария следующим образом: 

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

Далее приводится подробное описание каждой из записей заголовка:

  • author [необязательная запись]: имя и контактные данные автора.

  • license [необязательная запись]: краткая форма условий лицензирования, например BSD или LGPLv2.

  • revision [обязательная запись]: версия сценария. Не забывайте увеличивать номер версии при каждом внесении изменений в файл.

  • kate-version [обязательная запись]: минимальное значение версии KatePart, необходимой для работы сценария.

  • functions [обязательная запись]: массив JSON команд сценария.

  • actions [необязательная запись]: массив JSON объектов JSON, определяющий действия, которые будут доступны в меню приложения. Подробные сведения доступны в разделе Привязки клавиш.

Так как значением functions является массив JSON, отдельный сценарий может содержать произвольное количество команд командной строки. Доступ к каждой из функций можно получить с помощью встроенной командной строки KatePart.

Исходный код сценария

Все функции, указанные в заголовке, должны быть реализованы в сценарии. Таким образом, файл сценария из вышеприведённого примера должен реализовывать две функции: sort и moveLinesDown. Все функции должны быть записаны в следующем виде: 

// необходимые библиотеки JS katepart, например range.js, если используется Range
require ("range.js");

function <name>(arg1, arg2, …)
{
    // … реализация, смотрите также раздел: «Программный интерфейс (API) работы со сценариями»
}

Параметры в командной строке передаются функции как arg1, arg2 и так далее. Чтобы документировать каждую команду, просто реализуйте функцию 'help' следующим образом: 

function help(cmd)
{
    if (cmd == "sort") {
        return i18n("Sort the selected text.");
    } else if (cmd == "…") {
        // …
    }
}

После этого выполнение команды help sort приведёт к вызову соответствующей функции справки (help) с параметром cmd в значении названия указанной команды, то есть cmd == "sort". В ответ на команду в KatePart будет показан заданный текст справки. Обязательно выполните перевод строк.

При разработке сценария командной строки этот сценарий требуется перезагружать для проверки корректности поведения. Вместо перезапуска приложения достаточно просто перейти в командную строку и выполнить команду reload-scripts.

Привязки клавиш

Чтобы сценарий был доступен из меню приложения и по комбинации клавиш, он должен содержать соответствующий заголовок. В приведённом выше примере обе функции — sort и moveLinesDown — показываются как соответствующие пункты меню благодаря этой части заголовка сценария: 

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"
        }
    ]
};

Поля для одного действия таковы:

  • function [обязательная запись]: функция, пункт которой должен показываться в меню Сервис → Сценарии.

  • name [обязательная запись]: текст пункта, который показан в меню сценариев.

  • icon [необязательная запись]: значок, который показывается рядом с текстом в меню. Можно указать название одного из значков KDE.

  • category [необязательная запись]: если указана категория, сценарий будет показываться в соответствующем вложенном меню.

  • shortcut [необязательная запись]: здесь указывается комбинация клавиш, которая будет использоваться по умолчанию. Например: Ctrl+Alt+t. Дополнительные сведения доступны в документации Qt™.

  • interactive [необязательная запись]: если для работы сценария требуются введённые пользователем данные, установите этот параметр в значение true.

Чтобы поделиться созданным полезным сценарием с разработчиками KatePart, отправьте запрос на слияние изменений в соответствующий проект на GitLab.

Программный интерфейс (API) работы со сценариями

Программный интерфейс работы со сценариями, основы которого представлены здесь, можно использовать для любых сценариев, в том числе сценариев расстановки отступов и сценариев командной строки. Классы Cursor и Range определяются библиотечными файлами в $XDG_DATA_DIRS/katepart5/libraries. Если требуется воспользоваться ими в определённом сценарии, чтобы задействовать какие-либо функции Document или View, включите в сценарий необходимую библиотеку с помощью следующей команды: 

// необходимые библиотеки JS katepart, например range.js, если используется Range
require ("range.js");

Чтобы расширить стандартный программный интерфейс (API) работы со сценариями собственными функциями и прототипами, просто создайте файл в локальной папке файлов настройки KDE $XDG_DATA_HOME/katepart5/libraries и включите его в файл сценария с помощью следующего кода: 

require ("myscriptnamehere.js");

В Windows® эти файлы расположены в каталоге %USERPROFILE%\AppData\Local\katepart5\libraries. %USERPROFILE% обычно имеет значение C:\\Users\\пользователь.

Рекомендованным способом расширения возможностей существующих прототипов, например Cursor или Range, не является внесение изменений в глобальные файлы *.js. Вместо этого следует изменить прототип Cursor в JavaScript после включения cursor.js в сценарий с помощью команды require.

Курсоры и диапазоны

Поскольку KatePart является текстовым редактором, весь программный интерфейс по возможности основан на курсорах и диапазонах текста. Объект «Cursor» (курсор) является простым кортежем (line, column) (строка, столбец), который определяет позицию в тексте документа. Объект «Range» (диапазон) — это фрагмент текста от начальной до конечной позиции курсора. Подробное описание программного интерфейса приводится в следующих разделах.

Прототип Cursor (курсор)
Cursor();

Конструктор. Возвращает объект «Cursor» (курсор) в позиции (0, 0).

Пример: var cursor = new Cursor(); 

Cursor(int line, int column);

Конструктор. Возвращает объект «Cursor» (курсор) в позиции (строка, столбец).

Пример: var cursor = new Cursor(3, 42); 

Cursor(Cursor other);

Конструктор копирования. Возвращает копию курсора other.

Пример: var copy = new Cursor(other); 

Cursor Cursor.clone();

Возвращает клон курсора.

Пример: var clone = cursor.clone(); 

Cursor.setPosition(int line, int column);

Устанавливает курсор в место, указанное параметрами line и column.

Начиная с KDE 4.11 

bool Cursor.isValid();

Проверка корректности курсора. Курсор является некорректным, если строка и/или столбец установлены в значение -1.

Пример: var valid = cursor.isValid(); 

Cursor Cursor.invalid();

Возвращает новый некорректный курсор, размещённый в позиции (-1, -1).

Пример: var invalidCursor = cursor.invalid(); 

int Cursor.compareTo(Cursor other);

Сравнивает текущий курсор с курсором other. Возвращает

  • -1, если текущий курсор расположен перед курсором other,

  • 0, если курсоры находятся в одинаковых позициях, и

  • +1, если текущий курсор расположен после курсора other.

bool Cursor.equals(Cursor other);

Возвращает true, если текущий курсор и курсор other находятся в одинаковых позициях, в ином случае — false. 

String Cursor.toString();

Возвращает курсор как строку вида «Cursor(line, column)».

Прототип Range (диапазон)
Range();

Конструктор. Вызов new Range() возвращает диапазон в позиции (0, 0) - (0, 0). 

Range(Cursor start, Cursor end);

Конструктор. Вызов new Range(start, end) возвращает диапазон (start, end). 

Range(int startLine, int startColumn, int endLine, int endColumn);

Конструктор. Вызов new Range(startLine, startColumn, endLine, endColumn) возвращает диапазон с позиции (startLine, startColumn) до позиции (endLine, endColumn). 

Range(Range other);

Конструктор копирования. Возвращает копию диапазона other. 

Range Range.clone();

Возвращает клон диапазона.

Пример: var clone = range.clone(); 

bool Range.isEmpty();

Возвращает true, если начальная и конечная позиции курсора совпадают.

Пример: var empty = range.isEmpty();

Начиная с KDE 4.11 

bool Range.isValid();

Возвращает true, если начальная и конечная позиции курсора являются корректными, в ином случае — false.

Пример: var valid = range.isValid(); 

Range Range.invalid();

Возвращает диапазон от (-1, -1) до (-1, -1). 

bool Range.contains(Cursor cursor);

Возвращает true, если позиция курсора находится в этом диапазоне, в ином случае — false. 

bool Range.contains(Range other);

Возвращает true, если текущий диапазон содержит диапазон other, в ином случае — false. 

bool Range.containsColumn(int column);

Возвращает true, если column принадлежит полуоткрытому интервалу [start.column, end.column), в ином случае — false. 

bool Range.containsLine(int line);

Возвращает true, если line принадлежит полуоткрытому интервалу [start.line, end.line), в ином случае — false. 

bool Range.overlaps(Range other);

Возвращает true, если текущий диапазон и диапазон other имеют ненулевое пересечение, в ином случае — false. 

bool Range.overlapsLine(int line);

Возвращает true, если line принадлежит интервалу [start.line, end.line], в ином случае — false. 

bool Range.overlapsColumn(int column);

Возвращает true, если column принадлежит интервалу [start.column, end.column], в ином случае — false. 

bool Range.onSingleLine();

Возвращает true, если диапазон начинается и заканчивается в одной и той же строке, то есть если Range.start.line == Range.end.line.

Начиная с KDE 4.9 

bool Range.equals(Range other);

Возвращает true, если текущий диапазон и диапазон other совпадают, в ином случае — false. 

String Range.toString();

Возвращает диапазон как строку вида «Range(Cursor(line, column), Cursor(line, column))».

Глобальные функции

В этом разделе перечислены все глобальные функции.

Чтение и включение файлов
String read(String file);

Найти указанный file в каталоге katepart5/script/files и вернуть его содержимое в виде строки. 

void require(String file);

Найти указанный file в каталоге katepart5/script/libraries и обработать его код. В require предусмотрена встроенная защита от повторного включения одного и того же file.

Начиная с KDE 4.10

Отладка
void debug(String text);

Вывести text в stdout консоли, из которой запущено приложение.

Перевод

Полноценная локализация станет возможной только при использовании нескольких функций, предназначенных для перевода строк, а именно: i18n, i18nc, i18np и i18ncp. Поведение этих функций в точности соответствует поведению функций перевода строк KDE.

С помощью функций перевода и системы перевода KDE встроенные в сценарий строки сообщений можно перевести на язык интерфейса приложения. Строки в сценариях, которые являются частью официальной сборки KatePart, автоматически извлекаются и представляются для перевода командам переводчиков KDE. Другими словами, разработчикам основной ветви KatePart не приходится заниматься извлечением сообщений и их переводом. Впрочем, следует отметить, что перевод будет работать только в пределах инфраструктуры KDE, то есть перевод новых строк сценариев, разработанных за пределами KDE, невозможен. Поэтому созданные сценарии следует отправлять в основную ветвь разработки Kate, чтобы сделать возможным надлежащий перевод. 

void i18n(String text, arg1, …);

Перевести text на язык интерфейса приложения. Параметры arg1, … являются необязательными. Они позволяют заменить строки %1, %2 и так далее.

void i18nc(String context, String text, arg1, …);

Перевести text на язык интерфейса приложения. При этом переводчикам будет показана строка context, что облегчает перевод. Параметры arg1, … являются необязательными. Они позволяют заменить строки %1, %2 и так далее.

void i18np(String singular, String plural, int number, arg1, …);

Перевести singular или plural число сообщения на язык интерфейса приложения, в зависимости от указанного значения параметра number. Параметры arg1, … являются необязательными. Они позволяют заменить строки %1, %2 и так далее.

void i18ncp(String context, String singular, String plural, int number, arg1, …);

Перевести singular или plural число сообщения на язык интерфейса приложения, в зависимости от указанного значения параметра number. При этом переводчикам будет показана строка context, что облегчает перевод. Параметры arg1, … являются необязательными. Они позволяют заменить строки %1, %2 и так далее.

Программный интерфейс (API) View

Каким бы образом ни был запущен сценарий, он всегда будет использовать глобальную переменную «view», которая соответствует текущей активной области просмотра. Далее приводится список всех доступных функций объекта «View». 

void view.copy()

Копировать выделенный фрагмент, если таковой имеется. Когда ничего не выделено, копировать текущую строку, если включён параметр [ ] Вырезать или копировать текущую строку, если ничего не выделено.

Начиная с KDE Frameworks™ 5.79

void view.cut()

Вырезать выделенный фрагмент, если таковой имеется. Когда ничего не выделено, вырезать текущую строку, если включён параметр [ ] Вырезать или копировать текущую строку, если ничего не выделено.

Начиная с KDE Frameworks™ 5.79

void view.paste()

Вставить содержимое буфера обмена.

Начиная с KDE Frameworks™ 5.79

Cursor view.cursorPosition()

Возвращает текущую позицию курсора в области просмотра.

void view.setCursorPosition(int line, int column);
void view.setCursorPosition(Cursor cursor);

Устанавливает для текущего курсора позицию (строка, столбец) или позицию указанного курсора. 

Cursor view.virtualCursorPosition();

Возвращает позицию виртуального курсора. Все символы табуляции будут учтены с помощью соответствующего количества пробелов, которое будет зависеть от текущей ширины табуляции. 

void view.setVirtualCursorPosition(int line, int column);
void view.setVirtualCursorPosition(Cursor cursor);

Устанавливает для текущего виртуального курсора позицию (строка, столбец) или позицию указанного курсора. 

String view.selectedText();

Возвращает выделенный фрагмент текста. Если выделенного фрагмента текста нет, возвращается пустая строка. 

bool view.hasSelection();

Возвращает true, если в области просмотра есть выделенный текст, в ином случае — false. 

Range view.selection();

Возвращает диапазон выделенного фрагмента текста. Если выделенного фрагмента текста нет, возвращается некорректный диапазон. 

void view.setSelection(Range range);

Устанавливает выделение текста по указанному диапазону. 

void view.removeSelectedText();

Удаляет выделенный текст. Если в области просмотра отсутствует выделенный текст, никаких действий не выполняется. 

void view.selectAll();

Выделяет весь текст в документе. 

void view.clearSelection();

Снимает выделение с текста, не удаляя сам текст. 

void view.setBlockSelection(bool on);

Включает или отключает режим выделения блока. 

bool view.blockSelection();

Возвращает true, если режим выделения блока включён, в ином случае — false. 

void view.align(Range range);

Надлежащим образом повторно расставляет отступы строк в пределах указанного диапазона range согласно текущим параметрам расстановки отступов. 

void view.alignOn(Range range, String pattern = "");

Выравнивает строки в диапазоне range по позиции, указанной с помощью регулярного выражения pattern. При пустом значении pattern выравнивание по умолчанию выполняется по первому непустому символу. Если в шаблоне есть блок захвата, для захваченного совпадения будет добавлен отступ.

Примеры:

view.alignOn(document.documentRange(), '-'); вставит пробелы перед первым - в каждой строке, чтобы выровнять все дефисы по одной позиции.

view.alignOn(document.documentRange(), ':\\s+(.)'); вставит пробелы перед первым непустым символом, стоящим после двоеточия, чтобы выровнять все такие символы по одной позиции.

object view.executeCommand(String command,
                           String args,
                           Range range);

Выполняет команду командной строки command с необязательными аргументами args и необязательным диапазоном range. Возвращённый объект object имеет логическое свойство object.ok, которое указывает на то, было ли успешным выполнение команды command. В случае ошибки строка object.status будет содержать сообщение об ошибке.

Начиная с KDE Frameworks™ 5.50

Range view.searchText(Range range,
                      String pattern,
                      bool backwards = false);

Выполняет поиск первого вхождения pattern в range и возвращает найденный диапазон. Поиск выполняется в обратном направлении, если необязательный логический параметр backwards установлен в значение true.

Возвращённый диапазон будет некорректным (смотрите Range.isValid()), если шаблон pattern не найден в диапазоне range.

Начиная с KDE Frameworks™ 5.97

Программный интерфейс (API) Document

Каким бы образом ни был запущен сценарий, он всегда будет использовать глобальную переменную «document», которая соответствует текущему активному документу. Далее приводится список всех доступных функций объекта «Document». 

String document.fileName();

Возвращает название файла документа или пустую строку для несохранённых буферов с текстом. 

String document.url();

Возвращает полный URL-адрес документа или пустую строку для несохранённых буферов с текстом. 

String document.mimeType();

Возвращает тип MIME документа или тип MIME application/octet-stream, если не удалось найти соответствующий тип MIME. 

String document.encoding();

Возвращает текущую кодировку, которая будет использована для сохранения файла. 

String document.highlightingMode();

Возвращает глобальный режим подсветки, используемый во всём документе. 

String document.highlightingModeAt(Cursor pos);

Возвращает режим подсветки, используемый в указанной позиции в документе. 

Array document.embeddedHighlightingModes();

Возвращает массив режимов подсветки, встроенных в текущий документ. 

bool document.isModified();

Возвращает true, если в документе имеются несохранённые изменения, в ином случае — false. 

String document.text();

Возвращает всё содержимое документа в виде единой текстовой строки. Разрывы строк обозначаются символом перехода на новую строку «\n». 

String document.text(int fromLine, int fromColumn, int toLine, int toColumn);
String document.text(Cursor from, Cursor to);
String document.text(Range range);

Возвращает текст в указанном диапазоне. Чтобы код было легче читать, рекомендуется использовать основанную на объектах Cursor и Range версию функции. 

String document.line(int line);

Возвращает строку по её номеру в тексте. Если указанный номер находится вне диапазона номеров строк документа, возвращается пустая строка. 

String document.wordAt(int line, int column);
String document.wordAt(Cursor cursor);

Возвращает слово в указанной позиции курсора. 

Range document.wordRangeAt(int line, int column);
Range document.wordRangeAt(Cursor cursor);

Возвращает диапазон слова в указанной позиции курсора. Возвращённое значение диапазона будет некорректным (смотрите Range.isValid()), если текст находится за концом строки. Если в указанной позиции курсора отсутствует слово, возвращается пустой диапазон.

Начиная с KDE 4.9 

String document.charAt(int line, int column);
String document.charAt(Cursor cursor);

Возвращает символ в указанной позиции курсора. 

String document.firstChar(int line);

Возвращает первый отличный от пробела символ в указанной line. Первым символом строки считается символ в столбце 0. Если строка является пустой или состоит только из пробелов, функция возвращает пустую строку. 

String document.lastChar(int line);

Возвращает последний отличный от пробела символ в указанной line. Если строка является пустой или состоит только из пробелов, функция возвращает пустую строку. 

bool document.isSpace(int line, int column);
bool document.isSpace(Cursor cursor);

Возвращает true, если символ в указанной позиции курсора является пробелом, в ином случае — false. 

bool document.matchesAt(int line, int column, String text);
bool document.matchesAt(Cursor cursor, String text);

Возвращает true, если указанный text расположен в соответствующей позиции курсора, в ином случае — false. 

bool document.startsWith(int line, String text, bool skipWhiteSpaces);

Возвращает true, если строка с указанным номером начинается с фрагмента текста text, в ином случае — false. Параметр skipWhiteSpaces позволяет указать программе, следует ли игнорировать пробелы в начале строки. 

bool document.endsWith(int line, String text, bool skipWhiteSpaces);

Возвращает true, если строка с указанным номером заканчивается фрагментом текста text, в ином случае — false. Параметр skipWhiteSpaces позволяет указать программе, следует ли игнорировать пробелы в конце строки. 

bool document.setText(String text);

Заменяет всё содержимое документа на указанный текст. 

bool document.clear();

Удаляет весь текст в документе. 

bool document.truncate(int line, int column);
bool document.truncate(Cursor cursor);

Обрезает строку с указанным номером на указанном столбце или в указанной позиции курсора. Возвращает true в случае успеха или false, если строка с указанным номером находится вне диапазона номеров строк документа. 

bool document.insertText(int line, int column, String text);
bool document.insertText(Cursor cursor, String text);

Вставляет указанный text в указанной позиции курсора. Возвращает true в случае успеха или false, если документ доступен только для чтения. 

bool document.removeText(int fromLine, int fromColumn, int toLine, int toColumn);
bool document.removeText(Cursor from, Cursor to);
bool document.removeText(Range range);

Удаляет текст в указанном диапазоне. Возвращает true в случае успеха или false, если документ доступен только для чтения. 

bool document.insertLine(int line, String text);

Вставляет текст в указанной строке. Возвращает true в случае успеха или false, если документ доступен только для чтения или указанная строка находится вне диапазона номеров строк документа. 

bool document.removeLine(int line);

Удаляет строку с указанным номером. Возвращает true в случае успеха или false, если документ доступен только для чтения или указанная строка находится вне диапазона номеров строк документа. 

bool document.wrapLine(int line, int column);
bool document.wrapLine(Cursor cursor);

Переносит строку по указанной позиции курсора. Возвращает true в случае успеха или false (например, если номер строки < 0).

Начиная с KDE 4.9 

void document.joinLines(int startLine, int endLine);

Соединяет строки в диапазоне от startLine до endLine. Две последовательные текстовые строки всегда разделяются одиночным пробелом. 

int document.lines();

Возвращает число строк в документе. 

bool document.isLineModified(int line);

Возвращает true, если line в настоящее время содержит несохранённые данные.

Начиная с KDE 5.0 

bool document.isLineSaved(int line);

Возвращает true, если line была изменена и затем документ был сохранён. Следовательно, в настоящее время строка не содержит какие-либо несохранённые данные.

Начиная с KDE 5.0 

bool document.isLineTouched(int line);

Возвращает true, если line в настоящее время содержит несохранённые данные или была изменена ранее.

Начиная с KDE 5.0 

bool document.findTouchedLine(int startLine, bool down);

Поиск следующей изменённой строки, начиная со строки line. Поиск выполняется в направлении «вверх» (к началу документа) или «вниз» (к концу документа), в зависимости от значения параметра down.

Начиная с KDE 5.0 

int document.length();

Возвращает число символов в документе. 

int document.lineLength(int line);

Возвращает длину строки с номером line. 

void document.editBegin();

Начинает группу редактирования для упорядочения операций отмены или повтора действий. Не забывайте, что вызывать editEnd() следует именно столько раз, сколько вызывается editBegin(). Вызовы editBegin() используют встроенный счётчик, следовательно, их можно вкладывать один в другой. 

void document.editEnd();

Завершает группу редактирования. Последний вызов editEnd() (то есть соответствующий первому вызову editBegin()) завершает шаг по редактированию. 

int document.firstColumn(int line);

Возвращает первый отличный от пробела столбец в указанной с помощью параметра line строке. Если в строке будут только пробелы, функция вернёт значение -1. 

int document.lastColumn(int line);

Возвращает последний отличный от пробела столбец в указанной с помощью параметра line строке. Если в строке будут только пробелы, функция вернёт значение -1. 

int document.prevNonSpaceColumn(int line, int column);
int document.prevNonSpaceColumn(Cursor cursor);

Возвращает номер столбца с символом, отличным от пробела. Поиск будет выполнен в направлении начала документа, начиная с указанной позиции курсора. 

int document.nextNonSpaceColumn(int line, int column);
int document.nextNonSpaceColumn(Cursor cursor);

Возвращает номер столбца с символом, отличным от пробела. Поиск будет выполнен в направлении конца документа, начиная с указанной позиции курсора. 

int document.prevNonEmptyLine(int line);

Возвращает следующую непустую строку, содержащую отличные от пробелов символы. Поиск будет выполнен в направлении начала документа. 

int document.nextNonEmptyLine(int line);

Возвращает следующую непустую строку, содержащую отличные от пробелов символы. Поиск будет выполнен в направлении конца документа. 

bool document.isInWord(String character, int attribute);

Возвращает true, если указанный character с указанным параметром attribute может быть частью слова, в ином случае — false. 

bool document.canBreakAt(String character, int attribute);

Возвращает true, если указанный character с указанным параметром attribute может быть использован как место переноса строки, в ином случае — false. 

bool document.canComment(int startAttribute, int endAttribute);

Возвращает true, если диапазон, начало и конец которого определяются на основе указанных атрибутов, может быть закомментирован, в ином случае — false. 

String document.commentMarker(int attribute);

Возвращает метку комментария для однострочных комментариев для указанного параметра attribute. 

String document.commentStart(int attribute);

Возвращает метку комментария для начала многострочных комментариев для указанного параметра attribute. 

String document.commentEnd(int attribute);

Возвращает метку комментария для завершения многострочных комментариев для указанного параметра attribute. 

Range document.documentRange();

Возвращает диапазон, который включает весь документ. 

Cursor documentEnd();

Возвращает курсор, расположенный в последнем столбце последней строки в документе. 

bool isValidTextPosition(int line, int column);
bool isValidTextPosition(Cursor cursor);

Возвращает true, если курсор находится в корректной позиции в тексте. Позиция в тексте является корректной, только если курсор находится в начале, в середине или в конце корректной строки текста. Кроме того, позиция в тексте является некорректной, если курсор находится внутри суррогатной пары Юникода.

Начиная с KDE 5.0 

int document.attribute(int line, int column);
int document.attribute(Cursor cursor);

Возвращает атрибут в указанной позиции курсора. 

bool document.isAttribute(int line, int column, int attribute);
bool document.isAttribute(Cursor cursor, int attribute);

Возвращает true, если атрибут в указанной позиции курсора совпадает со значением параметра attribute, в ином случае — false. 

String document.attributeName(int line, int column);
String document.attributeName(Cursor cursor);

Возвращает название атрибута как удобочитаемый текст. Соответствует названию itemData в файлах подсветки синтаксиса. 

bool document.isAttributeName(int line, int column, String name);
bool document.isAttributeName(Cursor cursor, String name);

Возвращает true, если название атрибута в определённой позиции курсора соответствует указанному значению параметра name, в ином случае — false. 

String document.variable(String key);

Возвращает значение запрашиваемой переменной документа key. Если переменной документа с указанным названием не существует, возвращается пустая строка. 

void document.setVariable(String key, String value);

Устанавливает значение соответствующей переменной документа key.

Смотрите также переменные документа Kate

Начиная с KDE 4.8 

int document.firstVirtualColumn(int line);

Возвращает виртуальный столбец первого отличного от пробела символа в указанной строке или -1, если строка является пустой или содержит только пробелы. 

int document.lastVirtualColumn(int line);

Возвращает виртуальный столбец последнего отличного от пробела символа в указанной строке или -1, если строка является пустой или содержит только пробелы. 

int document.toVirtualColumn(int line, int column);
int document.toVirtualColumn(Cursor cursor);
Cursor document.toVirtualCursor(Cursor cursor);

Преобразует указанную «реальную» позицию курсора в виртуальную позицию курсора, возвращая либо целое значение (int), либо объект «Cursor». 

int document.fromVirtualColumn(int line, int virtualColumn);
int document.fromVirtualColumn(Cursor virtualCursor);
Cursor document.fromVirtualCursor(Cursor virtualCursor);

Преобразует указанную виртуальную позицию курсора в «реальную» позицию курсора, возвращая либо целое значение (int), либо объект «Cursor». 

Cursor document.anchor(int line, int column, Char character);
Cursor document.anchor(Cursor cursor, Char character);

Выполняет поиск указанного символа в направлении начала документа, начиная в указанной позиции курсора. Например, если функции будет передан символ «(», она вернёт позицию открывающей скобки «(». Выполняется подсчёт ссылок, то есть другие «(…)» будут проигнорированы. 

Cursor document.rfind(int line, int column, String text, int attribute = -1);
Cursor document.rfind(Cursor cursor, String text, int attribute = -1);

Выполняет поиск указанного текста с соответствующим значением параметра attribute в направлении начала текста. Параметр attribute игнорируется, если он установлен в значение -1. Возвращает некорректный курсор, если текст не удалось найти. 

int document.defStyleNum(int line, int column);
int document.defStyleNum(Cursor cursor);

Возвращает стиль по умолчанию, используемый в указанной позиции курсора. 

bool document.isCode(int line, int column);
bool document.isCode(Cursor cursor);

Возвращает true, если атрибут в указанной позиции курсора не совпадает ни с одним из следующих значений стилей: dsComment, dsString, dsRegionMarker, dsChar, dsOthers. 

bool document.isComment(int line, int column);
bool document.isComment(Cursor cursor);

Возвращает true, если значением атрибута символа в позиции курсора является dsComment, в ином случае — false. 

bool document.isString(int line, int column);
bool document.isString(Cursor cursor);

Возвращает true, если значением атрибута символа в позиции курсора является dsString, в ином случае — false. 

bool document.isRegionMarker(int line, int column);
bool document.isRegionMarker(Cursor cursor);

Возвращает true, если значением атрибута символа в позиции курсора является dsRegionMarker, в ином случае — false. 

bool document.isChar(int line, int column);
bool document.isChar(Cursor cursor);

Возвращает true, если значением атрибута символа в позиции курсора является dsChar, в ином случае — false. 

bool document.isOthers(int line, int column);
bool document.isOthers(Cursor cursor);

Возвращает true, если значением атрибута символа в позиции курсора является dsOthers, в ином случае — false. 

void document.indent(Range range, int change);

Устанавливает отступы для всех строк в диапазоне range на change табуляций или change раз на tabSize пробелов (в зависимости от выбранных пользователем параметров). Значение параметра change может быть отрицательным.

Программный интерфейс (API) редактора

Кроме программного интерфейса документа и области просмотра, существует и общий программный интерфейс редактора, который предоставляет доступ к общим функциям управления редактором с помощью сценариев. 

String editor.clipboardText();

Возвращает текст, который в настоящее время находится в глобальном буфере обмена.

Начиная с KDE Frameworks™ 5.50

String editor.clipboardHistory();

Редактор сохраняет журнал буфера обмена, который содержит до 10 записей. Эта функция возвращает все записи, которые в настоящее время находятся в журнале буфера обмена.

Начиная с KDE Frameworks™ 5.50

void editor.setClipboardText(String text);

Устанавливает для содержимого буфера обмена значение text. Запись text будет добавлена в журнал буфера обмена.

Начиная с KDE Frameworks™ 5.50