Sections and Page Layout

Page size, margins, orientation and page columns belong to a section, and one document can have several: a portrait report with a landscape page for a wide table, a title above two columns of text, an appendix with other margins. Users of a Windows Forms TextControl set them on the Page Layout tab and in the Page Setup dialog box and insert section breaks from the ribbon; your code does the same through Sections and the page properties of the control.

The methods below go into Form1.cs of the application from Create Your First Windows Forms Application and are called from the Click handler of a button. Headers and footers, which also belong to sections, are described in Headers and Footers, and sections in code without a user interface in Sections, Pages, Headers, and Footers.

What a Section Is

A Section is a part of the document with its own page size, margins, orientation, page columns, page border and headers and footers. Every document has at least one section, and sections are numbered from 1.

• A layer over the text. The text, tables and images of a section are in the usual collections of the TextControl; only headers and footers are reached through the section.
• Inherited settings. A new section takes over all settings of the previous one, including its headers and footers, and you change what should differ.
• New page or new line. A section that begins on a new page can have its own page size and headers and footers. A section that begins on a new line changes the number of columns, for example, without a page break.

Set Up Pages in the Ribbon

The Page Layout tab, a RibbonPageLayoutTab, works on the section with the input position:

Next Page inserts a section break after which the new section begins on a new page, Continuous one after which it continues on the next line:

The status bar shows the new section as Section: 2/2, and a header of the new section is labeled with its section number.

The Page Setup dialog box has the tabs Margins and Paper, Headers and Footers, Columns and Frames. On Margins and Paper, Section start sets whether the section begins on a new page, and Apply to chooses between the Whole document and the current Section:

SectionFormatDialog opens the dialog box from code. The zero-based tab index is 0 for margins, page size and orientation, 1 for headers and footers, 2 for page columns and 3 for page borders.

Insert a Section Break From Code

The following methods insert a section in landscape orientation at the input position and open the page setup:

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

public partial class Form1 : Form
{
    private void InsertLandscapeSection()
    {
        // A section break at the input position; the new section begins on a new page
        if (textControl1.Sections.Add(SectionBreakKind.BeginAtNewPage))
        {
            // The input position is now in the new section
            Section section = textControl1.Sections.GetItem();
            section.Format.Landscape = true;
        }
    }

    private void ShowPageSetup()
    {
        // 0 opens the tab with margins, page size and orientation
        textControl1.SectionFormatDialog(0);
    }
}

The code works as follows:

• TextControl.Sections returns the SectionCollection. Add inserts a section break at the input position, with BeginAtNewPage or BeginAtNewLine from SectionBreakKind, and returns true if it was added. A break inside a paragraph splits it in two.
• SectionCollection.GetItem without a parameter returns the section with the input position, which after Add is the new one.
• Section.Format returns the SectionFormat of the section, and Landscape turns its pages. The sections after it inherit the orientation, so set Landscape back to false in the section where portrait pages continue.
• textControl1.Sections[2] returns a section by its number through the indexer, for code that formats a section other than the one with the input position.
• SectionFormatDialog(0) opens the Margins and Paper tab.

Format a Section

A SectionFormat holds the page settings of one section:

Page sizes and margins are measured in the unit of TextControl.PageUnit, 1/100 inch by default, and column widths, lines and page borders in twips. Selection.SectionFormat reads and sets the settings of the selected text; when the selection spans sections with different settings, Columns returns 0. Sections, Pages, Headers, and Footers shows columns, margins and page borders in code.

Show the Current Section

The StatusBar of TX Text Control shows the section of the input position. Your own label can do the same with the SectionChanged event, which occurs when the input position moves to another section:

private void ShowSectionNumber()
{
    textControl1.SectionChanged += (sender, e) =>
    {
        // Sections are numbered from 1
        sectionLabel.Text = $"Section {textControl1.InputPosition.Section} of {textControl1.Sections.Count}";
    };
}

sectionLabel is a Label on your form. Call ShowSectionNumber once, for example in the constructor of the form. InputPosition.Section is the number of the section with the input position, and Sections.Count the number of sections.

Set the Page Format of the Whole Document

TextControl.PageSize, PageMargins and Landscape set the page format of all sections at once; Set the Page Format shows them in code. A PageSize takes the width and height in 1/100 inch, for example new PageSize(827, 1169) for A4, and ResetPageSize returns to the default, US letter. When the page settings change, the control raises PageFormatChanged. To make a document with several sections a document with one page layout, delete its section breaks, as Sections, Pages, Headers, and Footers shows.

Next Steps

• Headers and Footers: give a section its own header and restart page numbers.
• Tables and Table Formulas: fill the landscape page with a wide table.
• Printing and Print Preview: print the pages you set up.
• Sections, Pages, Headers, and Footers: sections with ServerTextControl.