Formatting

Version 6.1.0

In this article

• Direct formatting
• Styles
• Default styles
• Inheritance

This article describes how a MigraDoc document can be formatted using direct formatting and styles. Furthermore, it is explained, how set formats are inherited from parent to child objects and from inherited styles.

Direct formatting

For most use cases, we recommend using styles instead of direct formatting (see Styles for more information). However, as direct formatting is the most simple way of formatting, it is explained first.

Direct formatting is simply done by setting properties of the object:

paragraph.Format.Font.Size = Unit.FromPoint(20);
paragraph.Format.SpaceBefore = Unit.FromPoint(7);

See full DirectFormatting sample in Formatting in PDFsharp.Sample repository. Show resulting PDF

As you can see, you’ll probably have to navigate through different properties to set the desired one. If you want to set a specific format, check Formats.

Styles

Styles make document formatting much clearer and easier to maintain. By using styles, you can define a format at one single place to use it whenever you want. You can inherit from an existing style to introduce a slightly different style without redefining all aspects of the format. If you want to change the format of headings or quotes in your document, simply adjust the corresponding style instead of searching and editing each occurrence.

There is a set of predefined styles in MigraDoc (see Default Styles). As those styles mostly are not yet formatted, this is the first thing to do. All styles needed should be defined and formatted before adding the document’s content.

To edit a defined style, you can get it by its name via document.Styles:

// Set font Size and SpaceBefore for Heading1 style.
var style = document.Styles[StyleNames.Heading1];
style.Font.Size = Unit.FromPoint(20);
style.ParagraphFormat.SpaceBefore = Unit.FromPoint(7);

See full DefaultStyle sample in Formatting in PDFsharp.Sample repository. Show resulting PDF

If you want to set a specific format, check Formats.

StyleNames.Heading1 is a paragraph style and allows formatting the font as well as paragraph-related formats like spacing and borders. StyleNames.Hyperlink in contrast is a character style and allows only formatting the font as it is intended for inline text only.

You can then use this style by assigning its name to the desired object:

// Use Heading1 style for paragraph.
paragraph.Style = StyleNames.Heading1;

See full DefaultStyle sample in Formatting in PDFsharp.Sample repository. Show resulting PDF

Those properties not set on the Style object will be inherited from its base style (see Inheritance).

Note that Heading1 is only a string defining the name of the style. When introducing own styles, you can organize their names in an own enum, constants, or whatever way you want.

Use the AddStyle method to add a new style. You have to assign a base style this style will be inherited of. Doing that, a paragraph style must inherit from a paragraph style and a character style must inherit from a character style. If there’s no specific style you want to inherit from, you can inherit from StyleNames.Normal for paragraph styles and from StyleNames.DefaultParagraphFont for character styles:

const string codeBlockStyleName = "code block";

// Set font name and left indent for code block style.
var style = document.Styles.AddStyle(codeBlockStyleName, StyleNames.Normal);
style.Font.Name = "Courier New";
style.ParagraphFormat.LeftIndent = Unit.FromCentimeter(1);
style.ParagraphFormat.SpaceBefore = Unit.FromPoint(7);
style.ParagraphFormat.SpaceAfter = Unit.FromPoint(7);

See full OwnStyle sample in Formatting in PDFsharp.Sample repository. Show resulting PDF

If you want to set a specific format, check Formats.

If you’re using the Core build of MigraDoc, you may need to write an own font resolver to use a specific font (see Font resolving for more information).

After defining your own style, you can use it the same way as the predefined ones:

// Use code block style for paragraph.
paragraph.Style = codeBlockStyleName;

See full OwnStyle sample in Formatting in PDFsharp.Sample repository. Show resulting PDF

Note that a style must be defined before being used as a base style. If a style is not correctly defined and used, the InvalidStyleName will be used instead. This will result in an eye-catching magenta and dashed underlined text.

Default styles

There’s a set of predefined styles for the most common applications, which names are defined in the StyleNames enum. This includes paragraph styles for nine levels of headings (Heading1 - Heading9), List, Footnote and Header and Footer. With Hyperlink there is also a good example of a character style provided, as a hyperlink is only a part of text of the containing paragraph.

The paragraph style Normal and the character style DefaultParagraphFont are used when no style is defined. Furthermore, they are the root styles to use as base style when defining new styles.

Out of the box the predefined styles have little format assigned. Normal is defined as Arial 10 pt (which can be overridden by you). Due to inheritance, all text uses this font and size, if you don't edit any style.

The defined paragraph styles directly or indirectly inherit from Normal, while each heading style inherits directly from the heading style above. This way you can edit the heading styles by only assigning the format changes to the upper heading.

Hyperlink as a character style inherits from DefaultParagraphFont. DefaultParagraphFont itself is empty by design. Due to inheritance, a FormattedText object using DefaultParagraphFont will inherit the font format from the parent paragraph.

The heading style names only come with the corresponding OutlineLevel enum value assigned, ensuring that they are correctly displayed in the document outline. Assigning formats to the default styles and defining new styles is all up to you, when creating your document.

Except for DefaultParagraphFont, which must be kept as it is, you can modify every default style. You can also set a new base style to add a new style as a new layer in between:

const string headingBaseStyleName = "Heading";

// Set bold for all heading styles on new style layer.
var style = document.AddStyle(headingBaseStyleName, StyleNames.Normal);
style.Font.Bold = true;

// Change Heading1 to inherit from the new style layer.
style = document.Styles[StyleNames.Heading1];
style.BaseStyle = headingBaseStyleName;
style.Font.Size = Unit.FromPoint(20);

See full ModifyBaseStyle sample in Formatting in PDFsharp.Sample repository. Show resulting PDF

If you want to set a specific format, check Formats.

Inheritance

As said before, for each style except Normal and DefaultParagraphFont from StyleNames a base style must be defined. Regarding the document’s content, each object will have a parent, except the Document object itself, which is the root of the tree.

When evaluating the format to use, the properties of the object itself have priority. So, if a property is set directly at the object and also in the used style, the value of the property is considered instead the one set by the style.

If a property is not directly set, the used style is considered.

If the property is also not set in the style, its base style is inquired.

If the property is not set in any of the base styles, the value of the parent object will be inherited, which is calculated the same way.

Consider the following example:

// Set and use styles and direct formatting to show, how inheritance works.

// Set Normal style.
var style = document.Styles[StyleNames.Normal];
style.Font.Name = "times new roman";
style.Font.Size = Unit.FromPoint(12);

// Set Heading1 style.
style = document.Styles[StyleNames.Heading1];
style.Font.Size = Unit.FromPoint(20); 
style.Font.Bold = true;
style.ParagraphFormat.SpaceBefore = Unit.FromPoint(20);

// Set Heading2 style.
style = document.Styles[StyleNames.Heading2];
style.Font.Size = Unit.FromPoint(18);
style.Font.Italic = true;
style.ParagraphFormat.SpaceBefore = Unit.FromPoint(10);
style.ParagraphFormat.SpaceAfter = Unit.FromPoint(10);

…

section.AddParagraph("Example for inheritance.");

var paragraph1 = section.AddParagraph("Heading 1: ");
paragraph1.Style = StyleNames.Heading1;
paragraph1.Format.Font.Underline = Underline.Single;

var formattedText1 = paragraph1.AddFormattedText("Red");
formattedText1.Color = Colors.Red;
formattedText1.Bold = false;

var paragraph2 = section.AddParagraph("Heading 2: ");
paragraph2.Style = StyleNames.Heading2;

var formattedText2 = paragraph2.AddFormattedText("Blue");
formattedText2.Color = Colors.Blue;
formattedText2.Italic = false;

var paragraph3 = section.AddParagraph("Whole text in ");
paragraph3.Style = StyleNames.Normal;
paragraph3.Format.Font.Color = Colors.Green;

var formattedText3 = paragraph3.AddFormattedText("green");
formattedText3.Bold = true;

See full Inheritance sample in Formatting in PDFsharp.Sample repository. Show resulting PDF

Size, SpaceBefore and SpaceAfter are properties of the type Unit (see Formats / Unit for more information).

Color is a property of the type Color (see Formats / Colors for more information).

If you want to set a specific format, check Formats.

In this example a lot of inheritance happens. There are also some inherited properties that get overridden.

This is the same code, with comments added for every inherited or overridden property:

// Set and use styles and direct formatting to show, how inheritance works.
// Overridden and inherited values are explained for each style and document object in the following comments.

// Set Normal style.
var style = document.Styles[StyleNames.Normal];
style.Font.Name = "times new roman";
style.Font.Size = Unit.FromPoint(12);

// Set Heading1 style.
style = document.Styles[StyleNames.Heading1];
style.Font.Size = Unit.FromPoint(20); 
style.Font.Bold = true;
style.ParagraphFormat.SpaceBefore = Unit.FromPoint(20); // Overrides 'Unit.FromPoint(12)' from Normal.
// 'Font.Name = "times new roman"' will be inherited from Normal.

// Set Heading2 style.
style = document.Styles[StyleNames.Heading2];
style.Font.Size = Unit.FromPoint(18); // Overrides 'Unit.FromPoint(20)' from Heading1.
style.Font.Italic = true;
style.ParagraphFormat.SpaceBefore = Unit.FromPoint(10); // Overrides 'Unit.FromPoint(20)' from Heading1.
style.ParagraphFormat.SpaceAfter = Unit.FromPoint(10);
// 'Font.Bold = true' will be inherited from Heading1.
// 'Font.Name = "times new roman"' will be inherited from Heading1 > Normal.

…

section.AddParagraph("Example for inheritance.");
// 'Font.Name = "times new roman"' will be inherited from Normal.
// 'Font.Size = Unit.FromPoint(12)' will be inherited from Normal.

var paragraph1 = section.AddParagraph("Heading 1: ");
paragraph1.Style = StyleNames.Heading1;
paragraph1.Format.Font.Underline = Underline.Single;
// 'Font.Size = Unit.FromPoint(20)' will be inherited from Heading1.
// 'Font.Bold = true' will be inherited from Heading1.
// 'ParagraphFormat.SpaceBefore = Unit.FromPoint(20)' will be inherited from Heading1.
// 'Font.Name = "times new roman"' will be inherited from Heading1 > Normal.

var formattedText1 = paragraph1.AddFormattedText("Red");
formattedText1.Color = Colors.Red;
formattedText1.Bold = false; // Overrides 'true' from paragraph1 > Heading1.
// 'Font.Underline' = will be inherited from paragraph1.
// 'Font.Size = Unit.FromPoint(20)' will be inherited from paragraph1 > Heading1.
// 'ParagraphFormat.SpaceBefore = Unit.FromPoint(20)' from paragraph1 > Heading1 is not relevant for formattedText1.
// 'Font.Name = "times new roman"' will be inherited from paragraph1 > Heading1 > Normal.

var paragraph2 = section.AddParagraph("Heading 2: ");
paragraph2.Style = StyleNames.Heading2;
// 'Font.Size = Unit.FromPoint(18)' will be inherited from Heading2.
// 'Font.Italic = true' will be inherited from Heading2.
// 'ParagraphFormat.SpaceBefore = Unit.FromPoint(10)' will be inherited from Heading2.
// 'ParagraphFormat.SpaceAfter = Unit.FromPoint(10)' will be inherited from Heading2.
// 'Font.Bold = true' will be inherited from Heading2 > Heading1.
// 'Font.Name = "times new roman"' will be inherited from Heading2 > Heading1 > Normal.

var formattedText2 = paragraph2.AddFormattedText("Blue");
formattedText2.Color = Colors.Blue;
formattedText2.Italic = false; // Overrides 'true' from paragraph2 > Heading2.
// 'Font.Size = Unit.FromPoint(18)' will be inherited from Heading2.
// 'ParagraphFormat.SpaceBefore = Unit.FromPoint(10)' from Heading2 is not relevant for formattedText2.
// 'ParagraphFormat.SpaceAfter = Unit.FromPoint(10)' from Heading2 is not relevant for formattedText2.
// 'Font.Bold = true' will be inherited from Heading2 > Heading1.
// 'Font.Name = "times new roman"' will be inherited from Heading2 > Heading1 > Normal.

var paragraph3 = section.AddParagraph("Whole text in ");
paragraph3.Style = StyleNames.Normal;
paragraph3.Format.Font.Color = Colors.Green;
// 'Font.Name = "times new roman"' will be inherited from Normal.
// 'Font.Size = Unit.FromPoint(12)' will be inherited from Normal.

var formattedText3 = paragraph3.AddFormattedText("green");
formattedText3.Bold = true;
// 'Font.Color = Colors.Green' will be inherited from paragraph3.
// 'Font.Name = "times new roman"' will be inherited from Normal.
// 'Font.Size = Unit.FromPoint(12)' will be inherited from Normal.

See full Inheritance sample in Formatting in PDFsharp.Sample repository. Show resulting PDF

Size, SpaceBefore and SpaceAfter are properties of the type Unit (see Formats / Unit for more information).

Color is a property of the type Color (see Formats / Colors for more information).