RVF Specification

Top Previous Next

This topic contains thorough information about RichView file Format.

For the most of applications you need not to know about internals of RVF, all necessary information is in RVF Overview.

Changes in RVF Format

RVF Version 1.2

Older programs are not able to read new RVF files, but programs compiled with new versions of RichView can read old RVF files.

The most significant change is adding <Item Options> in <RVF Item>.

There are two new record types: -7 (background) and -8 (version information)

RVF reader reads version number from version information. If there is no version information item, reader understand the file as RVF version 1.0

RVF version 1.3 (current version):

▪	allows saving space characters in tag strings (for Delphi 3+); tags strings are saved in double quotes;

▪	in text mode, Unicode text is saved as a hexadecimal string (each byte is saved as two characters – hexadecimal digits)

More Detailed Information about Changes in RVF

Changes in RichView version 1.3:

RVF now can contain Unicode text (for text items). Older versions will be unable to load files with Unicode. Version number in RVF header was not changed, because there are no changes in the specification (additions only).

Note: Unicode is used only for saving Unicode text items, so file contains a mix of ANSI and Unicode text. Such files must be considered as binary, do not edit them in text editors.

Changes in RichView version 1.4:

Added: tables (rvsTable). This is not a change in RVF, but an addition.

Tables are saved in binary or hexadecimal text form, similar to pictures or controls.

Changes in RichView version 1.5:

RVF now can contain text and paragraph styles (rvsDocProperty). This is not a change in RVF, but addition.

Styles are saved in binary or hexadecimal text form, similar to pictures or controls.

Changes in RichView version 1.7:

RVF now can contain layout information and collection of list styles (rvsDocProperty). This is not a change in RVF, but addition.

Changes in RichView version 1.8

RVF version number is changed to 1.3

Syntax

{x} – zero or more repetitions of item x;

{x}+ – one or more repetitions of item x;

[x] – item x is optional;

xy – item x is followed by item y;

x | y – item x or item y;

'c' – a literal;

<n> – a nonterminal.

Data Types in RVF

<int> – an integer number, ['-']{<digit>}+;

<digit> ::= '0' | … | '9';

Integer number is either finished by ' ' (space character) or it is followed by the end of line; for the simplification, this space character will be omitted (i.e. it will be included in <int>).

<crlf> – end of line characters; usually it is a CR+LF, CR or LF characters; before binary data or Unicode it is required to use both CR and LF characters (#13#10).

<string> – string of characters (without CR, LF and #0 characters)

<quoted string> – string enclosed in double quotes; double quotes inside the string are doubled.

<Unicode string> – string of Unicode characters. Last character in string must be a paragraph separator (code $2029).

RVF Structure

<RVF> ::= [<Version Info>]{<RVF Record>}

Version Info

<Version Record Type> ::= '-8'

Currently, <Version> = 1, <SubVersion> = 3. If there is no <Version Info> in RVF, reader implies version 1.0 (no <Item Options> in <RVF Item>)

RVF Record Structure

RVF file consists of records. The most of records represent items (one record = one item), but there are some special record types.

<RVF Record> ::= <Record Header><crlf>({<string><crlf>}|{<Unicode sting>})[<Binary Data>]

<Query> ::= '0' | '1' | '2' | '3'

<Record Type>	Constant	Meaning
>=0	—	text; <Item Type> is an index in the collection of styles (RVStyle.TextStyles)
-1,-3..-6, -10..-12, -60	rvs*** constants	non-text item
-2	rvsCheckpoint	invisible label ("checkpoint")
-7	rvsBack	background (image, color)
-8	rvsVersionInfo	RVF version (only in <Version Info>)
-9	rvsDocProperty	text, paragraph, list styles,layout information, DocProperties

<Strings Count> is a number of lines between this <Record Header> and the next <Record Header> (or the end of file). If RVF reader does not understand this record type it should skip this number of lines. <Binary Data> (if present) is counted as one of strings after the header..

<Paragraph> is an index in the collection of paragraph styles (RVStyle.ParaStyles) (if this item starts a paragraph) or -1 (if the record represents item, and this item continues paragraph).

<Item Options> is a set of bits, converted to integer.

Bit Number	Meaning
0	Set if the item continues paragraph (<Paragraph>=-1); it's a redundant data;
1	Page break. Set if this item must start a new page (<Paragraph><>-1)
2	Set if the item should be displayed from the new line, but it does not start a new paragraph (in this case <Paragraph><>-1, but should be equal to the paragraph style of the previous non "-1" item)
3	Set if it is a text item containing Unicode.

<Tag>

If rvoTagsArePChars is in RichView.Options then<Tag> is a string associated with this item. RichView saves this string in double quotes. If the tag is equal to 0 (i.e. nil) then '0' will be saved.

if rvoTagsArePChars is not in RichView.Options then <Tag> is an integer value associated with this item. If RVF reader cannot convert <Tag> to integer it returns False (reading failed). So it's impossible to read RVF file saved with string tags in RichView with integer tags (except for the case when all tags are empty (0 or nil)).

See also tags.

<Query> can be 0, 1, 2, or 3.

<Query>	Meaning
0	Component or image is saved in text format (rvfoSaveBinary is excluded from RichView.RVFOptions)
1	The item is requested from program on loading, see below.
2	Component or image is saved in binary format (rvfoSaveBinary is in RichView.RVFOptions).
3	Special value for saving Unicode text as hexadecimal string

If <Query>=1, then the next line after the header is a name of item (picture or control).

Data is requested in events: OnRVFPictureNeeded, OnRVFControlNeeded.

The saving mode (to save full information about images or controls / to save only name and request it when reading) is determined by RichView.RVFOptions (for the request mode, rvfoSavePicturesBody and/or rvfoSaveControlsBody options should be cleared). You need to create control or image in this event and assign it to gr or ctrl parameters. For example:

procedure TMyForm.MyRichViewRVFControlNeeded(

Sender: TCustomRichView; Name: String;

Tag: Integer; var ctrl: TControl);

begin

ctrl := TButton.Create(nil);

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

TButton(ctrl).OnClick := MyClickProcedure;

end;

<Rest of Header> varies for different item types. Some new parameters can be added in future to <Rest of Header>. RVF reader should ignore all parameters in header after last parameter it can understand.

If <Query> is equal to 1 then <Rest of Header> is empty.

The next section is for <Query>=0 | 2 | 3.

RVF Records

Checkpoints

<Record Type> = rvsCheckpoint

<Paragraph> is ignored.

<String Count> = 1

<Raise Event> ::= '0' | '1'

If Raise Event is equal to '1' then OnCheckPointVisible event occurs when the checkpoint appears in visible area of RichView

Strings after the header:

▪	<Checkpoint name>

"Checkpoint" is not an item, but it's convenient to save it like an item. "Checkpoints" are saved before the associated items.

Text (Items)

<Record Type> >= 0

<Rest of Header> is empty

<Strings Count> is a number of paragraphs in this item. All paragraphs will be of the given text and paragraph style. If <Paragraph>=-1 then this item continues the paragraph of the previous item.

Strings after the header are text lines (paragraphs). Stings can be in Unicode encoding (determined by <Item Options>). If <Query=0, Unicode is saved as UTF-16 (WideString). If <Query=3, Unicode is saved as hexadecimal string

Break (Item)

<Record Type> = rvsBreak

<Paragraph> is ignored

<Break Color> is a color of horizontal line; if Break Color=clNone then line will be of color of the 0th text style.

<Break Style> is TRVBreakStyle value converted to integer.

<Break Width> is a width of line.

<String Count> >= 0.

Picture (Item)

<Record Type> = rvsPicture

<String Count> >= 3

<Vertical Align> is a vertical alignment of picture (TRVVAlign value converted to integer)

Strings after the header:

▪	<Picture Name>

▪	<Picture Delphi Type>

▪	<Picture Data>

<Picture Delphi Type> is a name of picture class (such as 'TBitmap', 'TIcon', 'TMetafile', 'TJpegImage').

<Picture Data> can be in text or binary format.

In text format, each byte is represented as two hexadecimal digits, so all data is encoded in one string.

In binary format, <crlf> after <Picture Delphi Type> must be CR+LF (both characters). Binary data consists of <Data Size> and <Data>. Data Size is a binary 4-byte number, the number of bytes in <Data>.

Note 1: In order to load picture of the given class from RVF, its class must be registered with RegisterClasses procedure. You need not to register TBitmap, TIcon, TMetafile, because they are registered by RichView. For Delphi 3+ RichView also registers TJpegImage (if the conditional define RVDONOTUSEJPEGIMAGE is not defined) In order to use third party graphics formats (descendants of TGraphic) in RVF you need to register them yourself with RegisterClasses procedure.

Note 2: Behavior of RichView when loading unregistered graphics format is defined in RVFOptions property. If rvfoIgnoreUnknownPicFmt option is defined then this picture will be just skipped. If this option is not defined then the function returns False (reading failed). In both cases RVFWarnings property will contain rvfwUnknownPicFmt.

Control (Item)

<Record Type> = rvsComponent

See the previous section, adjusted for: rvfoIgnoreUnknownCtrls, rvfwUnknownCtrls.

Bullet (Item)

<Record Type> = rvsBullet

<String Count> >= 1

<ImageList#> ::= <int>

Strings after the header:

▪	<Bullet Name>

<ImageList#> is the Tag property of the corresponding ImageList (do not confuse it with RichView item tags! It is TImageList.Tag property). On reading, OnRVFImageListNeeded occurs. You need to assign your imagelist to il parameter. Otherwise, the bullet will be skipped. The behavior of RichView when loading too large image index is defined in RVFOptions property. If rvfoConvLargeImageIdxToZero option is defined then index is set to 0. Otherwise the function returns False (reading failed). In both cases RVFWarnings property will contain rvfwConvLargeImageIdx.

Hotspot (Item)

<Record Type> = rvsHotspot

<String Count> = 1

<ImageList#> ::= <int>

Strings after the header:

▪	<Hotspot Name>

See the previous section for details.

Collections of styles, layout, DocProperties

<Record Type> = rvsDocProperty

<Paragraph> is ignored

<Query> can be 0 (data will be saved as a hexadecimal text) or 2 (in a binary form)

<Rest of Header> ::= '1' | '2' | '3' | '4' | '5' | '6'

<Rest of Header>	Meaning
1	Collection of text styles
2	Collection of paragraph styles
3	Layout
4	Collection of list styles
5	DocProperties
6	Special information, written by TRVReportHelper when saving page
7	DocParameters

<String Count> = 2 for 1..4 and 6. The first line contains name of TRVStyle object for 1,2,4, or empty for 3,6. Hexadecimal text or binary data follow next.

When saving DocProperties, <String Count>=DocProperties.Count. In each item of DocProperties, #13 are changed to #1, #10 to #2. On reading, they are changed back.

DocParameters are saved as lines like property=value (only for properties with non-default values).

Background

<Record Type> = rvsBackground

This item is similar to rvsPicture, but has differences:

▪	<Rest of Header> is a background color and style

▪	there is no <Picture Name> line;

▪	<Picture Delphi Type> is always TBitmap

▪	<Query>=1 is not supported

<String Count> = 2 | 0

<Paragraph> and <Tag> are ignored (0).

<Background Style>::= <int> (TRVBackgroundStyle value converted to integer)

<Color>::=<int> (background color)

If background style is bsNoBitmap (or background bitmap is empty), there are no strings after header (and <Query>=0).

Strings after the header:

▪	<Picture Delphi Type>

▪	<Picture Data>

Extra Item Properties

Some items may contain extra integer and string properties. They are saved as lines after the header (one line per property) in the form:

name=value

If the property has the default value, it is not saved. The list of names can be found in RVItem.pas, arrays RVFExtraItemIntPropNames and RVFExtraItemStrPropNames.

This specifications does not cover a case of saving style names instead of style indices (this feature is deprecated)