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"
)

Size

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

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
}