Formats and Styles

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

Formats

Formats are objects which contain visual information about document content element.

Following class diagram shows all format class objects available in GemBox.Document.

Each format class in the diagram links to its help page, so you can easily navigate to the details of each format.

FormatParagraphFormatListFormatCharacterFormatTableFormatTableRowFormatTableCellFormatTableStyleFormat
Format class diagram

Formats 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 formats for paragraphs and text can be set via DefaultParagraphFormat and DefaultCharacterFormat properties. All newly created Paragraphs and Runs will inherit those format properties. For more information about format property resolution, see here.

Note

If Text is , 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) format to DOCX.

Styles

Styles are objects which contain visual information about one or more document content elements.

They have an advantage over direct formats because their format 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 all style class objects 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 formats 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 format properties, however a table style is much more powerful and it allows you to define following formats:

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 format properties as a TableStyle (formats 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 effect on the particular region of the table, a format properties on element contained in that region of a table are 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.

Format property resolution

Format properties for an element can be set on multiple places: element formats, element styles, and default formats.

GemBox.Document calculates or resolves format properties, so you have the same format properties for an element as when it is rendered by a document processing application like Microsoft Word.

Format property values are resolved in the following order:

  1. element format
  2. element style
  3. ancestor element format
  4. ancestor element style
  5. default format (DefaultParagraphFormat and DefaultCharacterFormat).
Note

If you want to clear a format property value, for example, remove font weight from text format, don't do charFormat.Bold = false;. This will not clear the property value, it will just set its value to false. To clear the value, so that when it is resolved, it gets picked from the next source in format resolution order, use ClearFormatting(). This will also clear all other format properties.

The following example shows format property resolution on FontColor:

// 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 paragraph = new Paragraph(doc, run1, run2, run3);

// Add document content: run1, run2, run3 are in first paragraph, run4 is in second paragraph.
doc.Sections.Add(new Section(doc, paragraph, 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 and character style to run1 and run2.
paragraph.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 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 element format.
Debug.Assert(run1.CharacterFormat.FontColor == Color.Red);
// run2 font color is blue - from element style.
Debug.Assert(run2.CharacterFormat.FontColor == Color.Blue);
// run3 font color is green - from ascendant paragraph style. 
Debug.Assert(run3.CharacterFormat.FontColor == Color.Green);
// run4 font color is yellow - from default document format.
Debug.Assert(run4.CharacterFormat.FontColor == Color.Yellow);
Note

If document element is inside a table, then resolution of its format properties 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 format data.

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