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

Handling of Rich Text objects

Use of styles

Start search Mail feedback Back to Description

The styles are used to easily assign and transfer layout and look and feel of rich text elements. In difference from "real" or structural rich text elements that can be associated only with one parent container, one style object may be associated with any number of rich text objects.

All object classes have Style property to set/get associated style object.

Style object ( rtStyle class) itself is compound object and consists of specific styles.

rtStyle contains (may contain on or several of the list):

rtFontstyle, rtParagraphstyle, rtTableStyle, rtBorderStyle, rtRowDisplayStyle, rtHtmlStyle components. These components can also be freely associated with any number of styles. The styles may be assigned from one object to another either all at once by using rtStyle object or by specific style. If in doubt check the particular style property for existance:

if obj.Style.Font is Nothing then set obj.Style.Font = new rtFontstyle(0)

If objects are retrieved from rich text item they have all styles characteristic for the object. Some however may be optional. Thus rtTable object does not always have rtRowDisplayStyle, only in case any of the contained properties has been set for the table.

Some objects have a shorthand access to their specific styles - so rTextRun has Font property:

rTextRun.Font is equivalent of rTextRun.Style.Font

Dim style as New rtStyle (0), style1 as New rtStyle (0)

Dim fstyle as New rtFontstyle (0), fstyle1 as New rtFontstyle (0)

Dim pStyle as New rtParagraphstyle (0), pStyle1 as New rtParagraphstyle (0)

... set some values to the styles

We created 2 different styles and assign different rtFontstyle and rtParagraphstyle objects. Argument (0) is reserved to be used in future versions. Use any numeric value that will be ignored.

Set style.Font = fStyle

Set style.Paragraph = pStyle

Set style1.Font = fStyle1

Set style1.Paragraph = pStyle1

' if we apply the style it stays the same object wherever we use it

Set someTextRun.Style = style

Set someTextRun.Style.Font = fStyle1

It means we have effectively changed Font property of Style and now it contains fStyle1

If that was not our purpose, if we just want to apply Style and set Font to fStyle1 for this particular text run, we could use:

Set someTextRun.Style = style.clone

Set someTextRun.Style.Font = fStyle1

someTextRun.Style.Font.FontSize = 20

Note: Clone method creates a new object with the sam properties as the parent object. If properties were object themselves, they are not cloned automatically.

This will result in applying a new rtStyle object (having the same Paragraph and Font properties) and substituting the font object. The font object is still fStyle. Setting it to 20 will change it to 20pt for all objects using fStyle. To avoid it if it is not what is expected use clone method with any style objects you want to change only in one instance.

Set someTextRun.Style = style.clone

Set someTextRun.Style.Font = fStyle1.clone

someTextRun.Style.Font.FontSize = 20

It works the same way when retrieving rich text. In case the same font is used in several paragraphs in a row they all use the same font style object (and also the same paragraph style object if paragraph formatting is the same).

Dim ctx as New rtContainer, rtr as rTextRun

ctx.getRichTextItem doc, "Body"

Set rtr = ctx.getFirstElement (RT_OBJ_TEXTRUN)

rtr.Font.FontSize = 9

Will change the font size also in other text runs. To avoid it we can use cloning:

Set rtr.Style = rtr.Style.clone

Set rtrStyle.Font = Set rtrStyle.Font.Clone

Font.FontSize = 9

In order to force a uniform style of some range, say content of table, use setStyle method. setStyle is defined for all objects and rtContainer. setStyle method differs from Style property in:

1. it may take either style or any substyle as an argument ( rtStyle, rtParagraphstyle, etc.).

2. it updates existing style or substyle, but does not add nonexisting styles. If table does not have TableLayout property set it can not be added using setStyle. Use Style.TableLayout instead.

It has a second parameter that may either be True/False - if True styles get updated for all the hierarchy below.

table.setStyle fontStyle, True

3. Second parameter can also be the last object in hierarchy that will get this style applied -- "apply style until the object is the second parameter".

One particular use of setStyle method is on rTextRange object returned by Find and FindNext methods. It differs in that it applies only to objects returned by search - text runs and paragraphs (to be exact paragraph labels that share the style object with the parent paragraph). It also splits up the text runs if selected range does not include all text run.

In case the item contains 2 text runs - black and red:

Some text.

If we execute statement:

ctx.Find ("me te",0).setStyle newGreenFontStyle, True

The result will be (assuming that font style is the same except color is green):

Some text.

Consisting of 3 text runs. Note that it's not always possible to determine visually the number of text runs object text occupies. Sometimes innocent editing may produce empty (invisible) text runs having a variety of fonts and colors.