Help us shape the future of Go! Take the 2026 Go Developer Survey

gipdf

package module
v1.2.4 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Apr 14, 2025 License: MIT Imports: 5 Imported by: 0

README

gipdf

A Go library for creating PDF documents with an element-based composition system. Built on top of github.com/signintech/gopdf with an easier API for common document creation tasks.

Features

  • Composable element-based architecture
  • Simple layout management with support for dimensions and aspect ratios
  • Box elements with background colors and rounded corners
  • Image elements with automatic sizing
  • Debug mode to visualize element boundaries
  • Easy extension for custom elements

Installation

go get github.com/yourusername/gipdf

Basic Usage

package main

import (
    "github.com/yourusername/gipdf"
)

func main() {
    // Create a new document
    doc := gipdf.New(gipdf.Config{
        Width:  595.28,
        Height: 841.89,
        Debug:  false, // Set to true to visualize element boundaries
    })

    // Add a page
    doc.AddPage()

    // Create a box with a blue background
    box := &gipdf.Box{
        Width:      gipdf.Float(400),
        Height:     gipdf.Float(200),
        Background: gipdf.Color{R: 66, G: 133, B: 244},
        CornerRadius: [4]float64{10, 10, 10, 10}, // Rounded corners
    }

    // Add the box to the document at position x:50, y:50
    doc.Add(box, 50, 50)

    // Add an image
    img := &gipdf.Image{
        Path:  "path/to/image.jpg",
        Width: gipdf.Float(200), // Fixed width
        Ratio: 16.0/9.0,         // Will determine height based on aspect ratio
    }

    // Add the image inside a box
    boxWithImage := &gipdf.Box{
        Width:      gipdf.Float(300),
        Height:     gipdf.Float(200),
        Background: gipdf.Color{R: 255, G: 255, B: 255},
        Children:   []gipdf.Element{img},
    }

    doc.Add(boxWithImage, 50, 300)

    // Save the document
    doc.Save("output.pdf")
}

Element Types

Box

A container element that can have a background color, rounded corners, and contain child elements.

box := &gipdf.Box{
    Width:        gipdf.Float(300),
    Height:       gipdf.Float(200),
    Background:   gipdf.Color{R: 240, G: 240, B: 240},
    CornerRadius: [4]float64{5, 5, 5, 5}, // TL, TR, BR, BL
    Children:     []gipdf.Element{/* child elements */},
}
Image

An element for rendering images with control over dimensions and aspect ratio.

image := &gipdf.Image{
    Path:   "path/to/image.jpg",
    Ratio:  1.5,               // Aspect ratio (width/height)
    Width:  gipdf.Float(200),  // Fixed width (optional)
    Height: gipdf.Float(150),  // Fixed height (optional)
}

Advanced Usage

Debug Mode

Enable debug mode to see element boundaries:

doc := gipdf.New(gipdf.Config{
    Width:  595.28,
    Height: 841.89,
    Debug:  true,
})
Creating Custom Elements

Implement the Element interface to create custom elements:

type Element interface {
    Render(ctx *RenderContext, x, y, width, height float64) error
    AspectRatio() float64
    FixedWidth() *float64
    FixedHeight() *float64
}

Example custom element:

type Circle struct {
    Diameter *float64
    Color    Color
}

func (c *Circle) AspectRatio() float64  { return 1.0 }
func (c *Circle) FixedWidth() *float64  { return c.Diameter }
func (c *Circle) FixedHeight() *float64 { return c.Diameter }

func (c *Circle) Render(ctx *RenderContext, x, y, width, height float64) error {
    // Implementation to draw a circle
    // ...
    return nil
}

License

MIT

Dependencies

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Documentation

Index

Constants

View Source 
const (
	AlignStart  = "start"
	AlignCenter = "center"
	AlignEnd    = "end"
)

Variables

View Source 
var PageSizeA4 = gopdf.PageSizeA4

Functions

func Ptr added in v1.2.0 

func Ptr[T any](f T) *T

func Rectangle added in v1.2.0 

func Rectangle(gp *gopdf.GoPdf, x0 float64, y0 float64, x1 float64, y1 float64, style string, radi [4]float64, radiusPointNum int) error

Types

type AlignedElement added in v1.2.1 

type AlignedElement struct {
	Element
	HAlign string // "start", "center", "end"
	VAlign string // "start", "center", "end"
}

func Align added in v1.2.1 

func Align(el Element, hAlign, vAlign string) *AlignedElement

type Box added in v1.2.0 

type Box struct {
	Ratio        float64
	Width        *float64
	Height       *float64
	Background   Color
	CornerRadius [4]float64 // TL, TR, BR, BL
	Children     []Element
	NoPadding    bool
}

func (*Box) AspectRatio added in v1.2.0 

func (b *Box) AspectRatio() float64

func (*Box) FixedHeight added in v1.2.0 

func (b *Box) FixedHeight() *float64

func (*Box) FixedWidth added in v1.2.0 

func (b *Box) FixedWidth() *float64

func (*Box) Render added in v1.2.0 

func (b *Box) Render(ctx *RenderContext, x, y, width, height float64) error

type Color 

type Color struct {
	R, G, B uint8
}

func HexColor added in v1.2.3 

func HexColor(hex string) Color

func NewColor added in v1.2.0 

func NewColor(r, g, b uint8) Color

type Column 

type Column struct {
	Elements []Element
	Ratio    float64
	Width    *float64
	Height   *float64
}

func (*Column) AspectRatio 

func (c *Column) AspectRatio() float64

func (*Column) FixedHeight added in v1.1.1 

func (c *Column) FixedHeight() *float64

func (*Column) FixedWidth added in v1.1.1 

func (c *Column) FixedWidth() *float64

func (*Column) Render 

func (c *Column) Render(ctx *RenderContext, x, y, width, height float64) error

type Config 

type Config struct {
	PageSize        *gopdf.Rect
	PageUnits       Unit
	Fonts           []*Font
	BackGroundColor *Color
	Debug           bool
}

type Element added in v1.2.0 

type Element interface {
	Render(ctx *RenderContext, x, y, width, height float64) error
	AspectRatio() float64
	FixedWidth() *float64
	FixedHeight() *float64
}

type Empty added in v1.2.0 

type Empty struct {
	Ratio  float64
	Width  *float64
	Height *float64
}

Empty is a placeholder for empty elements in the document.

func (*Empty) AspectRatio added in v1.2.0 

func (e *Empty) AspectRatio() float64

func (*Empty) FixedHeight added in v1.2.0 

func (e *Empty) FixedHeight() *float64

func (*Empty) FixedWidth added in v1.2.0 

func (e *Empty) FixedWidth() *float64

func (*Empty) Render added in v1.2.0 

func (e *Empty) Render(ctx *RenderContext, x, y, width, height float64) error

type Font 

type Font struct {
	Family  string
	Data    func() ([]byte, error)
	Default bool
}

type Image added in v1.2.0 

type Image struct {
	GetBytes func() ([]byte, error)
	Ratio    float64
	Width    *float64
	Height   *float64
}

func (*Image) AspectRatio added in v1.2.0 

func (i *Image) AspectRatio() float64

func (*Image) FixedHeight added in v1.2.0 

func (i *Image) FixedHeight() *float64

func (*Image) FixedWidth added in v1.2.0 

func (i *Image) FixedWidth() *float64

func (*Image) Render added in v1.2.0 

func (i *Image) Render(ctx *RenderContext, x, y, width, height float64) error

type Margin added in v1.2.0 

type Margin struct {
	Top, Bottom, Left, Right float64
}

func DefaultMargin added in v1.2.0 

func DefaultMargin() Margin

type PDF added in v1.2.0 

type PDF struct {
	PageSet *PageSet
	Config  *Config
	// contains filtered or unexported fields
}

func New added in v1.2.0 

func New(config *Config) *PDF

func (*PDF) AddPage added in v1.2.0 

func (p *PDF) AddPage(elements ...Element) *Page

func (*PDF) Render added in v1.2.0 

func (p *PDF) Render() error

func (*PDF) WriteFile added in v1.2.0 

func (p *PDF) WriteFile(filename string) error

func (*PDF) WriteTo added in v1.2.0 

func (p *PDF) WriteTo(w io.Writer) (int64, error)

type Padding 

type Padding struct {
	Top, Right, Bottom, Left float64
}

type PaddingElement added in v1.2.2 

type PaddingElement struct {
	Element Element
	Padding Padding
}

func Pad added in v1.2.2 

func Pad(element Element, top, right, bottom, left float64) *PaddingElement

func (*PaddingElement) AspectRatio added in v1.2.2 

func (p *PaddingElement) AspectRatio() float64

func (*PaddingElement) FixedHeight added in v1.2.2 

func (p *PaddingElement) FixedHeight() *float64

func (*PaddingElement) FixedWidth added in v1.2.2 

func (p *PaddingElement) FixedWidth() *float64

func (*PaddingElement) Render added in v1.2.2 

func (p *PaddingElement) Render(ctx *RenderContext, x, y, width, height float64) error

type Page added in v1.2.0 

type Page struct {
	Elements   []Element
	Margin     Margin
	BackGround *Color
	Header     Element
	Footer     Element
}

func (*Page) AspectRatio added in v1.2.0 

func (p *Page) AspectRatio() float64

func (*Page) FixedHeight added in v1.2.0 

func (p *Page) FixedHeight() *float64

func (*Page) FixedWidth added in v1.2.0 

func (p *Page) FixedWidth() *float64

func (*Page) FooterHeight added in v1.2.0 

func (p *Page) FooterHeight() float64

func (*Page) HeaderHeight added in v1.2.0 

func (p *Page) HeaderHeight() float64

func (*Page) Render added in v1.2.0 

func (p *Page) Render(ctx *RenderContext, x, y, width, height float64) error

type PageSet added in v1.2.0 

type PageSet struct {
	Pages []*Page
}

func (*PageSet) Render added in v1.2.0 

func (ps *PageSet) Render(pdf *gopdf.GoPdf, pageSize gopdf.Rect, debug bool) error

type PositionedElement added in v1.2.1 

type PositionedElement struct {
	X, Y    float64  // Absolute position on the page (in points)
	Width   *float64 // Optional fixed width
	Height  *float64 // Optional fixed height
	Element Element  // Wrapped inner element
}

PositionedElement represents an element that is positioned at a specific location on the page. Can not be used with an aspect ratio!

func (*PositionedElement) AspectRatio added in v1.2.1 

func (p *PositionedElement) AspectRatio() float64

func (*PositionedElement) FixedHeight added in v1.2.1 

func (p *PositionedElement) FixedHeight() *float64

func (*PositionedElement) FixedWidth added in v1.2.1 

func (p *PositionedElement) FixedWidth() *float64

func (*PositionedElement) Render added in v1.2.1 

func (p *PositionedElement) Render(ctx *RenderContext, x, y, _, _ float64) error

type RenderContext added in v1.2.0 

type RenderContext struct {
	PDF        *gopdf.GoPdf
	PageHeight float64
	PageWidth  float64
	CursorY    float64
	Debug      bool
}

func (*RenderContext) EnsureSpace added in v1.2.0 

func (ctx *RenderContext) EnsureSpace(heightNeeded float64)

func (*RenderContext) MoveY added in v1.2.0 

func (ctx *RenderContext) MoveY(offset float64)

type Row 

type Row struct {
	Elements []Element
	Ratio    float64 // for nesting
	Width    *float64
	Height   *float64
}

func NewRow added in v1.2.0 

func NewRow(elements ...Element) *Row

func (*Row) AspectRatio 

func (r *Row) AspectRatio() float64

func (*Row) FixedHeight added in v1.1.1 

func (r *Row) FixedHeight() *float64

func (*Row) FixedWidth added in v1.1.1 

func (r *Row) FixedWidth() *float64

func (*Row) Render 

func (r *Row) Render(ctx *RenderContext, x, y, width, height float64) error

type Text added in v1.2.0 

type Text struct {
	Text     string
	Ratio    float64
	Width    *float64
	Height   *float64
	FontSize float64
	FontName string
	Color    *Color
}

func (*Text) AspectRatio added in v1.2.0 

func (t *Text) AspectRatio() float64

func (*Text) FixedHeight added in v1.2.0 

func (t *Text) FixedHeight() *float64

func (*Text) FixedWidth added in v1.2.0 

func (t *Text) FixedWidth() *float64

func (*Text) Render added in v1.2.0 

func (t *Text) Render(ctx *RenderContext, x, y, width, height float64) error

type Unit added in v1.2.0 

type Unit int
const (
	UnitUnset Unit = gopdf.UnitUnset // No units were set, when conversion is called on nothing will happen
	UnitPT    Unit = gopdf.UnitPT    // Points
	UnitMM    Unit = gopdf.UnitMM    // Millimeters
	UnitCM    Unit = gopdf.UnitCM    // Centimeters
	UnitIN    Unit = gopdf.UnitIN    // Inches
	UnitPX    Unit = gopdf.UnitPX    // Pixels
)

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.