rtLib — Notes Rich Text Management Library Documentation of rtLib — Notes Rich Text Management Library Download rtLib — Notes Rich Text Management Library FAQ of rtLib — Notes Rich Text Management Library Purchase rtLib — Notes Rich Text Management Library Feedback about rtLib — Notes Rich Text Management Library

Building and managing rich text


Start search Mail feedback Back to Description

There are several ways to navigate in rich text fields. After we call getRichText() method of rtContainer object or retrieve Container from rtItem, we can process the content in different ways.

1. We may use Find method of rtContainer to search for text. It instantiates rTextRange object corresponding to the text found. The text range may stretch over several rTextRun objects. That is the case if different sentences or words use different text formatting - color, font weight and/or size, etc. The rTextRange will include also other objects like images or doclinks between the text runs containing the text we searched for. The found range may streach also across several paragraphs.

We may use returned rTextRange object to insert text or any rich text object in place of select. For more info see Find method and rTextRange class help.

We can also use wildcards in search, however it will slightly slow down the execution time. All other methods are equally quick (or time consuming).

2. We may use getFirstElement() ande getNextElement() (getLastElement and getPrevElement) methods of rtContainer or rtObject classes. These methods take as argument an identifier of a particular class of rich text objects, like RT_OBJ_TEXTPARAGRAPH, RT_OBJ_NOTELINK, RT_OBJ_TEXTRUN, RT_OBJ_GRAPHIC, etc. These arguments may be added up, like RT_OBJ_NOTELINK +RT_OBJ_GRAPHIC will return any object - Notelinks or Images or even used RT_OBJ_ALL that will return any object.

Set image = ctx.getFirstElement (RT_OBJ_GRAPHIC)


Set image = table.getFirstElement (RT_OBJ_GRAPHIC)

The objects are returned from particular scope. Applying them to the table object (the second line of code) will retrieve images only from the table. Also we must notice that getNextElement/getPreviousElement does not search inside the current (relative element):

Set table = ctx.getFirstElement (RT_OBJ_TABLE)

Set table2 = ctx.getNextElement (RT_OBJ_TABLE, table)

A code like above will retrieve the second table that follows the first one. To find a table embedded in the first table we must use:

Set table2 = table.getFirstElement (RT_OBJ_TABLE)

The same way, if we use:

Set table = ctx.getFirstElement (RT_OBJ_TABLE)

Set image = ctx.getNextElement (RT_OBJ_GRAPHIC, table)

The rtGraphic object returned will be one that follows the table (but not within the table).

All the objects returned are contained in paragraphs. As a result we may use getFirstElement() and getNextElement() with argument RT_OBJ_TEXTPARAGRAPH to loop through paragraphs, then apply second search to locate objects in the paragraph content.
The objects available directly from top level container are only rTextParagraph class objects. The paragraphs contain all other elements.
set para = ctx.getFirstElement (RT_OBJ_TEXTPARAGRAPH)
set paraContent = para.Content
This returns rtContainer containing the paragraph content, the objects associated with paragraph content can be of any other type like rtTable, rtNoteLink, rTextRun or even rtRawCD and rtBlock that represent unidentified objects.
Note: all unidentified (unsupported) objects (each rtRawCD object represents a single CD-Record and rtBlock a serie of unprocessed rtRawCD class objects) are preserved during the rich text manipulations. You may also delete or copy them to other location or even manipulate their content directly overwritting particular values. However it may take a detailed knowledge of Rich Text inner structure to use these feature.
In case rTextParagraph object contains an embedded table, section or hotspot that in turn also may contain text, we must use getFirstElement(), getNextElement() methods to get the content of these container type objects.

3. One more alternative is to use rtContainer methods -- Tables, Hotspots, Sections, Doclinks, TextRuns that return rtEnumeration objects containing all objects of particular class. The difference for those elements that can be embedded in objects of the same class is that the returned rtEnumeration contains all objects even if they are mutually embedded. Thus the enumeration will contain both container table and those tables that are embedded within. The same applies to sections and hotspots. If we are not interested in particular location of the objects, this is an efficient way to obtain and loop through objects.

4. Finally Collection method of rtContainer returns an rtCollection object that may contain objects of different classes. We provide keywords as a parameter of Collection method:


The code above returns a collection of rtTable, rTextRun, rtHotLink and rtNoteLink objects. We retrieve all objects we need in one collection, then loop through and process as necessary.

For more information about parse groups available see Collection method.