Click or drag to resize
Formattings and Styles

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

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.

Navigate to TableStyleFormat classNavigate to TableCellFormat classNavigate to TableRowFormat classNavigate to TableFormat classNavigate to CharacterFormat classNavigate to ListFormat classNavigate to ParagraphFormat classNavigate to Format classGemBox.Document Formattings

Formattings can be set directly on elements, such as ParagraphParagraphFormat or RunCharacterFormat or they can be set indirectly, through styles, such as ParagraphStyleParagraphFormat or CharacterStyleCharacterFormat.

Default formattings for paragraphs and text can be set through DocumentModelDefaultParagraphFormat and DocumentModelDefaultCharacterFormat properties. All newly created Paragraphs and Runs will have those formatting properties. For more information about formatting properties resolution, see here.

Styles

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 and property in the diagram links to its help page, so you can easily navigate to the details of each style.

Navigate to CharacterStyle.CharacterFormat propertyNavigate to ListStyle.ListLevelFormats propertyNavigate to ParagraphStyle.CharacterFormat propertyNavigate to ParagraphStyle.ParagraphFormat propertyNavigate to TableStyle.CellFormat propertyNavigate to TableStyle.RowFormat propertyNavigate to TableStyle.TableFormat propertyNavigate to TableStyle.CharacterFormat propertyNavigate to TableStyle.ParagraphFormat propertyNavigate to TableStyle.ConditionalFormats propertyNavigate to CharacterStyle classNavigate to TableStyle classNavigate to ListStyle classNavigate to ParagraphStyle classNavigate to Style classGemBox.Document Styles

Note Note

Microsoft Word built-in styles, like Normal, Heading 1, Heading 2, Title, etc. can be created with StyleCreateStyle(StyleTemplateType, DocumentModel) static method. After a style is created, it has to be added to DocumentModelStyles collection to be used.

Alternatively, you can use utility method StyleCollectionGetOrAdd(StyleTemplateType) to get a built-in style or create and add a new one in a single statement.

Tip Tip

For a demonstration examples of formatting and styles, check out Formatting samples and Table samples from GemBox.Document Sample Explorer.

Table Styles

TableStyles are Style definitions which apply to the contents of zero or more Tables within a DocumentModel.

This definition may imply that the TableStyle can only define table formatting properties, however a table style is much more powerful and it allows you to define following formatting properties:

Additionally, unlike other Style definitions, TableStyle allow for the definition of conditional formats for different regions of the table.

Conditional format is represented by TableStyleFormat type and it also allows you to define all formatting properties as a TableStyle (formatting for a table, rows, cells, paragraphs and runs).

Table style conditional formats are accessible from TableStyleConditionalFormats property and are applied to different regions of the table as shown in the following tables:

Table 1: Table with custom style and conditional row banding format (among others) applied
TopLeftCellFirstRow, TableStyleOptions.FirstRowTopRightCell
FirstColumn

TableStyleOptions.
FirstColumn
OddBandedRows
TableStyleOptions.BandedRows, TableStyle.TableFormat.RowBandSize = 2
LastColumn

TableStyleOptions.
LastColumn
EvenBandedRows
TableStyleOptions.BandedRows
OddBandedRows
TableStyleOptions.BandedRows
EvenBandedRows, TableStyleOptions.BandedRows
BottomLeftCellLastRow, TableStyleOptions.LastRowBottomRightCell

Table 2: Table with custom style and conditional column banding format (among others) applied
TopLeftCellFirstRow, TableStyleOptions.FirstRowTopRightCell
FirstColumn

TableStyleOptions.
FirstColumn
OddBandedColumns

TableStyleOptions.
BandedColumns


TableStyle.TableFormat
.ColumnBandSize = 2
EvenBandedColumns

TableStyleOptions.
BandedColumns
OddBandedColumns

TableStyleOptions.
BandedColumns
EvenBandedColumns

TableStyleOptions.
BandedColumns
LastColumn

TableStyleOptions.
LastColumn
BottomLeftCellLastRow, TableStyleOptions.LastRowBottomRightCell

Each region of a table contains links to members used for defining and applying conditional formatting of that region.

Following remarks are useful for understanding table style conditional formatting:

If multiple table style conditional formats are applied and in affect in the particular region of the table, a particular formatting property value on element contained in that region of a table is resolved from conditional formats in the following order:

  1. TopLeftCell, TopRightCell, BottomLeftCell and BottomRightCell.

  2. FirstRow and LastRow.

  3. FirstColumn and LastColumn.

  4. OddBandedColumns and EvenBandedColumns.

  5. OddBandedRows and EvenBandedRows.

  6. WholeTable.

Following code shows how to create and apply custom table style with conditional formats like in above Table 1 and Table 2 using GemBox.Document component.

var tableStyle = new TableStyle("CustomTableStyle");

Color cornerCellColor = new Color(229, 184, 183),
    firstLastRowColor = new Color(214, 227, 188),
    firstLastColumnColor = new Color(184, 204, 228),
    oddBandedColor = new Color(251, 212, 180),
    evenBandedColor = new Color(204, 192, 217);

// Specify background color for corner cells.
tableStyle.ConditionalFormats[TableStyleFormatType.TopLeftCell].CellFormat.BackgroundColor = cornerCellColor;
tableStyle.ConditionalFormats[TableStyleFormatType.TopRightCell].CellFormat.BackgroundColor = cornerCellColor;
tableStyle.ConditionalFormats[TableStyleFormatType.BottomLeftCell].CellFormat.BackgroundColor = cornerCellColor;
tableStyle.ConditionalFormats[TableStyleFormatType.BottomRightCell].CellFormat.BackgroundColor = cornerCellColor;

// Specify background color for cells in the first and last row.
tableStyle.ConditionalFormats[TableStyleFormatType.FirstRow].CellFormat.BackgroundColor = firstLastRowColor;
tableStyle.ConditionalFormats[TableStyleFormatType.LastRow].CellFormat.BackgroundColor = firstLastRowColor;

// Specify background color for cells in the first and last column.
tableStyle.ConditionalFormats[TableStyleFormatType.FirstColumn].CellFormat.BackgroundColor = firstLastColumnColor;
tableStyle.ConditionalFormats[TableStyleFormatType.LastColumn].CellFormat.BackgroundColor = firstLastColumnColor;

// Specify background color for cells in odd banded and even banded rows.
tableStyle.ConditionalFormats[TableStyleFormatType.OddBandedRows].CellFormat.BackgroundColor = oddBandedColor;
tableStyle.ConditionalFormats[TableStyleFormatType.EvenBandedRows].CellFormat.BackgroundColor = evenBandedColor;

// Specify background color for cells in odd banded and even banded columns.
tableStyle.ConditionalFormats[TableStyleFormatType.OddBandedColumns].CellFormat.BackgroundColor = oddBandedColor;
tableStyle.ConditionalFormats[TableStyleFormatType.EvenBandedColumns].CellFormat.BackgroundColor = evenBandedColor;

// Specify row and column banding size.
tableStyle.TableFormat.RowBandSize = 2;
tableStyle.TableFormat.ColumnBandSize = 2;

// Add some spacing between cells for easier identification of individual cells.
tableStyle.TableFormat.DefaultCellSpacing = 1;

var document = new DocumentModel();

// Associate table style with a document. This is required for a style to be applied on an element from this document.
document.Styles.Add(tableStyle);

var table1 = new Table(document, 9, 9);
table1.TableFormat.PreferredWidth = new TableWidth(100, TableWidthUnit.Percentage);
// Specify style and which of the table style conditional formats will be applied.
table1.TableFormat.Style = tableStyle;
table1.TableFormat.StyleOptions = TableStyleOptions.FirstRow | TableStyleOptions.LastRow |
    TableStyleOptions.FirstColumn | TableStyleOptions.LastColumn | TableStyleOptions.BandedRows;

var table2 = new Table(document, 9, 9);
table2.TableFormat.PreferredWidth = new TableWidth(100, TableWidthUnit.Percentage);
// Specify style and which of the table style conditional formats will be applied.
table2.TableFormat.Style = tableStyle;
table2.TableFormat.StyleOptions = TableStyleOptions.FirstRow | TableStyleOptions.LastRow |
    TableStyleOptions.FirstColumn | TableStyleOptions.LastColumn | TableStyleOptions.BandedColumns;

document.Sections.Add(
    new Section(document,
        new Paragraph(document, "Table with custom style and conditional row banding format (among others) applied."),
        table1,
        new Paragraph(document),
        new Paragraph(document, "Table with custom style and conditional column banding format (among others) applied."),
        table2));

document.Save("CustomTableStyle.docx");
document.Save("CustomTableStyle.pdf");

Except custom (user defined) table styles, GemBox.Document supports a majority of built-in table styles from MS Word 2010 and MS Word 2013.

Supported built-in table styles from MS Word 2010 are:

Supported built-in table styles from MS Word 2013 are:

Note Note

Support for other built-in table styles will be added in future releases of GemBox.Document based on customer feedback.

Following code shows how to create and apply built-in table styles using GemBox.Document component.

var document = new DocumentModel();

// Create built-in table style and associate it with the document.
var colorfulGridAccent1Style = (TableStyle)Style.CreateStyle(StyleTemplateType.ColorfulGridAccent1, document);
document.Styles.Add(colorfulGridAccent1Style);

// Alternative: Get existing or create a new built-in table style from the document.
var gridTable2Accent6Style = (TableStyle)document.Styles.GetOrAdd(StyleTemplateType.GridTable2Accent6);

var table1 = new Table(document, 10, 10);
table1.TableFormat.PreferredWidth = new TableWidth(100, TableWidthUnit.Percentage);
table1.TableFormat.Style = colorfulGridAccent1Style;
table1.TableFormat.StyleOptions = TableStyleOptions.All;

var table2 = new Table(document, 10, 10);
table2.TableFormat.PreferredWidth = new TableWidth(100, TableWidthUnit.Percentage);
table2.TableFormat.Style = gridTable2Accent6Style;
table2.TableFormat.StyleOptions = TableStyleOptions.All;

document.Sections.Add(
    new Section(document,
        new Paragraph(document, "Table with built-in 'ColorfulGridAccent1' style and all conditional formats applied."),
        table1,
        new Paragraph(document),
        new Paragraph(document, "Table with built-in 'GridTable2Accent6' style and all conditional formats applied."),
        table2));

document.Save("BuiltInTableStyle.docx");
document.Save("BuiltInTableStyle.pdf");
Tip Tip

For a demonstration example, check out Table Styles sample from GemBox.Document Sample Explorer.

Formatting properties resolution

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:

  1. value is retrieved from element direct formatting, if formatting property value is set there, otherwise

  2. value is retrieved from element style formatting, if style is present and formatting property value is set there, otherwise

  3. value is retrieved from ancestor element direct formatting, if ancestor element contains the same formatting type and formatting property value is set there, otherwise

  4. 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

  5. value is retrieved from default formatting (DocumentModelDefaultParagraphFormat and DocumentModelDefaultCharacterFormat).

Note 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 FormatClearFormatting.

This will also clear all other formatting properties.

The following example shows formatting properties resolution on CharacterFormatFontColor 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 Note

If document element is inside a table, then resolution of its formatting property is more complex since it depends on a location of a parent table cell inside a table, definition of conditional table style formats on a table style referenced by the parent table (TableTableFormat.Style.ConditionalFormats) and applicability of a table style conditional formats specified on the parent table (TableTableFormat.StyleOptions).

Format caching

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.