&Anders.Lund; &Anders.Lund.mail;
&Dominik.Haumann; &Dominik.Haumann.mail;
Андрей
Балагута

    uj2@mail.ru

Перевод на русский
Алексей
Опарин

    opaleksej@yandex.ru

Перевод на русский

# Дополнительные возможности редактирования

## Комментирование

Команды "Комментировать" и "Раскомментировать", которые доступны из меню Сервис, позволяют добавить или убрать маркеры комментариев для выделенного блока текста (или для текущей строки, если текст не выделен), при условии, что комментарии поддерживаются форматом редактируемого текста.

Правила комментирования определяются синтаксисом; таким образом, если подсветка синтаксиса не включена, то команды "Закомментировать" и "Раскомментировать" будут недоступны.

Некоторые форматы поддерживают только однострочные маркеры комментариев, другие -- только многострочные, третьи -- и те, и другие. Если многострочные маркеры недоступны, то комментирование блока, в котором не до конца выделена последняя строка, будет невозможным.

Предпочтение отдаётся комментированию отдельных строк однострочными маркерами, если последние допустимы синтаксисом и если такое комментирование возможно -- это помогает избежать проблем со вложенными комментариями.

При удалении маркеров комментариев выделение снимается с раскомментированного текста. При удалении маркеров многострочного комментария пробелы снаружи маркеров игнорируются.

Чтобы закомментировать выделенный текст (или активную строку), выберите пункт менюСервис Закомментировать или нажмите соответствующее сочетание клавиш (по умолчанию &Ctrl;D).

Чтобы удалить маркеры комментариев, выберите пункт меню Сервис Раскомментировать или нажмите соответствующее сочетание клавиш ( по умолчанию &Ctrl;&Shift;D).

## Командная строка компонента редактора

Модуль Kate имеет встроенную командную строку, позволяющую производить различные действия, оставляя интерфейс минималистским. Она представляет из себя поле ввода внизу области редактора. Для получения к ней доступа, выберите пункт меню Вид Переключиться в командную строку или нажмите F7 (по умолчанию). Команды, доступные из неё, описаны ниже, кроме того, модули могут предоставлять свои дополнительные команды.

Для выполнения команды введите её и нажмите Enter. На месте команды будет выведено сообщение об успешном её выполнении или об ошибке. Если вы вызвали командную строку клавишей F7, она будет автоматически скрыта по прошествии нескольких секунд. Для того чтобы убрать сообщение и ввести новую команду, нажмите F7 ещё раз.

Вы всегда можете получить справку с помощью команды `help`. Для получение списка всех доступных команд, введите `help list`, для просмотра справки по определённой команде - `help команда`.

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

### Стандартные команды

#### Параметры редактора

Установленные таким способом параметры применяются только к текущему экземпляру редактора и не сохраняются. Удобно, если нужно установить параметры, отличные от стандартных (например, отступ).

##### Типы аргументов

BOOLEAN

  Используется для команд включения/выключения. Допустимые значения - `on`, `off`, `true`, `false`, `1` или `0`

INTEGER

  Целое число

STRING

  Строка

    set-tab-widthINTEGER width

  Устанавливает расстояние между позициями табуляции

    set-indent-widthINTEGER width

  Устанавливает ширину отступа. Только при создании отступов пробелами.

    set-word-wrap-columnINTEGER width

  Устанавливает максимальную длину строк в случае, если включён автоматический перенос.

    set-icon-borderBOOLEAN enable

  Устанавливает видимость рамок пиктограмм.

    set-folding-markersBOOLEAN enable

  Устанавливает видимость маркеров сворачивания блоков кода.

    set-line-numbersBOOLEAN enable

  Устанавливает видимость нумерации строк.

    set-replace-tabsBOOLEAN enable

  Заменять при вводе символы табуляции на пробелы.

    set-remove-trailing-spaceBOOLEAN enable

  Удалять пробелы в конце строки при снятии с неё курсора.

    set-show-tabsBOOLEAN enable

  Представлять символы табуляции пробельное пространство в конце строк маленькими точками.

    set-indent-spacesBOOLEAN enable

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

    set-mixed-indentBOOLEAN enable

  Использовать для отступов как символы табуляции, так и пробелы. Это реализуется путём замены пробелов в количестве, кратном ширине символа табуляциями, на последние.

  Эта команда также включит расстановку отступов пробелами, и установит ширину отступов, если она не указана, в половину значения `tab-width` (для текущего документа на время выполнения).

    set-word-wrapBOOLEAN enable

  Динамический перенос слов

    set-replace-tabs-saveBOOLEAN enable

  Заменять символы табуляции на пробелы при сохранении.

    set-remove-trailing-space-saveBOOLEAN enable

  Удалить пробелы в конце строк при сохранении.

    set-indent-modename

  Выбрать режим расстановки отступов. Параметр `name` может иметь следующие значения: 'cstyle', 'csands', 'xml', 'python', 'varindent' и 'none'. При других значениях используется 'none'.

    set-highlighthighlight

  Выбрать формат для подсветки, один из содержащихся в подменюСервис Подсветка синтаксиса. Доступно также автозавершение параметра.

#### Команды редактирования

Команды, которые непосредственно изменяют текущий документ.

    indent

  Подставляет отступы к выделенным строкам или к текущей.

    unindent

  Снимает отступы с выделенных строк или с текущей.

    cleanindent

  Очистить отступы в выделенных строках или в текущей в соответствии с параметрами расстановки отступов для текущего документа.

    comment

  Вставляет маркеры, отмечающие выделенные строки или текущую как комментарии, в соответствии с форматом текущего файла (определяется способом подсветки синтаксиса).

    uncomment

  Удалить маркеры, отмечающие выделенные строки или текущую как комментарии, в соответствии с форматом текущего файла.

    kill-line

  Удаляет текущую строку.

    replacepatternreplacement

  Заменить текст, совпадающий с `pattern` на `replacement`. Для включения пробелов в `pattern`, нужно заключить в двойные или одинарныекавычки и `pattern`, и `replacement`. Если аргументы не заключены в кавычки, первое слово будет принято за `pattern`, а остальное - за `replacement`. Если `replacement` не задать, все `pattern` будут удалены.

  Для настройки параметров поиска, нужно указать соответствующие флаги после двоеточия (`replace:options pattern replacement`). Возможные параметры:

  `b`

    Искать в обратном направлении.

  `c`

    Искать от позиции курсора.

  `e`

    Искать только в выделенном тексте.

  `r`

    Аргумент `pattern` - регулярное выражение. Вы можете использовать `\N` в `replacement` для получения N-ной подстроки найденного текста.

  `s`

    С учётом регистра.

  `p`

    Подтверждать каждую замену.

  `w`

    Только целые слова.

    dateformat

  Вставить строку с датой/временем в указанном формате (задаётся параметром `format`), или в yyyy-MM-dd hh:mm:ss, если параметр упущен. Доступны следующие подстановки:

  `d` | Номер дня в месяце без ведущего нуля (1-31).
  `dd` | Номер дня в месяце с ведущим нулём (01-31).
  `ddd` | Сокращённое название дня недели ('Пн'..''Вс, 'Mon'..'Sun').
  `dddd` | Полное названия дня недели ('Понедельник'..'Воскресенье', 'Monday'..'Sunday').
  `M` | Номер месяца без ведущего нуля (1-12).
  `MM` | Номер месяца с ведущим нулём (01-12).
  `MMM` | Сокращённое название месяца ('Янв'..'Дек', 'Jan'..'Dec').
  `yy` | Год двумя цифрами (00-99).
  `yyyy` | Год четырьмя цифрами (1752-8000).
  `h` | Час без ведущего нуля (0..23 или 1..12, в зависимости от настроек).
  `hh` | Час с ведущим нулём (00..23 or 01..12, в зависимости от настроек).
  `m` | Минуты без ведущего нуля (0..59).
  `mm` | Минуты с ведущим нулём (00..59).
  `s` | Секунды без ведущего нуля (0..59).
  `ss` | Секунды с ведущим нулём (00..59).
  `z` | Миллисекунды без ведущих нулей (0..999).
  `zzz` | Миллисекунды с ведущими нулями (000..999).
  `AP` | Использовать 12-часовый формат часов. AP будет заменено на "AM" или "PM".
  `ap` | Использовать 12-часовый формат часов. ap будет заменено на "am" или "pm".

    charidentifier

  Эта команда позволяет вставить символ по его числовому идентификатору в десятичной, восьмеричной или шестнадцатеричной системах счисления. Чтобы использовать её, откройте диалоговое окно "Команда правки" и наберите `char: [number]` в строке ввода, после чего нажмите кнопку OK.

  ##### Примеры использования команды `char`

  Введите: `char:234`

  Получите: `ê`

  Введите: `char:0x1234`

  Получите: `ሴ`

`s///[ig]` `%s///[ig]`

  "Типичный пользователь" при виде этих команд обязательно вздрогнет и начнёт искать на клавиатуре кнопку "Windows". В самом деле, кому придёт в голову искать текст подобным образом? Но вы же не "типичный", не так ли? Поэтому попробуем разобраться в этих двух sed-подобных командах. Первая выполняет поиск/замену в текущей строке, вторая -- во всём файле (`%s///`).

  Вкратце, команды производят поиск текста, заданного маской поиска -- регулярным выражением (regexp) между первой и второй наклонной чертой, и, при нахождении, выполняет замену выражением, которое задано между второй и третьей чертой. Круглые скобки в маске поиска позволяют задать подстроки в найденном тексте, на которые можно потом ссылаться в выражении замены. Обратная ссылка -- это регулярное выражение, которое при совпадении заменяется на фактический текст и может быть использовано в шаблоне замены. Для этого, в нужном месте поставьте обратную черту, а за ней номер подстроки по порядку (`\1` -- для первой пары скобок, `\2` -- для второй, и т. д.).

  Чтобы искать сами скобки `(` или `)`, нужно предварить их обратной чертой: `\(\)`

  Если в самом конце указать `i`, поиск будет проводиться с учётом регистра, а если `g` - будут заменены все вхождения текста, совпадающего с регулярным выражением, иначе - только первое.

  ##### Замена текста в текущей строке

  Будучи противником принципа "разделяй и властвуй", вы решили откомпилировать свою программу. Но компилятор начал на вас ругаться: класс `myClass`, упомянутый в строке 3902, не определён.

  "Чёрт!", - думаете вы, -- "да это же мой класс `MyClass`". Вы добираетесь до строки 3902 и, вместо того, чтобы пытаться искать слово в этой длинной строке (а кто сейчас укладывает каждую строчку кода в 60 символов?), вы запускаете диалоговое окно "Команда правки", вводите `s/myclass/MyClass/i`, жмёте OK, сохраняете и компилируйте -- успешно и без ошибок.

  ##### Замена текста во всём файле

  Представьте себе, что у вас есть файл, в котором вы несколько раз упоминаете некоего человека по имени госпожа Иванова. Но вдруг вам сообщают, что эта самая госпожа Иванова вчера вышла замуж за господина с редкой фамилией Петров. Естественно, вам нужно заменить все упоминания о госпоже Ивановой на текст госпожа Петрова.

  Вызовите командную строку и введите следующий текст: `%s/госпожа Иванова/госпожа Петрова/` -- и ваша работа сделана.

  ##### Более сложный пример

  Этот пример показывает, как пользоваться обратными ссылками и классами символов (если вы не знаете, что это такое, советуем ознакомиться с приведенными ниже разделами).

  Допустим, у вас набрана такая строка:

      void MyClass::DoStringOps( String      &foo, String &bar String *p, int  &a, int &b )

  Теперь вы думаете, что это недостаточно "красивый" код, и решаете, что вам нужно использовать ключевое слово `const` с параметрами, передаваемыми по ссылке (теми, перед которыми стоит амперсанд). Вы также хотите удалить лишние пробелы.

  Запустите диалоговое окно "Команда правки" и наберите: `s/\s+(\w+)\s+(&)/ const \1 \2/g`, и не забудьте нажать кнопку OK -- иначе ничего не выйдет. Символ `g` в конце команды указывает компилятору "пересчитывать" регулярное выражение обратной ссылки каждый раз, когда встречаются совпадения.

  Вывод: `void MyClass::DoStringOps( const String &foo, const String &bar String *p, const int &a, const int &b )`

  Миссия завершена! Ну, и что же произошло? Мы искали некоторое количество пробелов (`\s+`), за которыми идут несколько латинских символов (`\w+`), следом за ними опять несколько пробелов (`\s+`), после которых стоит амперсанд, и по ходу дела сохраняли эти алфавитные символы и амперсанд для использования их в операции замены. После этого мы заменили совпадающие части строки следующей последовательностью: один пробел, за которым идёт спецификатор const, за ним ещё один пробел, после которого наши сохранённые символы (`\1`), ещё один пробел и сохранённый амперсанд (`\2`)

  В одном случае латинские символы составили слово String, в другом -- слово int, т.е. символьный класс `\w` с последующим знаком `+` определяет символьный набор произвольной длины.

#### Команды навигации

    gotoINT line

  Перейти к указанной строке.

    findpattern

  Перейти к первому образцу, заданному параметром `pattern`. Последующие вхождения образца можно найти посредством пункта меню Правка Найти далее (клавиша по умолчанию - F3).

  Параметры команды поиска можно задавать добавлением двоеточия и "флагов" после её имени (`find:options pattern`). Флаги - набор из следующих букв:

  `b`

    Искать в обратном направлении.

  `c`

    Искать от позиции курсора.

  `e`

    Искать только в выделенном тексте.

  `r`

    Аргумент `pattern` - регулярное выражение. Вы можете использовать `\N` в `replacement` для получения N-ной подстроки найденного текста.

  `s`

    С учётом регистра.

  `w`

    Только целые слова.

    ifindpattern

  Поиск по мере набора. Поддерживается установка дополнительных флагов

  `b`

    Искать в обратном направлении.

  `r`

    Поиск по регулярному выражению.

  `s`

    С учётом регистра.

  `c`

    Искать от позиции курсора.

## Использование сворачивания кода

Сворачивание кода позволяет скрывать участки документа в редакторе, упрощая осмотр громоздких документов. В &kate; разделение на сворачиваемые участки определяется правилами подсветки синтаксиса, следовательно, доступно не для всех форматов файлов. В основном, сворачивание кода доступно в режиме написания исходного кода, XML-разметки и т.п. Большинство способов подсветки позволяют также самостоятельно определять скрываемые области, чаще всего используя ключевые слова `BEGIN` и `END`.

Для того чтобы включить/отключить функцию сворачивания, выберите пункт меню Вид Показать маркеры сворачивания. На панели маркеров сворачивания с левой стороны документа появится графическое представление сворачиваемых участков. Знак "-" показывает, что участок развёрнут, знак "+" обозначает свёрнутый участок. Щелчок на знаке "+" приведёт к разворачиванию свёрнутого участка, и наоборот (с одновременным изменением графического представления).

Для управления состоянием сворачиваемых участков служат четыре команды, смотрите справку по меню.

Если вы не хотите использовать функцию сворачивания, можно отключить параметр Показать маркеры сворачивания (если доступны) на странице настройки внешнего вида редактора

## Написание сценариев Javascript в компоненте редактора

### Введение

Начиная с версии 2.5, компонент редактора &kate; поддерживает написание сценариев на языке ECMA, известном также как JavaScript.

Сценарии можно вызывать только из встроенной командной строки. При этом необходимо, чтобы сценарий и файл .desktop (если он существует) находились в той папке, в которой &kate; сможет их разыскать. Подходящая папка для этого - `katepart/scripts` в папках данных &kde;. Найти папки данных можно командой `kde4-config `--path` `data``. Как правило, существуют системная и пользовательские папки данных. Естественно, сценарии в системных папках доступны всем пользователям системы, а в пользовательских - только их владельцам.

Эта функциональность находится на экспериментальной стадии разработки, весьма вероятно его изменение в дальнейшем.

Сценарии нельзя добавлять в меню или назначать им комбинации клавиш. Может быть, в дальнейшем мы сможем это исправить.

Также невозможно использовать в сценариях аргументы. Потерпите, в светлом будущем это вполне может произойти ;)

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

Здесь приведен полный список функций и свойств, доступных для объектов document и view. Разумеется, доступны любые стандартные объекты языка, такие как Math, String, Regex и т.д.

Во время исполнения сценария, объектом `document` является текущий документ, а объектом `view` является текущий вид (панель).

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

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

`debug( `string`) [функция]`

  #### параметры

  - `string` выводимая строка

  Выводит строку на STDERR, используя `kDebug()`. Для вывода используется выделенное пространство, в начало может быть добавлен префикс `Kate (KJS Scripts):`

#### Программный интерфейс (API) класса `document`

`document.attribute( `line` , `column` ); [функция]`

  #### Параметры

  - `uint line` Строка, в которой находится атрибут.

  - `uint column` Столбец, в котором находится атрибут.

  Возвращает числовые значения позиции атрибута в документе [`line`,`column`]. Атрибут представляет собой вид или стиль текста, а также используется для определения подсветки синтаксиса в различных частях текста смешанных форматов вроде HTML или PHP.

`document.canBreakAt( `Char c`, `uint attribute` ); [функция]`

  #### Параметры

  - `c` Знак для проверки

  - `attribute` Атрибут для позиции `c`.

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

`document.canComment( `uint start_attribute`, `uint end_attribute` ); [функция]`

  #### Параметры

  - `start_attribute` Атрибут начала участка комментария.

  - `end_attribute` Атрибут конца участка комментария.

  Возвращает принадлежность start_attribute и end_attribute к одной и той же системе подсветки синтаксиса. Если это так - всё нормально.

  #### использование canComment

      if ( document.canComment( document.attribute(1,0), document.attribute(5,0) ) ) {
          // 1,0 и 5,0 принадлежат к одной системе подсветки синтаксиса
      }

`document.clear(); [функция]`

  Очищает документ.

`document.commentStart( `uint attribute` ); [функция]`

  #### Параметры

  - `attribute` Атрибут текста, для которого вводится строка commentStart.

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

`document.commentMarker( `uint attribute` ); [функция]`

  #### Параметры

  - `attribute` Атрибут текста, для которого вводится строка commentMarker

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

`document.commentEnd( `uint attribute` ); [функция]`

  #### Параметры

  - `attribute` Атрибут текста, для которого вводится строка commentEnd

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

`document.editBegin(); [функция]`

  Начало группы редактирования. Все действия включаются в одну группу отмены до вызова editEnd().

`document.editEnd(); [функция]`

  Окончание группы редактирования.

`document.highlightMode; [свойство:только для чтения]`

  Название режима подсветки (JavaScript или C++). Если к документу не применяется режим подсветки, устанавливается значение None. Помните - необходимо использовать англоязычное название.

`document.indentMode; [свойство:только для чтения]`

  Название режима отступов документа, такое как `normal` или `cstyle`. Помните - если режим отступов не задан, устанавливается значение `none`.

`document.indentWidth; [свойство:только для чтения]`

  Устанавливает ширину отступа. Только при создании отступов пробелами.

`document.insertLine( `uint line`, `string text` ); [функция]`

  #### Параметры

  - `line` номер строки в документе

  - `text` вставляемый текст

  Вставляет новую строку с текстом `text` в строку под номером `line`.

`document.insertText( `uint line`, `uint column`, `string text` ); [функция]`

  #### Параметры

  - `line` номер строки

  - `column` номер столбца

  - `text` вставляемый текст

  Вставляет текст `text` в строку номер `line`, столбец номер `column`.

document.length(); [функция]

  Возвращает размер документа в байтах.

`document.lines(); [функция]`

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

document.mixedIndent; [свойство:только для чтения]

  Логическая величина. Сообщает, применяется ли в документе смешанный тип отступов. Если это так - отступы осуществляются при помощи и пробелов, и позиций табуляции, сходно с редактором Emacs.

document.removeLine( `uint line` ); [функция]

  #### Параметры

  - `line` номер строки

  Удаляет строку документа номер line.

`document.removeText( `uint startLine`, `uint startColumn`, `uint endLine`, `uint endColumn` ); [функция]`

  #### Параметры

  - `startLine` указывает начальную строку

  - `startColumn` указывает начальный столбец

  - `endLine` указывает конечную строку

  - `endColumn` указывает конечный столбец

  Удаляет участок текста, начиная от строки номер `startLine` и столбца номер `startColumn` до строки номер `endLine` и столбца номер `endColumn`.

`document.setText( `string text` ); [функция]`

  #### Параметры

  - `text` текст документа

  Приводит всё содержимое документа к тексту с параметрами `text`.

`document.spaceIndent; [свойство:только для чтения]`

  Логическая величина. Сообщает, применяется ли к документу отступ пробелами. Если это так, то отступы в документе производятся на величину indentWidth между уровнями, иначе сдвиг происходит на одну позицию табуляции.

`document.textFull(); [функция]`

  Возвращает весь текст документа. Если в тексте есть переводы строк, то знак перевода строки отобразится как `\n`.

`document.textLine( uint line ); [функция]`

  #### Параметры

  - `line` строка номер

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

`document.textRange( `uint startLine`, `uint startColumn`, `uint endLine`, `uint endColumn` ); [функция]`

  #### Параметры

  - `startLine` указывает начальную строку

  - `startColumn` указывает начальный столбец

  - `endLine` указывает конечную строку

  - `endColumn` указывает конечный столбец

  Возвращает указанный участок текста. Если в пределах участка есть переводы строк, то знак перевода отобразится как `\n`.

#### Аппаратно-программный интерфейс (API) `view`

`view.clearSelection(); [функция]`

  Снимает выделение со всего текста.

`view.cursorColumn(); [функция]`

  Возвращает столбец, в котором находится курсор (учитываются все знаки табуляции).

`view.cursorColumnReal(); [функция]`

  Возвращает номер столбца, в котором реально находится курсор (знак табуляции считается за один символ).

`view.cursorLine(); [функция]`

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

`view.hasSelection(); [функция]`

  Если выделенный текст есть, возвращает `true`, иначе `false`.

`view.removeSelectedText(); [функция]`

  Если есть выделенный текст, он удаляется.

`view.selectAll(); [функция]`

  Выделяет весь текст.

`view.selection(); [функция]`

  Возвращает выделенный текст. Если в пределах выделенного текста есть переводы строк, они отображаются знаком `\n`.

`view.selectionEndColumn; [свойство:только для чтения]`

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

`view.selectionEndLine; [свойство:только для чтения]`

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

`view.selectionStartColumn; [свойство:только для чтения]`

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

`view.selectionStartLine; [свойство:только для чтения]`

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

`view.setCursorPosition( `uint line`, `uint column` ); [функция]`

  #### Параметры

  - `line` Указывает строку для курсора.

  - `column` Указывает столбец для курсора.

  Устанавливает курсор ввода в позицию [`line`, `col`]. Установка курсора происходит визуально, символ табуляции считается за несколько символов, в зависимости от расположения текста, но не больше значения параметра Ширина табуляции. Отсчёт номеров строк и столбцов начинается от нуля.

`view.setCursorPositionReal( `uint line`, `uint column` ); [функция]`

  #### Параметры

  - `line` Указывает строку для курсора.

  - `column` Указывает столбец для курсора.

  Устанавливает курсор в позицию [`line`, `col`]. При рассчёте позиции табуляция соответствует одному символу. Отсчёт строк и столбцов начинается от нуля.

`view.setSelection( `uint startLine`, `uint startColumn`, `uint endLine`, `uint endColumn` ); [функция]`

  #### Параметры

  - `startLine` указывает начальную строку

  - `startColumn` указывает начальный столбец

  - `endLine` указывает конечную строку

  - `endColumn` указывает конечный столбец

  Устанавливает выделение от строки номер `startLine` и столбца номер `startColumn` до строки номер `endLine` и столбца номер `endColumn`.

#### Пример сценария

В качестве примера рассмотрим небольшой сценарий, переводящий выделенный текст в верхний регистр. Очевидно, сначала необходимо проверить, есть ли выделенный текст вообще. Если есть - возьмём этот текст, изменим регистр и заменим его новым текстом. Сценарий будет выглядеть примерно так:

    if ( view.hasSelection() )
    {
      column = view.selectionStartColumn;
      line = view.selectionStartLine;

      selection = view.selection().toUpperCase();

      document.editBegin();
      view.removeSelectedText();
      document.insertText( line, column, selection );
      document.editEnd();
    }

Для группировки действий так, чтобы их можно было отменить одним вызовом пункта меню Отмена, мы поместили строки

    view.removeSelectedText()

и

    document.insertText()

между

    document.editBegin()

и

    document.editEnd()

.

#### Пример файла `.desktop`

Вот пример простого .desktop-файла, соответствующего приведенному выше сценарию.

    [Desktop Entry]
    Encoding=UTF-8
    Name=Kate Part JavaScript Uppercase
    Comment=Script to uppercase the selection
    X-Kate-Command=uppercase-selection
    X-Kate-Help=<p>Usage: <code>uppercase-selection</code></p>

Мы видим, что здесь можно определить кодировку, ввести название, комментарий, указать путь к справке с помощью X-Kate-Help и название для командной строки через X-Kate-Command. Если файлы находятся в SVN-хранилище KDE, то пункты Name, Comment and X-Kate-Help автоматически переводятся на другие языки командами переводчиков KDE.

#### Резюме

&kate; может разыскивать в определённых папках (см. выше) файлы `*.js`. Для каждого найденного файла будет проведен поиск соответствующего файла `.desktop`, например файлу uppercase.js соответствует файл uppercase.desktop.

Если требуемый файл `.desktop` не найден, сценарий будет зарегистрирован в командной строке katepart с именем без расширения .js, для нашего примера это будет `uppercase`.Если такое формирование названия команды подходит, и вам не требуются какие-то дополнительные возможности, которые предоставляет файл `.desktop`, он может не понадобиться вам совсем.

Если файл `.desktop` найден, то katepart считывает имя из пункта .desktop-файла X-Kate-Command, например X-Kate-Command=uppercase-selection.