layout

Documentation

Overview

Package layout resolves the supported visual formatting rules and paginates content while preserving computed styles until each box is placed.

Index

• func BreakLines(text string, usable float64, measure func(string, float64) float64, ...) []string
• type BoxFragment
• type ClipRect
• type FragmentBounds
• type FragmentNode
• type FragmentNodeKind
• type InlineBoxDecoration
• type OpacityGroup
• type Options
  • func DefaultOptions() Options
• type Page
  • func Flow(root *boxes.Box, opts Options) []Page
• type PageGeometry
• type PlacedBox
• type TablePaintEdges
• type TablePaintLayer
• type TextRun

Functions

func BreakLines

func BreakLines(text string, usable float64, measure func(string, float64) float64, fontSize float64) []string

BreakLines splits text at spaces without exceeding the usable width. It measures incrementally with measure, which must be monotonic. A word wider than the available width is not split; it overflows, as with CSS overflow when hyphenation is disabled.

Types

type BoxFragment

type BoxFragment struct {
	Source             *boxes.Box
	Path               []int
	PageNumber         int
	FragmentainerIndex int
	FragmentIndex      int
	FragmentCount      int
	IsFirst            bool
	IsLast             bool
	Repeated           bool
	PaintIndex         int
	Bounds             FragmentBounds
}

BoxFragment describes one placed piece of a source box. PaintIndex addresses Page.Blocks; Path locates the source under Flow's root. Page.FragmentTree is the sole representation of page-local hierarchy.

type ClipRect

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

ClipRect defines a clipping rectangle in page coordinates (top-left origin).

type FragmentBounds

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

FragmentBounds is a border-box rectangle in page points.

type FragmentNode

type FragmentNode struct {
	Fragment        BoxFragment
	Placed          PlacedBox
	Kind            FragmentNodeKind
	Parent          *FragmentNode // concrete instance of the parent fragment on this page
	OwnerPaintIndex int           // page block whose paint operation emits this decoration
	DecorationIndex int           // order inside the owning page block's decoration sequence
	Children        []*FragmentNode
	// contains filtered or unexported fields
}

FragmentNode is an emitted occurrence. Fragment and the flat views receive their final paint indices and chain metadata when Flow closes the page.

type FragmentNodeKind

type FragmentNodeKind string

const (
	FragmentPageBlock  FragmentNodeKind = "page-block"
	FragmentDecoration FragmentNodeKind = "decoration"
	FragmentTextRun    FragmentNodeKind = "text-run"
)

type InlineBoxDecoration

type InlineBoxDecoration struct {
	Box              PlacedBox
	OffsetX, OffsetY float64
}

InlineBoxDecoration is one painted line fragment attached to the first run of its inline source. Offsets are relative to that run so later placement translations keep text and decoration together.

type OpacityGroup

type OpacityGroup struct {
	ID      int
	Opacity float64
}

OpacityGroup identifies a compositing group for a box and its descendants.

type Options

type Options struct {
	PageWidth, PageHeight float64
	PageBackground        [4]float64
	HasPageBackground     bool
	PageRotation          int
	PageBleed             float64
	PageMarks             css.PageMarks
	PageRules             []css.PageRule

	Margin      float64 // equal on all four sides (v0.3)
	PageMargins css.PageMargins

	FontSize     float64 // pt
	LineHeight   float64 // Global override; 0 uses the font's normal value.
	Measure      func(text string, fontSize float64) float64
	MeasureBold  func(text string, fontSize float64) float64 // nil = Measure
	Faces        map[string]*fonts.Face                      // @font-face registry (nil = Helvetica only)
	FontVariants map[string]fonts.Variants
	// contains filtered or unexported fields
}

Options configures the page and base typography.

func DefaultOptions

func DefaultOptions() Options

DefaultOptions uses A4, a 1-inch margin, and a 12 pt base font size.

type Page

type Page struct {
	Number       int
	Geometry     PageGeometry
	Blocks       []PlacedBox
	Fragments    []BoxFragment
	FragmentTree []*FragmentNode
	// contains filtered or unexported fields
}

Page is a page numbered from 1. FragmentTree is the structural output; Blocks and Fragments are flat views published when Flow completes.

func Flow

func Flow(root *boxes.Box, opts Options) []Page

Flow lays out the direct children of root and opens a new page when the block does not fit in the remaining content area.

type PageGeometry

type PageGeometry struct {
	Width, Height float64
	Margins       css.PageMargins
	Background    [4]float64
	HasBackground bool
	Rotation      int
	Bleed         float64
	Marks         css.PageMarks
}

PageGeometry is the resolved physical and content geometry for one output page.

type PlacedBox

type PlacedBox struct {
	FragmentainerIndex             int // 0 is page flow; columns start at 1.
	Text                           string
	Image                          *images.Raster // resolved <img> content
	SVG                            *svg.Document  // SVG inline
	HasBg                          bool
	CollapsedTableCell             bool       // Borders are centered on collapsed table-grid edges.
	CollapsedBorderPaintSuppressed [4]bool    // top, right, bottom, left
	TablePaintGroup                *boxes.Box // Source table whose cell paint is composed in phases.
	Bg                             [4]float64
	BorderWidth                    float64
	BorderCornerRadii              [4]boxes.CornerRadius
	Border                         [4]float64
	BorderTop, BorderRight         boxes.BorderSide
	BorderBottom, BorderLeft       boxes.BorderSide
	FontSize                       float64 // resolved (Options default when the box does not set one)
	HasColor                       bool
	Color                          [4]float64
	Link                           string
	Align                          string // left | center | right | justify
	PadLeft                        float64
	PadRight                       float64
	Font                           *fonts.Face // nil = Helvetica base-14
	Bold                           bool
	Italic                         bool
	Underline                      bool
	Strike                         bool
	Opacity                        float64
	HasOpacity                     bool
	OpacityGroups                  []OpacityGroup
	TablePaintUnderlays            []TablePaintLayer
	TablePaintOverlays             []TablePaintLayer
	ClipRects                      []ClipRect
	LetterSpacing                  float64
	Runs                           [][]TextRun // Inline runs per line; nil outside normal flow.
	X, Y                           float64
	Width                          float64
	Height                         float64
	// contains filtered or unexported fields
}

PlacedBox is a positioned block. X and and are its top-left coordinates in points.

type TablePaintEdges

type TablePaintEdges uint8

TablePaintEdges selects the border edges visible on a structural fragment.

const (
	TablePaintTop TablePaintEdges = 1 << iota
	TablePaintRight
	TablePaintBottom
	TablePaintLeft
	TablePaintAllEdges = TablePaintTop | TablePaintRight | TablePaintBottom | TablePaintLeft
)

type TablePaintLayer

type TablePaintLayer struct {
	Source *boxes.Box
	Bounds FragmentBounds
	Edges  TablePaintEdges
}

TablePaintLayer retains the source box and fragment geometry for table, row-group, and row paint layers that the cell grid does not place directly.

type TextRun

type TextRun struct {
	Text                            string
	Shaped                          fonts.ShapedText
	Image                           *images.Raster
	ImageHeight                     float64
	SVG                             *svg.Document
	SVGHeight                       float64
	X, Y                            float64 // Absolute X; Y is the line top.
	BaselineOffset                  float64 // Distance from Y to the baseline.
	Width                           float64
	LineH                           float64 // Height of the line.
	FontSize                        float64
	Bold, Italic, Underline, Strike bool
	HasColor                        bool
	Color                           [4]float64
	Link                            string
	Font                            *fonts.Face
	LetterSpacing                   float64
	Alpha                           float64 // effective alpha (color multiplied by opacity)
	GroupOpacity                    bool    // opacity comes from the composited block
	ListMarkerShape                 string
	LineY                           float64
	InlineDecorations               []InlineBoxDecoration
	// contains filtered or unexported fields
}

TextRun represents a positioned inline item: text or a replaced image.