# Sections

> Divide documents into sections with ServerTextControl: section breaks, SectionFormat, landscape pages, page columns, margins, page borders and loaded sections.

- **Product:** TX Text Control .NET Server
- **Section:** Documentation
- **Kind:** Topic
- **Path:** TX Text Control .NET Server > Document Processing > Sections
- **5556 words**
- **Web URL:** https://docs.textcontrol.com/tx-text-control-dotnet-server/document-processing/sections/
- **LLMs URL:** https://docs.textcontrol.com/tx-text-control-dotnet-server/document-processing/sections/llms.txt
- **LLMs-Full URL:** https://docs.textcontrol.com/tx-text-control-dotnet-server/document-processing/sections/llms-full.txt

---

Sections let one document mix page layouts: a portrait report with a landscape page for a wide table, a heading above two columns of text or an appendix with its own margins. `ServerTextControl` inserts section breaks, formats each section and reads the sections of the documents you load.

The programs below are console applications, each a complete *Program.cs*. The page format of a document with a single section is set in [Creating Documents](https://docs.textcontrol.com/tx-text-control-dotnet-server/document-processing/creating/llms-full.txt), and the headers and footers of a section in [Headers and Footers](https://docs.textcontrol.com/tx-text-control-dotnet-server/document-processing/headers-footers/llms-full.txt).

### What a Section Is

A [Section](https://docs.textcontrol.com/tx-text-control-dotnet-server/reference/txtextcontrol/section/llms-full.txt) is a part of a document that has its own page size, page margins, orientation, page columns and headers and footers. Every document has at least one section, and sections are numbered from 1.

- **Sections are a layer over the text.** The text, tables and images of a section are in the usual collections of `ServerTextControl`, such as `Tables` and `Images`. Only the headers and footers are reached through the section.
- **A new section inherits.** When you insert a section break, the new section takes over all settings of the previous one, and you change the settings that should differ.
- **Some settings need a new page.** The page size and different headers and footers can only change at a section that begins on a new page.

Documents that you load bring their sections along. A mail merge that appends several records to one document also creates sections: each record starts a new one.

### Insert a Section Break

[ServerTextControl.Sections](https://docs.textcontrol.com/tx-text-control-dotnet-server/reference/txtextcontrol/servertextcontrol/sections-property/llms-full.txt) returns the [SectionCollection](https://docs.textcontrol.com/tx-text-control-dotnet-server/reference/txtextcontrol/sectioncollection/llms-full.txt) of the document. [SectionCollection.Add](https://docs.textcontrol.com/tx-text-control-dotnet-server/reference/txtextcontrol/sectioncollection/add-method/llms-full.txt) inserts a section break at the current input position and returns `true` if the section was added. If the input position is inside a paragraph or a table, the break splits it in two. The parameter is a value of [SectionBreakKind](https://docs.textcontrol.com/tx-text-control-dotnet-server/reference/txtextcontrol/sectionbreakkind/enumeration/llms-full.txt):

| Value | The new section begins |
|---|---|
| `BeginAtNewPage` | On the next page, with a new paragraph |
| `BeginAtNewLine` | On the next line, with a new paragraph |

A second overload, `Add(SectionBreakKind, int)`, inserts the break at a text position instead of the input position.

The following program creates a report whose second section is in landscape orientation:

```csharp
using TXTextControl;

using (ServerTextControl tx = new ServerTextControl())
{
    tx.Create();

    // Section 1: portrait, the default
    tx.Selection.Text = "Quarterly Report\r\nThis part is in portrait orientation.";

    // Section 2: begins on a new page and is turned to landscape
    tx.Sections.Add(SectionBreakKind.BeginAtNewPage);
    tx.Selection.Text = "This part has room for a wide table.";
    tx.Sections[2].Format.Landscape = true;

    // Section 3: inherits landscape from section 2, so turn it back
    tx.Sections.Add(SectionBreakKind.BeginAtNewPage);
    tx.Selection.Text = "The report continues in portrait orientation.";
    tx.Sections[3].Format.Landscape = false;

    foreach (Section section in tx.Sections)
    {
        Console.WriteLine($"Section {section.Number} of {tx.Sections.Count}: landscape {section.Format.Landscape}");
    }

    tx.Save("orientation.pdf", StreamType.AdobePDF);
}
```

The code works as follows:

- Each `Add` inserts a break, and the text that follows goes into the new section.
- `tx.Sections[2]` returns the section with the number 2 through the collection's [indexer](https://docs.textcontrol.com/tx-text-control-dotnet-server/reference/txtextcontrol/sectioncollection/item-property/llms-full.txt). [GetItem](https://docs.textcontrol.com/tx-text-control-dotnet-server/reference/txtextcontrol/sectioncollection/getitem-method/llms-full.txt) without a parameter returns the section that contains the input position.
- [Section.Format](https://docs.textcontrol.com/tx-text-control-dotnet-server/reference/txtextcontrol/section/format-property/llms-full.txt) returns the [SectionFormat](https://docs.textcontrol.com/tx-text-control-dotnet-server/reference/txtextcontrol/sectionformat/llms-full.txt) of the section, and [Landscape](https://docs.textcontrol.com/tx-text-control-dotnet-server/reference/txtextcontrol/sectionformat/landscape-property/llms-full.txt) turns its pages.
- Section 3 inherits landscape orientation from section 2, so the program sets it back to portrait.

Open *orientation.pdf*: the second page is in landscape orientation, the first and third in portrait.

### Format a Section

`SectionFormat` holds the page settings of a section. Change its properties through `Section.Format`:

| Property | Sets | Default |
|---|---|---|
| [Landscape](https://docs.textcontrol.com/tx-text-control-dotnet-server/reference/txtextcontrol/sectionformat/landscape-property/llms-full.txt) | Landscape (`true`) or portrait (`false`) orientation | `false` |
| [BreakKind](https://docs.textcontrol.com/tx-text-control-dotnet-server/reference/txtextcontrol/sectionformat/breakkind-property/llms-full.txt) | Whether the section begins on a new page or a new line | `BeginAtNewPage` |
| [Columns](https://docs.textcontrol.com/tx-text-control-dotnet-server/reference/txtextcontrol/sectionformat/columns-property/llms-full.txt) | The number of page columns | `1` |
| [EqualColumnWidth](https://docs.textcontrol.com/tx-text-control-dotnet-server/reference/txtextcontrol/sectionformat/equalcolumnwidth-property/llms-full.txt) | Whether all columns have the same width, calculated from the page size | `true` |
| [ColumnLineWidth](https://docs.textcontrol.com/tx-text-control-dotnet-server/reference/txtextcontrol/sectionformat/columnlinewidth-property/llms-full.txt), [ColumnLineColor](https://docs.textcontrol.com/tx-text-control-dotnet-server/reference/txtextcontrol/sectionformat/columnlinecolor-property/llms-full.txt) | A line between the columns: its width in twips (0 for no line) and its color | `0` |
| [PageMargins](https://docs.textcontrol.com/tx-text-control-dotnet-server/reference/txtextcontrol/sectionformat/pagemargins-property/llms-full.txt) | The page margins, as a [PageMargins](https://docs.textcontrol.com/tx-text-control-dotnet-server/reference/txtextcontrol/pagemargins/llms-full.txt) object | 1 inch each |
| [PageBorder](https://docs.textcontrol.com/tx-text-control-dotnet-server/reference/txtextcontrol/sectionformat/pageborder-property/llms-full.txt) | A border in the page margin, as a [PageBorder](https://docs.textcontrol.com/tx-text-control-dotnet-server/reference/txtextcontrol/pageborder/llms-full.txt) object | No border |
| [PageSize](https://docs.textcontrol.com/tx-text-control-dotnet-server/reference/txtextcontrol/sectionformat/pagesize-property/llms-full.txt) | The width and height of the page, always as the values in portrait orientation | US letter |
| [RestartPageNumbering](https://docs.textcontrol.com/tx-text-control-dotnet-server/reference/txtextcontrol/sectionformat/restartpagenumbering-property/llms-full.txt) | Whether the page numbers start again in this section | `false` |

Two units are in use:

- **Page sizes and margins** are measured in the unit of [ServerTextControl.PageUnit](https://docs.textcontrol.com/tx-text-control-dotnet-server/reference/txtextcontrol/servertextcontrol/pageunit-property/llms-full.txt), which is 1/100 inch by default. A margin of `75` is 0.75 inch.
- **Column widths, column distances, lines and page borders** are measured in twips, 1/1440 inch.

`RestartPageNumbering` works together with page number fields, which [Headers and Footers](https://docs.textcontrol.com/tx-text-control-dotnet-server/document-processing/headers-footers/#restart-page-numbers-in-a-section) describes.

### Set Page Columns

A newsletter or a glossary often continues in two columns below a heading that spans the page. A section that begins on a new line changes the number of columns without a page break:

```csharp
using TXTextControl;

using (ServerTextControl tx = new ServerTextControl())
{
    tx.Create();

    tx.Selection.Text = "Company Newsletter";

    // The columns begin on the next line
    tx.Sections.Add(SectionBreakKind.BeginAtNewLine);

    SectionFormat format = tx.Sections[2].Format;
    format.Columns = 2;
    format.EqualColumnWidth = true;
    format.ColumnLineWidth = 20; // twips
    format.ColumnLineColor = System.Drawing.Color.Gray;

    // Enough text to fill the first column and continue in the second
    for (int i = 1; i <= 100; i++)
    {
        tx.Selection.Text = "This is paragraph " + i + " of the two-column part.\r\n";
    }

    tx.Save("columns.pdf", StreamType.AdobePDF);
}
```

The heading spans the width of the page. The paragraphs below it fill the left column first and continue at the top of the right one, with a gray line between the two columns of equal width:

![The top of columns.pdf: the heading "Company Newsletter" across the page, and below it paragraphs 1 to 18 in the left column and 56 to 73 in the right column, separated by a vertical gray line.](https://docs.textcontrol.com/assets/img/tx-text-control-dotnet-server/page-columns-line.40fda28d.webp)

Text fills one column before it continues in the next: with 40 paragraphs instead of 100, all of them stay in the left column, and the right column stays empty.

The distances between the columns and columns of different widths are set with the [SectionFormat constructors](https://docs.textcontrol.com/tx-text-control-dotnet-server/reference/txtextcontrol/sectionformat/constructor/llms-full.txt). `SectionFormat(int columns, int[] columnWidths, int[] columnDistances)` takes one width per column and one distance less than there are columns. The widths and distances together must not exceed the width of the page minus the left and right margins; otherwise an exception occurs.

#### Columns of Different Widths

A narrow column for side notes next to a wide one for the main text needs two widths. When you choose the width of the first column and the distance, the second column gets the rest of the text area:

```text
second column = page width - left margin - right margin - first column - distance
```

The page size and the margins are in 1/100 inch, the default of `PageUnit`, and the column widths in twips. One inch is 1440 twips, so the program multiplies the page values by 14.4:

```csharp
using TXTextControl;

using (ServerTextControl tx = new ServerTextControl())
{
    tx.Create();

    tx.Selection.Text = "Product Catalog";
    tx.Sections.Add(SectionBreakKind.BeginAtNewLine);

    // 2 inches for the first column, 0.25 inch between the columns, in twips
    int firstColumnWidth = 2880;
    int columnDistance = 360;

    // Page size and margins are in 1/100 inch, so 14.4 converts them to twips
    SectionFormat currentFormat = tx.Sections.GetItem().Format;
    int secondColumnWidth = (int)(
        currentFormat.PageSize.Width * 14.4
        - currentFormat.PageMargins.Left * 14.4
        - currentFormat.PageMargins.Right * 14.4
        - firstColumnWidth
        - columnDistance);

    // The constructor sets EqualColumnWidth to false
    tx.Sections.GetItem().Format = new SectionFormat(
        2,
        new int[] { firstColumnWidth, secondColumnWidth },
        new int[] { columnDistance });

    SectionFormat format = tx.Sections.GetItem().Format;
    Console.WriteLine($"Column widths: {string.Join(", ", format.ColumnWidths)} twips");

    for (int i = 1; i <= 100; i++)
    {
        tx.Selection.Text = "This is paragraph " + i + " of the catalog.\r\n";
    }

    tx.Save("unequal-columns.pdf", StreamType.AdobePDF);
}
```

The code works as follows:

- `Sections.Add` with `BeginAtNewLine` starts the section with the columns below the heading, and `GetItem` without a parameter returns this new section, because it contains the input position.
- [PageSize](https://docs.textcontrol.com/tx-text-control-dotnet-server/reference/txtextcontrol/sectionformat/pagesize-property/llms-full.txt) and [PageMargins](https://docs.textcontrol.com/tx-text-control-dotnet-server/reference/txtextcontrol/sectionformat/pagemargins-property/llms-full.txt) are read from the current format. With a US letter page, 8.5 inches wide, and margins of 1 inch, the text area is 9360 twips wide, and the second column gets 6120 twips.
- The `SectionFormat` constructor takes the number of columns, one width per column and one distance less than there are columns. It is assigned to [Section.Format](https://docs.textcontrol.com/tx-text-control-dotnet-server/reference/txtextcontrol/section/format-property/llms-full.txt) as a whole, because [ColumnWidths](https://docs.textcontrol.com/tx-text-control-dotnet-server/reference/txtextcontrol/sectionformat/columnwidths-property/llms-full.txt) and [ColumnDistances](https://docs.textcontrol.com/tx-text-control-dotnet-server/reference/txtextcontrol/sectionformat/columndistances-property/llms-full.txt) are read only.

`PageSize` always holds the values in portrait orientation. For a section in landscape orientation, calculate with `PageSize.Height` as the width of the page. If you set [PageUnit](https://docs.textcontrol.com/tx-text-control-dotnet-server/reference/txtextcontrol/servertextcontrol/pageunit-property/llms-full.txt) to another unit, such as millimeters, use the factor for that unit instead of 14.4.

### Set Margins and a Page Border

The following program gives every section of a loaded document the same margins and a page border:

```csharp
using TXTextControl;

using (ServerTextControl tx = new ServerTextControl())
{
    tx.Create();
    tx.Load("Documents/sample.docx", StreamType.WordprocessingML);

    foreach (Section section in tx.Sections)
    {
        // Left, top, right and bottom: 0.75 inch in the default unit of 1/100 inch
        section.Format.PageMargins = new PageMargins(75, 75, 75, 75);

        // Lines on all four sides at the default distance from the edge of the page
        section.Format.PageBorder = new PageBorder(20, PageBorder.DefaultDistance, System.Drawing.Color.DarkBlue);
    }

    tx.Save("bordered.pdf", StreamType.AdobePDF);
}
```

The code works as follows:

- The loop reaches every section, so documents with several sections get the same margins everywhere.
- The [PageMargins constructor](https://docs.textcontrol.com/tx-text-control-dotnet-server/reference/txtextcontrol/pagemargins/constructor/llms-full.txt) takes the left, top, right and bottom margin.
- The [PageBorder constructor](https://docs.textcontrol.com/tx-text-control-dotnet-server/reference/txtextcontrol/pageborder/constructor/llms-full.txt) sets the line width, the distance and the color of all four lines. The distance is measured from the edge of the page, and [DefaultDistance](https://docs.textcontrol.com/tx-text-control-dotnet-server/reference/txtextcontrol/pageborder/defaultdistance-field/llms-full.txt) is 454 twips, which is 8 mm.

`PageBorder` also sets each line on its own, with properties such as `TopLineWidth`, `TopLineColor` and `TopDistance`. With [MeasureFromText](https://docs.textcontrol.com/tx-text-control-dotnet-server/reference/txtextcontrol/pageborder/measurefromtext-property/llms-full.txt), the distances are measured from the text instead of the edge of the page, and only then can [SurroundHeader](https://docs.textcontrol.com/tx-text-control-dotnet-server/reference/txtextcontrol/pageborder/surroundheader-property/llms-full.txt) and [SurroundFooter](https://docs.textcontrol.com/tx-text-control-dotnet-server/reference/txtextcontrol/pageborder/surroundfooter-property/llms-full.txt) include the header and footer. [FirstPageOnly](https://docs.textcontrol.com/tx-text-control-dotnet-server/reference/txtextcontrol/pageborder/firstpageonly-property/llms-full.txt) draws the border on the first page of the section only, and [OmitFirstPage](https://docs.textcontrol.com/tx-text-control-dotnet-server/reference/txtextcontrol/pageborder/omitfirstpage-property/llms-full.txt) on all pages but the first.

### Read the Sections of a Loaded Document

Before you change a document from another source, you may want to know how its pages are set up. The following program prints the layout of every section of *Documents/sample.docx*:

```csharp
using TXTextControl;

using (ServerTextControl tx = new ServerTextControl())
{
    tx.Create();
    tx.Load("Documents/sample.docx", StreamType.WordprocessingML);

    foreach (Section section in tx.Sections)
    {
        SectionFormat format = section.Format;

        Console.WriteLine($"Section {section.Number}: starts at character {section.Start}, {section.Length} characters");
        Console.WriteLine($"  Page size (portrait values): {format.PageSize.Width} x {format.PageSize.Height}");
        Console.WriteLine($"  Margins: {format.PageMargins.Left}, {format.PageMargins.Top}, {format.PageMargins.Right}, {format.PageMargins.Bottom}");
        Console.WriteLine($"  Landscape: {format.Landscape}, columns: {format.Columns}, break: {format.BreakKind}");
        Console.WriteLine($"  Headers and footers: {section.HeadersAndFooters.Count}");
    }
}
```

- [Section.Number](https://docs.textcontrol.com/tx-text-control-dotnet-server/reference/txtextcontrol/section/number-property/llms-full.txt) is the number of the section, from 1.
- [Section.Start](https://docs.textcontrol.com/tx-text-control-dotnet-server/reference/txtextcontrol/section/start-property/llms-full.txt) is the one-based number of its first character, and [Section.Length](https://docs.textcontrol.com/tx-text-control-dotnet-server/reference/txtextcontrol/section/length-property/llms-full.txt) the number of its characters without the section break. Compare them with the `Start` and `Length` of paragraphs or fields to find out which section an element belongs to.
- [Section.Select](https://docs.textcontrol.com/tx-text-control-dotnet-server/reference/txtextcontrol/section/select-method/llms-full.txt) selects the text of the section, without the section breaks.

[Selection.SectionFormat](https://docs.textcontrol.com/tx-text-control-dotnet-server/reference/txtextcontrol/selection/sectionformat-property/llms-full.txt) gets or sets the page settings of the selected text. When a selection spans several sections with different settings, most properties return their default values, while `Columns` returns 0 and `PageSize` a width and a height of zero.

To turn a document with several sections into one with a single page layout, the section breaks have to be deleted. The blog article [How to Delete All Section Breaks in a DOCX Document using C#](https://www.textcontrol.com/blog/2023/11/21/how-to-delete-all-section-breaks-in-a-docx-document-using-csharp/) shows how.

### Next Steps

- [Headers and Footers](https://docs.textcontrol.com/tx-text-control-dotnet-server/document-processing/headers-footers/llms-full.txt): give a section its own header and restart its page numbers.
- [Creating Documents](https://docs.textcontrol.com/tx-text-control-dotnet-server/document-processing/creating/llms-full.txt): set the page format of a new document.
- [Tables](https://docs.textcontrol.com/tx-text-control-dotnet-server/document-processing/tables/llms-full.txt): add the wide table for the landscape section.
- [Sections](https://docs.textcontrol.com/tx-text-control-dotnet-server/document-editor/sections/llms-full.txt) in the Document Editor: insert and format sections from JavaScript.

---

## Nearby

- **Previous:** [Headers and Footers](https://docs.textcontrol.com/tx-text-control-dotnet-server/document-processing/headers-footers/llms-full.txt)
- **Next:** [Footnotes](https://docs.textcontrol.com/tx-text-control-dotnet-server/document-processing/footnotes/llms-full.txt)