rvico TRichView Reference | Overview

RichView Format (RVF) Overview

Top  Previous  Next

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 RichVew document features can be saved in RVF (including text, images, bullets, hotspots, controls, checkpoints, tables). 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 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;

style templates are saved in RVF, if rvfoSaveTextStyles and rvfoSaveParaStyles are included in RVFOptions, and UseStyleTemplates=True.

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.

hmtoggle_arrow1Example

As you can see, RichView passes two parameters that can help you to identify your control:

Tag: TRVTag – 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.

hmtoggle_arrow1Example

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 or twips) 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...

RVF Specification

RichView properties:

Options,

RVFOptions,

RVFWarnings;

UseStyleTemplates;

StyleTemplateInsertMode.

RichView events:

OnRVFImageListNeeded,

OnVFControlNeeded,

OnRVFPictureNeeded,

OnControlAction (ControlAction=rvcaAfterRVFLoad),

OnItemAction (ItemAction=rviaInserting and rviaInserted);

OnStyleTemplatesChange.

RichView methods:

LoadRVFFromStream, InsertRVFFromStream, AppendRVFFromStream, LoadRVF,

SaveRVFToStream, SaveRVF,

Copy, CopyDef, CopyRVF.

RichViewEdit methods:

InsertRVFFromStreamEd, InsertRVFFromFileEd,

Paste, PasteRVF, CanPasteRVF, CutDef.


TRichView © trichview.com