Items' "Tags"

RichView Items' "Tags" Overview

Top Previous Next

Each item of RichView has an associated integer value – tag. Tags are provided for the convenience of storing additional integer value (4 bytes) or pointer information for special needs in application. Moreover, RichView can work in mode where all tags are treated as PChar – pointers to dynamically allocated strings. The main purpose of tags is organizing work with hypertext.

Do not confuse RichView items tags with "Tag" properties of TComponent descendants! (RichView uses "Tag" properties of inserted controls for its own needs; you can set "Tag" properties of ImageList for organizing saving/loading "bullets" and "hotspots" from RVF; but this topic is about completely another tags!)

What you need to know about items tags:

▪	if you do not want to use them – just forget about them; they always will be equal to 0;

▪	in the default mode (rvoTagsArePChars is not in RichView.Options) RichView does not use tags and you can use them as you wish;

▪	if rvoTagsArePChars in RichView.Options then tags are treated as pointers to dynamically allocated strings (see below for details);

▪	"checkpoints" also have tags; all rules for items tags work for checkpoints tags;

▪	editor can clear (set to 0) tags when applying different style to text according to RichViewEdit.EditorOptions;

▪	tag mode can be changed in the TRichView component editor.

"Tags are PChars mode"

In this mode RichView:

▪	frees tag string's memory when deleting/clearing items,

▪	compares tags in internal routines as strings,

▪	saves tags in RVF as strings.

When RichViewEdit needs to duplicate tags (for example when user press Enter key and the current line will be separated into two lines) the editor duplicates it by allocating the same string (using StrNew) so both new items will have their own tag strings.

There are some rules for using components in this mode:

•	All main AddXXX methods (methods for adding items to the end of document) have AddXXXTag modifications, which accept Tag as a last parameter. You must pass value obtained from StrNew or StrAlloc functions, or 0 (nil) converted to Integer to this parameter

For example

MyRichView.AddNLTag('Example', 0, 0, Integer(StrNew('Tag Example')));

Do not confuse StrNew with NewStr. Do not use NewStr!

The same rule applies to InsertStringTag and InsertStringWTag of TRichViewEdit.

•	You can use AddXXX methods which do not have Tag parameter. These functions create a new item with Tag=0 (nil) which is legal value for this mode.

•	All methods of RichView/RichViewEdit which return Tag (as function value or as var-parameter) return a pointer to tag string, not to the copy of string; you need not and should not free memory for the returned string;

•	All methods of RichView/RichViewEdit for item modifying (SetXXXInfo) accept pointers to newly dynamically allocated strings, like AddXXXTag methods. But there is one exception - you can pass tag value obtained from this item before (with GetXXXInfo)

Example:

var Tag: Integer;

S: String;

TagStr: PChar;

// Converting the first text item and its tag string to upper case

MyRichView.GetTextInfo(0, S, Tag);

TagStr := StrNew(PChar(Tag));

TagStr := StrUpper(TagStr);

MyRichView.SetItemText(0, UpperCase(S));

MyRichView.SetItemTag(0, Integer(TagStr));

•	If you want to save and load document in RVF you must provide that tag strings do not contain #10, #13 and #0 characters.

•	You cannot mix integer and string tag (for different items in one RichView); you should not switch tag mode when the component contains nonzero tags.