Class PageSetup

Namespace

DocToolkit

Assembly

DocToolkit.Primitives.dll

The paper a generated document is laid out on: size, orientation and margins, all in points.

Immutable and built by factories — A4, Letter or Custom(double, double) — then copied by Landscape() and WithMargins. The same shape as DocxBlock, PptxSlide, XlsxSheet and XlsxFormula, so the five read as a set.

Points throughout, because DocxBlock.Image already takes widthPoints/heightPoints, and a library with two length units is a library that will eventually mix them up. OOXML stores these as twentieths of a point; that conversion lives in SectionPropertiesFactory and never reaches a caller.

Only two presets. A3, Legal and the rest are one line each and can be added when somebody asks; Custom(double, double) covers them meanwhile.

There is no Portrait(). It has no defensible answer for a square custom page — "the longer side vertical" is undefined when there is no longer side. Both presets are already portrait and this type is immutable, so start from the preset again.

public sealed class PageSetup

Inheritance

object

PageSetup

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.ReferenceEquals(object, object)

Properties

A4

ISO A4 portrait — 210 × 297 mm — with one-inch margins. The default for every producer.

The one-decimal values are not sloppiness: 210 mm is 595.2756 pt, and 595.3 × 20 is the 11906 twentieths Word itself writes for A4. Rounding to 595 would write 11900 and render a page 0.3 pt narrower than every other tool's A4.

public static PageSetup A4 { get; }

Property Value

PageSetup

BottomPoints

The bottom margin, in points.

public double BottomPoints { get; }

Property Value

double

FirstPageFooter

The footer on page one when HasDistinctFirstPage, or null for none.

public DocxHeader? FirstPageFooter { get; }

Property Value

DocxHeader

FirstPageHeader

The header on page one when HasDistinctFirstPage, or null for none.

public DocxHeader? FirstPageHeader { get; }

Property Value

DocxHeader

Footer

The footer on every page, or null for none.

public DocxHeader? Footer { get; }

Property Value

DocxHeader

HasDistinctFirstPage

Whether page one is treated differently — set by calling WithFirstPage(DocxHeader?, DocxHeader?), and emitted as w:titlePg.

public bool HasDistinctFirstPage { get; }

Property Value

bool

Header

The header on every page, or null for none.

public DocxHeader? Header { get; }

Property Value

DocxHeader

HeightPoints

The page height, in points.

public double HeightPoints { get; }

Property Value

double

LeftPoints

The left margin, in points.

public double LeftPoints { get; }

Property Value

double

Letter

US Letter portrait — 8.5 × 11 in — with one-inch margins.

public static PageSetup Letter { get; }

Property Value

PageSetup

RightPoints

The right margin, in points.

public double RightPoints { get; }

Property Value

double

TopPoints

The top margin, in points.

public double TopPoints { get; }

Property Value

double

WidthPoints

The page width, in points.

public double WidthPoints { get; }

Property Value

double

Methods

Custom(double, double)

A page of the given size, in points, with one-inch margins.

public static PageSetup Custom(double widthPoints, double heightPoints)

Parameters

widthPoints double

The page width. Must be positive.

heightPoints double

The page height. Must be positive.

Returns

PageSetup

Remarks

The content area is deliberately NOT validated here, unlike WithMargins(double, double, double, double) and Landscape(). A page smaller than the one-inch defaults — Custom(100, 400) — is a legitimate starting point for Custom(100, 400).WithMargins(0, 60, 0, 40), and guarding construction would make a small page impossible to build at all rather than merely awkward. Tried 2026-08-15 and reverted: it broke three tests that construct exactly that shape.

The cost is real and is the caller's to avoid: a Custom page too small for the default margins, used without WithMargins(double, double, double, double), produces a document Word renders blank. Nothing refuses it, because the only place that could is the conversion boundary, and moving the check there would change when a shipped API throws.

Exceptions

ArgumentOutOfRangeException

Either dimension is not a positive, finite number no larger than int.MaxValue / 20.

Landscape()

A copy with the width and height swapped, keeping the margins as they are.

This swaps rather than normalises, so calling it twice returns to where you started.

public PageSetup Landscape()

Returns

PageSetup

Exceptions

ArgumentException

The swap leaves no content area — the margins were valid against the old dimensions and are not against the new ones.

ToString()

Returns a string that represents the current object.

public override string ToString()

Returns

string

A string that represents the current object.

WithFirstPage(DocxHeader?, DocxHeader?)

A copy whose first page is treated separately.

public PageSetup WithFirstPage(DocxHeader? header, DocxHeader? footer)

Parameters

header DocxHeader

Page one's header, or null for none.

footer DocxHeader

Page one's footer, or null for none.

Returns

PageSetup

Remarks

Calling this is the switch: it emits w:titlePg, and then null means blank on page one rather than "use the ordinary one". That mirrors the format — an absent first-page reference produces no header, and there is no inheritance to fall back on — and it makes the common case sayable: a title page with nothing running across it.

Not calling this at all leaves page one looking like every other page.

WithFooter(DocxHeader)

A copy carrying footer on every page.

public PageSetup WithFooter(DocxHeader footer)

Parameters

footer DocxHeader

The footer content.

Returns

PageSetup

Exceptions

ArgumentNullException

footer is null.

WithHeader(DocxHeader)

A copy carrying header on every page.

public PageSetup WithHeader(DocxHeader header)

Parameters

header DocxHeader

The header content.

Returns

PageSetup

Exceptions

ArgumentNullException

header is null.

WithMargins(double)

A copy with all four margins set to points.

public PageSetup WithMargins(double points)

Parameters

points double

The margin to apply on all four sides.

Returns

PageSetup

Exceptions

ArgumentOutOfRangeException

points is negative, NaN or too large.

ArgumentException

The margins leave no content area.

WithMargins(double, double, double, double)

A copy with the four margins set individually, clockwise from the top — the order CSS uses.

public PageSetup WithMargins(double topPoints, double rightPoints, double bottomPoints, double leftPoints)

Parameters

topPoints double

The top margin.

rightPoints double

The right margin.

bottomPoints double

The bottom margin.

leftPoints double

The left margin.

Returns

PageSetup

Exceptions

ArgumentOutOfRangeException

A margin is negative, NaN or too large.

ArgumentException

The horizontal or vertical margins together are at least the page's width or height. Such a document opens and renders as a blank page rather than failing, so it is refused here.