Headers and Footers

Headers and footers repeat on every page of a section: a letterhead, a report title, "Page 3 of 12". In a Windows Forms TextControl, users add them from the ribbon or the Page Setup dialog box and type into them after activating them with the mouse. Your code adds them, fills them with text and page numbers, decides how they're activated and follows the user between header, footer and main text.

The examples are methods of Form1.cs in the application from Create Your First Windows Forms Application, called from the Click handler of a button. A section is a part of a document with its own page settings, which Sections and Page Layout introduces. For headers and footers added without a user interface, see Sections, Pages, Headers, and Footers.

How Headers and Footers Work

A HeaderFooter is a text part with its own Selection, paragraphs, tables and images. Each section has a HeaderFooterCollection in Section.HeadersAndFooters. TextControl.HeadersAndFooters is the collection of the whole document; a header or footer added to it goes to the first section, and every other section receives one connected to the previous section. Once a document has more than one section, use the collection of the section, because most collections of a HeaderFooter from the document's collection are then null.

Each header or footer has a type from HeaderFooterType:

A new section takes over the headers and footers of the previous one, connected to them so that both show the same content. HeaderFooter.ConnectedToPrevious set to false gives a section a header of its own.

Add Headers and Footers in the Ribbon

The Headers & Footers group of the Insert tab has three buttons:

• Header edits the header of the current section, and its menu has Edit Header and Remove Header.
• Footer does the same for the footer, with Edit Footer and Remove Footer.
• Page Number is enabled while a header or footer is being edited. Its menu has Insert Page Number, Format Page Number... and Remove Page Number.

While a header or footer is activated, the input position is inside it. TX Text Control Words marks an activated header with a dashed line and a label such as First Header:

The Headers and Footers tab of the Page Setup dialog box sets all headers and footers at once. Header, Header on first, Footer and Footer on first choose the design, Different header odd and even and Different footer odd and even add the even variants, and Distance from edge sets the positions. With Apply to set to Whole document, the Header and Footer lists offer None, All sections equal and All sections different; for the current section, None, Same as previous section and This section different.

SectionFormatDialog opens this dialog box from code, and SectionFormatDialog(1) opens it on the Headers and Footers tab.

Add a Footer With Page Numbers

A PageNumberField shows the number of the page it's on. It's only possible in a header or footer and is added through HeaderFooter.PageNumberFields. The following method adds a centered footer with "Page x of y" to the section with the input position:

using System;
using System.Windows.Forms;
using TXTextControl;

public partial class Form1 : Form
{
    private void AddPageNumberFooter()
    {
        // Add a footer to the section with the input position
        Section section = textControl1.Sections.GetItem();
        section.HeadersAndFooters.Add(HeaderFooterType.Footer);
        HeaderFooter footer = section.HeadersAndFooters.GetItem(HeaderFooterType.Footer);

        // "Page x of y"
        footer.Selection.Text = "Page ";
        footer.PageNumberFields.Add(new PageNumberField(1, NumberFormat.ArabicNumbers));
        footer.Selection.Text = " of ";

        PageNumberField numberOfPages = new PageNumberField();
        numberOfPages.ShowNumberOfPages = true;
        footer.PageNumberFields.Add(numberOfPages);

        footer.Selection.ParagraphFormat.Alignment = TXTextControl.HorizontalAlignment.Center;

        // 0.5 inch from the bottom of the page, in twips
        footer.Distance = 720;
    }
}

The code works as follows:

• SectionCollection.GetItem without a parameter returns the section with the input position.
• HeaderFooterCollection.Add adds a footer and returns true if it was added, and GetItem returns it. GetItem throws an ArgumentException for a type the section doesn't have.
• footer.Selection.Text inserts text at the input position of the footer.
• The PageNumberField constructor takes the start number and a NumberFormat: ArabicNumbers, Letters, CapitalLetters, RomanNumbers or SmallRomanNumbers. ShowNumberOfPages makes the second field show the number of pages.
• HeaderFooter.Distance is the distance from the bottom of the page to the bottom of the footer in twips; the default is 567 twips, 1 cm.
• HorizontalAlignment is written with its namespace, because Form1.cs also uses System.Windows.Forms, which has a type of the same name.

Every page now shows its number and the number of pages, and the fields follow when pages are added.

Control How Users Edit Headers and Footers

Two properties of the TextControl decide how a header or footer is entered and shown, and two events report it. The following methods set them up and move the input position into the header from code:

using System;
using System.Windows.Forms;
using TXTextControl;

public partial class Form1 : Form
{
    private void ConfigureHeaders()
    {
        // Open headers and footers with a double-click and mark them with a line
        textControl1.HeaderFooterActivationStyle = HeaderFooterActivationStyle.ActivateDoubleClick;
        textControl1.HeaderFooterFrameStyle = HeaderFooterFrameStyle.DividingLine;

        textControl1.HeaderFooterActivated += TextControl1_HeaderFooterActivated;
        textControl1.HeaderFooterDeactivated += TextControl1_HeaderFooterDeactivated;
    }

    private void TextControl1_HeaderFooterActivated(object sender, HeaderFooterEventArgs e)
    {
        Text = "Editing: " + e.HeaderFooter.Type;
    }

    private void TextControl1_HeaderFooterDeactivated(object sender, HeaderFooterEventArgs e)
    {
        Text = "Editing: main text";
    }

    private void EditHeader()
    {
        Section section = textControl1.Sections.GetItem();

        // GetItem throws an ArgumentException for a header that doesn't exist
        bool hasHeader = false;

        foreach (HeaderFooter headerFooter in section.HeadersAndFooters)
        {
            if (headerFooter.Type == HeaderFooterType.Header)
            {
                hasHeader = true;
            }
        }

        if (!hasHeader)
        {
            section.HeadersAndFooters.Add(HeaderFooterType.Header);
        }

        // Move the input position into the header
        section.HeadersAndFooters.GetItem(HeaderFooterType.Header).Activate();
    }
}

The code works as follows:

• HeaderFooterActivationStyle is ActivateClick for a single click into a header or footer, or ActivateDoubleClick for a double-click.
• HeaderFooterFrameStyle marks an activated header or footer with a DividingLine to the main text, a DottedFrame, a SingleFrame or NoFrame.
• HeaderFooterActivated occurs when a header or footer receives the input position, and HeaderFooterDeactivated when it loses it. HeaderFooterEventArgs.HeaderFooter is the header or footer, and its Type tells which one. The example writes it into the title bar of the form.
• HeaderFooter.Activate moves the input position into the header, as Edit Header does, and Deactivate moves it back to the main text. Both return true if they succeeded. Call textControl1.Focus() after Activate when a button of your own opens the header, so that the user can type into it at once.

HeaderFooterCollection.Remove removes headers and footers by type; Remove(HeaderFooterType.Header) removes the even header too, if there is one. Add and Remove also accept several values combined, such as HeaderFooterType.Header | HeaderFooterType.Footer.

Put Images and Other Content Into a Header

A header has the same collections as the main text: HeaderFooter.Images takes a logo, HeaderFooter.Tables a table and HeaderFooter.Barcodes a barcode, with the same Add methods as in Images and Charts and Barcodes. An image in a header that lies behind the text appears on every page of the section, like a watermark. The blog article Merging Multiple Records with First-Page Headers and Footers combines first page headers with a mail merge.

Next Steps

• Sections and Page Layout: give a section its own page settings and headers.
• Fields, Hyperlinks, and Bookmarks: the other fields of a document.
• Footnotes: notes at the bottom of the page.
• Sections, Pages, Headers, and Footers: headers and footers with ServerTextControl.