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: 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.
Divide a Document into Sections
Use the following methods to insert a section in code:
- Document.InsertSection - inserts a new section at the specified document position.
- Document.AppendSection - appends a new section.
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. 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.
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:
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
GutterAtTopisfalse. 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.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:
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: 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();
Section Protection
You can protect/unprotect certain sections in your document.
In the UI, do the following to protect/unprotect sections:
- Click Protect Document on the Review ribbon tab to open the Document Protection dialog.
- In the invoked dialog, set the document protection type to Filling in Forms (allows users to fill in forms and form fields).
Select sections to be protected. When the section checkbox is selected, you can modify text only in form fields in this section.
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 |