Sections and Page Layout in Word 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.
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 shows how to insert a continuous section break after the specified paragraph:
using DevExpress.XtraRichEdit;
using DevExpress.XtraRichEdit.API.Native;
using (var wordProcessor = new RichEditDocumentServer())
{
wordProcessor.LoadDocument(@"Documents//Alice.docx");
Document document = wordProcessor.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;
wordProcessor.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;
using (var wordProcessor = new RichEditDocumentServer()) {
wordProcessor.LoadDocument(@"Documents\Alice.docx");
Document document = wordProcessor.Document;
Section section = document.Sections[0];
var middlePosition = section.Paragraphs[section.Paragraphs.Count / 2].Range.End;
document.InsertText(middlePosition, Characters.PageBreak.ToString());
wordProcessor.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;
using (var wordProcessor = new RichEditDocumentServer()) {
wordProcessor.LoadDocument(@"Documents//Alice.docx");
Document document = wordProcessor.Document;
Section firstSection = wordProcessor.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.
Example
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";
using (var wordProcessor = new RichEditDocumentServer()) {
Document document = wordProcessor.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 (var wordProcessor = new RichEditDocumentServer()) {
wordProcessor.LoadDocument("Document.docx");
Document document = wordProcessor.Document;
Section firstSection = wordProcessor.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:
using DevExpress.XtraRichEdit;
using DevExpress.XtraRichEdit.API.Native;
using DevExpress.Office.Utils;
using (var wordProcessor = new RichEditDocumentServer()) {
wordProcessor.LoadDocument(@"Documents//Alice.docx");
Document document = wordProcessor.Document;
Section firstSection = wordProcessor.Document.Sections[0];
var pageMargins = firstSection.Margins;
pageMargins.GutterPosition = GutterPosition.Left;
pageMargins.Gutter = Units.InchesToDocumentsF(1);
wordProcessor.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;
using (var wordProcessor = new RichEditDocumentServer())
{
wordProcessor.LoadDocument(@"Documents//Alice.docx");
Document document = wordProcessor.Document;
// Enable mirrored margins
document.MarginsType = MarginsType.Mirrored;
foreach (Section section in wordProcessor.Document.Sections)
{
var pageMargins = section.Margins;
// Set the value for mirrored margins
pageMargins.Gutter = Units.InchesToDocumentsF(0.5f);
}
wordProcessor.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 sample specifies the initial number and NumberingFormat.CardinalText numbering format, and inserts the PAGE field to the section footer.
using DevExpress.XtraRichEdit;
using DevExpress.XtraRichEdit.API.Native;
using (var wordProcessor = new RichEditDocumentServer())
{
wordProcessor.CreateNewDocument();
Section section = wordProcessor.Document.Sections[0];
section.PageNumbering.ContinueNumbering = false;
section.PageNumbering.FirstPageNumber = 3;
section.PageNumbering.NumberingFormat = NumberingFormat.CardinalText;
var footer = section.BeginUpdateFooter();
footer.Fields.Create(footer.Range.End, "PAGE");
section.EndUpdateFooter(footer);
wordProcessor.Document.UpdateAllFields();
}
Protect Sections from Modification
You can protect certain sections in your document. To do this, use the ProtectedForForms property.
The following code snippet loads a document with two sections, turns on form protection for the first section in the document, unprotects the second section, and saves the updated document.
using DevExpress.XtraRichEdit;
using DevExpress.XtraRichEdit.API.Native;
using (var wordProcessor = new RichEditDocumentServer()) {
wordProcessor.LoadDocument(@"C:\DocumentWithTwoSections.docx", DocumentFormat.OpenXml);
wordProcessor.Document.Sections[0].ProtectedForForms = true;
wordProcessor.Document.Sections[1].ProtectedForForms = false;
wordProcessor.Document.Protect("", DocumentProtectionType.FillInForms);
wordProcessor.SaveDocument("DocumentWithTwoSectionsProtected.docx", DocumentFormat.OpenXml);
}
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 |