|
What is RVF?
RVF (RichView Format) is a file format specially designed for saving/loading TRichView documents. It is quite simple and compact format. It can be text file or binary file (defined by RichView.RVFOptions).
This format is used:
| ▪ | RVF can be copied to the Clipboard; editor can paste RVF; |
All RichVew document features can be saved in RVF (including text, images, bullets, hotspots, controls, checkpoints, tables). Collections of text, paragraph, list styles, margins and background can be saved optionally (see below).
The main things you need to know about RVF
| ▪ | you can save pictures and controls in binary mode or text mode (binary mode is much more efficient and compact); |
| ▪ | you can save pictures and controls in RVF, or create them on request when loading; |
| ▪ | if you load pictures and controls in RVF you need to register them with RegisterClasses procedure (you do not need to register TBitmap, TMetafile, TIcon and TJpegImage) |
| ▪ | formatting of text and paragraph (i.e. styles) is saved in RVF documents optionally, if rvfoSaveTextStyles and rvfoSaveParaStyles are included in RVFOptions. |
RVF and Image Lists
RichView can save and load all document content itself, but there is an exception: bullets, hotspots and list markers having imagelist picture in list levels.
When loading, RichView needs to know which ImageList to use for the given bullet or hotspot. It asks the application about it by calling OnRVFImageListNeeded event. You need to process this event if you want to load bullets and hotspots.
When saving, RichView stores Tag properties of ImageList with bullet or hotspot. When reading, RichView calls OnRVFImageListNeeded event and pass this value to it.
Example
If you have two ImageLists (ImageList1 and ImageList2) that you use for bullets in MyRichView, you can:
| ▪ | set ImageList1.Tag to 1, set ImageList2.Tag to 2, |
| ▪ | process MyRichView.OnImageListNeeded event:: |
procedure TMyForm.MyRichViewRVFImageListNeeded(
Sender: TCustomRichView; ImageListTag: Integer;
var il: TCustomImageList);
begin
case ImageListTag of
1:
il := ImageList1;
2:
il := ImageList2;
end;
end;
DO NOT CONFUSE IMAGELIST.TAG WITH RICHVIEW ITEMS' TAGS. IN THIS CASE RICHVIEW USES TIMAGELIST.TAG PROPERTY.
RichView does not own any ImageList, it never destroys them. It just holds references to them.
If you want to load pictures and/or controls from RVF you need to register them with RegisterClasses procedure (you need not to register TBitmap, TMetafile, TIcon and TJpegImage - they are already registered by RichView)
RVF and Pictures & Controls
You can save full information about pictures and inserted controls in RVF, but you can also use advanced feature: you can save pictures/controls yourself and include in RVF only some "identifiers" that can be used to create pictures/controls when needed (on loading). Two values can be uses as these "identifiers": RichView items tags and names.
These options do not affect loading from RVF. RichView autodetects these modes (binary/text, indices/names of styles).
When loading, you can use OnRVFPictureNeeded and OnRVFPictureNeeded events.
Example:
procedure TMyForm.MyRichViewRVFControlNeeded(
Sender: TCustomRichView; Name: String; Tag: Integer;
var ctrl: TControl);
begin
case Tag of
1:
begin
ctrl := TButton.Create(nil);
TButton(ctrl).Caption := Name;
end;
2:
begin
ctrl := TEdit.Create(nil);
TEdit(ctrl).Text := Name;
end;
end;
end;
procedure MyRichViewRVFPictureNeeded(Sender: TCustomRichView;
Name: String; Tag: Integer; var gr: TGraphic);
begin
gr := TBitmap.Create(nil);
TBitmap(gr).LoadFromFile(Name);
end;
As you can see, RichView passes two parameters that can help you to identify your image or control:
| ▪ | Tag: Integer – RichView item tag (do not confuse with tag properties of TComponent descendants); |
| ▪ | Name: String – string that can be associated with any control or picture in RichView. |
Options for Saving
When saving RVF, the following options in RichView.RVFOptions affect the result:
Option
|
Meaning
|
rvfoSavePicturesBody
|
| ▪ | If set, full information about all pictures in RichView are saved in RVF. |
|
rvfoSaveControlsBody
|
| ▪ | If set, full information about all controls in RichView are saved in RVF. |
|
rvfoSaveBinary
|
| ▪ | If set, all non-text data are saved in RVF as they are (pictures, controls, tables, background, styles, Unicode text). |
| ▪ | If not set, all binary data are converted to text (hexadecimal string); RVF becomes a plain text format, like RTF, but file size is increased. |
|
rvfoSaveBack
|
(since version 1.2)
If set, background (color and image) is saved in RVF.
This flag affects only saving the whole document; selection is never saved (or copied to the Clipboard) with background.
(see rvfoLoadBack below)
|
rvfoUseStyleNames
(almost obsolete)
|
If set, TRichView saves quoted names of text and paragraph styles instead of their indices (requires Delphi3+)
Pluses:
| ▪ | content of file remains synchronized with collections of styles even if you delete or insert new styles; |
Minuses:
| ▪ | names of styles must be unique; |
| ▪ | files become sensitive to changing style names. |
It's not recommended to use this options together with rvfoSaveTextStyles and rvfoSaveParaStyles.
|
rvfoSaveTextStyles
|
If set, collection of text styles associated with this RichView (TextStyles property of the linked TRVStyle component) is saved in RVF.
See RVFTextStylesReadMode property.
|
rvfoSaveParaStyles
|
If set, collections of paragraph and list styles associated with this RichView (ParaStyles and ListStyles properties of the linked TRVStyle component) are saved in RVF.
See RVFParaStylesReadMode property.
|
rvfoSaveLayout
|
If set, the following properties are stored in RVF:
Left-, Right-, Top-, BottomMargin, MinTextWidth, MaxTextWidth, BiDiMode.
Layout is saved only when saving the whole document (not selection).
(see rvfoLoadLayout below)
|
rvfoSaveDocProperties
|
If set, DocProperties and DocParameters are saved in RVF.
(see rvfoLoadDocProperties below)
|
Options for Loading
When loading RVF, the following options in RichView.RVFOptions affect the result:
Option
|
Meaning
|
rvfoLoadBack
|
If not set, RichView ignores background information, saved in RVF.
(see rvfoSaveBack above)
|
rvfoIgnoreUnknownPicFmt
|
| ▪ | If set, RichView skips pictures of unknown (unregistered) classes. |
| ▪ | if not set, RVF reading methods return False (failure value) if pictures of unknown classes exist in RVF |
|
rvfoIgnoreUnknownCtrls
|
The same as rvfoIgnoreUnknownPicFmt, but for Controls
|
rvfoConvLargeImageIdxToZero
|
| ▪ | If set, too large (>=Imagelist.Count) image indices for bullets and hotspots are converted to 0. |
| ▪ | if not set, RVF reading methods return False (failure value) in such case. |
|
rvfoConvUnknownStylesToZero
|
| ▪ | If set, RichView converts too large (>= RichView.Style.TextStyles.Count, or RichView.Style.ParaStyles.Count) style indices to 0. |
| ▪ | If not set, RVF reading methods return False (failure value) in such case. |
|
rvfoLoadLayout
|
If not set, RichView ignores layout information saved in RVF
(see rvfoSaveLayout above)
|
rvfoLoadDocProperties
|
If set, DocProperties and DocParameters are loaded from RVF (but not by methods for RVF insertion)
(see rvfoSaveDocProperties above)
|
After loading you can check RichView.RVFWarnings property. Depending on RichView.RVFOptions some flags in RichView.RVFWarnings can be errors or warning:
Warning
|
Meaning
|
rvfwUnknownPicFmt
|
Pictures of unknown classes exist in RVF.
See rvfoIgnoreUnknownPicFmt.
|
rvfwUnknownCtrls
|
Controls of unknown classes exist in RVF.
See rvfoIgnoreUnknownCtrls.
|
rvfwConvLargeImageIdx
|
Bullets or hotspots with too large image indices exist in RVF. See rvfoConvLargeImageIdxToZero.
|
rvfwConvUnknownStyles
|
Text, paragraph or list styles with too large indices exist in RVF. See rvfoConvUnknownStylesToZero.
|
rvfwConvToUnicode
rvfwConvFromUnicode
|
There was a conversion from ANSI text in RVF file to Unicode in RichView or vice versa. This is a result of loading RVF file with set of styles different from the set which was used when saving. Conversion is performed automatically, without generating errors.
For example, in applications compiled in Delphi/C++Builder 2009+, this conversion (from ANSI to Unicode) always occurs when loading RVF files (with non-Unicode text styles) saved by applications compiled in older version of Delphi/C++Builder
|
rvfwInvalidPicture
|
Some pictures were replaced with InvalidPicture.
|
See also...
RVF Specification
RichView properties:
RichView events:
RichView methods:
RichViewEdit methods:
|
