Styles and StyleTemplates in TRichView

<< Click to display table of contents >>

Styles and StyleTemplates in TRichView

As you could see, this manual sometimes calls items in TextStyles and ParaStyles "styles", and sometimes it calls them simply "text/paragraph attributes". Apart from historical reasons, there are other reasons for this dual naming, resulting from different cases of use.

Using a predefined set of styles

In this mode, you have some predefined set of items in TextStyles and ParaStyles, and they are not changed while the application works.

In this mode, these items may be called "styles".


You can configure RichView1 to allow insertion of RVF and RTF files/streams without adding new styles.

However, this case of usage is very limited. Normally, users want to apply new formatting to parts of a document: change colors, fonts, alignments, etc., so it is impossible to create all necessary styles initially.

Using a dynamic set of styles

In this mode, you can have some initial set of items in TextStyles and ParaStyles; but the most of items are added while the application works. For example, new items may be added when inserting RVF or RTF files/streams, or when applying changes to the selection (ApplyStyleConversion, ApplyParaStyleConversion). RichViewActions add new items as well.

In this mode, items of TextStyles and ParaStyles work more like direct text/paragraph attributes rather than styles: the most of them do not have a special unique name or meaning.

Some items of TextStyles and ParaStyles may be marked as Standard (usually, the items added initially). They may have a special meaning, they are not removed by DeleteUnusedStyles, they can be saved in RTF as a style sheet (if rvrtfSaveStyleSheet in RTFOptions). However, this is not a complete solution for styles, because all other items are completely independent of them: if you change properties of standard styles, only text/paragraphs formatted using them are changed; all other parts of the document are unstyled. It makes standard styles almost useless, so usually an application should create only one standard text style and one standard paragraph style (defaults for new documents).

The complete solution for implementing real text and paragraph styles is "style templates".

Style templates (+dynamic set of styles)

StyleTemplates is a collection in TRVStyle component. Unlike TextStyles and ParaStyles, style templates do not define text and paragraph properties of document items and paragraphs directly. Instead, they provide a mechanism for modifying TextStyles and ParaStyles.

Using style templates is optional; they are used only if TRichView.UseStyleTemplates=True.

Document items do not have direct links to style templates, they are still linked with TextStyles and ParaStyles. But items in TextStyles and ParaStyles may be linked to style templates using StyleTemplateId property.

Each item in a document may be (indirectly) linked to up to 2 style templates:

via its paragraph style, or

via its text style (if this is a text item, tab, label, sequence, footnote, endnote, or note reference).

It's recommended (but not necessary) to link every paragraph style to some style template. The recommended name for the default paragraph style template is "Normal".

As for text styles, it is recommended to link them to style templates only if it is necessary.

There are 3 kinds of style templates: applicable to text, applicable to paragraphs, applicable to text and paragraphs.

Each style template may have properties of both text and paragraph. Unlike items of TextStyles or ParaStyles, a style template:

may define only a subset of text and paragraph properties (listed in ValidTextProperties and ValidParaProperties);

may inherit text and paragraph properties from a parent style template.

When some document item is (indirectly) linked to both a paragraph style template and a text style template, both these style templates are linked with its text style: a text style template as TextStyles[StyleNo].StyleTemplateId, a paragraph style template as TextStyles[StyleNo].ParaStyleTemplateId. TRichView automatically provides for each document item that TextStyles[StyleNo].ParaStyleTemplateId = ParaStyles[ParaNo].StyleTemplateId. In such cases, a text style template has a priority in defining text attributes: a paragraph style template defines only text attributes not defined by a text style template.

Not all properties of items in TextStyles and ParaStyles are defined by their style template: they can have some properties changed. A list of changed properties is not stored, it is calculated when it is needed. These changes may be (optionally) kept when applying another style template to these items, and they are kept when StyleTemplates are edited.

TRichViewEdit has the following methods for applying the specified style template to the selection: ApplyStyleTemplate, ApplyTextStyleTemplate, ApplyParaStyleTemplate. The same methods may be used to clear a style template or additional formatting.

Style templates can be edited using ChangeStyleTemplates method.