Wrapper to make a deck client

[ajstarks]

I'm exploring the package as a possible replacement for fpdf as a
deck client.

The progress so far.

For example I'm looking for a method to specify page dimensions outside of built-in ones. Also the default orientation is portrait, what is the best method for flipping to landscape? The current methods rotate the whole page, but not the operations on the page.

[kolkov]

Hi @ajstarks, great to see you building a deck client on gxpdf! We've implemented everything you need in the upcoming v0.4.0.

Custom Page Dimensions

New method NewPageWithDimensions(widthPt, heightPt) for arbitrary sizes:

// Custom 6×9 inch book page
page, err := c.NewPageWithDimensions(creator.InchesToPoints(6), creator.InchesToPoints(9))

// Custom millimeter dimensions
page, err := c.NewPageWithDimensions(creator.MMToPoints(200), creator.MMToPoints(300))

Landscape Orientation

NewPageWithSize now accepts an optional orientation parameter — the industry-standard approach used by PDFKit, jsPDF, gofpdf, and others:

// Portrait (default — same as before)
page, err := c.NewPageWithSize(creator.A4)

// True landscape — swapped MediaBox, no /Rotate, content stays upright
page, err := c.NewPageWithSize(creator.A4, creator.Landscape)
page, err := c.NewPageWithSize(creator.Letter, creator.Landscape)

Presentation Slides

Since deck is about slides, we also added presentation sizes as first-class constants:

// Widescreen 16:9 (960×540 pt = 13.33×7.5 in) — PowerPoint/Keynote default
page, err := c.NewPageWithSize(creator.Slide16x9)

// Classic 4:3 (720×540 pt = 10×7.5 in)
page, err := c.NewPageWithSize(creator.Slide4x3)

35+ Built-in Page Sizes

We expanded from 8 to 35+ page sizes — ISO A/B/C series, ANSI engineering, photo, book, envelopes, JIS, and more. All available as typed constants with full IDE autocomplete.

Unit Conversion Helpers

creator.InchesToPoints(8.5)  // 612
creator.MMToPoints(210)      // ~595
creator.CMToPoints(21)       // ~595

---

These changes are on the feat/v0.4.0-creator-api branch. Before we finalize and release v0.4.0, we'd love your feedback:

1. Does this API match what you need for deck? Anything missing or awkward for your use case?
2. Slide dimensions — we went with 960×540 (16:9) and 720×540 (4:3). Do these match what deck uses, or do you need different defaults?
3. Landscape API style — we chose NewPageWithSize(A4, Landscape) over a separate NewPageLandscape(A4) method after researching 16 PDF libraries. Does the optional parameter feel natural to you?

You can review the full implementation in PR #44. Your input as a real-world user building on gxpdf is valuable — happy to adjust the API before it ships.

[ajstarks]

The changes look very nice. I think I can work with what you have planned for 0.4.0

For slide dimensions I tend to use 1920x1080 and 1600x900 for 16:9. For 4:3 I tend to use 1200x900.

FWIW, In terms of page sizes, my standard for deck clients is to use the code below, and the command line client just uses the name.

const (
	mm2pt       = 2.83464 // mm to pt conversion
)
// PageDimen describes page dimensions
// the unit field is used to convert to pt.
type PageDimen struct {
	width, height, unit float64
}
// opts are command line options
var opts options

// fontmap maps generic font names to specific implementation names
var fontmap = map[string]string{}

// pagemap defines page dimensions
var pagemap = map[string]PageDimen{
	"Letter":     {792, 612, 1},
	"Legal":      {1008, 612, 1},
	"Tabloid":    {1224, 792, 1},
	"ArchA":      {864, 648, 1},
	"Widescreen": {1152, 648, 1},
	"4R":         {432, 288, 1},
	"Index":      {360, 216, 1},
	"A2":         {420, 594, mm2pt},
	"A3":         {420, 297, mm2pt},
	"A4":         {297, 210, mm2pt},
	"A5":         {210, 148, mm2pt},
}

...
// setpagesize parses the page size string (wxh)
func setpagesize(s string) (float64, float64) {
	var width, height float64
	var err error
	d := strings.FieldsFunc(s, func(c rune) bool { return !unicode.IsNumber(c) })
	if len(d) != 2 {
		return 0, 0
	}
	width, err = strconv.ParseFloat(d[0], 64)
	if err != nil {
		return 0, 0
	}
	height, err = strconv.ParseFloat(d[1], 64)
	if err != nil {
		return 0, 0
	}
	return width, height
}

...
// set page dimensions
	pw, ph := setpagesize(opts.pagesize)
	if pw == 0 && ph == 0 {
		p, ok := pagemap[opts.pagesize]
		if !ok {
			p = pagemap["Letter"]
		}
		pw = p.width * p.unit
		ph = p.height * p.unit
	}
	pageconfig := fpdf.InitType{
		UnitStr:    "pt",
		SizeStr:    opts.pagesize,
		Size:       fpdf.SizeType{Wd: pw, Ht: ph},
		FontDirStr: setfontdir(opts.fontdir),
	}

	// set default fonts
	fontmap["sans"] = opts.sansfont
	fontmap["serif"] = opts.serifont
	fontmap["mono"] = opts.monofont
	fontmap["symbol"] = opts.symbolfont

[kolkov]

Thanks for sharing your pagemap code — really helpful to see how deck handles page dimensions in practice.

Slide Dimensions

Good news: our Slide16x9 (960 × 540 pt) is exactly 13.33 × 7.5 inches — the PowerPoint/Keynote widescreen default. When exported at 2× DPI (144 dpi), it produces a 1920 × 1080 pixel image, which maps directly to your rendering canvas.

Your Widescreen entry (1152 × 648 pt = 16 × 9 inches) is a larger physical canvas. If you need that specific size, NewPageWithDimensions supports it directly:

// deck's "Widescreen" — 16×9 inches
page, _ := c.NewPageWithDimensions(creator.InchesToPoints(16), creator.InchesToPoints(9))

// Or use the standard slide size matching PowerPoint
page, _ := c.NewPageWithSize(creator.Slide16x9)

Landscape Handling

We noticed your pagemap defines all sizes landscape-first (width > height). Our library uses portrait-first for paper sizes (the convention used by every major PDF library we surveyed), with Landscape to swap. But Slide16x9 and Slide4x3 are already landscape-oriented — no need to pass Landscape for slides.

If there's demand for a built-in Slide16x9Large (1152 × 648 pt) matching deck's Widescreen, we can add it — let us know.