Building and managing rich text
Rich Text retrieval and basic manipulation
We may retrieve, edit write back the rich text or create it from scratch. The objects types that are not directly supported are preserved as
rtBlock objects. Any new object types that may be introduced by Lotus in future releases will be handled in this way until a corresponding class is implemented. In this respect it uses the same forward compatible approach as Notes.
As a result we may concentrate on those object types we have implement direct handling for.
Let us discuss the approach taken and options available based on a few simple examples.
We can retrieve rich text starting with rtItem or rtContainer. The difference is -- rtItem is closely linked to the particular item the rich text has been retrieved from. If we retrieve rich text using a freestanding rtContainer object, we obtain an in-memory "image" of the rich text in item. When we manipulate it, we must specifically write it back to see the changes in notes document; and it does not matter which level of hierarchy we write back and to which item.
A basic functionality of rtContainer is to retrieve the rich text item's content, manipulate and store it back, copy to another document or merge with another item:
Use "libRichText" ' this is the only statement we need to access the rich text classes
Dim ctx as New rtContainer ' we will use ctx as standard variable for topmost rtContainer, i.e. rich text Context
Return value equals False may mean that rtLib did not manage to read the item because the item was corrupt; in case there were no item of that name rtl9ib throws an error.
rtContainer is also used to manipulate a content of embedded structures as is discussed below.
If the previous code returned True (success), we have retrieved the rich text field and may start to manipulate it. The simplest exmple would be to merge it with another field in another document:
Call ctx.AppendItemValue(docOther, "Body")
The body field in document docOther will get extended with the rich text contained in the field that we just retrieved
For those with sad experience in using CopyItem and CopyToDocument methods, we may note that during this operation fonts information and doclinks are preserved in good order.
As a more complex example we may want to replace a specific text. At the beginning let us just replace a simple text:
Call ctx.Replace ("IBM", "Lotus", RT_RELACE_ALL + RT_FIND_WORDS)
That's it -- all mention of IBM in text is replaced with a word "Lotus". RT_FIND_WORDS added in version 1.2 greatly improves automated text processing like cross-indexing used to create links in this help file.
Search string may contain the same wildcards as applicable in LotusScript Like operator. Last parameter - flags are combined of flags used by StrCompare (or Instr) and RT_FIND_WILDCARDS and RT_FIND_SPECIAL_CHARACTERS.
We must note that this regards only regular text of the document. Specific objects like button labels, section titles, pop-up texts or text of computed hotspot will not by default be replaced using this function. However they all are available and in case we want a fully global replacement, we must make a little effort to find them and replace separately or we must specifically define the Labels to be included along with regular text (see rtLabel class and defineLabelAsText property of rtContainer class).
Slightly more complex sample is discussed in chapter "Management of rich text item".
Limitation: The library concentrates on classes dealing with the most popular constructs in "end user" documents and practically does not include functionality of design manipulation (with an exception of image resources and access to all design elements as NotesDocuments).
The library provides a means to deal with both basic classes of needs - with building and with editing of rich text. Further follow a few characteristic samples of usage.