New to Telerik UI for WinForms? Download free 30-day trial

Styles

RadRichTextEditor sccc

Styles can be created and added to a document programmatically or via the Styles dialog. In addition, styles can be instantiated from a docx or a XAML document on import, to provide for a consistent look of the document and richer editing capabilities.

This topic covers:

StyleDefinition Overview

The class that contains the logic behind the styles feature is StyleDefinition.

Each StyleDefinition has the following properties:

  • Name - the name of the style. All styles in a document have a unique name, which is used as an identifier when applying the style.

  • DisplayName - a name that will be shown in the UI.

  • Type - specifies which document elements the style will target, e.g. a Paragraph, a Table, a Span.

  • BasedOn - specifies that the current style inherits the StyleDefinition set to this property. This is how hierarchical Styles can be defined.

The type of the style must match that of the inherited style. It is not possible to have a Character style inherit a Paragraph style for example.

  • BasedOnName - the same as above, the only difference being in the way the style is set - using its Name.

  • LinkedStyle - provides a relation between a Paragraph and Character style.

The Name and Type properties are compulsory for each StyleDefinition.

Types of Styles

The style types that are most commonly used are Character styles and styles for Paragraph.

The former styles set values for the properties of Span, such as FontSize, ForeColor and FontWeight. These values are contained in the SpanProperties of the style. When such a style is applied to a document, it changes the formatting of the text in the selection or (if there is no selection) the formatting of the word that the Caret is positioned in.

Paragraph Styles include properties of a Paragraph, such as Background, TextAlignment, LineSpacing, SpacingAfter, etc. The values of these properties are kept in the ParagraphProperties of the StyleDefinition object. This type of styles can also contain values of Character styles in the SpanProperties property. When applied, the values of the ParagraphProperties will be applied to the Paragraphs and the values of the SpanProperties - to all Spans in these Paragraphs.

You can have a Paragraph style linked to a Character style using the LinkedStyle property. In this way, you can apply Paragraph and Span properties at the same time. The difference between this case and the Paragraph Styles that also set SpanProperties is the way they are applied. With linked styles, if you have selection which includes text in only one Paragraph the Paragraph Style is not applied. In that case, the Character style is applied only on the selected part of the document.

Table styles include properties of Table, such as Borders and Background. They are contained in the TableProperties of the style. When such a style is applied to a document, it changes the formatting of the tables.

Declaring New Styles

New Styles can be declared and added to the StylesRepository of the document. In this way they will be discovered by the default UI and could be applied to parts of the document.

Declaring a Character Style

This is how a Character style can be defined and registered:


StyleDefinition charStyle = new StyleDefinition();
charStyle.Type = StyleType.Character;
charStyle.SpanProperties.FontFamily = new Telerik.WinControls.RichTextEditor.UI.FontFamily("Calibri");
charStyle.SpanProperties.FontSize = Unit.PointToDip(20);
charStyle.SpanProperties.ForeColor = Colors.Orange;
charStyle.DisplayName = "charStyle";
charStyle.Name = "charStyle";

this.radRichTextEditor1.Document.StyleRepository.Add(charStyle);

Dim charStyle As New StyleDefinition()
charStyle.Type = StyleType.Character
charStyle.SpanProperties.FontFamily = New Telerik.WinControls.RichTextEditor.UI.FontFamily("Calibri")
charStyle.SpanProperties.FontSize = Unit.PointToDip(20)
charStyle.SpanProperties.ForeColor = Colors.Orange
charStyle.DisplayName = "charStyle"
charStyle.Name = "charStyle"
Me.radRichTextEditor1.Document.StyleRepository.Add(charStyle)

This style will set "Calibri" as a FontFamily to the part of the document it is applied to, 20 dip as a FontSize and Orange as a ForeColor.

Declaring a Paragraph Style

A paragraph style can be defined as follows:

paragraph.StyleName = RadDocumentDefaultStyles.GetHeadingStyleNameByIndex(1);

paragraph.StyleName = RadDocumentDefaultStyles.GetHeadingStyleNameByIndex(1)

When applied to a Paragraph, this style will set the Background color of the Paragraph to Red and the TextAlignment to Center.

Declaring a Linked Style

Linked styles should be used when both properties of Paragraph and Span should be set by the same style. They can be declared like this:


StyleDefinition linkedParagraphStyle = new StyleDefinition();
linkedParagraphStyle.Type = StyleType.Paragraph;
linkedParagraphStyle.ParagraphProperties.Background = Colors.Yellow;
linkedParagraphStyle.DisplayName = "linkedParagraphStyle";
linkedParagraphStyle.Name = "linkedParagraphStyle";

StyleDefinition linkedCharStyle = new StyleDefinition();
linkedCharStyle.Type = StyleType.Character;
linkedCharStyle.SpanProperties.FontWeight = FontWeights.Bold;
linkedCharStyle.SpanProperties.FontSize = Unit.PointToDip(30);
linkedCharStyle.SpanProperties.ForeColor = Colors.Purple;
linkedCharStyle.DisplayName = "linkedCharStyle";
linkedCharStyle.Name = "linkedCharStyle";
linkedParagraphStyle.LinkedStyle = linkedCharStyle;

this.radRichTextEditor1.Document.StyleRepository.Add(linkedParagraphStyle);
this.radRichTextEditor1.Document.StyleRepository.Add(linkedCharStyle);

Dim linkedParagraphStyle As New StyleDefinition()
linkedParagraphStyle.Type = StyleType.Paragraph
linkedParagraphStyle.ParagraphProperties.Background = Colors.Yellow
linkedParagraphStyle.DisplayName = "linkedParagraphStyle"
linkedParagraphStyle.Name = "linkedParagraphStyle"
Dim linkedCharStyle As New StyleDefinition()
linkedCharStyle.Type = StyleType.Character
linkedCharStyle.SpanProperties.FontWeight = FontWeights.Bold
linkedCharStyle.SpanProperties.FontSize = Unit.PointToDip(30)
linkedCharStyle.SpanProperties.ForeColor = Colors.Purple
linkedCharStyle.DisplayName = "linkedCharStyle"
linkedCharStyle.Name = "linkedCharStyle"
linkedParagraphStyle.LinkedStyle = linkedCharStyle
Me.radRichTextEditor1.Document.StyleRepository.Add(linkedParagraphStyle)
Me.radRichTextEditor1.Document.StyleRepository.Add(linkedCharStyle)

Only styles of type Paragraph and Character can be linked.

Applying a Style

Styles are applied using the ChangeStyleName method of RadRichTextEditor or the ChangeStyleNameCommand. In both cases, the parameter that has to be passed is the Name of the StyleDefinition.

Styles of type Character get applied to the currently selected part of the document. If there is no selection, the values that will be changed are those of the word that the Caret is positioned in.

Styles of type Paragraph follow the same logic and are applied to all paragraphs in the selection or the current paragraph.

For example, the following line will apply the "linkedParagraphStyle" to the current Paragraph and the parts of the text which are selected:


this.radRichTextEditor1.RichTextBoxElement.ChangeStyleName("linkedParagraphStyle");

Me.radRichTextEditor1.RichTextBoxElement.ChangeStyleName("linkedParagraphStyle")

Styles of type LinkedStyle change the values of the paragraph when there is no selection and apply both their Paragraph and Span properties. When there is selection, LinkedStyle changes only the Span properties of the selected text.

Default Styles

The default style for span and paragraph properties is Normal. It internally inherits the default style of the document located in RadDocument.Style.

The document's default style is only for the current instance of the document and if you create a new document, those settings will not be copied. For this purpose you can use the DocumentInheritsDefaultStyleSettings property of RadRichTextEditor . When set to true it will copy each property you set in RadRichTextEditor.DefaultStyleSettings to newly created documents. You can find more information on setting default style settings on the document here)

The default style for table properties is TableNormal, which does not inherit any other styles. It has an inheritor - TableGrid, which contains predefined borders and is the one applied when inserting a table from the UI of RadRichTextEditor.

All default styles as well as some other predefined styles can be applied using the members exposed by the RadDocumentDefaultStyles class. The set of properties provided by the class are of type string and should be applied using the StyleName property of the respective document element.

For example the TableGrid style can be applied to a table as follows:

table.StyleName = RadDocumentDefaultStyles.DefaultTableGridStyleName;

table.StyleName = RadDocumentDefaultStyles.DefaultTableGridStyleName

And a paragraph can have Heading 1 style applied to it like this:

paragraph.StyleName = RadDocumentDefaultStyles.GetHeadingStyleNameByIndex(1);

paragraph.StyleName = RadDocumentDefaultStyles.GetHeadingStyleNameByIndex(1)

Style Evaluation

Each style first checks its local value for the property that is being evaluated and then turns to its base style. If no local value is found, it turns to its default style. If no local value is found, the evaluation system turns to the default style of the document.

Here is how style properties for different styles are inherited:

Span style

Span styles can only be based on other span styles. The inheritance is as follows:

  • Span properties are inherited from the base span style.

Paragraph style

Paragraph styles can be based on other paragraph styles or on linked styles.

When a paragraph style is based on another paragraph style the inheritance of the properties is as follows:

  • Paragraph properties are inherited from the base paragraph style.

  • Span properties are inherited from the base paragraph style.

When a paragraph style is based on a linked style the inheritance of the properties is as follows:

  • Paragraph properties are inherited from the paragraph style part in its base linked style.

  • Span properties are inherited from the span style part in its base linked style

Linked style

Linked styles are composite styles and their components are a paragraph and a span style with link between them. When paragraph properties need to be applied they are taken from the linked paragraph style and accordingly when span properties need to be applied they are taken from the linked span style.

Linked styles can be based on other linked styles or on paragraph styles.

  • When a linked style is based on a paragraph style the inheritance of the properties is as follows:

  • Paragraph properties are inherited from the base paragraph style.

  • Span properties are inherited from the base paragraph style.

  • When a linked style is based on another linked style the inheritance of the properties is as follows:

  • Paragraph properties are inherited from the paragraph style part in its base linked style.

  • Span properties are inherited from the span style part in its base linked style.

Table style

Table styles can only be based on other table styles. The inheritance is as follows:

  • Span properties are inherited from the base table style.

  • Paragraph properties are inherited from the base table style.

  • Table cell properties are inherited from the base table style.

  • Table properties are inherited from the base table style.

In this article