Headers & footers

Version 6.1.0

In this article

This article describes how headers and footers are added to a MigraDoc document.

Setting up headers & footers

You can create a simple header for a section like this:

// Set up header.
var header = section.Headers.Primary;
header.AddParagraph("Test document");

See full SettingUp sample in PDFsharp.Sample repository. Show resulting PDF

You can add various content here like paragraphs, tables, text frames, images, and charts. In most cases, you will probably set up a header by adding a paragraph.

A footer can be set up similarly by calling the Footers property of the Section instance instead of the Headers property.

MigraDoc has pre-defined styles for headers and footers (see Document / Formatting for more information). Use the Header and Footer constants of the StyleNames class to access them. You can set up the header style like this:

// Style for header.
var style = document.Styles[StyleNames.Header];
style.ParagraphFormat.Alignment = ParagraphAlignment.Center;

See full SettingUp sample in PDFsharp.Sample repository. Show resulting PDF

It is not required to assign the header and footer styles to the header and footer content, as all header and footer content will automatically inherit the format from the appropriate style.

Scope of headers & footers

Headers and footers are always bound to a section. But the next section will continue using a copy of the previous header respectively footer, if it has no own header respectively footer. So, you have to assign a new HeaderFooter instance if you want to clear it beginning with the current section:

// If no footer is set here, the footer will be copied from the previous section.
// Overwrite the inherited footer with an empty one.
section.Footers.Primary = new HeaderFooter();

See full SettingUp sample in PDFsharp.Sample repository. Show resulting PDF

If you are working with different headers and footers for first and even pages (see First & even pages), you may have to clean up even more. This is because this behavior also applies to the EvenPage and FirstPage properties of section.Headers and section.Footers. The properties from section.PageSetup, like OddAndEvenPagesHeaderFooter and DifferentFirstPageHeaderFooter, are also inherited from the previous section (see Formats / Page setup for more information).

Also, if you set OddAndEvenPagesHeaderFooter and DifferentFirstPageHeaderFooter back to false, you should clear all mentioned properties. Otherwise, they could be accidentally reactivated in a later section. So, for cleaning up you may add these lines once for the header and once for the footer:

// If no footers are set here, the footers will be copied from the previous section.
// Overwrite the inherited footer with empty ones.
section.Footers.Primary = new HeaderFooter();
section.Footers.EvenPage = new HeaderFooter();
section.Footers.FirstPage = new HeaderFooter();

See full FirstAndEvenPages sample in PDFsharp.Sample repository. Show resulting PDF

Presenting various information

Of course, you can create headers and footers with much more complex content. An easy way to organize various information in a header or footer is using tab stops (see Formats / TabStops for more information):

// Style for footer.
style = document.Styles[StyleNames.Footer];
style.ParagraphFormat.ClearAll();
style.ParagraphFormat.TabStops.AddTabStop(Unit.FromCentimeter(8), TabAlignment.Center);
style.ParagraphFormat.TabStops.AddTabStop(Unit.FromCentimeter(16), TabAlignment.Right);
…
// Set up footer.
var footer = section.Footers.Primary;
var paragraph = footer.AddParagraph("\tSection one\t");
paragraph.AddPageField();

See full SettingUp sample in PDFsharp.Sample repository. Show resulting PDF

The position parameter of AddTabStop is of type Unit (see Formats / Unit for more information).

For more information about page fields see Fields.

First & even pages

By now we only used the Primary property of section.Headers and section.Footers. Usually, they are applied to all pages of a section. But with MigraDoc you can also specify own headers and footers for even pages and special ones for the first page of a section.

If you want to use differing headers and footers for odd and even pages, you have to activate it in the section’s page setup. Afterwards, you can set up the primary headers and footers and those for even pages. But you may have noticed that using the EvenPage property can only be activated for headers and footers together. In the following example, we want the header to be identical and the footer to vary. So, we assign a copy of the primary header to the even page header. Note also the tabs "\t" inside the footer. The code excerpt shown in Presenting various information is necessary to format the content correctly.

// Use the EvenPage header and footer.
section.PageSetup.OddAndEvenPagesHeaderFooter = true;
…
// Set up primary header with short document title.
var header = section.Headers.Primary;
header.AddParagraph("Test document");

// Despite of OddAndEvenPagesHeaderFooter, even pages shall use the same header as odd ones.
section.Headers.EvenPage = section.Headers.Primary.Clone();
…
// Set up primary footer with page number on the right.
var footer = section.Footers.Primary;
var paragraph = footer.AddParagraph("\tSection one\t");
paragraph.AddPageField();

// Set up even page footer with page number on the left.
footer = section.Footers.EvenPage;
paragraph = footer.AddParagraph();
paragraph.AddPageField();
paragraph.AddText("\tSection one");

See FirstAndEvenPages sample in PDFsharp.Sample repository. Show resulting PDF

For more information about page fields see Fields.

With or without special headers and footers for even pages, you may add ones for the first page of the section. Also, here you have to activate it in the page setup. And, of course, you have to set up the first page header and footer.

// Use the FirstPage header and footer.
section.PageSetup.DifferentFirstPageHeaderFooter = true;
…
// Set up first page header with long document title.
header = section.Headers.FirstPage;
header.AddParagraph("The Test document");
…
// Set up first page footer without page number.
footer = section.Footers.FirstPage;
footer.AddParagraph("\tSection one");

See FirstAndEvenPages sample in PDFsharp.Sample repository. Show resulting PDF

If you use even or first page headers and footers, you may want to reset them in the next section (see Scope of headers & footers for more information).

Size & position

The position of the header and footer is set in the page setup (see Formats / Page setup). The HeaderDistance property defines the distance from the page’s top border to the top of the header. FooterDistance defines the distance from the page’s bottom border to the bottom of the footer.

// Set header and footer distance from page border.
section.PageSetup.HeaderDistance = Unit.FromCentimeter(0.75);
section.PageSetup.FooterDistance = Unit.FromCentimeter(0.75);

See SizeAndPosition sample in PDFsharp.Sample repository. Show resulting PDF

The distance properties are of the type Unit (see Formats / Unit for more information).

If not set, a distance of 1.25 centimeters is inherited from the default page setup.

These properties only define the start position of the header and the end position of the footer. Header and footer will grow towards the middle of the page. You have to take care that header, footer, and page content won’t overlap.

The width and the margins to the left and right page borders of headers and footers are equal to the ones of the page content itself (see Formats / Page setup for more information). To realize different margins for the header or footer, you can work around with positive or negative indents (see Formats / Paragraph for more information).