Skip to main content

Sections in Rich Text Documents

  • 10 minutes to read

Every rich text document can be divided into multiple sections. Every section can specify its own page layout, headers, footers, page numbering, and other formatting options. Simple documents contain a single section that defines layout options for all content.

Sections in the User Interface

You can use the Page Layout ribbon tab to insert sections and page breaks and set the page layout options. Refer to the following topic for information on how to add a Ribbon UI to the RichEditControl: How to: Create the RichEditControl with a Ribbon UI

Use the RichEditBehaviorOptions.PageBreakInsertMode property to specify whether a page break is inserted next to the specified position or in the new line.

RichEdit_ShowPageSetupDialog_RibbonCaptionButton

The RichEditControl ships with the Page Setup Dialog. This dialog allows users to define page’s format options for a specific section or an entire document.

Tip

Set the DocumentCapabilitiesOptions.Sections property to Hidden or Disabled to restrict users from organizing document sections.

Divide a Document into Sections

Use the following methods to insert a section in code:

Sections are added to the Document.Sections collection.

Specify the Section.StartType property to define the section break’s type. Word Processing Document API supports the following section breaks:

Next Page
Starts a new section on the following page.
Continuous
Starts a new section on the same page.
Even Page
Starts a new section on the next even-numbered page.
Odd Page
Starts a new section on the next odd-numbered page.
Column
Starts a new section in the next column.

The following code sample inserts a continuous section break after the specified paragraph:

using DevExpress.XtraRichEdit;
using DevExpress.XtraRichEdit.API.Native;
//...

richEditControl.LoadDocument(@"Documents//Alice.docx");

Document document = richEditControl.Document;
var section = document.InsertSection(document.Paragraphs[4].Range.End);

// Retrieve the inserted section
var sectionPosition = document.CreatePosition(section.Range.End.ToInt() + 1);
Section insertedSection = document.GetSection(sectionPosition);
insertedSection.StartType = SectionStartType.Continuous;

richEditControl.SaveDocument("Alice_formatted.docx", DocumentFormat.OpenXml);   

Linked Sections

When you create a new section, it is automatically linked to the previous section, and the content from the first section header and footer is automatically inserted in the second section header and footer.

Unlink the newly created section from the previous section and remove the existing content before inserting new content in the header or footer. Call the SubDocument.Delete() method for a corresponding SubDocument to clear content. Refer to the following article for more information on how to retrieve header and footer content: Headers and Footers

Divide Sections into Pages

You can insert a page break to divide a section or an entire document into pages. Insert the Characters.PageBreak symbol in the specified position to complete the task.

The following code sample divides the first section into two pages:

using DevExpress.Office;
using DevExpress.Office.Utils;
using DevExpress.XtraRichEdit;
using DevExpress.XtraRichEdit.API.Native;
//...

richEditControl.LoadDocument(@"Documents\Alice.docx");
Document document = richEditControl.Document;

Section section = document.Sections[0];
var middlePosition =  section.Paragraphs[section.Paragraphs.Count / 2].Range.End;
document.InsertText(middlePosition, Characters.PageBreak.ToString());
richEditControl.SaveDocument("Alice_formatted.docx", DocumentFormat.OpenXml);

Define Page Formatting Options

You can use properties available in the SectionPage class to specify the page’s paper type, orientation, and size. Use the Section.Page property to obtain page formatting settings.

The following code sample modifies the first section’s page formatting options: sets orientation to portrait and page size to A3 Extra.

image

using DevExpress.XtraRichEdit;
using DevExpress.XtraRichEdit.API.Native;
using DevExpress.Drawing.Printing;
//...

Section firstSection = richEditControl.Document.Sections[0];
firstSection.Page.Landscape = false;
firstSection.Page.PaperKind = DXPaperKind.A3Extra;

Specify Page Borders

The Section.PageBorders property allows you specify page borders options for a specific section. Use the SectionPageBorders.ResetBorders() method to reset all page borders in the section.

Use the following properties on the document level to specify page border alignments options:

AlignBordersAndEdges
Specifies whether to align paragraph borders and table edges with page borders.
BorderSurroundsHeader
Specifies whether the page border includes or excludes the header.
BorderSurroundsFooter
Specifies whether the page border includes or excludes the footer.

The following code snippet adds page borders to two sections:

  • In the first section, page borders are shown only on the first page.
  • In the second section, page borders are shown on all pages.
using DevExpress.XtraRichEdit;
using DevExpress.XtraRichEdit.API.Native;
using System.Diagnostics;
using System.Drawing;

string fileName = "Test.docx";
Document document = richEditControl.Document;

// Generate a document with two sections and multiple pages in each section.
document.AppendText("\f\f\f");
document.Paragraphs.Append();
document.AppendSection();
document.AppendText("\f\f");

Section firstSection = document.Sections[0];
SectionPageBorders pageBorders1 = firstSection.PageBorders;

// Set page borders for the first page of the first section.
SetPageBorders(pageBorders1.LeftBorder, BorderLineStyle.Single, 1f, Color.Red);
SetPageBorders(pageBorders1.TopBorder, BorderLineStyle.Single, 1f, Color.Red);
SetPageBorders(pageBorders1.RightBorder, BorderLineStyle.Single, 1f, Color.Red);
SetPageBorders(pageBorders1.BottomBorder, BorderLineStyle.Single, 1f, Color.Red);
pageBorders1.AppliesTo = PageBorderAppliesTo.FirstPage;

Section secondSection = document.Sections[1];
SectionPageBorders pageBorders2 = secondSection.PageBorders;

// Set page borders for all pages of the second section.
SetPageBorders(pageBorders2.LeftBorder, BorderLineStyle.Double, 1.5f, Color.Green);
SetPageBorders(pageBorders2.TopBorder, BorderLineStyle.Double, 1.5f, Color.Green);
SetPageBorders(pageBorders2.RightBorder, BorderLineStyle.Double, 1.5f, Color.Green);
SetPageBorders(pageBorders2.BottomBorder, BorderLineStyle.Double, 1.5f, Color.Green);
pageBorders2.AppliesTo = PageBorderAppliesTo.AllPages;
pageBorders2.ZOrder = PageBorderZOrder.Back;

wordProcessor.SaveDocument(fileName, DocumentFormat.OpenXml);

void SetPageBorders(PageBorder border, BorderLineStyle lineStyle,
    float borderWidth, Color color) {
        border.LineStyle = lineStyle;
        border.LineWidth = borderWidth;
        border.LineColor = color;
    }

Process.Start(new ProcessStartInfo(fileName) { UseShellExecute = true });

The following picture shows the resulting page borders:

Word Processing API - Page Borders for Sections

Specify Page Margins

The Section.Margins property allows you specify margin options for a specific section. Margins are measured in units specified by the Document.Unit property (the default value is Document). You can use Units class API to convert values.

The following code snippet changes the first section’s margins:

using DevExpress.XtraRichEdit;
using DevExpress.XtraRichEdit.API.Native;
using DevExpress.Office.Utils;
//...

richEditControl.LoadDocument("Document.docx");

Document document = richEditControl.Document;

Section firstSection = richEditControl.Document.Sections[0];

var pageMargins = firstSection.Margins;
pageMargins.Left = Units.InchesToDocumentsF(0.5f);
pageMargins.Top = Units.InchesToDocumentsF(0.7f);
pageMargins.Right = Units.InchesToDocumentsF(0.5f);
pageMargins.Bottom = Units.InchesToDocumentsF(1.5f);

Add Gutter Margins

You can add a gutter margin - an extra space that ensures that binding will not obscure the text on printed pages.

Use the following properties to specify gutter margin position:

Document.GutterAtTop
Positions the gutter margin at the page top. This gutter is enabled for the entire document.
SectionMargins.GutterPosition
This property is in effect only if GutterAtTop is false. Allows you to position a gutter margin at page left or right. This gutter is applied to a specific section.

Whether you enabled top or side gutter margin, use the SectionMargins.Gutter property to change the margin size. This value is added to the already specified margin, regardless of position. The gutter value is specified for each section individually.

The following code sample adds a left gutter to the first document section:

image

using DevExpress.XtraRichEdit;
using DevExpress.XtraRichEdit.API.Native;
using DevExpress.Office.Utils;
//...

richEditControl.LoadDocument(@"Documents//Alice.docx");

Document document = richEditControl.Document;
Section firstSection = wordProcessor.Document.Sections[0];

var pageMargins = firstSection.Margins;
pageMargins.GutterPosition = GutterPosition.Left;
pageMargins.Gutter = Units.InchesToDocumentsF(1);

richEditControl.SaveDocument("Alice_formatted.docx", DocumentFormat.OpenXml);   

Enable Mirrored Margins

The Document.MarginType property defines the margin type: regular or mirrored. Enable mirrored margins if you print on both sides of paper and want to bind the printout. If you open a fold, two pages will face each other and you’ll likely want to apply symmetrical margins. For example, you can apply a bigger margin on the inside edge.

You can add a gutter margin in mirrored layout. Specify the SectionMargins.Gutter property. Note that the SectionMargins.GutterPosition property is ignored. Gutter margins appear on the inside of the fold.

The following code sample enables mirrored margins and specifies an additional space value:

image

using DevExpress.XtraRichEdit;
using DevExpress.XtraRichEdit.API.Native;
using DevExpress.Office.Utils;
//...
richEditControl.LoadDocument(@"Documents//Alice.docx");
Document document = richEditControl.Document;

// Enable mirrored margins
document.MarginsType = MarginsType.Mirrored;

foreach (Section section in richEditControl.Document.Sections) {
    var pageMargins = section.Margins;

    // Set the value for mirrored margins
    pageMargins.Gutter = Units.InchesToDocumentsF(0.5f);
}

richEditControl.SaveDocument("Alice_formatted.docx", DocumentFormat.OpenXml);   

Add Page Numbering

Each section can start its own page number sequence and use its own number format. Use the Section.PageNumbering property to retrieve related options. The following properties are available: SectionPageNumbering.ContinueNumbering, SectionPageNumbering.FirstPageNumber, and SectionPageNumbering.NumberingFormat.

Note

Even if the document contains a single section, you should set that section’s ContinueNumbering to false to specify a custom page numbering sequence.

The PAGE field shows document page numbers. To apply new settings to existing page numbers, call the Document.UpdateAllFields() method.

The following code specifies the initial number and the NumberingFormat.CardinalText numbering format.

XtraRichEdit_PageNumbering

Section section = richEditControl.Document.Sections[0];
section.PageNumbering.ContinueNumbering = false;
section.PageNumbering.FirstPageNumber = 3;
section.PageNumbering.NumberingFormat = NumberingFormat.CardinalText;

if (section.HasHeader(HeaderFooterType.Primary))
{
    var footer = section.BeginUpdateFooter();
    footer.Fields.Create(footer.Range.End, "PAGE");
    section.EndUpdateFooter(footer);
}

richEditControl.Document.UpdateAllFields();

Protect Sections from Modification

You can protect/unprotect certain sections in your document.

Protect Sections from Modification from the UI

In the UI, do the following to protect/unprotect sections:

  1. Click Protect Document on the Review ribbon tab to open the Document Protection dialog.
  2. In the invoked dialog, set the document protection type to Filling in Forms (allows users to fill in forms and form fields).
  3. Select sections to be protected. When the section checkbox is selected, you can modify text only in form fields in this section.

    Rich Text Editor - Document Protection

Protect Sections from Modification in Code

To protect sections in code, set the section’s ProtectedForForms property to true. When a section is protected, you can only modify text in form fields. The following code snippet loads a file with two sections, protects the first section in the document, and unprotects the second section in the document:

//...
richEditControl.LoadDocument(@"C:\DocumentWithTwoSections.docx", DocumentFormat.OpenXml);
richEditControl.Document.Sections[0].ProtectedForForms = true;
richEditControl.Document.Sections[1].ProtectedForForms = false;
richEditControl.Document.Protect("", DocumentProtectionType.FillInForms);
//...

Other Page Formatting Tasks

The table below lists other page layout-related tasks you can complete with Rich Text Editor for WinForms.

To execute this task Use these API members Example
Enable line numbering SectionLineNumbering.CountBy How to: Add Line Numbering
Divide page content into columns SectionColumns.CreateUniformColumns How to: Create a Three-Column Layout with Uniform Columns
Specify headers and footers Section.BeginUpdateHeader
Section.BeginUpdateFooter
Headers and Footers
Specify footnote and endnote options Section.FootnoteOptions
Section.EndnoteOptions
Footnotes and Endnotes
Add watermarks to selected sections ShapeCollection.InsertTextWatermark
ShapeCollection.InsertImageWatermark
Add a Watermark to an Individual Document Section