"Checkpoints"

RichView Items' Checkpoints Overview

Top Previous Next

Checkpoints are...

Each item can have associated checkpoint – an invisible label that you can use for jumping to the specified part of document. Other word-processing tools call similar objects as "bookmarks" or "anchors".

Checkpoint has:

▪	name (any string; RichView does not use it itself);

▪	tag (just like any RichView items tags)

▪	RaiseEvent flag; if RaiseEvent=True then RichView generates OnCheckpointVisible event when this checkpoint appears in the field of view (usually as a result of scrolling); this feature only works for RichView, and does not work for RichViewEdit (in this version).

Limitations: checkpoint names and tags must not contain line breaking characters (#10, #13) and #0. Failing to follow these rules will cause problems in saving documents in RichView Format.

Drawing checkpoints

You can set the option to make checkpoints visible: include rvoShowCheckpoints in RichView.Options. By default, checkpoints are shown as dotted vertical lines with a small circle in the top left corner of the associated item. Displaying checkpoints is useful in editing mode.

Checkpoints colors:

▪	RichView.Style.CheckpointColor for "normal" checkpoints (clGreen by default)

▪	RichView.Style.CheckpointEvColor for checkpoints with RaiseEvent=True (clLime by default)

You can create your own procedure for drawing checkpoints, see TRVStyle.OnDrawCheckpoint.

Using checkpoints

The usual using of checkpoint is obtaining its vertical coordinate (relative to the top of document area) and scrolling document so that the item associated with the checkpoint becomes visible. There are some more interesting applications for checkpoints.

Adding checkpoints in the document

You can add checkpoint at the end of the document using AddNamedCheckpointEx, AddNamedCheckpointExTag, AddNamedCheckpoint, AddCheckpoint, AddCheckpointTag. All these methods have a subset of functionality of the AddNamedCheckpointExTag method.

function TRichView.AddNamedCheckpointExTag(const CpName: String;

RaiseEvent: Boolean; Tag: Integer): Integer;

The parameters of this function were described above. This function (and all these functions) returns the index of the added checkpoint in RichView (the first checkpoint has index=0).

These calls are equivalent:

AddNamedCheckpointEx(Name, RaiseEvent)

and

AddNamedCheckpointExTag(Name, RaiseEvent,0);

AddNamedCheckpoint(Name)

and

AddNamedCheckpointExTag(Name, False, 0);

AddCheckpointTag(Tag)

and

AddNamedCheckpointExTag('', False, Tag);

AddCheckpoint

and

AddNamedCheckpointExTag('', False, 0);

Recommended for using: AddCheckpoint, AddNamedCheckpointEx, AddNamedCheckpointExTag.

As it was told, the above described methods add a new checkpoint to the end of the document. When you add a new item to the end of the document, the last added checkpoint becomes associated with this item. (So, TRichView can contain any number of checkpoints associated with items and one checkpoint at the end of the document).

You can modify the checkpoint by SetCheckpointInfomethod, and remove it by RemoveCheckpoint.

The rest of methods can be separated into two groups:

1.	Methods returning information about some checkpoint. These methods return a value of TCheckpointData class.

2.	Methods extracting checkpoint properties from the TCheckpointData value.

Methods and events of the first group (obtaining TCheckpointData):

TCheckpointData is a pointer. If these methods return nil, it means that there is no such checkpoint, item has no associated checkpoint, etc.

▪	GetFirstCheckpoint, GetNextCheckpoint(CheckpointData), GetLastCheckpoint, GetPrevCheckpoint(CheckpointData) – allow you to obtain a list of all checkpoints in the document (except for checkpoints in table cells, see below);

▪	GetItemCheckpoint(ItemNo) – returns the checkpoint associated with the specified item;

▪	GetCheckpointByNo(No) – returns the checkpoint with the specified index;

▪	FindCheckpointByName(Name) – returns the first checkpoint having the specified Name;

▪	FindCheckpointByTag(Tag) – returns the first checkpoint having the specified Tag; Tag is considered as integer value (integers are compared) or as a pointer to string (strings are compared) depending the RichView.Options;

▪	event OnCheckpointVisible (Sender: TRichView; CheckpointData: TCheckpointData); this event is generated when:

o	RichView.CPEventKind = cpeWhenVisible and some checkpoint (with RaiseEvent=True) becomes visible (example of application: you can mark pictures in TRichView with checkpoints; when this picture becomes visible you can display information about it in a separate window)

RichView.CPEventKind = cpeAsSectionStart; in this mode it's guaranteed that the last event is generated for visible checkpoint or for the nearest checkpoint above the visible area (example of application: you can mark beginnings of chapters of your document with checkpoints, create a table of contents in ListBox (one listbox item = one chapter = one "RaiseEvent" checkpoint); if you select listbox item associated with the last raised checkpoint, the list box will always have name of the chapter in the field of view highlighted)

Methods of the second group (extracting information from TCheckpointData):

▪	GetCheckpointInfo(CheckpointData, Tag, Name, RaiseEvent) – returns Tag, Name and "RaiseEvent" flag of checkpoint;

▪	GetCheckpointXY(CheckpointData, X,Y), GetCheckpointYEx(CheckpointData): Integer – obtaining information about coordinates of checkpoint (Y is the most useful; you can pass this Y to RichView.ScrollTo method);

▪	GetCheckpointItemNo(CheckpointData) : Integer – returns an index of the associated item; it can return -1 for checkpoint in the end of document (no associated item);

▪	GetCheckpointNo(CheckpointData): Integer – returns the index of the checkpoint;

Methods belonging to the both groups:

▪	GetCheckpointY(no): Integer – equivalent to GetCheckpointYEx(GetCheckpointByNo(No));

Methods of editor

The first group of methods contains editing-style analogs of SetCheckpointInfo and RemoveCheckpoint:

▪	SetCheckpointInfoEd – adds checkpoint for the specified item, as an editing operation;

▪	RemoveCheckpointEd – deletes checkpoint for the specified item, as an editing operation.

The second group contains methods working with the item at the position of caret (if the caret is between items, they work with the item to the left):

▪	GetCurrentCheckpoint – returns checkpoint associated with the item at the caret position;

▪	SetCurrentCheckpointInfo – adds/modifies checkpoint for the item at the caret position, as an editing operation;

▪	RemoveCurrentCheckpoint – deletes checkpoint for the item at the caret position, as an editing operation.

The third group contains methods working with the checkpoint at the position of caret:

▪	InsertCheckpoint – inserts checkpoint in the caret position (adds/modifies checkpoint for the item to the right; if the caret was in the middle of text item, the method preliminarily splits this item at the caret position), as an editing operation;

▪	GetCheckpointAtCaret – returns the checkpoint exactly at the caret position;

▪	RemoveCheckpointAtCaret – deletes the checkpoint exactly at the caret position, as an editing operation.

RTF and HTML

In HTML, checkpoints are saved as anchors (<a name> tag). Either checkpoint name or checkpoint index can be used, see rvsoUseCheckpointsNames option for SaveHTML and SaveHTMLEx. Links to checkpoints must start with '#' character.

In RTF, checkpoints are saved as bookmarks (checkpoints names are used). When importing RTF, bookmark start is read as checkpoint (bookmark name is written in checkpoint name). When reading RTF, links to bookmarks are converted to links started from '#'. When writing RTF, links started from '#' are written as links to bookmarks.

Example 1

Enumerating all checkpoints in the document (not including checkpoints in table cells). This method is very fast even for large documents, because all checkpoints are organized in a special list.

var Tag: Integer;

Name: String;

RaiseEvent: Boolean;

CheckpointData: TCheckpointData;

begin

CheckpointData := MyRichView.GetFirstCheckPoint;

while CheckpointData<>nil do begin

MyRichView.GetCheckpointInfo(CheckpointData,Tag,Name,RaiseEvent);

// processing this checkpoint

...

CheckpointData := MyRichView.GetNextCheckpoint(CheckpointData);

end;

Example 2

Enumerating all checkpoints in the document, including checkpoints in table cells

procedure EnumCheckpoints(RVData: TCustomRVData);

var i,r,c: Integer;

table: TRVTableItemInfo;

Tag: Integer;

Name: String;

RaiseEvent: Boolean;

CheckpointData: TCheckpointData;

begin

for i := 0 to RVData.ItemsCount-1 do begin

CheckpointData := RVData.GetItemCheckpoint(i);

if CheckpointData<>nil then begin

RVData.GetCheckpointInfo(CheckpointData,Tag,Name,RaiseEvent);

// processing this checkpoint

...

end;

if RVData.GetItemStyle(i)=rvsTable then begin

table := TRVTableItemInfo(RVData.GetItem(i));

for r := 0 to table.RowCount-1 do

for c := 0 to table.ColCount-1 do

if table.Cells[r,c]<>nil then

EnumCheckpoints(table.Cells[r,c].GetRVData);

end;

Call:

EnumCheckpoints(MyRichView.RVData);

In the second example, RVData.GetCheckpointXY returns checkpoint coordinates relative to the top left corner of this RVData (it may be left top corner of the cell). In order to get absolute coordinates of this checkpoint in the document (for MyRichView.ScrollTo), obtain the coordinates of top left corner of this RVData (TCustomRVFormattedData(RVData).GetOriginEx(X,Y)), relative coordinates of checkpoint (TCustomRVFormattedData(RVData).GetCheckpointXY(X,Y)), and sum them up

Compatibility Issues

Incompatibility with old (freeware) versions of RichView: in older versions checkpoints were items. Now it's not true – they are an additional information associated with items (text, pictures or controls). Therefore, you now can't add two or more checkpoints one by one without an item "between" them. You can choose one of two options when compiling RichView source:

▪	RichView raises an exception when you try to add checkpoint after checkpoint (default mode);

▪	RichView ignores the second checkpoint; Add*Checkpoint* methods will return the index of previously added checkpoint in this case. This mode is turned on by defining RVALLOWCPBYCP conditional define.