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:
▪in TDBRichView, TDBRichViewEdit to save their contents to binary fields;
▪RVF can be copied to the Clipboard; editor can paste RVF;
▪data can be dragged&dropped as RVF;
▪you can load/save RVF with the methods: LoadRVFFromStream, InsertRVFFromStream, AppendRVFFromStream, LoadRVF, SaveRVFToStream, SaveRVF.
All TRichVew document features can be saved in RVF. Collections of text, paragraph, list styles,style templates, margins and background can be saved optionally (see below).
The main things you need to know about RVF
▪main settings affecting RVF saving and loading can be changed in the TRichView component editor;
▪in order to load bullets, hotspots and list levels with imagelist from RVF you need to process OnRVFImageListNeeded event;
▪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 controls in RVF you need to register their classes with RegisterClasses procedure (for example: RegisterClasses([TButton]));
▪the same for pictures; however, if picture class is not registered, TRichView will try to find the proper graphic class basing on content;
▪formatting of text and paragraph (i.e. styles) is saved in RVF documents optionally, if rvfoSaveTextStyles and rvfoSaveParaStyles are included in RVFOptions;
▪style templates are saved in RVF, if rvfoSaveTextStyles and rvfoSaveParaStyles are included in RVFOptions, and UseStyleTemplates=True.
RVF and Image Lists
TRichView 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.
procedure TMyForm.MyRichViewRVFControlNeeded( const Tag: TRVTag; var ctrl: TControl); begin case StrToInt(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; |
As you can see, TRichView passes two parameters that can help you to identify your control:
▪Tag: TRVTag – TRichView item tag (do not confuse with tag properties of TComponent descendants);
▪Name: TRVUnicodeString – string that can be associated with any control or picture in RichView.
 | Example [VCL and LCL] |
// this example assumes that images may be only bitmaps procedure MyRichViewRVFPictureNeeded(Sender: TCustomRichView; const ItemName: TRVUnicodeString; Item: TRVNonTextItemInfo; Index1, Index2: Integer; var gr: TRVGraphic); begin gr := TBitmap.Create; if (Index1>=0) and (Index2>=0) then gr.LoadFromFile((Item as TRVTableItemInfo).Cells[Index1, Index2].BackgroundImageFileName) else if Item is TRVTableItemInfo then gr.LoadFromFile(TRVTableItemInfo(Item).BackgroundImageFileName) else if Item is TRVGraphicItemInfo then gr.LoadFromFile(TRVGraphicItemInfo(Item).ImageFileName); end; |
Pictures may be stored directly in RVF. RVF contains names of graphic classes used for these images. If you want to use the same graphic classes for loaded pictures, you need to register these classes using RegisterClasses procedure. TRichView itself registers TBitmap, TMetafile, TIcon, TJPEGImage, TWicImage (for Delphi 2010+), TPngImage (for Delphi 2009+). If you include RVGifAnimate2007 unit in your project, TGifImage will be registered as well (for Delphi 2007+). All other graphic classes must be registered explicitly. If the graphic class specified in RVF is not available when reading, TRichView will try to detect an appropriate class by the graphic content.
If you include rvfoIgnoreGraphicClasses in RichView.RVFOptions, TRichView ignores names of graphic classes stored in RVF and always tries to find a proper graphic class by graphic content.
Options for Saving and Loading. Warnings
RichView.RVFOptions define options for RVF saving and loading.
After loading you can check RichView.RVFWarnings property. Depending on RichView.RVFOptions some flags in RichView.RVFWarnings can be errors or warning:
Units of measurement
RVF file may be written with different units of measurement (pixels, twips, or EMU) than specified in Style.Units of TRichView which loads this file.
When inserting RVF, lengths from RVF are converted to Style.Units.
When loading RVF, the control works according to rvfoCanChangeUnits option. If it is excluded from RVFOptions, lengths from RVF are converted to Style.Units. If it is included, and RVF contains either text or paragraph styles, existing styles are converted to units read from RVF (using Style.ConvertToDifferentUnits method), so lengths from RVF are read without conversion.
If a conversion of units is performed while reading RVF, rvfwConvUnits is included in RVFWarnings.
See also...
RichView properties:
▪Options,
RichView events:
▪OnControlAction (ControlAction=rvcaAfterRVFLoad),
▪OnItemAction (ItemAction=rviaInserting and rviaInserted);
RichView methods:
▪LoadRVFFromStream, InsertRVFFromStream, AppendRVFFromStream, LoadRVF,
RichViewEdit methods:
▪InsertRVFFromStreamEd, InsertRVFFromFileEd,
▪Paste, PasteRVF, CanPasteRVF, CutDef.