Styles
RadFlowDocument includes repository of Style objects which contain sets of character, paragraph or table style properties. They provide rich editing capabilities with consistent look over different content inside the document. Styles allow formatting properties to be stored and managed independently from the content. RadFlowDocument keeps its styles in StyleRepository object accessible through the RadFlowDocument.StyleRepository property.
Style Class Overview
The class containing the styling structure is called Style. Each style contains the following properties:
Id: The ID of the style. All styles in a StyleRepository should have unique IDs. This property cannot be set after adding the style in a StyleRepository, in such situations InvalidOperationException is thrown. The value of this property will be associated with the StyleId property of the corresponding document element.
StyleType: The type of the style, described with StyleType enumeration. It can be Character, Paragraph or Table and determines the types of document elements to which the style is applied.
Name: The name of the style, which can be used in an application's user interface.
BasedOnStyleId: The ID of the parent (base) style, which the current style inherits.
NextStyleId: The ID of the style, which is automatically applied by an editing application to a new paragraph added after the paragraph with the current style applied to it.
LinkedStyleId: The ID of a style to which the current style is linked. This property can point only from paragraph style to character style and vice versa.
IsDefault: Specifies that the style is the default style for its style type. This property is used in conjunction with the style type to determine the style, which is applied to objects that do not have explicitly applied a style.
IsCustom: Specifies that the style is user-defined and it is not automatically generated by an application. This setting does not allow the formatting associated with the style to be changed automatically by an application.
IsPrimary: Specifies that the style is important for the document. Typically applications show such styles in easily accessible part of the UI.
UIPriority: Specifies a number used by an application to sort the styles in its UI.
Style Types
A style can contain one or more of five different sets of style properties, depending on its type: CharacterProperties, ParagraphProperties, TableProperties, TableRowProperties, TableCellProperties. There are three types of styles:
Character styles: Used to contain properties of a Run such as: font style, font size, font family, font-weight, etc. Styles of this type contain only CharacterProperties set of style properties.
Paragraph styles: Used to contain properties of a Paragraph such as: text alignment, spacing (before and after), indentation, etc. Styles of this type contain ParagraphProperties and CharacterProperties sets of style properties, where character properties are used to format the Runs inside the styled Paragraph.
Table styles: Used to contain properties of a Table and table-related document elements (TableRow and TableCell), such as borders, background, alignment, padding, etc. Styles of this type contain TableProperties, TableRowProperties, TableCellProperties, ParagraphProperties and CharacterProperties sets of style properties, where table row and table cell properties are used to format child TableRows and TableCells, paragraph and character properties are used to format the Paragraphs and Runs in the styled table.
Numbering styles: Used to represent Lists in the user interface of an application. Style with this type cannot be referenced directly by document elements. It holds only information about the associated list.
Creating New Styles
A style should be added to RadFlowDocument's style repository in order to be further applied to elements and participate in style properties evaluation process. For example, the code from Example 1 creates a table style and adds it to the style repository.
Example 1: Create a table style and add it to the style repository
Style tableStyle = new Style("TableStyle", StyleType.Table);
tableStyle.Name = "Table Style";
tableStyle.TableProperties.Borders.LocalValue = new TableBorders(new Border(1, BorderStyle.Single, new ThemableColor(Colors.Blue)));
tableStyle.TableProperties.Alignment.LocalValue = Alignment.Center;
tableStyle.TableCellProperties.VerticalAlignment.LocalValue = VerticalAlignment.Center;
document.StyleRepository.Add(tableStyle);
If a style is not added to the StyleRepository, applying it to a document element would not take any effect.
To apply a style to a spesific element you neet to set its StyleId proerty.
Example 2: Apply a custom style to an element
Table table = new Table(document, 10, 5);
table.StyleId = tableStyle.Id;
section.Blocks.Add(table);
Default Styles
Default style is a style which, according to its style type, is applied to objects that do not have explicitly applied a style. By default, style repository contains two default styles:
"Normal": Default style for Paragraph and Run document elements. "Normal" style additionally inherits from the default style properties of the document stored in RadFlowDocument.DefaultStyle property.
"TableNormal": Default style for Table, TableRow and TableCell document elements.
If you want to set default values for properties of all Run and Paragraph document elements, it is convenient to use CharacterPoperties and ParagraphProperties stored in RadFlowDocument.DefaultStyle property. Setting default values for properties for all Table, TableRow and TableCell document elements should be done in the default table style - "TableNormal".
You can change the default styling properties for a document through the DefaultStyle property of RadFlowDocument. Example 3 shows how you can do that for the font-family, and similar code can be used for the other styling properties for the runs and paragraphs inside a document.
Example 3: Set a default font-family
RadFlowDocument document = new RadFlowDocument();
document.DefaultStyle.CharacterProperties.FontFamily.LocalValue = new ThemableFontFamily("Verdana");
Built-in Styles
Built-in styles are commonly used styles, which are predefined for convenience. They have to be explicitly added to the style repository before usage using the StyleRepository.AddBuiltInStyle() method.
BuiltInStyleNames static class contains properties and methods for getting the IDs of all built-in styles. Example 4 shows how to get the ID of the "Heading 1" built-in style.
Example 4: Get the ID of a built-in style
string heading1StyleId = BuiltInStyleNames.GetHeadingStyleIdByIndex(1);
Style heading1Style = document.StyleRepository.AddBuiltInStyle(heading1StyleId);
BuiltInStyles static class can be used for working with the raw built-in styles.
Linked Styles
Linked style is a grouping of paragraph style and character style into a pair with a link between them. This allows applications to apply common set of style properties to Paragraphs and Runs:
Linked style is applied to Paragraph: The paragraph style part of the linked pair is applied to the Paragraph.
Linked style is applied to Run: The character style part of the linked pair is applied to the Run.
Styles are linked by setting Style.LinkedStyleId property to the ID of the other style in the pair.
Style Evaluation and Inheritance
When evaluating the actual value of a style property in one of the style properties sets (CharacterProperties, ParagraphProperties, TableProperties, TableRowProperties, TableCellProperties), the style system uses the following rules:
- If the style property has a local value set, it is returned.
- If the corresponding style property of the base style has a local value set, this value is returned.
- If the corresponding style property in the default style has a local value*, this value is returned.
- If this is character or paragraph style property, and if the corresponding property from document's default Paragraph and Character settings stored in RadFlowDocument.DefaultStyles property has a local value, this value is used.
* If a style is of character or paragraph style type it takes into consideration the default style only if it is based on it.
Some of the style properties always have a local value set.
Corresponding style property of the base style is determined depending on the style type using the following rules:
Character style
Character style can only be based on other character styles. The inheritance is as follows:
- Character properties inherit the character properties from the base style.
Paragraph style
Paragraph style can be based on other paragraph or linked styles.
-
When a paragraph style is based on another paragraph style, the inheritance of the properties is as follows:
Paragraph properties inherit the paragraph properties from the base paragraph style.
Character properties inherit the character properties 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 inherit the paragraph properties from the paragraph style part in the base linked style.
Character properties inherit the character properties from the character style part in the base linked style.
Table style
Table styles can only be based on other table styles. The inheritance is as follows:
Character properties inherit the character properties from the base style.
Paragraph properties inherit the paragraph properties from the base table style.
Table properties inherit the table properties from the base table style.
Table row properties inherit the table row properties from the base table style.
Table cell properties inherit the table cell properties from the base table style.
Linked 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 inherit the paragraph properties from the base paragraph style.
Character properties inherit the character properties 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 inherit the paragraph properties from the base linked paragraph style.
Character properties inherit the character properties from the base linked character style.