Building TRichView Document
You can build document by:
3.reformatting and redrawing RichView.
Therefore, a general structure of document generation procedure is:
Note: all methods introduced in RichView (except for the formatting methods) do not reformat document, do not redraw RichView and do not call OnChange event (RichView does not have OnChange event, it is introduced in TRichViewEdit) ( viewer-style methods)
A group of methods for adding items is the largest group of methods (and contains a large number of methods for backward compatibility).
Important: Do not pass string with cr, lf or cr+lf, tab and page break characters in the functions below, except for AddText*** methods!
Some text items can be hypertext. Hypertext items are added by the same methods as regular text items.
These methods add text specified in a String parameter. This parameter is Unicode for Delphi/C++Builder 2009, and ANSI for the older versions of Delphi/C++Builder. Since TRichView stores text as Unicode, when using ANSI parameter, the methods perform conversion to Unicode.
▪AddNL(S, StyleNo, ParaNo, Tag) – adds one item with text S; StyleNo is an index in the collection of text styles (TRichView.Style.TextStyles); ParaNo is an index in the collection of paragraph styles (RichView.Style.ParaStyles) (if this item will start a new paragraph) or -1 (if this item will continue the paragraph). Optionally, you can specify Tag.
▪Add(S, StyleNo) – equivalent to AddNL(S, StyleNo, -1).
▪AddTextNL(s, StyleNo, FirstParaNo, OtherParaNo, Tag) – adds one or more text items; the first item is added with FirstParaNo paragraph style, and other items are added as new paragraphs with OtherParaNo paragraph style; items are separated by cr, lf or cr+lf characters in s; s can contain page break and tab characters. Optionally, you can specify Tag.
▪AddFmt(FormatStr, Args, StyleNo, ParaNo) adds Format(FormatStr, Args) string, where Format is a function from SysUtils unit.
You can add picture of any Delphi format – TBitmap, TIcon, TMetafile, TJpegImage or third party graphic format.
You should create a picture and TRichView will destroy it itself when necessary (for example, when you call RichView.Clear).
▪Name: TRVUnicodeString – name of picture; this string is not used by TRichView itself; this string should not contain cr and lf characters;
▪gr: TRVGraphic - picture;
▪ParaNo:Integer is an index in the collection of paragraph styles (TRichView.Style.ParaStyles) (if this picture will start the paragraph) or -1 (if this picture will continue paragraph);
▪VAlign: TRVVAlign – vertical alignment of a picture;
▪optionally, you can specify Tag.
You can add any Delphi control in TRichView, and it will work as usual. You should create the control and TRichView will destroy it itself when necessary (for example, when you call RichView.Clear).
AddControl(Name, ctrl,ParaNo, VAlign, Tag) adds a control, just like AddPicture adds a picture.
VCL and LCL: TRichView uses Tag properties of inserted components for internal needs (do not confuse with TRichView items tags).
▪Name: TRVUnicodeString – name of the bullet; this string is not used by TRichView itself; this string should not contain cr and lf characters;
▪ImageIndex: Integer – index of the picture in image list;
▪ImageList: TCustomImageList – image list; this will be just a reference to imagelist; TRichView does not hold copy of image list, and does not free it;
▪ParaNo:Integer is an index in the collection of paragraph styles (TRichView.Style.ParaStyles) (if this bullet will start a paragraph) or -1 (if this bullet will continue paragraph)).
▪VAlign: TRVVAlign – vertical alignment of a bullet;
▪optionally, you can specify Tag.
Hotspots are just like bullets, but can have two images ("normal" and "hot") and can be used as hypertext link.
AddHotspot(Name, ImageIndex, HotImageIndex, ImageList, ParaNo, VAlign, Tag) is similar to AddBullet. It has one additional parameter (HotImageIndex) defining the image index used when this item is below the mouse pointer.
List markers can be added using SetListMarkerInfo method. Unlike the methods above, this method can insert list markers not only to the end of document, but set them for existing paragraphs.
Tables, labels, numbered sequences, endnotes, footnotes, references to parent footnotes and endnotes, page numbers, page counts, equations, custom item types do not have special methods for adding them to documents. All of them are added by AddItem method.
Page break is an item property ("this item starts a new page" flag). Only items that start a new paragraph can start a new page.
var ItemNo: Integer;
MyRichView.AddNL('First page', 0, 0);
ItemNo := MyRichView.ItemCount;
MyRichView.AddNL('Second page', 0, 0);
MyRichView.PageBreaksBeforeItems[ItemNo] := True;
You can append RVF data by the methods:
▪function InsertRVFFromStream(Stream: TStream; Index: Integer):Boolean;
This method can insert RVF. The first item of RVF will have the specified Index. For example, if you want to append items from RVF, write:
InsertRVFFromStream is the only method of RichView (not RichViewEdit) for inserting items.
▪function AppendRVFFromStream(Stream: TStream; ParaNo: Integer):Boolean;
This method is similar to InsertRVFFromStream (if it used for appending RVF), but it ignores paragraph style of the first item in RVF and uses ParaNo instead of it. ParaNo is an index in the collection of paragraph styles (RichView.Style.ParaStyles) (if item will start a paragraph) or -1 (if the item will continue paragraph).
▪procedure AppendFrom(Source: TCustomRichView);
This is the most efficient method to copy contents of one RichView to another one. But items of some types (including Inserted controls and tables) are not copied with this method (just ignored).
Methods for loading (Load***) belong to this group of methods as well.
There is an important change in version 1.2: you can add items from new line without starting a new paragraph. There are no new methods for generating documents (it is added in v1.3: AddTextNLW), but there is a method that affects their behavior: TRichView.SetAddParagraphMode.