wpf-9116-controls-and-libraries-rich-text-editor-rich-edit-control-document-sections.md
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.
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: Create a Simple Rich Text Editor
Use the DXRichEditBehaviorOptions.PageBreakInsertMode property to specify whether a page break is inserted next to the specified position or in the new line.
The RichEditControl ships with the Page Setup Dialog. This dialog allows users to define a page’s formatting options of a whole document or a particular section.
Tip
Set the DXRichEditDocumentCapabilitiesOptions.Sections property to Hidden or Disabled to restrict users from managing document 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.Docx);
Imports DevExpress.XtraRichEdit
Imports DevExpress.XtraRichEdit.API.Native
'...
richEditControl.LoadDocument("Documents//Alice.docx")
Dim document As Document = richEditControl.Document
Dim section = document.InsertSection(document.Paragraphs(4).Range.End)
' Retrieve the inserted section
Dim sectionPosition = document.CreatePosition(section.Range.End.ToInt() + 1)
Dim insertedSection As Section = document.GetSection(sectionPosition)
insertedSection.StartType = SectionStartType.Continuous
richEditControl.SaveDocument("Alice_formatted.docx", DocumentFormat.Docx)
When you create a new section, it is automatically linked to the previous section. 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
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.Docx);
Imports DevExpress.Office
Imports DevExpress.Office.Utils
Imports DevExpress.XtraRichEdit
Imports DevExpress.XtraRichEdit.API.Native
'...
richEditControl.LoadDocument("Documents\Alice.docx")
Dim document As Document = richEditControl.Document
Dim section As Section = document.Sections(0)
Dim middlePosition = section.Paragraphs(section.Paragraphs.Count \ 2).Range.End
document.InsertText(middlePosition, Characters.PageBreak.ToString())
richEditControl.SaveDocument("Alice_formatted.docx", DocumentFormat.Docx)
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.
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;
Imports DevExpress.XtraRichEdit
Imports DevExpress.XtraRichEdit.API.Native
Imports DevExpress.Drawing.Printing
'...
Dim firstSection As Section = richEditControl.Document.Sections(0)
firstSection.Page.Landscape = False
firstSection.Page.PaperKind = DXPaperKind.A3Extra
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:
AlignBordersAndEdgesSpecifies whether to align paragraph borders and table edges with page borders.BorderSurroundsHeaderSpecifies whether the page border includes or excludes the header.BorderSurroundsFooterSpecifies 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.Docx);
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 });
Imports DevExpress.XtraRichEdit
Imports DevExpress.XtraRichEdit.API.Native
Imports System.Diagnostics
Imports System.Drawing
Private fileName As String = "Test.docx"
Dim document As Document = richEditControl.Document
' Generate a document with two sections and multiple pages in each section.
Private Sub SurroundingSub()
document.AppendText(vbFormFeed & vbFormFeed & vbFormFeed)
document.Paragraphs.Append()
document.AppendSection()
document.AppendText(vbFormFeed & vbFormFeed)
End Sub
Dim firstSection As Section = document.Sections(0)
Dim pageBorders1 As SectionPageBorders = 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
Dim secondSection As Section = document.Sections(1)
Dim pageBorders2 As SectionPageBorders = 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.Docx)
Private Sub SetPageBorders(ByVal border As PageBorder, ByVal lineStyle As BorderLineStyle, ByVal borderWidth As Single, ByVal color As Color)
border.LineStyle = lineStyle
border.LineWidth = borderWidth
border.LineColor = color
End Sub
Process.Start(New ProcessStartInfo(fileName) With {.UseShellExecute = True})
The following picture shows the resulting page borders:
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);
Imports DevExpress.XtraRichEdit
Imports DevExpress.XtraRichEdit.API.Native
Imports DevExpress.Office.Utils
'...
richEditControl.LoadDocument("Document.docx")
Dim document As Document = richEditControl.Document
Dim firstSection As Section = richEditControl.Document.Sections(0)
Dim 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)
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.GutterAtTopPositions the gutter margin at the page top. This gutter is enabled for the entire document.SectionMargins.GutterPositionThis 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:
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.Docx);
Imports DevExpress.XtraRichEdit
Imports DevExpress.XtraRichEdit.API.Native
Imports DevExpress.Office.Utils
'...
richEditControl.LoadDocument("Documents//Alice.docx")
Dim document As Document = richEditControl.Document
Dim firstSection As Section = richEditControl.Document.Sections(0)
Dim pageMargins = firstSection.Margins
pageMargins.GutterPosition = GutterPosition.Left
pageMargins.Gutter = Units.InchesToDocumentsF(1)
richEditControl.SaveDocument("Alice_formatted.docx", DocumentFormat.Docx)
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:
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.Docx);
Imports DevExpress.XtraRichEdit
Imports DevExpress.XtraRichEdit.API.Native
Imports DevExpress.Office.Utils
'...
richEditControl.LoadDocument("Documents//Alice.docx")
Dim document As Document = richEditControl.Document
' Enable mirrored margins
document.MarginsType = MarginsType.Mirrored
For Each section As Section In richEditControl.Document.Sections
Dim pageMargins = section.Margins
' Set the value for mirrored margins
pageMargins.Gutter = Units.InchesToDocumentsF(0.5F)
Next section
richEditControl.SaveDocument("Alice_formatted.docx", DocumentFormat.Docx)
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: ContinueNumbering, FirstPageNumber, and 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.
Section section = richEditControl1.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);
}
richEditControl1.Document.UpdateAllFields();
Dim section As Section = richEditControl1.Document.Sections(0)
section.PageNumbering.ContinueNumbering = False
section.PageNumbering.FirstPageNumber = 3
section.PageNumbering.NumberingFormat = NumberingFormat.CardinalText
If section.HasHeader(HeaderFooterType.Primary) Then
Dim footer = section.BeginUpdateFooter()
footer.Fields.Create(footer.Range.End, "PAGE")
section.EndUpdateFooter(footer)
End If
richEditControl1.Document.UpdateAllFields()
You can protect/unprotect certain sections in your document.
In the UI, do the following to protect/unprotect sections:
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.Docx);
richEditControl.Document.Sections[0].ProtectedForForms = true;
richEditControl.Document.Sections[1].ProtectedForForms = false;
richEditControl.Document.Protect("", DocumentProtectionType.FillInForms);
//...
'...
richEditControl.LoadDocument("C:\DocumentWithTwoSections.docx", DocumentFormat.Docx)
richEditControl.Document.Sections(0).ProtectedForForms = True
richEditControl.Document.Sections(1).ProtectedForForms = False
richEditControl.Document.Protect("", DocumentProtectionType.FillInForms)
'...
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 |
See Also
How to: Create a Three-Column Layout with Uniform Columns