<< Нажмите, чтобы показать Содержание >> Спецификация формата RVF

В этом разделе содержится подробная информация о формате RichView Format (RVF).

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

Синтаксис

{x}        – ноль или более повторений элемента x;

{x}+        – одно или более повторений элемента x;

[x]        – элемент x не обязателен;

xy        – за элементом x идёт элемент y;

x | y        – элемент x или элемент y;

'c'        – символьная строка;

<n>        – определяемый элемент.

Типы данных в RVF

<целое> – целое число, ['-']{<цифра>}+;

<цифра> ::= '0' | … | '9';

Целое число завершается ' ' (символом пробела) или концом строки; для простоты, мы не будем указывать символ пробела (то есть он будет включён <целое>).

<кс> – символы конца строки; обычно это символы CR+LF, CR или LF; перед бинарными данными перевод строки должен содержать оба символа CR и LF (#13#10).

<строка> – строка ANSI-символов (без символов CR, LF и #0)

<юникодная строка> – строка юникодных символов (UTF-16). Последним символом в строке должен быть разделитель абзаца (код $2029).

<спец. строка> – строка ANSI-текста, если версия RVF равна 1.3 или меньше, и текст UTF-8, если версия RVF равна 1.3.1 или больше. В этой строке символ #1 представляет символ #13, символ #2 представляет символ #10.

<спец. строка 2> – строка ANSI-текста, если версия RVF равна 1.3.1 или меньше, и текст UTF-8, если версия RVF равна 1.3.2 или больше. В этой строке символ #1 представляет символ #13, символ #2 представляет символ #10.

<строка в кавычках> – <спец. строка>, заключённая в двойные кавычки. Если в строку входит символ двойных кавычек, он повторяется дважды.

Структура RVF

<RVF> ::= [<Инфо о версии>]{<Запись RVF>}

Инфо о версии

<Инфо о версии> := <Тип записи версии><Версия><Подверсия>[<Подподверсия>]<кс>

<Тип записи версии> ::= '-8'

<Версия> ::= <целое>

<Подверсия> ::= <целое>

<Подподверсия> ::= <целое>

▪В настоящий момент, <Версия> = 1, <Подверсия> = 3, <Подподверсия> = 2. В этой версии имена элементов документа, теги и строковые свойства хранятся как UTF-8.

▪Ранее использовалось: <Версия> = 1, <Подверсия> = 3.  <Подподверсия> = 1 для Delphi 2009+; для более старых Delphi <Подподверсия> не писалась. В этой версии, имена элементов документе хранились как ANSI, теги и строковые свойства хранились как  UTF-8 если <ПодПодВерсия> = 1, или ANSI если <ПодПодВерсия> = 0 пропущена.

▪Если <Инфо о версии> отсутствует в RVF, подразумевается версия 1.0 (без <Параметры элемента> в <Элемент RVF>)

Структура записи RVF

RVF состоит из записей. Большинство записей представляют элементы документа (одна запись = один элемент), но есть специальные типы записей.

<Запись RVF> ::= <Заголовок записи><кс>({<строка><кс>}|{<юникодная строка>})[<Бинарные данные>]

<Заголовок записи> ::= <Тип записи><Число строк><Абзац><Параметры элемента><Запрос><Тег><Остаток заголовка>

<Тип записи> ::= <целое>

<Число строк> ::= <целое>

<Абзац> ::= <целое>

<Параметры элемента>::=<целое>

<Запрос> ::= '0' | '1' | '2' | '3'

<Тег> ::= <строка в кавычках>

<Тип записи> – это тип <Записи RVF>

<Число строк> – это количество строк между этим <Заголовок записи> и следующим <Заголовок записи> (или концом файла). Если программа для чтения RVF не понимает этот тип записи, она должна пропустить это количество строк. <Бинарные данные> (если присутствуют) считаются одной из строк после заголовка.

<Абзац> – это номер элемента коллекции стилей абзацев (RVStyle.ParaStyles) (если этот элемент начинает абзац) или -1 (если запись представляет собой элемент, и этот элемент продолжает абзац).

<Параметры элемента> – это набор битов, преобразованных в целое число.

<Тег> – это строка, ассоциированная с элементом документа. TRichView сохраняет это строку в двойных кавычках. Пустые теги сохраняются как '0' (без кавычек). В RVF 1.3.1 и более новых версиях строки тегов сохраняются в кодировке UTF-8, а в более старых версиях – в ANSI. При сохранении символы #13 и #10 заменяются на #1 и #2, при загрузке они восстанавливаются.

См. раздел о тегах.

<Запрос> может быть числом в диапазоне 0..3

Если <Запрос>=1, то следующей строкой за заголовком следует имя элемента (рисунка или компонента).

Данные запрашиваются событиями: OnRVFPictureNeeded, OnRVFControlNeeded.

Режим сохранения (сохранение полной информации о рисунках или компонениах / сохранение только имени и запрос при чтении) определяется свойством RichView.RVFOptions (для режима запроса необходимо убрать опции rvfoSavePicturesBody и/или rvfoSaveControlsBody). В этом событии необходимо создать компонент или изображение и присвоить его параметрам gr или ctrl. Например:

procedure TMyForm.MyRichViewRVFControlNeeded(

  Sender: TCustomRichView; Name: TRVUnicodeString;

  Tag: TRVTag; var ctrl: TControl);

begin

  ctrl := TButton.Create(nil);

  TButton(ctrl).Caption := 'Demo';

  TButton(ctrl).OnClick := MyClickProcedure;

end;

<Остаток заголовка> отличается для различных элементов. Некоторые новые параметры могут быть добавлены в будущем в <Остаток заголовка>. При чтении RVF следует игнорировать все параметры, следующие в строке после последнего поддерживаемого параметра.

Если <Запрос> равен 1 то <Остаток заголовка> пуст.

Информация далее для <Запрос>=0 | 2 | 3.

Записи RVF

Закладки

<Тип записи> = rvsCheckpoint

<Абзац> игнорируется

<Число строк> = 1

<Остаток заголовка> ::= <Флаг события>

<Флаг события> ::= '0' | '1'

Если <Флаг события> равен '1', то событие OnCheckPointVisible вызывается, когда закладка становится видимой при прокрутке документа.

Строки после заголовка записи:

▪<Имя закладки>

<Имя закладки> ::= <спец. строка>

Закладки не являются элементами документа, но удобно сохранять их таким же образом. Закладка сохраняется перед элементом, к которому она привязана.

Текст (Элементы)

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

<Тип записи> >= 0

<Остаток заголовка> := [<Доп. свойства>] [<Подсказка>]

<Подсказка> := <строка в кавычках>, значение свойства rvespHint.

<Доп свойства> := +<строка в кавычках>

<Число строк> равно числу абзацев, содержащихся в этой записи. Все абзацы будут указанного стиля текста и абзаца. Если <Абзац>=-1, то этот элемент продолжает предыдущий абзац.

Строки после заголовка записи – это текст (абзацы). Строки могут быть в юникодной кодировке (определяется в <Параметры элемента>). Если <Запрос>=0, юникодный текст сохранён как UTF-16 (WideString). Если <Запрос>=3, юникодный текст сохранён как шестнадцатеричная строка.

<Доп. свойства> не сохраняются по умолчанию. Они могут быть использованы для сохранения дополнительных свойств элементов, унаследованных от TRVTextItemInfo.

Горизонтальная линия (Элемент)

<Тип записи> = rvsBreak

<Абзац> игнорируется

<Остаток заголовка> ::= <Цвет линии><Стиль линии><Толщина линии> [<Непрозрачность цвета>]

<Цвет линии> ::= <целое>

<Стиль линии> ::= <целое>

<Толщина линии> ::= <целое>

<Цвет линии> – это цвет горизонтальной линии, TColor; если он равен clNone, то линия будет иметь цвет 0-го стиля текста. Версия FMX может также сохранить <Непрозрачность цвета>, значение от 0 до 255.

<Стиль линии> – это значение TRVBreakStyle, сохранённое как число.

<Толщина линии> это толщина линии.

<Число строк> >= 0.

Рисунок (Элемент)

<Тип записи> = rvsPicture

<Число строк> >= 3

<Остаток заголовка> = <Вертикальное выравнивание>

<Вертикальное выравнивание> ::=  <целое>

<Вертикальное выравнивание> – это значение TRVVAlign, сохранённое как число.

Строки после заголовка:

▪<Имя элемента>

▪<Delphi-тип рисунка>

▪<Данные рисунка>

<Имя элемента> ::= <спец. строка 2>, это имя элемента документа.

<Delphi-тип рисунка> – это имя графического класса (такое как 'TBitmap', 'TIcon', 'TMetafile', 'TJPEGImage') или расширение графического класса ('bmp', 'ico', 'wmf', 'jpg')

<Данные рисунка> могут быть в текстовом или бинарном формате.

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

В бинарном формате, <кс> после <Delphi-тип рисунка> должен быть CR+LF (оба символа). Бинарные данные состоят из <Размер данных> и <Данные>. Размер данных – это двоичное 4-байтовое число, число байт в <Данные>.

Примечание 1: [VCL и Lazarus] Для загрузки изображения заданного класса из RVF необходимо зарегистрировать этот класс с помощью процедуры RegisterClasses. Стандартные графические классы ТРВ-Редактор регистрирует самостоятельно. Если класс не зарегистрирован, TRichView может определить формат изображения по содержимому и самостоятельно выбрать соответствующий графический класс.

Примечание 2: Поведение TRichView при загрузке незарегистрированного графического формата определяется в свойстве RVFOptions. Если включена опция rvfoIgnoreUnknownPicFmt, то это изображение будет просто пропущено. Если эта опция не исключена, функция чтения RVF возвращает False (ошибка чтения). В обоих случаях свойство RVFWarnings будет содержать значение rvfwUnknownPicFmt.

Компонент (Элемент)

<Тип записи> = rvsComponent

Всё как для рисунков, с поправкой на: rvfoIgnoreUnknownCtrls, rvfwUnknownCtrls.

Значок (Элемент)

<Тип записи> = rvsBullet

<Число строк> >= 1

<Остаток заголовка> = <Номер ImageList><Номер изображения>

<Номер ImageList> ::= <целое>

<Номер изображения> ::= <целое>

Строки после заголовка:

▪<Имя элемента>

<Имя элемента> ::= <спец. строка 2>, это имя элемента документа.

<Номер ImageList> – это значение свойства Tag соответствующего компонента TImageList (не следует путать с тегами элементов документа! Здесь используется свойство TImageList.Tag). При чтении вызывается событие OnRVFImageListNeeded. Вы должны присвоить компонент TImageList параметру il события. В противном случае значок будет пропущен. Поведение TRichView при чтении слишком большого номера изображения задаётся в RVFOptions. Если опция rvfoConvLargeImageIdxToZero включена, то номер изображения будет сброшен в 0. В противном случае функция чтения RVF возвращает False (ошибка чтения). В обоих случаях свойство RVFWarnings будет содержать значение rvfwConvLargeImageIdx.

Интерактивный значок (Элемента)

<Тип записи> = rvsHotspot

<Число строк> >= 1

<Остаток заголовка> = <Номер ImageList><Номер изображения><Активный номер изображения>

<Номер ImageList> ::= <целое>

<Номер изображения> ::= <целое>

<Активный номер изображения> ::= <целое>

Строки после заголовка:

▪<Имя элемента>

<Имя элемента> ::= <спец. строка 2>, это имя элемента документа.

См. описание обычного значка выше.

Коллекции стилей, разметка, DocProperties и др.

<Тип записи> = rvsDocProperty

<Абзац> игнорируется

<Запрос> может быть 0 (данные сохранены как шестнадцатеричный текст) или 2 (данные сохранены в бинарной форме)

<Остаток заголовка> ::= '1' | '2' | '3' | '4' | '5' | '6'|'7'|'8'|'9'|'10'|'11'|'12'|'13'

<Число строк> = 2 для 1..4 и 6, 7, 10. Первая строка содержит имя компонента TRVStyle для 1,2,4,10, или пустая для 3,6,9,12. Затем следует шестнадцатеричные или бинарные данные.

При сохранении DocProperties, <Число строк>=DocProperties.Count. Каждый элемент DocProperties сохраняется как <спец. строка>.

DocParameters сохраняются строками вида свойство=значение (только для свойств, имеющие значение, отличное от значения по умолчанию).

Для 8, первая строка содержит название поддокумента (такое как 'header').

Для 11, каждый шаблон стиля сохраняется в двух строках, поэтому <Число строк>=StyleTemplates.Count*2. Первая строка содержит имя шаблона (<спец. строка>), вторая строка содержит его идентификатор.

Для 12,  DocObjects сохраняются с помощью специального класса-коллекции TRVCollectionBuilder, позволяющего сохранять элементы коллекции различных классов.

Для 13, следующая строка содержит число (<целое>).

Фон (устаревшая версия)

Это устаревший тип записи. Он может быть прочитан, но не сохраняется новыми версиями ТРВ-Редактора

<Тип записи> = rvsBack

Эта запись похожа на rvsPicture, но имеет отличия:

▪<Остаток заголовка> содержит цвет и стиль фона, и опционально его непрозрачность.

▪отсутствует строка <Имя элемента>;

▪<Delphi-тип рисунка> всегда 'TBitmap'

▪<Запрос>=1 не поддерживается

<Число строк> = 2 | 0

<Абзац> и <Тег> игнорируются (0).

<Остаток заголовка>::=<Стиль фона><Цвет> [<Непрозрачность цвета>]

<Стиль фона>::= <целое> (значение TRVBackgroundStyle, сохранённое как число)

<Цвет>::=<целое> (цвет фона)

Версия FMX может сохранять <Непрозрачность цвета>, значение от 0 до 255.

Если стиль фона равен bsNoBitmap (если если фоновые изображение пусто), то после заголовка нет строк (и <Запрос>=0).

Строки после заголовка:

▪<Delphi-тип рисунка>

▪<Данные рисунка>

Цвет фона сохраняется как TColor, даже в версии FireMonkey. Версия FireMonkey также может сохранять степень непрозрачности цвета (значение от 0 до 255).

Фон (новая версия)

<Тип записи> = rvsBackEx

<Остаток заголовка>::=<Цвет> [<Непрозрачность цвета>]

Цвет фона сохраняется как TColor, даже в версии FireMonkey. Версия FireMonkey также может сохранять степень непрозрачности цвета (значение от 0 до 255).

Если фоновое изображение отсутствует, и все свойства имеют значения по умолчанию, <Число строк> = 0. В противном случае оно равно числу строк после заголовка:

▪<Delphi-тип рисунка> | 'none'

▪<Свойство фона>*

▪<Данные рисунка>

<Delphi-тип рисунка> – это имя графического класса (такое как 'TBitmap', 'TIcon', 'TMetafile', 'TJPEGImage') или расширение графического класса ('bmp', 'ico', 'wmf', 'jpg')

<Данные рисунка> такие же, как для рисунков (см. выше). Сохраняется только если первая строка после заголовка не равна 'none'.

<Свойство фона> это свойство BackgroundProperties.

<Свойство фона> ::= <Свойство> '=' <Значение>

<Свойство> ::= 'HorizontalAlignment' | 'VerticalAlignment' | 'HorizontalSizeKind' | 'VerticalSizeKind' | 'HorizontalOffsetKind' | 'VerticalOffsetKind' | 'HorizontalOffset' | 'VerticalOffset' | 'ImageWidth' | 'ImageHeight' | 'Attachment' | 'HorizontalRepeat' | 'VerticalRepeat' | 'Visible'

<Значение> ::= <целое> (значение свойства, сохранённое как целое число)

Маркер списка (Элемент)

<Тип записи> = rvsMarker

<Число строк> >= 0

<Остаток заголовка> ::= <Номер списка> <Номер уровня> <Начальное значение> <Сброс>

Все элементы <Остаток заголовка> являются <целое> (<Сброс> равен ord(значение Boolean))

Текстовая метка (Элемент)

<Тип записи> = rvsLabel

<Число строк> >= 6

Строки после заголовка:

▪<Текст>

▪<Стиль текста>

▪<Минимальная ширина>

▪<Выравнивание>

▪'protect' | 'no protect'

▪<Имя элемента>

<Текст> ::= <спец. строка>, это свойство Text. <Стиль текста> ::= <целое>, это свойство TextStyleNo. <Минимальная ширина> ::= <целое>, это свойство MinWidth. <Выравнивание> ::= <целое>, это ord(Alignment). Следующая строка зависит от свойства ProtectTextStyleNo. <Имя элемента> ::= <спец. строка 2>.

Последовательность (Элемент)

<Тип записи> = rvsSequence

<Число строк> >= 10

Строки после заголовка:

▪<Идентификатор последовательности>

▪<Тип нумерации>

▪<Сброс>

▪<Начальное значение>

▪<Стиль текста>

▪<Минимальная ширина>

▪<Выравнивание>

▪'protect' | 'no protect'

▪<Имя элемента>

▪<Строка формата>

<Идентификатор последовательности> ::= <спец. строка>, это свойство SeqName. <Тип нумерации> ::= <целое>, это ord(NumberType). <Сброс> ::= <целое>, это ord(Reset). <Начальное значение> ::= <целое>, это StartFrom. Следующие пять строк имеют те же значения, что и для текстовой метки. <Строка формата> ::= <спец. строка>, это свойство FormatString.

Сноска и концевая сноска (Элементы)

<Тип записи> = rvsFootnote | rvsEndnote

<Число строк> >= 8

Строки после заголовка:

▪<Стиль текста>

▪<Минимальная ширина>

▪<Выравнивание>

▪'protect' | 'no protect'

▪<Сброс>

▪<Начальное значение>

▪<Имя элемента>

▪<Документ>

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

<Документ> может храниться в текстовом  или бинарном формате. Это значение свойства Document, сохранённое в формате RVF.

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

В бинарном формате <кс> после <Имя элемента> должно быть CR+LF (оба символа). Бинарные данные состоят из <Размер данных> и <Данные>. Размер данных – это 4-байтовое двоичное число, количество байтов в <Данные>.

Ссылка на сноску (Элемент)

<Тип записи> = rvsNoteReference

<Число строк> >= 5

Строки после заголовка:

▪<Стиль текста>

▪<Минимальная ширина>

▪<Выравнивание>

▪'protect' | 'no protect'

▪<Имя элемента>

Значение этих строк такое же, как и у текстовых меток.

Дополнительные свойства элементов документа

Некоторые элементы могут содержать дополнительные целочисленные и строковые свойства. Они сохраняются в виде строк после заголовка (одна строка на каждое свойство) в следующем формате:

свойство=значение

Если свойство имеет значение по умолчанию, оно не сохраняется. Список имён свойств можно найти в файле RVItem.pas, в массивах RVFExtraItemIntPropNames и RVFExtraItemStrPropNames.

Начиная с ТРВ-Редактора версии 11, значения сохраняются как <спец. строка>.

Обратите внимание, что все свойства-цвета сохраняются как значения TColor, даже в FireMonkey (где все свойства цвета имеют тип TAlphaColor). В дополнение к самому цвету, версия FireMonkey может сохранить дополнительное свойство непрозрачности цвета (со значением от 0 до 255).

---

Данная спецификация не охватывает случай сохранения имён стилей вместо номеров стилей (эта функция устарела).

Основные изменения в формате RVF

Версия RVF 1.2

Более старые программы не могут читать новые RVF-файлы, но программы, скомпилированные с новыми версиями ТРВ-Редактора, могут читать старые RVF-файлы.

Наиболее значительное изменение – добавление <Параметры элемента> в <Заголовок записи>.

Появились два новых типа записей: -7 (фоновая информация) и -8 (информация о версии).

Программа, читающая RVF, считывает номер версии из информации о версии. Если элемент информации о версии отсутствует, она понимает файл как RVF версии 1.0.

Версия RVF 1.3 (используемая ТРВ-Редактором до версии 17.3 в Delphi 2007 и старее):

▪позволяет сохранять пробелы в строках тегов (для Delphi 3+); строки тегов сохраняются в двойных кавычках;

▪В текстовом режиме юникодный текст сохраняется как шестнадцатеричная строка (каждый байт сохраняется как два символа – шестнадцатеричные цифры).

Версия RVF 1.3 (используемая ТРВ-Редактором до версии 17.3 в Delphi 2009 и новее):

▪DocProperties, дополнительные строковые свойства, теги элементов (если rvoTagsArePChars в Options; примечание: начиная с ТРВ-Редактора версии 3.2, теги всегда являются строками), имена стилей (если rvfoUseStyleNames в RVFOptions) сохраняются как UTF-8 (с символами CR и LF, заменёнными на #1 и #2)

Версия RVF 1.3.2 (текущая):

Имена элементов сохраняются как UTF-8.

Более подробная информация об изменениях в RVF

Изменения в ТРВ-Редакторе версии 1.3:

Теперь RVF может содержать текст в формате Юникод (для текстовых элементов). Более старые версии не смогут загружать файлы с текстом в формате Юникод. Номер версии в заголовке RVF не изменился, поскольку в спецификации нет изменений (только дополнения).

Примечание: Юникод используется только для сохранения текстовых элементов в формате Юникод, поэтому файл содержит смесь текста ANSI и Юникод. Такие файлы следует рассматривать как бинарные, не редактируйте их в текстовых редакторах.

Изменения в ТРВ-Редакторе версии 1.4:

Добавлено: таблицы (rvsTable). Это не изменение в RVF, а дополнение.

Таблицы сохраняются в двоичном или шестнадцатеричном текстовом формате, аналогично рисункам или компонентам.

Изменения в ТРВ-Редакторе версии 1.5:

Теперь RVF может содержать стили текста и абзацев (rvsDocProperty). Это не изменение RVF, а дополнение.

Стили сохраняются в двоичном или шестнадцатеричном текстовом формате, аналогично рисункам или компонентам.

Изменения в ТРВ-Редакторе версии 1.7:

Теперь RVF может содержать информацию о разметке и коллекцию стилей списков (rvsDocProperty). Это не изменение в RVF, а дополнение.

Изменения в ТРВ-Редакторе версии 1.8

Номер версии RVF изменён на 1.3

Изменения в ТРВ-Редакторе версии 11

Номер версии RVF изменён на 1.3.1 для Delphi 2009 и новее. Значения дополнительных свойств элемента сохраняются как <спец. строка>, что позволяет им содержать символы переноса строки.

Изменения в ТРВ-Редакторе версии 13

Сохранение единиц измерения. Возможность указания размеров в твирах.

Изменения в ТРВ-Редакторе версии 17.2

Номер версии RVF изменён на 1.3.2. Имена элементов документа сохраняются как <спец. строка 2>, то есть UTF-8.

Изменения в ТРВ-Редакторе версии 23.3

Запись rvsBack устарела. Теперь используется rvsBackEx.