
Можливості компонента редактора KatePart можна дуже просто розширити за допомогою написання скриптів. Для написання скриптів слід використовувати мову ECMAScript (широко відому як JavaScript). У KatePart передбачено підтримку двох типів скриптів: скрипти встановлення відступів та скрипти командного рядка.
Скрипти встановлення відступів, які також будемо називати інструментами відступів, автоматично встановлюють відступи у тексті під час його введення. Наприклад, після натискання клавіші Enter програма зазвичай збільшує відступ у наступному рядку.
У наступних розділах наведено покрокові настанови щодо створення основи простого інструменту відступів. На першому кроці вам слід створити файл *.js
з назвою, наприклад, javascript.js
у локальній домашній теці $
. Тут змінна середовища XDG_DATA_HOME
/katepart5/script/indentationXDG_DATA_HOME
типово має значення ~/.local
або ~/.local/share
.
У Windows® ці файли зберігаються у %USERPROFILE%\AppData\Local\katepart5\script\indentation
. %USERPROFILE%
зазвичай є скороченням для C:\\Users\\
.користувач
Заголовок файла javascript.js
подається у межах закоментованого блоку і має таку форму
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 у файлах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 визначають глибину відступу у пробілах
Крім того, може бути повернуто масив з двох елементів:
повернуто [ відступ, вирівнювання ];
Першим елементом такого масиву є глибина відступу, подібна на значення, про яке ми говорили раніше. Інший же елемент є абсолютним значенням, що відповідає стовпчику «вирівнювання». Якщо це значення буде більшим за значення відступу, до відступу після додавання відступу, визначеного першим параметром, буде додано різницю між цими значенням. Якщо ж значення другого параметра буде меншим за відступ, його буде проігноровано. Одночасне використання для встановлення відступів пробілів і символів табуляції часто називають «мішаним режимом».
Розглянемо такий приклад: для встановлення відступів використовується символ табуляції, а ширину відступу визначено як 4 пробіли. У нашому прикладі, <таб> — це символ табуляції, а «.» — пробіл:
1: <таб><таб>foobar("привіт", 2: <таб><таб>......."світе");
Під час встановлення відступу для рядка 2 функція indent()
повертає значення [8, 15]. У результаті буде додано два символи табуляції для встановлення відступу до стовпчика 8, а потім буде додано 7 пробілів для вирівнювання за другим параметром, більшим за перший, отже рядок залишатиметься вирівняним під час перегляду файла за будь-якої встановленої ширити відступу табуляції.
У типовому пакунку KDE для KatePart передбачено декілька інструментів відступів. Код цих інструментів мовою JavaScript зберігається у каталозі $
.XDG_DATA_DIRS
/katepart5/script/indentation
У Windows® ці файли зберігаються у %USERPROFILE%\AppData\Local\katepart5\script\indentation
. %USERPROFILE%
зазвичай є скороченням для C:\\Users\\
. користувач
Під час розробки скрипту встановлення відступів корисним буває перезавантаження скриптів для перевірки коректності поведінки під час встановлення відступів. Замість перезапуску програми достатньо просто перейти до командного рядка і виконати команду reload-scripts.
Якщо вами було створено якийсь корисний скрипт, ви зробити його вашим власним внеском до проєкту розробки KatePart. Будь ласка, повідомте про вашу розробку у списку листування програми.
Оскільки всі користувачі мають різні потреби, у KatePart передбачено підтримку невеличких допоміжних інструментів для пришвидшення роботи з фрагментами тексту за допомогою вбудованого командного рядка. Наприклад, команду sort (впорядкувати) реалізовано саме за допомогою такого інструменту або скрипту. У цьому розділі ви знайдете пояснення щодо способу створення файлів *.js
, які допоможуть вам розширити можливості KatePart додаванням допоміжних скриптів.
Скрипти командного рядка зберігаються у одній теці зі скриптами встановлення відступів. Отже на першому кроці вам слід створити файл *.js
з назвою myutils.js
у локальній домашній теці $
. Тут змінна середовища XDG_DATA_HOME
/katepart5/script/commandsXDG_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 <назва>(параметр1, параметр2, ...) { // ...реалізація, див. також: Інтерфейс (API) роботи зі скриптами }
Параметри у командному рядку передаються функції як параметр1
, параметр2
тощо. Щоб надати користувачам можливість ознайомлюватися з документацією щодо команди, просто реалізуйте функцію '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. Будь ласка, повідомте про вашу розробку у списку листування програми.
Програмним інтерфейсом роботи зі скриптами, основи якого викладено тут, можна користуватися у будь-яких скриптах, зокрема скриптах роботи з відступами та командному рядку програми. Класи Cursor
і Range
визначаються бібліотечними файлами у $
. Якщо вам потрібно ними скористатися у певному скрипті для використання якихось із функцій XDG_DATA_DIRS
/katepart5/librariesDocument
або View
, будь ласка, включіть до скрипту потрібну вам бібліотеку такою командою:
// вимагаємо бібліотек JS katepart, наприклад range.js, якщо використовується Range require ("range.js");
Щоб розширити стандартний програмний інтерфейс (API) для роботи зі скриптами власними функціями і прототипами просто створіть файл у локальній теці файлів налаштування KDE, $
, і включіть його до вашого скрипту за допомогою такого коду: XDG_DATA_HOME
/katepart5/libraries
require ("vashscript.js");
У Windows® ці файли зберігаються у %USERPROFILE%\AppData\Local\katepart5\libraries
. %USERPROFILE%
зазвичай є скороченням для C:\\Users\\
.користувач
Рекомендованим способом розширення можливостей прототипів, зокрема Cursor
або Range
, не є внесення змін до загальних файлів *.js
. Для цього вам краще внести зміи до прототипу Cursor
у JavaScript після команди включення cursor.js
до вашого скрипту за допомогою require
.
Оскільки KatePart є текстовим редактором, весь програмний інтерфейс (API) за можливості засновано на курсорах та діапазонах тексту. Об’єкт Cursor (курсор) є простим кортежем (line, column)
(рядок, стовпчик), що визначає позицію у тексті документа. Об’єкт Range (діапазон) це фрагмент тексту від початкової позиції курсора до кінцевої позиції курсора. Докладніше про програмний інтерфейс (API) ми поговоримо у наступних розділах.
Cursor();
Конструктор. Повертає об’єкт Cursor (курсор) у позиції
(0, 0)
.Приклад:
var cursor = new Cursor();
Cursor(
int
,рядок
int
);стовпчик
Конструктор. Повертає об’єкт Cursor (курсор) у позиції (рядок, стовпчик).
Приклад:
var cursor = new Cursor(3, 42);
Cursor(
Cursor
);інший
Конструктор копіювання. Повертає копію курсора
інший
.Приклад:
var copy = new Cursor(other);
Cursor Cursor.clone();
Повертає клон курсора.
Приклад:
var clone = cursor.clone();
Cursor.setPosition(
int
,рядок
int
);позиція
Встановлює курсор у місце вказане параметрами
рядок
іпозиція
.Актуальна версія: KDE 4.11
bool Cursor.isValid();
Перевіряє, чи є курсор коректним. Курсор вважається некоректним, якщо значення його позицій у рядку і/або стовпчику дорівнюють
-1
.Приклад:
var valid = cursor.isValid();
Cursor Cursor.invalid();
Повертає новий некоректний курсор, розташований у позиції
(-1, -1)
.Приклад:
var invalidCursor = cursor.invalid();
int Cursor.compareTo(
Cursor
);інший
Порівнює поточний курсор з курсором
інший
. Повертає-1
, якщо поточний курсор розташовано перед курсоромінший
,0
, якщо курсори у однакових позиціях і+1
, якщо поточний курсор розташовано після курсораінший
.
bool Cursor.equals(
Cursor
);інший
Повертає
true
, якщо цей курсор і курсорінший
є однаковими. Якщо це не так, повертаєfalse
.String Cursor.toString();
Повертає об’єкт курсора як рядок у формі «
Cursor(line, column)
».
Range();
Конструктор. Виклик
new Range()
повертає Range (діапазон) у (0, 0) - (0, 0).Range(
Cursor
,початок
Cursor
);кінець
Конструктор. Виклик функції
new Range(
повертає Range (діапазон)(початок
,кінець
)початок
,кінець
).Range(
int
,початковийРядок
int
,початковийСтовпчик
int
,кінцевийРядок
int
);кінцевийСтовпчик
Конструктор. Виклик функції
new Range(
повертає Range (діапазон) від позиції (початковийРядок
,початковийСтовпчик
,кінцевийРядок
,кінцевийСтовпчик
)початковийРядок
,початковийСтовпчик
) до позиції (кінцевийРядок
,кінцевийСтовпчик
).Range(
Range
);інший
Конструктор копіювання. Повертає копію Range
інший
.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();
Повертає Range (діапазон) від (-1, -1) до (-1, -1).
bool Range.contains(
Cursor
);курсор
Повертає
true
, якщо позиція курсора міститься у діапазоні, у іншому випадку повертаєfalse
.bool Range.contains(
Range
);інший
Повертає
true
, якщо поточний діапазон містить діапазонінший
. Якщо це не так, повертаєfalse
.bool Range.containsColumn(
int
);стовпчик
Повертає
true
, якщостовпчик
належить напіввідкритому інтервалу[start.column, end.column)
. Якщо це не так, повертаєfalse
.bool Range.containsLine(
int
);рядок
Повертає
true
, якщорядок
належить до напіввідкритого інтервалу[start.line, end.line)
. Якщо це не так, повертаєfalse
.bool Range.overlaps(
Range
);інший
Повертає
true
, якщо поточний діапазон і діапазонінший
мають ненульовий перетин. Якщо це не так, повертаєfalse
.bool Range.overlapsLine(
int
);рядок
Повертає
true
, якщорядок
належить до інтервалу[start.line, end.line]
. Якщо це не так, повертаєfalse
.bool Range.overlapsColumn(
int
);стовпчик
Повертає
true
, якщостовпчик
належить інтервалу[start.column, end.column]
. Якщо це не так, повертаєfalse
.bool Range.onSingleLine();
Повертає
true
, якщо діапазон починається і завершується на тому самому рядку, тобто якщоRange.start.line == Range.end.line
.Актуальна версія: KDE 4.9
bool Range.equals(
Range
);інший
Повертає
true
, якщо поточний діапазон і діапазонінший
тотожні. Якщо це не так, повертаєfalse
.String Range.toString();
Повертає діапазон у форматі «
Range(Cursor(line, column), Cursor(line, column))
».
У цьому розділі наведено всі загальні функції.
String read(
String
);назва файла
Виконає пошук файла з назвою
назва файла
у каталозіkatepart5/script/files
і поверне його вміст як рядок.
void require(
String
);назва файла
Виконає пошук файла з назвою
назва файла
у каталозіkatepart5/script/libraries
і обробить його код. Уrequire
передбачено вбудований захист від повторного включення одного і того самого файла.Актуальна версія: KDE 4.10
void debug(
String
);текст
Виводить
текст
доstdout
у консоль, з якої запущено програму.
Повноцінна локалізація стане можливою лише за використання декількох функцій, призначених для перекладу рядків у скриптах, а саме i18n
, i18nc
, i18np
і i18ncp
. Робота цих функцій подібна до роботи функцій перекладу рядків у KDE.
За допомогою функцій перекладу і системи перекладу KDE вбудовані у скрипт рядки повідомлень може бути перекладено мовою інтерфейсу програми. Рядки у скриптах, які є частиною офіційної збірки KatePart буде автоматично видобуто і подано для перекладу командами перекладачів KDE. Іншими словами, якщо ви є розробником основної гілки KatePart, ви не маєте перейматися видобуванням повідомлень і їхнім перекладом. Втім, слід зауважити, що переклад працюватиме лише у межах інфраструктури KDE, тобто переклад нових рядків скриптів, розроблених поза межами KDE, неможливий. Тому вам варто надіслати вашу роботу до основної гілки розробки Kate, щоб уможливити належний переклад.
void i18n(
String
,текст
параметр1
, ...);Перекладає
текст
мовою, використаною у інтерфейсі програми. Параметрипараметр1
, ... є необов’язковими. Вони є замінниками рядків%1
,%2
тощо.void i18nc(
String
,контекст
String
,текст
параметр1
, ...);Перекладає
текст
мовою, використаною у інтерфейсі програми. Крім того, перекладачі зможуть побачити рядокконтекст
. За допомогою контексту перекладачам буде простіше правильно перекласти рядок. Параметрипараметр1
, ... є необов’язковими. Вони є замінниками рядків%1
,%2
тощо.void i18np(
String
,однина
String
,множина
int
,кількість
параметр1
, ...);Перекладає
однину
абомножину
повідомлення мовою, використаною у інтерфейсі програми залежно від вказаного значеннякількість
. Параметрипараметр1
, ... є необов’язковими. Вони є замінниками рядків%1
,%2
тощо.void i18ncp(
String
,контекст
String
,однина
String
,множина
int
,кількість
параметр1
, ...);Перекладає
однину
абомножину
повідомлення мовою, використаною у інтерфейсі програми залежно від вказаного значеннякількість
. Крім того, перекладачі зможуть побачити рядокконтекст
. За допомогою контексту перекладачам буде простіше правильно перекласти рядок. Параметрипараметр1
, ... є необов’язковими. Вони є замінниками рядків%1
,%2
тощо.
Яким би чином не було запущено скрипт, він завжди користуватиметься загальною змінною «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
,рядок
int
); void view.setCursorPosition(стовпчик
Cursor
);курсор
Встановлює для поточного курсора позицію, вказану напряму (рядок, стовпчик), або позицію вказаного курсора.
Cursor view.virtualCursorPosition();
Повертає позицію віртуального курсора. Всі символи табуляцій буде враховано за допомогою відповідної кількості пробілів, яка залежатиме від поточної ширини табуляції.
void view.setVirtualCursorPosition(
int
,рядок
int
); void view.setVirtualCursorPosition(стовпчик
Cursor
);курсор
Встановлює для віртуального курсора позицію, вказану напряму (рядок, стовпчик), або позицію вказаного курсора.
String view.selectedText();
Повертає позначений фрагмент тексту. Якщо жодного фрагменту не позначено, повертає порожній рядок.
bool view.hasSelection();
Повертає
true
, якщо у області перегляду позначено фрагмент тексту, інакше повертаєfalse
.Range view.selection();
Повертає діапазон позначеного фрагменту тексту. Якщо жодного фрагменту не позначено, буде повернуто некоректний діапазон.
void view.setSelection(
Range
);діапазон
Встановлює позначення тексту за вказаним діапазоном.
void view.removeSelectedText();
Вилучає позначений текст. Якщо у області перегляду не було позначено жодного тексту, ніяких дій виконано не буде.
void view.selectAll();
Позначає весь текст у документі.
void view.clearSelection();
Знімає позначення фрагменту тексту, не вилучаючи сам текст.
object view.executeCommand(
String
,команда
String
,аргументи
Range
);діапазон
Виконує команду
команда
із додатковими аргументамиаргументи
і необов'язковим діапазономдіапазон
. Повернутий об'єктobject
є булевою властивістюobject.ok
, яка вказує на те, чи було успішним виконання командикоманда
. Якщо сталася помилка, у рядкуobject.status
міститиметься повідомлення про помилку.Актуальна версія: KDE Frameworks™ 5.50
Яким би чином не було запущено скрипт, він завжди користуватиметься загальною змінною «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
);позиція
Повертає режим підсвічування, використаний за вказаною позицією у тексті.
Array document.embeddedHighlightingModes();
Повертає масив режимів підсвічування, вбудованих до поточного документа.
bool document.isModified();
Повертає
true
, якщо у документі є незбережені зміни, інакше повертаєfalse
.String document.text();
Повертає увесь вміст документа у формі єдиного рядка тексту. Розриви рядків буде позначено символом розриву рядка «
\n
».String document.text(
int
,зРядка
int
,зіСтовпчика
int
,доРядка
int
); String document.text(доСтовпчика
Cursor
,з
Cursor
); String document.text(до
Range
);діапазон
Повертає фрагмент тексту у вказаному діапазоні. Для того, щоб код було легше читати, ми рекомендуємо вам використовувати засновану на об’єктах Cursor і Range версію функції.
String document.line(
int
);рядок
Повертає рядок за його номером у тексті. Якщо вказаний номер не належатиме до діапазону номерів рядків документа, буде повернуто порожній рядок.
String document.wordAt(
int
,рядок
int
); String document.wordAt(стовпчик
Cursor
);курсор
Повертає слово за вказаною позицією курсора.
-
Range document.wordRangeAt(
int
,рядок
int
); Range document.wordRangeAt(стовпчик
Cursor
);курсор
Повертає діапазон слова за вказаним розташуванням курсора. Повернуте значення діапазону буде некоректним (див. Range.isValid()), якщо текст розташовано за кінцем рядка. Якщо за вказаним розташуванням курсора не буде слова, функцією буде повернуто порожній діапазон.
Актуальна версія: KDE 4.9
String document.charAt(
int
,рядок
int
); String document.charAt(стовпчик
Cursor
);курсор
Повертає символ за вказаною позицією курсора.
String document.firstChar(
int
);рядок
Повертає перший символ вказаного рядка
рядок
, який не є пробілом. Першим символом рядка вважається символ у стовпчику 0. Якщо рядок є порожнім або складається лише з пробілів, функція повертає порожній рядок.String document.lastChar(
int
);рядок
Повертає останній символ вказаного рядка
рядок
, який не є пробілом. Якщо рядок є порожнім або складається лише з пробілів, функція повертає порожній рядок.bool document.isSpace(
int
,рядок
int
); bool document.isSpace(стовпчик
Cursor
);курсор
Повертає
true
, якщо символ у вказаній позиції курсора є пробілом. Якщо це не так, повертаєfalse
.bool document.matchesAt(
int
,рядок
int
,стовпчик
String
); bool document.matchesAt(текст
Cursor
,курсор
String
);текст
Повертає
true
, якщо вказанийтекст
розташовано за відповідною позицією курсора. Якщо це не так, повертаєfalse
.bool document.startsWith(
int
,рядок
String
,текст
bool
);пропускатиПробіли
Повертає
true
, якщо рядок з вказаним номером починається з фрагмента текстутекст
. Якщо це не так, повертаєfalse
. За допомогою параметрапропускатиПробіли
можна вказати програмі, чи слід ігнорувати пробіли.bool document.endsWith(
int
,рядок
String
,текст
bool
);пропускатиПробіли
Повертає
true
, якщо рядок з вказаним номером завершується фрагментом текстутекст
. Якщо це не так, повертаєfalse
. За допомогою параметрапропускатиПробіли
можна вказати програмі, чи слід ігнорувати пробіли.bool document.setText(
String
);текст
Замінює весь вміст документа на
текст
.bool document.clear();
Вилучає з документа весь текст.
bool document.truncate(
int
,рядок
int
); bool document.truncate(стовпчик
Cursor
);курсор
Обрізає рядок з вказаним номером на вказаному стовпчику або позиції курсора. Повертає
true
у разі успіху абоfalse
, якщо рядка з вказаним номером у документі немає.bool document.insertText(
int
,рядок
int
,стовпчик
String
); bool document.insertText(текст
Cursor
,курсор
String
);текст
Вставляє фрагмент тексту
текст
у вказану позицію курсора. Повертаєtrue
у разі успіху абоfalse
, якщо документ відкрито у режимі лише для читання.bool document.removeText(
int
,зРядка
int
,зіСтовпчика
int
,доРядка
int
); bool document.removeText(доСтовпчика
Cursor
,з
Cursor
); bool document.removeText(до
Range
);діапазон
Вилучає текст у вказаному діапазоні. Повертає
true
у разі успіху абоfalse
, якщо документ відкрито у режимі лише для читання.bool document.insertLine(
int
,рядок
String
);текст
Вставляє вказаний фрагмент тексту до рядка з вказаним номером. Повертає
true
у разі успіху абоfalse
, якщо документ відкрито у режимі лише для читання або рядка з вказаним номером у документі немає.bool document.removeLine(
int
);рядок
Вилучає рядок з вказаним номером. Повертає
true
у разі успіху абоfalse
, якщо документ відкрито у режимі лише для читання або рядка з вказаним номером у документі немає.bool document.wrapLine(
int
,рядок
int
); bool document.wrapLine(стовпчик
Cursor
);курсор
Обрізає рядок з вказаним номером за вказаним розташуванням курсора. Повертає
true
у разі успіху. У інших випадках повертаєfalse
(наприклад, якщо номер рядка < 0).Актуальна версія: KDE 4.9
void document.joinLines(
int
,початковийРядок
int
);кінцевийРядок
Об’єднує рядки у діапазоні від
початковийРядок
докінцевийРядок
. Послідовні рядки тексту завжди відокремлюються одинарним пробілом.int document.lines();
Повертає кількість рядків у документі.
bool document.isLineModified(
int
);рядок
Повертає
true
, якщо у рядкурядок
зараз містяться незбережені дані.Актуальна версія: KDE 5.0
bool document.isLineSaved(
int
);рядок
Повертає
true
, якщорядок
було змінено, після чого документ було збережено. Інакше кажучи, у рядку вже не міститься незбережених даних.Актуальна версія: KDE 5.0
bool document.isLineTouched(
int
);рядок
Повертає
true
, якщо у рядкурядок
зараз містяться незбережені дані або його вміст було раніше змінено.Актуальна версія: KDE 5.0
bool document.findTouchedLine(
int
,початковийРядок
bool
);напрямок
Шукати наступний змінений рядок, починаючи з рядка
початковийРядок
. Пошук виконується у напрямку кінця або початку документа залежно від напрямку пошуку, визначеного параметромнапрям
.Актуальна версія: KDE 5.0
int document.length();
Повертає кількість символів у документі.
int document.lineLength(
int
);рядок
Повертає довжину рядка з номером
рядок
.void document.editBegin();
Започатковує групу редагування для впорядкування операцій зі скасування або повторення дій. Не забувайте, що викликати
editEnd()
слід саме стільки разів, скільки разів було викликаноeditBegin()
. ВикликиeditBegin()
використовують вбудований лічильник, отже їх може бути вкладено один у оден.void document.editEnd();
Завершує групу редагування. Останній виклик
editEnd()
(тобто відповідник першого викликуeditBegin()
) завершує крок з редагування.int document.firstColumn(
int
);рядок
Повертає перший відмінний від пробілу стовпчик у вказаному за допомогою параметра номера,
рядок
, рядку. Якщо у рядку будуть лише пробіли, функція поверне значення-1
.int document.lastColumn(
int
);рядок
Повертає останній відмінний від пробілу стовпчик у вказаному за допомогою параметра номера,
рядок
, рядку. Якщо у рядку будуть лише пробіли, функція поверне значення-1
.int document.prevNonSpaceColumn(
int
,рядок
int
); int document.prevNonSpaceColumn(стовпчик
Cursor
);курсор
Повертає номер стовпчика з символом, відмінним від пробілу. Пошук буде виконано у напрямку початку документа, починаючи з вказаної позиції курсора.
int document.nextNonSpaceColumn(
int
,рядок
int
); int document.nextNonSpaceColumn(стовпчик
Cursor
);курсор
Повертає номер стовпчика з символом, відмінним від пробілу. Пошук буде виконано у напрямку кінця документа, починаючи з вказаної позиції курсора.
int document.prevNonEmptyLine(
int
);рядок
Повертає наступний непорожній рядок, що містить символи, відмінні від пробілів. Пошук відбуватиметься у напрямку початку документа.
int document.nextNonEmptyLine(
int
);рядок
Повертає наступний непорожній рядок, що містить символи, відмінні від пробілів. Пошук відбуватиметься у напрямку кінця документа.
bool document.isInWord(
String
,символ
int
);атрибут
Повертає
true
, якщо вказанийсимвол
з вказаним параметроматрибут
може бути частиною слова. Якщо це не так, повертаєfalse
.bool document.canBreakAt(
String
,символ
int
);атрибут
Повертає
true
, якщо вказанийсимвол
з вказаним параметроматрибут
може бути використано для розбиття рядка. Якщо це не так, повертаєfalse
.bool document.canComment(
int
,атрибутПочатку
int
);атрибутКінця
Повертає
true
, якщо діапазон тексту, початок і кінець якого визначаються на основі вказаних атрибутів, можна закоментувати. Якщо це не так, повертаєfalse
.String document.commentMarker(
int
);атрибут
Повертає позначку коментаря для окремого рядка коментарів з вказаним параметром
атрибут
.String document.commentStart(
int
);атрибут
Повертає позначку, якою має розпочинатися багаторядковий коментар для вказаного значення параметра
атрибут
.String document.commentEnd(
int
);атрибут
Повертає позначку, якою має розпочинатися багаторядковий коментар для вказаного значення параметра
атрибут
.Range document.documentRange();
Повертає діапазон всього документа.
Cursor documentEnd();
Повертає курсор, розташований у останній позиції останнього рядка у документі.
bool isValidTextPosition(
int
,рядок
int
); bool isValidTextPosition(позиція
Cursor
);курсор
Повертає
true
, якщо вказану позицію курсора розташовано у коректній позиції у тексті. Позиція у тексті є коректною, лише якщо її розташовано на початку, у середині або у кінці коректного рядка тексту. Крім того, текстова позиція є некоректною, якщо її розташовано посередині замінника символу Unicode.Актуальна версія: KDE 5.0
int document.attribute(
int
,рядок
int
); int document.attribute(стовпчик
Cursor
);курсор
Повертає атрибут за вказаною позицією курсора.
bool document.isAttribute(
int
,рядок
int
,стовпчик
int
); bool document.isAttribute(атрибут
Cursor
,курсор
int
);атрибут
Повертає
true
, якщо атрибут за вказаною позицією курсора дорівнює значенню параметраатрибут
. Якщо це не так, повертаєfalse
.String document.attributeName(
int
,рядок
int
); String document.attributeName(стовпчик
Cursor
);курсор
Повертає назву атрибута придатну до читання. Ця назва відповідає назві
itemData
у файлах підсвічування синтаксичних конструкцій.bool document.isAttributeName(
int
,рядок
int
,стовпчик
String
); bool document.isAttributeName(назва
Cursor
,курсор
String
);назва
Повертає
true
, якщо назва атрибута у певній позиції курсора відповідає вказаному значенню параметраназва
. Якщо це не так, повертаєfalse
.String document.variable(
String
);ключ
Повертає значення вказаної змінної документа
ключ
. Якщо змінної з вказаною назвою у документі не існує, повертає порожній рядок.void document.setVariable(
String
,ключ
String
);значення
Встановлює значення відповідної змінної документа
ключ
.Див. також змінні документа Kate
Актуальна версія: KDE 4.8
int document.firstVirtualColumn(
int
);рядок
Повертає віртуальний стовпчик першого відмінного від пробілу символу у вказаному рядку або
-1
, якщо рядок є порожнім або містить лише символи пробілів.int document.lastVirtualColumn(
int
);рядок
Повертає віртуальний стовпчик останнього відмінного від пробілу символу у вказаному рядку або
-1
, якщо рядок є порожнім або містить лише символи пробілів.int document.toVirtualColumn(
int
,рядок
int
); int document.toVirtualColumn(стовпчик
Cursor
); Cursor document.toVirtualCursor(курсор
Cursor
);курсор
Перетворює вказану «реальну» позицію курсора на віртуальну позицію курсора, повертає або ціле значення (int), або об’єкт Cursor.
int document.fromVirtualColumn(
int
,line
int
); int document.fromVirtualColumn(virtualColumn
Cursor
); Cursor document.fromVirtualCursor(virtualCursor
Cursor
);віртуальнийКурсор
Перетворює вказану віртуальну позицію курсора на «реальну» позицію курсора, повертає або ціле значення (int), або об’єкт Cursor.
Cursor document.anchor(
int
,рядок
int
,стовпчик
Char
); Cursor document.anchor(символ
Cursor
,курсор
Char
);символ
Виконує пошук у напрямку початку документа, починаючи від вказаної позиції курсора, вказаного символу. Наприклад, якщо функції буде передано символ «(», функція поверне позицію початкової дужки «(». Відповідність дужок не враховуватиметься, тобто інші «(...)» буде проігноровано.
Cursor document.rfind(
int
,рядок
int
,стовпчик
String
,текст
int
); Cursor document.rfind(атрибут
= -1Cursor
,курсор
String
,текст
int
);атрибут
= -1Виконує пошук у напрямку початку документа вказаного фрагмента тексту з відповідним значенням параметра
атрибут
. Параметратрибут
буде проігноровано, якщо він матиме значення-1
. Функція поверне значення некоректного курсора, якщо фрагмент тексту знайти не вдасться.int document.defStyleNum(
int
,рядок
int
); int document.defStyleNum(стовпчик
Cursor
);курсор
Повертає типовий стиль курсора, використаний за вказаною позицією у тексті.
bool document.isCode(
int
,рядок
int
); bool document.isCode(стовпчик
Cursor
);курсор
Повертає
true
, якщо атрибут за вказаною позицією курсора не дорівнює жодному зі значень стилів:dsComment
,dsString
,dsRegionMarker
,dsChar
,dsOthers
.bool document.isComment(
int
,рядок
int
); bool document.isComment(стовпчик
Cursor
);курсор
Повертає
true
, якщо значенням атрибута символу у позиції курсора єdsComment
. Якщо це не так, повертаєfalse
.bool document.isString(
int
,рядок
int
); bool document.isString(стовпчик
Cursor
);курсор
Повертає
true
, якщо значенням атрибута символу у позиції курсора єdsString
. Якщо це не так, повертаєfalse
.bool document.isRegionMarker(
int
,рядок
int
); bool document.isRegionMarker(стовпчик
Cursor
);курсор
Повертає
true
, якщо значенням атрибута символу у позиції курсора єdsRegionMarker
. Якщо це не так, повертаєfalse
.bool document.isChar(
int
,рядок
int
); bool document.isChar(стовпчик
Cursor
);курсор
Повертає
true
, якщо значенням атрибута символу у позиції курсора єdsChar
. Якщо це не так, повертаєfalse
.bool document.isOthers(
int
,рядок
int
); bool document.isOthers(стовпчик
Cursor
);курсор
Повертає
true
, якщо значенням атрибута символу у позиції курсора єdsOthers
. Якщо це не так, повертаєfalse
.
Окрім програмного інтерфейсу документа та області перегляду, існує і загальний програмний інтерфейс редактора, який надає доступ до загальних функцій керування редактором за допомогою скриптів.
String editor.clipboardText();
Повертає текст, який зберігається у загальному буфері обміну даними.
Актуальна версія: KDE Frameworks™ 5.50
String editor.clipboardHistory();
Редактор зберігає журнал буфера обміну даними, який містить до 10 записів. Ця функція повертає усі записи, які зараз перебувають у журналі буфера обміну даними.
Актуальна версія: KDE Frameworks™ 5.50
void editor.setClipboardText(
String
);текст
Встановлює для вмісту буфера обміну даними значення
текст
. Запистекст
буде додано до журналу буфера обміну даними.Актуальна версія: KDE Frameworks™ 5.50