Formattings Styles

Formattings and styles are a means to set visual properties like color, font, size, alignment, positioning etc. to your document content elements.

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.

FormatParagraphFormatListFormatCharacterFormatTableFormatTableRowFormatTableCellFormatTableStyleFormat
Format class diagram

Formattings can be set directly on elements, such as ParagraphFormat or CharacterFormat or they can be set indirectly, through styles, such as ParagraphFormat or CharacterFormat.

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

Note

If Text is Empty, then Run and its CharacterFormat won't be saved to DOCX.

In that case, if Run is the last or the only element in the parent Paragraph, use CharacterFormatForParagraphMark of the parent paragraph to save character (font) formatting to DOCX.

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.

StyleParagraphStyleListStyleTableStyleCharacterStyleConditionalFormatsParagraphFormatCharacterFormatTableFormatRowFormatCellFormatParagraphFormatCharacterFormatListLevelFormatsCharacterFormat
Style class diagram
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 Styles collection to be used.

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

Tip

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

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 ConditionalFormats 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

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

For a demonstration example, check out Table Styles example from GemBox.Document Examples.

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 (DefaultParagraphFormat and DefaultCharacterFormat).
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 ClearFormatting(). This will also clear all other formatting properties.

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

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 (TableFormat.Style.ConditionalFormats) and applicability of a table style conditional formats specified on the parent table (TableFormat.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.