rvico TRichView Reference | Overview

Building RichView Document

 Top  Previous  Next

Creating a New Document

You can build document by:

1.clearing TRichView,
2.appending items
3.reformatting and redrawing RichView.

Therefore, a general structure of document generation procedure is:

MyRichView.Clear;
<Methods for adding contents>
MyRichView.Format;

 

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 a largest group of methods (and contains a large number of methods for backward compatibility).

Appending Text Items

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.

Methods without Unicode support:

If your application uses Unicode, do not use the methods below (for Unicode text styles), use the methods from the next section.

▪AddNL(S, StyleNo, ParaNo) – adds one item with text S; StyleNo is an index in the collection of text styles (RichView.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).
▪Add(S, StyleNo) – equivalent to AddNL(S, StyleNo, -1).
▪AddFmt(FormatStr, Args, StyleNo, ParaNo) – equivalent to AddNL(Format(FormatStr, Args), StyleNo, ParaNo), where Format is function from SysUtils unit.
▪"Tagged" analogs: AddNLTag, AddTag (see Tags)
▪AddTextNL(s, StyleNo, FirstParaNo, OtherParaNo), AddTextNLA – adds one or more text items; 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.
▪AddTextBlockNL(s, StyleNo, ParaNo) – the same, but adds all text as one paragraph (line breaks inside the paragraph are used instead)

Methods with special Unicode processing

▪AddNLATag, AddNLWTag, AddTextNLA, AddTextNLW

Obsolete methods

▪AddFromNewLine, AddCenterLine, AddText, AddTextFromNewLine.

Notes for former users of freeware version:

In older versions of RichView you was not able to add empty strings, which are useful as empty paragraphs. Now there is no such limitation.

In older versions, there was no special processing of tab characters: they were displayed as special characters. Now Add*** methods replace tab characters with spaces or insert them as tabulators (RichView.Style.SpacesInTab space characters per one tab; changing SpacesInTab will not change already created document).

Appending Images

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

▪AddPictureEx(Name, gr, ParaNo, VAlign)
(Name: String – name of picture; this string is not used by RichView itself; this string should not contain cr and lf characters; gr: TGraphic - picture; ParaNo:Integer is an index in the collection of paragraph styles (RichView.Style.ParaStyles) (if this picture will start the paragraph) or -1 (if this picture will continue paragraph); VAlign: TRVVAlign – vertical alignment of picture).
▪"Tagged" analogs: AddPictureExTag (See Tags).
▪Obsolete method: AddPicture.

Appending Hot Images

▪AddHotPicture, AddHotPictureTag

Appending Delphi Controls

You can add any Delphi control in RichView, and it will work as usual. You should create control and RichView will destroy it itself when necessary (for example, when you call RichView.Clear). The methods for adding controls assign the control.Parent to RichView.

▪AddControlEx(Name, ctrl,ParaNo, VAlign), AddControlExTag(Name, ctrl,ParaNo, VAlign, Tag)- similar to methods for pictures.
▪Obsolete method: AddControl.

This version of TRichView, like old ones, uses Tag properties of inserted components for internal needs (do not confuse with RichView items tags).

Appending Bullets – Images from ImageLists

▪AddBulletEx (Name, ImageIndex, ImageList, ParaNo)
(Name: String – name of the bullet; this string is not used by RichView itself; this string should not contain cr and lf characters; ImageIndex: Integer – index of the picture in imagelist; ImageList: TCustomImageList – imagelist; this will be just a reference to imagelist; RichView does not hold copy of imagelist, and does not free it; ParaNo:Integer is an index in the collection of paragraph styles (RichView.Style.ParaStyles) (if this bullet will start a paragraph) or -1 (if this bullet will continue paragraph)).
▪"Tagged" analog: AddBulletExTag (See Tags).
▪Obsolete method: AddBullet.

Appending Hotspots – Hypertext Images from ImageLists

Hotspots are just like bullets, but can have two images ("normal" and "hot") and can be used as hypertext link.

▪AddHotspotEx(Name, ImageIndex, HotImageIndex, ImageList, ParaNo) – similar to AddBulletEx
▪"Tagged" analog: AddHotspotExTag (See Tags).
▪Obsolete method: AddHotspot.

Appending Breaks – Horizontal Lines

▪AddBreak, AddBreakEx, AddBreakExTag, AddBreakTag.

Adding Paragraphs' Bullets and Numbering (list markers)

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.

Appending Checkpoints

Checkpoints are not items of RichView, but methods for adding checkpoints are similar to methods for adding items. The main methods for appending checkpoints are AddNamedCheckpointEx, AddNamedCheckpointExTag. See "checkpoints".

Adding Page Breaks

Page break is an item property ("this item starts a new page"). Only items that start a new paragraph can start a new page.

Example:

var ItemNo: Integer;

 

MyRichView.AddNL('First page', 0, 0);

ItemNo := MyRichView.ItemCount;

MyRichView.AddNL('Second page', 0, 0);

MyRichView.PageBreaksBeforeItems[ItemNo] := True;

Appending and Inserting RVF

You can append RVF data by the methods:

▪function InsertRVFFromStream(Stream: TStream; Index: Integer):Boolean;

This method can insert RVF. First item of RVF will have the specified Index. For example, if you want to append items from RVF, write:

MyRichView.InsertRVFFromStream(MyStream, MyRichView.ItemCount);

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 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 item will continue paragraph).

Appending Contents of Another RichView

▪procedure AppendFrom(Source: TCustomRichView);

This is the most efficient method to copy contents of one RichView to another one. Both the source and the target RichViews must have  the same "tag" mode (rvoTagsArePChars in Options) and must be linked to the same RVStyle. Inserted controls and tables are not copied with this method  (just ignored).

Loading

Methods for loading (Load***) belong to this group of methods as well.

Additional Notes

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 (there are added in v1.3: AddTextBlockNL, AddTextNLW), but there is a method that affects their behavior: TRichView.SetAddParagraphMode.

Some custom item types (such as tables) do not have special methods for appending them. They can be appended by general method AddItem.


RichView © Sergey Tkachenko