Sections in Rich Text Documents
- 5 minutes to read
Sections in the User Interface
You can insert section and page breaks and set the page layout options using the Page Layout ribbon tab. Refer to the How to: Create the RichEditControl with a Ribbon UI topic for information on how to add a Ribbon UI to the RichEditControl.
Use the RichEditBehaviorOptions.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 end users to define a page’s format options for an entire document or a specific section.
Tip
Set the DocumentCapabilitiesOptions.Sections property to Hidden or Disabled to restrict end users from managing document sections.
Divide a Document into Sections
The Document.Sections property provides access to the document’s section collection. 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.
Specify the Section.StartType property to define the section break’s type. The RichEditControl supports the following section breaks:
- Next Page
- Starts the new section on the following page.
- Continuous
- Starts the 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 on the next column on the page.
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.
Section firstSection = richEditControl1.Document.Sections[0];
firstSection.Page.Landscape = false;
firstSection.Page.PaperKind = DevExpress.Drawing.Printing.DXPaperKind.A3Extra;
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;
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 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 code sample below 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();
Protect Sections from Modification
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 certain sections in your document in code, use the ProtectedForForms property.
//...
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 Word Processing Document API.
| 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 |