Formattings and styles are a means to set visual properties like color, font, size, alignment, positioning etc. to your document content elements.
The following sections present formattings and styles available in GemBox.Document.
Formattings are objects which contain visual information about document content element.
Following class diagram shows formattings available in GemBox.Document.
Each formatting class in the diagram links to its help page, so you can easily navigate to the details of each formatting.
Formattings can be set directly on elements, such as Paragraph ParagraphFormat or Run CharacterFormat or they can be set indirectly, through styles, such as ParagraphStyle ParagraphFormat or CharacterStyle CharacterFormat.
Default formattings for paragraphs and text can be set through DocumentModel DefaultParagraphFormat and DocumentModel DefaultCharacterFormat properties. All newly created Paragraphs and Runs will have those formatting properties. For more information about formatting properties resolution, see here.
Styles are objects which contain visual information about one or more document content elements.
They have an advantage over direct formattings because their formatting properties can be set and changed in one single place, and all document content elements, which have that particular style applied, will be affected by the change.
The following class diagram shows styles available in GemBox.Document.
Each style class in the diagram links to its help page, so you can easily navigate to the details of each style.
 Note |
|---|
Microsoft Word built-in styles, like Normal, Heading 1, Heading 2, Title, etc. can be created with Style CreateStyle(StyleTemplateType, DocumentModel) static method. After a style is created, it has to be added to DocumentModel Styles collection to be used. |
| Note |
|---|
| Table related styles are not yet exposed through GemBox.Document API. |
Formatting properties for an element can be set from multiple places: element direct formatting, element style, ancestor element direct formatting, ancestor element style and default formatting.
GemBox.Document calculates or resolves formatting properties, so you have the same formatting properties for an element as when it is rendered by a document processing application like Microsoft Word.
When retrieving values of formatting properties for a specific document content element, they will be resolved in the following way:
- value is retrieved from element direct formatting, if formatting property value is set there, otherwise
- value is retrieved from element style formatting, if style is present and formatting property value is set there, otherwise
- value is retrieved from ancestor element direct formatting, if ancestor element contains the same formatting type and formatting property value is set there, otherwise
- value is retrieved from ancestor element style formatting, if ancestor element contains the same style type, style is present, and formatting property value is set there, otherwise
- value is retrieved from default formatting (DocumentModel DefaultParagraphFormat and DocumentModel DefaultParagraphFormat).
| Note |
|---|
If you want to clear formatting property value, for example, you want to remove font weight from text formatting, don't do charFormat.Bold = false;. This will not clear property value, it will just set its value to false. To clear a value, so that when it is retrieved, it gets picked from the next source in format resolution hierarchy, use Format ClearFormatting . This will also clear all other formatting properties. |
The following example shows formatting properties resolution on CharacterFormat FontColor property.
// Create a new empty document. var doc = new DocumentModel(); // Create Runs and Paragraph. Run run1 = new Run(doc, "First"), run2 = new Run(doc, "Second"), run3 = new Run(doc, "Third"), run4 = new Run(doc, "Fourth"); Paragraph para = new Paragraph(doc, run1, run2, run3); // Add document content: run1, run2, run3 are in first paragraph (para), run4 is in second paragraph. doc.Sections.Add(new Section(doc, para, new Paragraph(doc, run4))); // Create and add paragraph and character styles to the document. ParagraphStyle paraStyle = new ParagraphStyle("GreenFont"); CharacterStyle charStyle = new CharacterStyle("BlueFont"); doc.Styles.Add(paraStyle); doc.Styles.Add(charStyle); // Set paragraph style to first paragraph (para) and character style to run1 and run2. para.ParagraphFormat.Style = paraStyle; run1.CharacterFormat.Style = charStyle; run2.CharacterFormat.Style = charStyle; // Set document default font color to yellow. doc.DefaultCharacterFormat.FontColor = Color.Yellow; // Set first paragraph style (para) font color to green. paraStyle.CharacterFormat.FontColor = Color.Green; // Set run1 and run2 style font color to blue. charStyle.CharacterFormat.FontColor = Color.Blue; // Set run1 font color to red. run1.CharacterFormat.FontColor = Color.Red; // run1 font color is red - from direct formatting. Debug.Assert(run1.CharacterFormat.FontColor == Color.Red); // run2 font color is blue - from style. Debug.Assert(run2.CharacterFormat.FontColor == Color.Blue); // run3 font color is green - from ascendant paragraph (para) style. Debug.Assert(run3.CharacterFormat.FontColor == Color.Green); // run4 font color is yellow - from default document formatting. Debug.Assert(run4.CharacterFormat.FontColor == Color.Yellow);
| Note |
|---|
| Since table related styles are not yet exposed through GemBox.Document API, resolution for table related formattings is not yet supported in GemBox.Document. |
GemBox.Document internally uses flyweight pattern to store formatting data.
Formattings with the same properties are cached and reused by multiple elements and styles in the same document.
This technique is totally transparent to the user and makes GemBox.Document highly memory efficient.