Document Model

Overview

The document package (Layer 2) provides types for page sizes, units, styles, and the document node tree. Most users interact with these types for configuration rather than direct tree manipulation.

import "github.com/gpdf-dev/gpdf/document"

Page Sizes

var (
    A4     = Size{Width: 595.28, Height: 841.89}   // 210mm x 297mm
    A3     = Size{Width: 841.89, Height: 1190.55}   // 297mm x 420mm
    Letter = Size{Width: 612, Height: 792}           // 8.5" x 11"
    Legal  = Size{Width: 612, Height: 1008}          // 8.5" x 14"
)

Since v1.0.14 The full ISO 216 / ISO 269 series is available: A0–A10, B0–B10, C0–C10 (envelopes) and DL. All sizes are portrait and rounded to two decimal places in points. A selection:

var (
    A0  = Size{Width: 2383.94, Height: 3370.39}  // 841mm x 1189mm
    A5  = Size{Width: 419.53, Height: 595.28}    // 148mm x 210mm
    A6  = Size{Width: 297.64, Height: 419.53}    // 105mm x 148mm
    A10 = Size{Width: 73.70, Height: 104.88}     // 26mm x 37mm
    B4  = Size{Width: 708.66, Height: 1000.63}   // 250mm x 353mm
    B5  = Size{Width: 498.90, Height: 708.66}    // 176mm x 250mm (ISO B5)
    C4  = Size{Width: 649.13, Height: 918.43}    // 229mm x 324mm
    C5  = Size{Width: 459.21, Height: 649.13}    // 162mm x 229mm
    C6  = Size{Width: 323.15, Height: 459.21}    // 114mm x 162mm
    DL  = Size{Width: 311.81, Height: 623.62}    // 110mm x 220mm
    // ... A0–A10, B0–B10, C0–C10 are all defined
)

Every size is re-exported from the gpdf package, so gpdf.A6, gpdf.B5, gpdf.DL, etc. can be used without importing document:

doc := gpdf.NewDocument(gpdf.WithPageSize(gpdf.A6))

ISO B vs. JIS B: the B series follows ISO 216, which differs from the JIS B series commonly used in Japan (ISO B5 = 176mm x 250mm, JIS B5 = 182mm x 257mm). For JIS sizes, build a document.Size from millimeters:

// JIS B5 (182mm x 257mm)
jisB5 := document.Size{
    Width:  document.Mm(182).Resolve(0, 0),
    Height: document.Mm(257).Resolve(0, 0),
}
doc := template.New(template.WithPageSize(jisB5))

Size

type Size struct {
    Width, Height float64  // in points (1pt = 1/72 inch)
}

Since v1.0.14 Landscape() returns the size in landscape orientation (width >= height). Sizes that are already landscape or square are returned unchanged, so the call is idempotent.

func (s Size) Landscape() Size

template.WithPageSize(document.A4.Landscape())  // 841.89pt x 595.28pt
document.A4.Landscape().Landscape()              // unchanged (idempotent)

Units and Values

Value

A dimension with a unit:

type Value struct {
    Amount float64
    Unit   Unit
}

Unit Constructors

Function	Unit	Example
Pt(v)	Points (1/72 inch)	Pt(12) — native PDF unit
Mm(v)	Millimeters	Mm(20) — 20mm margin
Cm(v)	Centimeters	Cm(2.5) — 2.5cm
In(v)	Inches	In(1) — 1 inch
Em(v)	Relative to font size	Em(2) — 2x font size
Pct(v)	Percentage of parent	Pct(50) — 50%

// Usage examples
document.Mm(20)   // 20 millimeters
document.Pt(12)   // 12 points
document.In(0.5)  // half inch
document.Pct(50)  // 50% of parent

Value Methods

func (v Value) Resolve(parentSize, fontSize float64) float64
func (v Value) IsAuto() bool

Resolve() converts any unit to points. IsAuto() checks for auto-sized values.

Edges (Box Model)

Edges

type Edges struct {
    Top, Right, Bottom, Left Value
}

UniformEdges

func UniformEdges(v Value) Edges

Creates edges with the same value on all sides:

document.UniformEdges(document.Mm(20))  // 20mm on all sides

Custom Edges

document.Edges{
    Top:    document.Mm(25),
    Right:  document.Mm(15),
    Bottom: document.Mm(25),
    Left:   document.Mm(15),
}

Style

The Style struct controls all visual properties:

type Style struct {
    // Font
    FontFamily     string
    FontSize       float64
    FontWeight     FontWeight    // WeightNormal (400) or WeightBold (700)
    FontStyle      FontStyle     // StyleNormal or StyleItalic

    // Color
    Color          pdf.Color
    Background     *pdf.Color

    // Text layout
    TextAlign      TextAlign     // AlignLeft, AlignCenter, AlignRight, AlignJustify
    LineHeight     float64
    LetterSpacing  float64
    TextIndent     Value
    TextDecoration TextDecoration
    VerticalAlign  VerticalAlign

    // Box model
    Margin  Edges
    Padding Edges
    Border  BorderEdges
}

TextAlign

const (
    AlignLeft    TextAlign = iota  // default
    AlignCenter
    AlignRight
    AlignJustify
)

FontWeight

const (
    WeightNormal FontWeight = 400
    WeightBold   FontWeight = 700
)

TextDecoration

const (
    DecorationNone          TextDecoration = 0
    DecorationUnderline     TextDecoration = 1
    DecorationStrikethrough TextDecoration = 2
    DecorationOverline      TextDecoration = 4
)

Decorations can be combined with bitwise OR.

VerticalAlign

const (
    VAlignTop    VerticalAlign = iota  // default
    VAlignMiddle
    VAlignBottom
)

Used for table cell vertical alignment:

template.TableCellVAlign(document.VAlignMiddle)

Document Metadata

type DocumentMetadata struct {
    Title    string
    Author   string
    Subject  string
    Creator  string
    Producer string
}

template.WithMetadata(document.DocumentMetadata{
    Title:  "Quarterly Report",
    Author: "ACME Corp",
})

Image Types

ImageFitMode

const (
    FitContain  ImageFitMode = iota  // Scale to fit within bounds (preserve ratio)
    FitCover                          // Scale to fill bounds (may crop)
    FitStretch                        // Stretch to fill (distort)
    FitOriginal                       // Use original image dimensions
)

ImageFormat

const (
    ImageFormatJPEG ImageFormat = iota
    ImageFormatPNG
)

Node Types

The document tree is composed of nodes:

const (
    NodeDocument NodeType = iota
    NodePage
    NodeBox
    NodeText
    NodeImage
    NodeTable
    NodeList
    NodeRichText
)

Most users don't interact with nodes directly — the template builder creates them automatically.

Geometry Types

type Rectangle struct {
    X, Y, Width, Height float64
}

type Point struct {
    X, Y float64
}