pptx

package
v0.0.0-...-2a9920d Latest Latest
Warning

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

 Go to latest Published: Aug 12, 2026 License: Apache-2.0 Imports: 34 Imported by: 0

Documentation

Overview

Package pptx provides a high-level API for authoring PPTX files.

Package pptx provides a high-level API for authoring PPTX files.

Package pptx provides a high-level API for authoring PPTX files.

Package pptx provides a high-level API for authoring PPTX files.

Package pptx provides a high-level interface for working with PPTX files.

Package pptx provides a high-level interface for working with PPTX files. It is the primary entry point for both human developers and AI callers.

Package pptx provides a high-level interface for working with PPTX files.

Package pptx provides a high-level API for authoring PPTX files.

Package pptx provides a high-level API for authoring PPTX files, and serves as the primary entry point for both human developers and AI callers.

Index

Constants

View Source 
const (
	AlphaOpaque      = 100000
	AlphaTransparent = 0
)

Alpha bounds (OOXML range 0..100000; 100000 = fully opaque).

View Source 
const DefaultSectionName = "Default Section"

DefaultSectionName is the name of the implicit section that holds slides not assigned to any caller-created section.

View Source 
const (
	// EMUsPerPixel is the number of EMUs per pixel at 96 DPI.
	// 1 inch = 914400 EMU, 1 inch = 96 pixels (96 DPI),
	// therefore 1 px = 914400 / 96 = 9525 EMU.
	EMUsPerPixel = 914400 / 96 // = 9525
)

Variables

View Source 
var (
	// SlideSize16x9 is the widescreen slide size (16:9).
	// Width: 1280 px (13.333 inches), Height: 720 px (7.5 inches).
	SlideSize16x9 = SlideSize{Width: 1280, Height: 720}

	// SlideSize4x3 is the standard slide size (4:3).
	// Width: 960 px (10 inches), Height: 720 px (7.5 inches).
	SlideSize4x3 = SlideSize{Width: 960, Height: 720}

	// SlideSize16x10 is the wide slide size (16:10).
	// Width: 1280 px (13.333 inches), Height: 800 px (8.333 inches).
	SlideSize16x10 = SlideSize{Width: 1280, Height: 800}
)

Standard slide size variables.

View Source 
var ErrFontNotFound = errors.New("pptx: font not found")

ErrFontNotFound is returned when the FontSource cannot resolve a font.

View Source 
var ErrImageMIMEMismatch = errors.New("pptx: declared image MIME does not match content")

ErrImageMIMEMismatch is returned when the declared MIME type does not match the type sniffed from the bytes.

View Source 
var ErrImagePartMissing = errors.New("pptx: image media part not found")

ErrImagePartMissing is returned by Image.Bytes when the picture's embedded relationship or its media part cannot be resolved in the reopened package.

View Source 
var ErrNoFontSource = errors.New("pptx: no font source registered (use SetFontSource)")

ErrNoFontSource is returned by EmbedFont when no FontSource is registered.

View Source 
var ErrThemeNotFound = errors.New("pptx: no theme part in package")

ErrThemeNotFound is returned by LoadTheme when the package has no theme part.

View Source 
var ErrUnknownImageFormat = errors.New("pptx: unrecognized or malformed image data")

ErrUnknownImageFormat is returned when image bytes carry no recognizable image signature (PNG, JPEG, GIF, BMP, WebP).

Functions

func EMUToPx 

func EMUToPx(emu int) int

EMUToPx converts EMU to pixels (at 96 DPI).

func GetEmbeddedDefaultTemplate 

func GetEmbeddedDefaultTemplate() (*opc.Package, error)

GetEmbeddedDefaultTemplate returns a clone of the default embedded template.

func GetEmbeddedTemplate 

func GetEmbeddedTemplate(name TemplateType) (*opc.Package, error)

GetEmbeddedTemplate returns a clone of the named embedded template.

func InitEmbeddedTemplates 

func InitEmbeddedTemplates() error

InitEmbeddedTemplates initializes all embedded templates.

func LoadDefaultTemplate 

func LoadDefaultTemplate() (*opc.Package, error)

LoadDefaultTemplate loads the default template using the global manager.

func LoadTemplate 

func LoadTemplate(name TemplateType) (*opc.Package, error)

LoadTemplate loads the named template using the global manager.

func PxToEMU deprecated 

func PxToEMU(px int) int

PxToEMU converts pixels to EMU (at 96 DPI).

Deprecated: shape methods now take EMU directly; use pptx.Px (which returns a typed EMU) to convert pixel coordinates.

func RegisterTemplate 

func RegisterTemplate(name TemplateType, path string) error

RegisterTemplate registers a template by file path using the global manager.

func RegisterTemplateFromBytes 

func RegisterTemplateFromBytes(name TemplateType, data []byte) error

RegisterTemplateFromBytes registers a template from raw bytes using the global manager.

func ValidateIcon 

func ValidateIcon(svg []byte) error

ValidateIcon reports whether svg satisfies the icon translator constraints (single path, solid fill, no gradients, no elliptical arcs), without drawing it. It is the registration-time check curated assets and scene.WithIconExtension use to fail fast (D-005).

Types

type Alignment 

type Alignment int

Alignment is a paragraph's horizontal alignment. 

const (
	AlignLeft Alignment = iota
	AlignCenter
	AlignRight
	AlignJustify
)

type Anchor 

type Anchor int

Anchor names a reference point on a shape — used to position a Decoration or attach a Connector endpoint. The scene renderer translates an Anchor (plus offset) into EMU coordinates at render time. 

const (
	AnchorTopLeft Anchor = iota
	AnchorTopCenter
	AnchorTopRight
	AnchorCenterLeft
	AnchorCenter
	AnchorCenterRight
	AnchorBottomLeft
	AnchorBottomCenter
	AnchorBottomRight
)

func (Anchor) Point 

func (a Anchor) Point(b Box) Position

Point returns the EMU coordinate of the anchor on the given box.

type AutoFitMode 

type AutoFitMode int

AutoFitMode controls how a TextFrame fits text to its shape (RFC §8.4). 

const (
	// AutoFitNone keeps the text and shape sizes fixed (text may overflow).
	AutoFitNone AutoFitMode = iota
	// AutoFitNormal shrinks the font to fit the shape.
	AutoFitNormal
	// AutoFitShape grows the shape to fit the text.
	AutoFitShape
)

type BaselineShift 

type BaselineShift int

BaselineShift raises or lowers a run relative to the baseline. 

const (
	BaselineNone BaselineShift = iota
	Superscript
	Subscript
)

type BoundaryCheckResult 

type BoundaryCheckResult struct {
	// Status is the boundary state.
	Status BoundaryStatus
	// ElementRect is the element rectangle (x, y, cx, cy in px).
	ElementRect Rect
	// ViewportRect is the viewport rectangle (0, 0, width, height in px).
	ViewportRect Rect
	// OverflowX is the overflow amount along X (positive = right overflow, negative = left overflow).
	OverflowX int
	// OverflowY is the overflow amount along Y (positive = bottom overflow, negative = top overflow).
	OverflowY int
	// IsVisible indicates whether any part of the element is within the viewport.
	IsVisible bool
}

BoundaryCheckResult holds the result of a boundary check.

type BoundaryStatus 

type BoundaryStatus int

BoundaryStatus describes the boundary state of an element. 

const (
	// BoundaryStatusInside means the element is fully within the viewport.
	BoundaryStatusInside BoundaryStatus = iota
	// BoundaryStatusPartial means the element partially overflows the viewport.
	BoundaryStatusPartial
	// BoundaryStatusOutside means the element is fully outside the viewport.
	BoundaryStatusOutside
	// BoundaryStatusOverflowRight means the element overflows the right edge.
	BoundaryStatusOverflowRight
	// BoundaryStatusOverflowLeft means the element overflows the left edge.
	BoundaryStatusOverflowLeft
	// BoundaryStatusOverflowTop means the element overflows the top edge.
	BoundaryStatusOverflowTop
	// BoundaryStatusOverflowBottom means the element overflows the bottom edge.
	BoundaryStatusOverflowBottom
)

func (BoundaryStatus) String 

func (bs BoundaryStatus) String() string

String returns the string representation of the boundary status.

type Box 

type Box struct {
	X, Y, W, H EMU
}

Box is a positioned rectangle: the offset (X, Y) and extent (W, H) of a shape on the slide canvas, in EMU. It is the geometry every builder primitive accepts.

func (Box) Bottom 

func (b Box) Bottom() EMU

Bottom returns the Y coordinate of the box's bottom edge.

func (Box) Inset 

func (b Box) Inset(in Inset) Box

Inset shrinks the box inward by the given inset and returns the result.

func (Box) Position 

func (b Box) Position() Position

Position returns the box's top-left offset.

func (Box) Right 

func (b Box) Right() EMU

Right returns the X coordinate of the box's right edge.

func (Box) Size 

func (b Box) Size() Size

Size returns the box's extent.

type BulletKind 

type BulletKind int

BulletKind is a paragraph's bullet style. 

const (
	BulletNone BulletKind = iota
	BulletDisc
	BulletNumber
	BulletCheckbox
)

type Cell 

type Cell struct {
	// contains filtered or unexported fields
}

Cell is a handle to a table cell.

func (*Cell) Covered 

func (c *Cell) Covered() bool

Covered reports whether the cell is covered by a neighboring cell's merge (hMerge or vMerge) — i.e. it is not the merge anchor and renders no content.

func (*Cell) Fill 

func (c *Cell) Fill() Fill

Fill returns the cell's interior fill, or nil when the cell has no explicit fill — the read inverse of SetFill.

func (*Cell) GridSpan 

func (c *Cell) GridSpan() int

GridSpan returns the number of columns the cell spans (1 for an unmerged cell) — the read inverse of MergeRight.

func (*Cell) MergeDown 

func (c *Cell) MergeDown(n int) *Cell

MergeDown spans the cell across n rows (n ≥ 2), marking the covered cells.

func (*Cell) MergeRight 

func (c *Cell) MergeRight(n int) *Cell

MergeRight spans the cell across n columns (n ≥ 2), marking the covered cells.

func (*Cell) RowSpan 

func (c *Cell) RowSpan() int

RowSpan returns the number of rows the cell spans (1 for an unmerged cell) — the read inverse of MergeDown.

func (*Cell) SetBorders 

func (c *Cell) SetBorders(line Line) *Cell

SetBorders sets all four cell borders to line (resolved against the theme).

func (*Cell) SetFill 

func (c *Cell) SetFill(f Fill) *Cell

SetFill sets the cell's interior fill (resolved against the active theme).

func (*Cell) SetText 

func (c *Cell) SetText(text string) *Cell

SetText replaces the cell text with a single themed body run.

func (*Cell) TextFrame 

func (c *Cell) TextFrame() *TextFrame

TextFrame returns a rich-text frame over the cell's text body (the Phase 04 model — paragraphs, runs, hyperlinks).

type Color 

type Color interface {
	// contains filtered or unexported methods
}

Color is a write-time-resolved color: either a literal RGB value or a theme token. A token resolves against the active Theme when the color is applied, so the same builder input re-renders in a new palette after a theme swap (P2; D-012, D-030). Construct colors with RGB / RGBA (literals) or TokenColor / TokenTextColor (tokens).

The interface is sealed — resolve is unexported — so the only colors are the ones this package defines; callers cannot inject a type the codec can't emit.

func RGBA 

func RGBA(hex RGB, alpha int) Color

RGBA returns a literal color with the given OOXML alpha (0..100000).

func TokenColor 

func TokenColor(role ColorRole) Color

TokenColor returns a color bound to a semantic surface role (e.g. ColorAccent). It resolves to the active theme's value at apply time — swap the theme and the same token yields the new palette's color.

func TokenColorAlpha 

func TokenColorAlpha(role ColorRole, alpha int) Color

TokenColorAlpha returns a token color (TokenColor) at the given OOXML alpha (0..100000) — the token analogue of RGBA. It keeps the value token-bound (P2) while letting a caller dim it, e.g. a Decoration's opacity or a gradient glow's transparent edge.

func TokenTextColor 

func TokenTextColor(role TextColorRole) Color

TokenTextColor returns a color bound to a semantic text role (e.g. TextPrimary), resolved against the active theme at apply time.

type ColorPalette 

type ColorPalette struct {
	Surfaces map[ColorRole]RGB
	Text     map[TextColorRole]RGB
}

ColorPalette maps the surface and text color roles to concrete RGB values.

type ColorRole 

type ColorRole int

ColorRole is a semantic page-level surface color (RFC §7.1). 

const (
	ColorCanvas ColorRole = iota
	ColorSurface
	ColorSurfaceAlt
	ColorAccent
	ColorAccentAlt
	ColorAccentWarm
	ColorSuccess
	ColorWarning
	ColorError
	ColorInfo
	// ColorPaper is a faintly tinted off-white "paper" canvas, distinct from
	// pure white, for a designed background tone (D-104). It is appended last so
	// every prior ColorRole value is unchanged. It defaults to ColorCanvas's
	// value (white) so a deck is byte-identical until a theme overrides the tint.
	// ColorPaper has no theme1.xml slot — like TextMuted it keeps its default on
	// read-back (RFC §7.3); its resolved background RGB still round-trips.
	ColorPaper
)

type Component 

type Component interface {
	// Render writes the component's shapes into the slide via ctx.
	// An error indicates a rendering failure.
	Render(ctx *SlideContext) error
}

Component is the interface that all renderable slide building blocks must implement.

type ComponentList 

type ComponentList []Component

ComponentList is an ordered collection of components.

func (*ComponentList) Add 

func (cl *ComponentList) Add(c Component)

Add appends a component to the list.

func (ComponentList) Count 

func (cl ComponentList) Count() int

Count returns the number of components in the list.

func (ComponentList) RenderAll 

func (cl ComponentList) RenderAll(ctx *SlideContext) error

RenderAll renders every component in order, stopping on the first error.

type ComponentRenderError 

type ComponentRenderError struct {
	Index      int
	Component  Component
	Underlying error
}

ComponentRenderError is returned when a component fails to render.

func (*ComponentRenderError) Error 

func (e *ComponentRenderError) Error() string

Error implements the error interface.

func (*ComponentRenderError) Unwrap 

func (e *ComponentRenderError) Unwrap() error

Unwrap returns the underlying error.

type ComponentWithName 

type ComponentWithName interface {
	Component
	// Name returns the component's name.
	Name() string
}

ComponentWithName is a component that has a human-readable name (useful for debugging and logging).

type ComponentWithPosition 

type ComponentWithPosition interface {
	Component
	// SetPosition sets the component's position in EMU.
	SetPosition(x, y int)
	// Position returns the component's current position in EMU.
	Position() (x, y int)
}

ComponentWithPosition is a component whose position can be read and set.

type ComponentWithSize 

type ComponentWithSize interface {
	Component
	// Bounds returns the bounding box (x, y, cx, cy in EMU).
	Bounds() (x, y, cx, cy int)
}

ComponentWithSize is a component that exposes its bounding box.

type ComponentWithSizeSetter 

type ComponentWithSizeSetter interface {
	Component
	// SetSize sets the component's size in EMU.
	SetSize(cx, cy int)
	// Size returns the component's current size in EMU.
	Size() (cx, cy int)
}

ComponentWithSizeSetter is a component whose size can be read and set.

type CompositeComponent 

type CompositeComponent struct {
	// contains filtered or unexported fields
}

CompositeComponent groups multiple components and renders them in order.

func NewCompositeComponent 

func NewCompositeComponent(name string, components ...Component) *CompositeComponent

NewCompositeComponent creates a CompositeComponent with the given name and initial children.

func (*CompositeComponent) Add 

func (cc *CompositeComponent) Add(c Component)

Add appends a child component.

func (*CompositeComponent) Components 

func (cc *CompositeComponent) Components() []Component

Components returns all child components.

func (*CompositeComponent) Name 

func (cc *CompositeComponent) Name() string

Name implements ComponentWithName.

func (*CompositeComponent) Render 

func (cc *CompositeComponent) Render(ctx *SlideContext) error

Render implements Component.

type ConditionalComponent 

type ConditionalComponent struct {
	// contains filtered or unexported fields
}

ConditionalComponent renders one of two components depending on a runtime condition.

func NewConditionalComponent 

func NewConditionalComponent(condition func() bool, ifComponent, elseComponent Component) *ConditionalComponent

NewConditionalComponent creates a ConditionalComponent. ifComponent is rendered when condition returns true; elseComponent is rendered otherwise. Either may be nil.

func (*ConditionalComponent) Render 

func (cc *ConditionalComponent) Render(ctx *SlideContext) error

Render implements Component.

type Crop 

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

Crop is a per-edge crop expressed as a fraction (0..1) of the corresponding image dimension trimmed from that edge.

type DarkPalette 

type DarkPalette struct {
	Surfaces map[ColorRole]RGB     // VariantDark surface overrides
	Text     map[TextColorRole]RGB // VariantDark text overrides
}

DarkPalette is a theme's optional VariantDark color override set (R8.3). The scene renderer's dark-variant derivation writes its pinned neutral-gray default first, then overlays these surface/text roles when DarkColors is non-nil — so a brand renders its own deep dark side (e.g. navy) instead of the pinned gray. A nil DarkColors (the zero value) keeps the pinned gray default, byte-identical. It mirrors ColorPalette so any role can be overridden; the same maps carry the dark accent/extension overrides (R8.7).

DarkPalette has no theme1.xml slot — it is consumed only by the scene renderer to derive the VariantDark theme and is never serialized. The resolved dark RGB a slide renders with round-trips (and is reported via the render Stats.Colors hook, D-058); the field itself does not (like ColorPaper, D-104).

type DeduplicationStats 

type DeduplicationStats struct {
	// GlobalMediaCount is the number of unique media resources actually stored.
	GlobalMediaCount int64

	// TotalReferences is the total number of references across all slides.
	TotalReferences int64

	// SlideCount is the number of slides that reference media.
	SlideCount int64

	// SavedBytes is the estimated number of bytes saved by deduplication.
	SavedBytes int64

	// DeduplicationRate is the deduplication ratio (0.0 – 1.0).
	DeduplicationRate float64
}

DeduplicationStats holds deduplication statistics.

type EMU 

type EMU int64

EMU is the English Metric Unit, OOXML's canonical integer length unit. 1 inch = 914400 EMU. All public geometry in pptx is expressed in EMU; the Pt/Cm/In/Px constructors convert from human units at the call site. 

const (
	// Slide16x9Width / Slide16x9Height — the 13.333" × 7.5" widescreen canvas.
	Slide16x9Width  EMU = 12192000
	Slide16x9Height EMU = 6858000
	// Slide4x3Width / Slide4x3Height — the 10" × 7.5" classic canvas.
	Slide4x3Width  EMU = 9144000
	Slide4x3Height EMU = 6858000
)

Standard slide canvas sizes (RFC §8.1 / D-023).

func Cm 

func Cm(cm float64) EMU

Cm converts centimeters to EMU.

func In 

func In(in float64) EMU

In converts inches to EMU.

func Pt 

func Pt(pt float64) EMU

Pt converts points to EMU (1 pt = 1/72 inch).

func Px 

func Px(px float64) EMU

Px converts pixels to EMU at the 96-DPI reference PowerPoint uses.

func (EMU) Centimeters 

func (e EMU) Centimeters() float64

Centimeters returns the EMU value expressed in centimeters.

func (EMU) Inches 

func (e EMU) Inches() float64

Inches returns the EMU value expressed in inches.

func (EMU) Pixels 

func (e EMU) Pixels() float64

Pixels returns the EMU value expressed in pixels at the 96-DPI reference.

func (EMU) Points 

func (e EMU) Points() float64

Points returns the EMU value expressed in points.

type Elevation 

type Elevation struct {
	Blur    EMU // blur radius
	OffsetX EMU
	OffsetY EMU
	Color   RGB
	Alpha   int // 0–100000 (OOXML alpha), 0 = transparent
}

Elevation is a resolved shadow specification. A zero Elevation (Blur and offsets all zero) is "flat" — no shadow.

func (Elevation) IsFlat 

func (e Elevation) IsFlat() bool

IsFlat reports whether the elevation renders no shadow.

type ElevationRole 

type ElevationRole int

ElevationRole is a shadow/elevation step (RFC §7.1). 

const (
	ElevationFlat ElevationRole = iota
	ElevationRaised
	ElevationElevated
)

type Elevations 

type Elevations map[ElevationRole]Elevation

Elevations maps each elevation role to a resolved Elevation.

type EmbeddedTemplateManager 

type EmbeddedTemplateManager struct {
	// contains filtered or unexported fields
}

EmbeddedTemplateManager creates and caches presentation templates programmatically.

func GetEmbeddedTemplateManager 

func GetEmbeddedTemplateManager() *EmbeddedTemplateManager

GetEmbeddedTemplateManager returns the global EmbeddedTemplateManager.

func (*EmbeddedTemplateManager) GetDefaultTemplate 

func (etm *EmbeddedTemplateManager) GetDefaultTemplate() (*opc.Package, error)

GetDefaultTemplate returns a clone of the default template.

func (*EmbeddedTemplateManager) GetTemplate 

func (etm *EmbeddedTemplateManager) GetTemplate(name TemplateType) (*opc.Package, error)

GetTemplate returns a clone of the named template, initializing it on first use.

func (*EmbeddedTemplateManager) HasTemplate 

func (etm *EmbeddedTemplateManager) HasTemplate(name TemplateType) bool

HasTemplate reports whether the named template exists.

func (*EmbeddedTemplateManager) Init 

func (etm *EmbeddedTemplateManager) Init() error

Init initializes all embedded templates. Only the first call has any effect.

type Fill 

type Fill interface {

	// Kind reports the fill variety, for reading a (reopened) deck.
	Kind() FillKind
	// SolidColor returns the fill color and true when Kind is FillSolid.
	SolidColor() (Color, bool)
	// Gradient returns the gradient description and true when Kind is FillGradient.
	Gradient() (GradientRead, bool)
	// contains filtered or unexported methods
}

Fill is a shape's interior fill. Construct with SolidFill, NoFill, LinearGradient or RadialGradient. The interface is sealed (applyFill is unexported); a fill resolves its colors against the active theme when applied, so theme tokens re-render after a theme swap (P2).

V1 ships SolidFill, NoFill, and gradient fills (D-041). Pattern and picture (blip) shape fills remain tracked separately.

The read accessors (Kind / SolidColor / Gradient) let a fill recovered from a reopened deck be inspected (RFC §16). A reopened fill surfaces resolved literal colors — theme tokens are resolved to sRGB at write time (D-030), so the slide carries no token to reconstruct.

func LinearGradient 

func LinearGradient(angleDeg float64, stops ...GradientStop) Fill

LinearGradient returns a linear gradient fill across the stops (Pos 0..1) at angleDeg, measured clockwise from the positive x-axis (D-041).

func NoFill 

func NoFill() Fill

NoFill returns an explicit empty fill (<a:noFill/>) — the shape is transparent rather than inheriting a style fill.

func RadialGradient 

func RadialGradient(stops ...GradientStop) Fill

RadialGradient returns a radial gradient fill (path="circle") from the centre outward across the stops — the primitive behind glow ornaments (D-041).

func SolidFill 

func SolidFill(c Color) Fill

SolidFill returns a solid fill of the given color (literal or theme token).

type FillKind 

type FillKind int

FillKind discriminates a Fill read back from a deck. 

const (
	// FillSolid is a single-color fill (SolidFill).
	FillSolid FillKind = iota
	// FillNone is an explicit empty fill (NoFill / <a:noFill/>).
	FillNone
	// FillGradient is a linear or radial gradient fill.
	FillGradient
)

type Fit 

type Fit int

Fit selects how an image fills its frame. PowerPoint stores no single "fit" value, so V1 ships FitFill / FitNone and lets caller-side Box sizing drive aspect (engine, not product — D-026). Aspect-aware cover/contain is a V1.x candidate: it needs the image's dimensions, which can be read from the format header via image.DecodeConfig — the dimension header is not pixel data, so it is permitted (§7/D-046); the chart composer already reads it for aspect-fit. 

const (
	// FitFill stretches the image to fill the frame (the default).
	FitFill Fit = iota
	// FitNone places the image without a stretch fill mode.
	FitNone
)

type FontSource 

type FontSource interface {
	Resolve(name, style string, weight int) ([]byte, error)
}

FontSource resolves a font name + style + weight to its raw bytes. A missing font returns (nil, ErrFontNotFound). Callers inject one via SetFontSource or pptx.WithFontSource.

The returned bytes are embedded **verbatim** — pptx-go applies no size cap and no signature/format validation (the caller's responsibility, parallel to image and SVG bytes under CLAUDE.md §7). A FontSource may be invoked from the save path (the automatic embedding/fallback passes) and, when shared across several presentations saved concurrently, must be safe for concurrent use.

type FontSpec 

type FontSpec struct {
	Family string
	Size   float64
	Weight int
	Italic bool
	// Tracking is letter-spacing in points (signed): positive opens glyphs apart
	// (wide-tracked eyebrows/labels), negative tightens them (display headlines).
	// 0 (the zero value) emits nothing — byte-identical to an untracked run.
	// Emitted as the OOXML a:rPr/@spc attribute (1/100 pt). (D-060.)
	Tracking float64
	// LineHeight is the role's line spacing as a percent of single (100 = single,
	// 120 = 1.2×); tight display sets ~100–105, body ~120–135. 0 (the zero value)
	// and 100 emit nothing — byte-identical. The scene renderer applies it to a
	// node's paragraphs; emitted as OOXML a:pPr/a:lnSpc/a:spcPct. (D-061.)
	LineHeight float64
	// Case is the role's case transform (e.g. CaseUpper for tracked-caps
	// eyebrows). It is rendered via the OOXML a:rPr/@cap attribute, so the run
	// text stays original-case (round-trips) and PowerPoint/the rasterizer caps
	// it at display. CaseNone (the zero value) emits nothing — byte-identical.
	// (D-062.)
	Case TextCase
	// AvgCharWidth is the role face's average glyph advance as a fraction of the
	// font size, used only by the deterministic wrap/overflow estimator (it never
	// renders). A soul sets a measured factor for its bundled face (serif/display
	// faces advance differently from the default sans). 0 (the zero value) uses
	// the built-in ~0.5 sans fallback — byte-identical estimate. (D-064.)
	AvgCharWidth float64
	// Fallback is an ordered list of substitute families for this role. When a
	// FontSource is registered and it cannot resolve Family, the write-time
	// fallback pass emits the first Fallback entry the source can resolve (instead
	// of letting the host pick an arbitrary default), so output degrades to a
	// controlled near-match. Empty (the zero value) means no fallback —
	// byte-identical. The chosen face is recorded as the run's a:latin typeface
	// (OOXML run fonts are single-valued). (D-066.)
	Fallback []string
}

FontSpec is a resolved typography value: a font family, size in points, weight (100–900, 400 = regular, 700 = bold), italic flag, and letter-spacing.

func (FontSpec) Bold 

func (f FontSpec) Bold() bool

Bold reports whether the weight is bold (≥600).

type Format 

type Format int

Format is a standard slide canvas aspect ratio (RFC §8.1). Pass one to pptx.New via WithFormat. 

const (
	// Slides16x9 is the 16:9 widescreen canvas (12192000 x 6858000 EMU,
	// 13.333" x 7.5"). This is the default.
	Slides16x9 Format = iota

	// Slides4x3 is the 4:3 standard canvas (9144000 x 6858000 EMU, 10" x 7.5").
	Slides4x3
)

type FuncComponent 

type FuncComponent func(ctx *SlideContext) error

FuncComponent wraps a plain function as a Component.

func (FuncComponent) Render 

func (fc FuncComponent) Render(ctx *SlideContext) error

Render implements Component.

type GradientRead 

type GradientRead struct {
	// Stops are the gradient color stops in document order (Pos 0..1).
	Stops []GradientStop
	// Angle is the linear gradient angle in degrees clockwise from the positive
	// x-axis; it is 0 for a radial gradient.
	Angle float64
	// Radial reports whether the gradient is radial (RadialGradient).
	Radial bool
}

GradientRead is the readable description of a gradient fill (LinearGradient or RadialGradient) recovered from a deck.

type GradientSpec 

type GradientSpec struct {
	Stops  []GradientStop
	Angle  int
	Radial bool
}

GradientSpec is a named brand gradient (R8.5): an ordered stop list plus a linear angle and a linear/radial flag, stored on a Theme under a name and requested by a scene Background's GradientName. Each stop's Color is a pptx.Color, so a soul can pin an exact brand hue with an RGB literal (variant-independent) or follow the active theme with a TokenColor. Angle is the linear gradient angle in degrees clockwise from the positive x-axis and is ignored when Radial is true. It has no theme1.xml slot — the resolved gradient fill round-trips, the named spec does not (like DarkColors / Accents).

type GradientStop 

type GradientStop struct {
	Pos   float64
	Color Color
}

GradientStop is a color at a position (Pos 0..1) along a gradient.

type Image 

type Image struct {
	// contains filtered or unexported fields
}

Image is an opaque handle to an image added to a slide. It exposes typed mutators (alt text, crop, fit) without surfacing the OOXML wire type (P3), and read accessors over a reopened deck (RFC §16).

func (*Image) AltText 

func (im *Image) AltText() string

AltText returns the image's alternative text — the read inverse of SetAltText (empty when unset).

func (*Image) Bytes 

func (im *Image) Bytes() ([]byte, error)

Bytes resolves the image's embedded bytes by following the picture's <a:blip r:embed> relationship to its media part in the reopened package (R4). It returns ErrImagePartMissing when the relationship or part is absent. The bytes are returned verbatim — pptx-go does not decode pixel data (§7).

func (*Image) Crop 

func (im *Image) Crop() Crop

Crop returns the image's per-edge crop as fractions (0..1) — the read inverse of SetCrop (a zero Crop when uncropped).

func (*Image) Duotone 

func (im *Image) Duotone() (shadow, highlight RGB, ok bool)

Duotone returns the picture's two-tone (shadow, highlight) recolor as resolved hex values and ok=true when a duotone effect is set (the read inverse of SetDuotone); ok=false when the picture is not recolored.

func (*Image) Fit 

func (im *Image) Fit() Fit

Fit returns the image's fill mode — the read inverse of SetFit (FitFill when a stretch fill is present, FitNone otherwise).

func (*Image) Opacity 

func (im *Image) Opacity() int

Opacity returns the image's opacity (OOXML alpha 0..100000) — the read inverse of SetOpacity (AlphaOpaque when no alpha-modulation effect is set).

func (*Image) Rotation 

func (im *Image) Rotation() float64

Rotation returns the image's clockwise rotation in degrees within [0, 360°) — the read inverse of SetRotation (0 when unset).

func (*Image) SetAltText 

func (im *Image) SetAltText(text string) *Image

SetAltText sets the image's alternative text (the cNvPr/@descr attribute).

func (*Image) SetCornerRadius 

func (im *Image) SetCornerRadius(role RadiusRole) *Image

SetCornerRadius rounds the picture's corners using a theme radius token (P2, D-114): it sets the picture geometry to roundRect and converts the absolute token radius to the OOXML adjust against the picture box. RadiusNone (the zero value) resolves to 0 and leaves the picture rectangular — byte-identical. The rounded picture matches the card/surface radius finish.

func (*Image) SetCrop 

func (im *Image) SetCrop(c Crop) *Image

SetCrop sets a source-rectangle crop (fractions 0..1 trimmed per edge).

func (*Image) SetDuotone 

func (im *Image) SetDuotone(shadow, highlight Color) *Image

SetDuotone recolors the picture as a two-tone (duotone) image: the picture's shadows map to shadow and its highlights to highlight, producing an on-brand tint of a photo (R14.1). Both colors accept theme tokens or literals (P2), so a theme swap re-tints the photo. A nil color on either side leaves the picture un-recolored (byte-identical). The colors are resolved against the active theme at call time and emitted as literal <a:srgbClr> values inside an <a:duotone> blip effect.

func (*Image) SetElevation 

func (im *Image) SetElevation(role ElevationRole) *Image

SetElevation casts a soft drop shadow on the picture from a theme elevation token (P2, D-114), matching the card/surface elevation finish. ElevationFlat (the zero value) resolves to a flat elevation and emits no shadow — byte-identical.

func (*Image) SetFit 

func (im *Image) SetFit(f Fit) *Image

SetFit sets the image fill mode (FitFill stretches; FitNone omits the stretch fill).

func (*Image) SetOpacity 

func (im *Image) SetOpacity(alpha int) *Image

SetOpacity scales the image opacity via the blip's <a:alphaModFix> (alpha 0..100000; AlphaOpaque clears the effect). It is the picture analogue of a fill's alpha — used by a Decoration's opacity.

func (*Image) SetRotation 

func (im *Image) SetRotation(deg float64) *Image

SetRotation rotates the image clockwise by deg degrees about its centre (the picture's <a:xfrm rot>, normalized to [0,360°)).

type ImageSource 

type ImageSource interface {
	// contains filtered or unexported methods
}

ImageSource is image input for AddImage. Construct one with ImageFile, ImageBytes, or ImageReader. The interface is sealed (resolveImage is unexported) so callers cannot inject a source the builder can't encode; new backends are added here behind the same seam.

func ImageBytes 

func ImageBytes(data []byte, mime string) ImageSource

ImageBytes returns an ImageSource from raw bytes with a declared MIME type (e.g. "image/png"). The declared type is verified against the bytes.

func ImageFile 

func ImageFile(path string) ImageSource

ImageFile returns an ImageSource that reads the image at path. The format is taken from the bytes, not the file extension.

func ImageReader 

func ImageReader(r io.Reader, mime string) ImageSource

ImageReader returns an ImageSource that reads all bytes from r with a declared MIME type. r is drained when the image is added.

type Inset 

type Inset struct {
	Top, Right, Bottom, Left EMU
}

Inset is per-edge padding in EMU.

func UniformInset 

func UniformInset(v EMU) Inset

UniformInset returns an Inset with the same value on all four edges.

type Layout 

type Layout struct {
	// contains filtered or unexported fields
}

Layout is a read-only view of one slide layout in a template.

func (*Layout) Name 

func (l *Layout) Name() string

Name returns the layout's display name (may be empty if the template omits it).

type Line 

type Line struct {
	// Width is the stroke width in EMU.
	Width EMU
	// Color is the stroke color (literal or theme token); nil leaves it unset.
	Color Color
	// Dash is an optional preset dash style ("dash", "dot", "sysDash", …);
	// empty is solid.
	Dash string
}

Line is a shape's outline. A zero Line (Width 0, nil Color) leaves the outline unset (the shape inherits its style line).

type Master 

type Master struct {
	// contains filtered or unexported fields
}

Master is a read-only view of one slide master and the layouts it owns.

func (*Master) Layout 

func (m *Master) Layout(name string) (*Layout, bool)

Layout returns the master's layout with the given name, if present.

func (*Master) Layouts 

func (m *Master) Layouts() []*Layout

Layouts returns the layouts owned by this master, in document order.

func (*Master) Name 

func (m *Master) Name() string

Name returns the master's name (may be empty).

type MasterCache 

type MasterCache struct {
	// contains filtered or unexported fields
}

MasterCache is a read-only cache of slide masters and layouts. All fields are frozen after initialization and support lock-free concurrent reads.

func NewMasterCache 

func NewMasterCache() *MasterCache

NewMasterCache creates a new MasterCache instance.

func (*MasterCache) AllLayouts 

func (c *MasterCache) AllLayouts() map[string]*slide.SlideLayoutData

AllLayouts returns all slide layouts (read-only).

func (*MasterCache) AllMasters 

func (c *MasterCache) AllMasters() map[string]*slide.SlideMasterData

AllMasters returns all slide masters (read-only).

func (*MasterCache) GetLayout 

func (c *MasterCache) GetLayout(layoutID string) (*slide.SlideLayoutData, bool)

GetLayout returns the slide layout with the given ID.

func (*MasterCache) GetLayoutByName 

func (c *MasterCache) GetLayoutByName(name string) (*slide.SlideLayoutData, bool)

GetLayoutByName returns the slide layout with the given name.

func (*MasterCache) GetMaster 

func (c *MasterCache) GetMaster(masterID string) (*slide.SlideMasterData, bool)

GetMaster returns the slide master with the given ID.

func (*MasterCache) GetMasterByName 

func (c *MasterCache) GetMasterByName(name string) (*slide.SlideMasterData, bool)

GetMasterByName returns the slide master with the given name.

func (*MasterCache) GetMasterPlaceholder 

func (c *MasterCache) GetMasterPlaceholder(masterID, phType string) (*slide.Placeholder, bool)

GetMasterPlaceholder returns the placeholder for the given master ID and placeholder type.

func (*MasterCache) GetPlaceholder 

func (c *MasterCache) GetPlaceholder(layoutID, phType string) (*slide.Placeholder, bool)

GetPlaceholder returns the placeholder for the given layout ID and placeholder type. phType should be a value returned by PlaceholderType.String(), e.g. "title" or "body".

func (*MasterCache) GetPlaceholderByID 

func (c *MasterCache) GetPlaceholderByID(layoutID, placeholderID string) (*slide.Placeholder, bool)

GetPlaceholderByID returns the placeholder for the given layout ID and placeholder ID.

func (*MasterCache) Init 

func (c *MasterCache) Init(masters []*slide.SlideMasterData, layouts []*slide.SlideLayoutData)

Init populates the cache with the provided data. Only the first call has any effect; subsequent calls are silently ignored.

func (*MasterCache) InitFunc 

func (c *MasterCache) InitFunc(initFn func() ([]*slide.SlideMasterData, []*slide.SlideLayoutData))

InitFunc lazily initializes the cache using the provided factory function. The function is called only on the first access.

func (*MasterCache) LayoutCount 

func (c *MasterCache) LayoutCount() int

LayoutCount returns the number of slide layouts.

func (*MasterCache) LayoutExists 

func (c *MasterCache) LayoutExists(layoutID string) bool

LayoutExists reports whether a layout with the given ID exists.

func (*MasterCache) ListLayoutIDs 

func (c *MasterCache) ListLayoutIDs() []string

ListLayoutIDs returns the IDs of all slide layouts.

func (*MasterCache) ListLayoutNames 

func (c *MasterCache) ListLayoutNames() []string

ListLayoutNames returns the names of all slide layouts.

func (*MasterCache) ListMasterIDs 

func (c *MasterCache) ListMasterIDs() []string

ListMasterIDs returns the IDs of all slide masters.

func (*MasterCache) MasterCount 

func (c *MasterCache) MasterCount() int

MasterCount returns the number of slide masters.

func (*MasterCache) MasterExists 

func (c *MasterCache) MasterExists(masterID string) bool

MasterExists reports whether a master with the given ID exists.

type MasterManager 

type MasterManager struct {
	// contains filtered or unexported fields
}

MasterManager manages slide masters and layouts.

func NewMasterManager 

func NewMasterManager() *MasterManager

NewMasterManager creates a new MasterManager.

func NewMasterManagerWithCache 

func NewMasterManagerWithCache(cache *MasterCache) *MasterManager

NewMasterManagerWithCache creates a MasterManager backed by the given cache.

func (*MasterManager) AllLayouts 

func (m *MasterManager) AllLayouts() map[string]*slide.SlideLayoutData

AllLayouts returns all slide layouts.

func (*MasterManager) AllMasters 

func (m *MasterManager) AllMasters() map[string]*slide.SlideMasterData

AllMasters returns all slide masters.

func (*MasterManager) Cache 

func (m *MasterManager) Cache() *MasterCache

Cache returns the internal read-only cache.

func (*MasterManager) GetLayout 

func (m *MasterManager) GetLayout(layoutID string) (*slide.SlideLayoutData, bool)

GetLayout returns the layout with the given ID.

func (*MasterManager) GetLayoutByName 

func (m *MasterManager) GetLayoutByName(name string) (*slide.SlideLayoutData, bool)

GetLayoutByName returns the layout with the given name.

func (*MasterManager) GetMaster 

func (m *MasterManager) GetMaster(masterID string) (*slide.SlideMasterData, bool)

GetMaster returns the master with the given ID.

func (*MasterManager) GetMasterByName 

func (m *MasterManager) GetMasterByName(name string) (*slide.SlideMasterData, bool)

GetMasterByName returns the master with the given name.

func (*MasterManager) GetPlaceholder 

func (m *MasterManager) GetPlaceholder(layoutID, phType string) (*slide.Placeholder, bool)

GetPlaceholder returns the placeholder for the given layout ID and type.

func (*MasterManager) LayoutCount 

func (m *MasterManager) LayoutCount() int

LayoutCount returns the number of slide layouts.

func (*MasterManager) ListLayoutIDs 

func (m *MasterManager) ListLayoutIDs() []string

ListLayoutIDs returns the IDs of all slide layouts.

func (*MasterManager) ListLayoutNames 

func (m *MasterManager) ListLayoutNames() []string

ListLayoutNames returns the names of all slide layouts.

func (*MasterManager) LoadFromZip 

func (m *MasterManager) LoadFromZip(zipReader *zip.Reader) error

LoadFromZip loads slide masters and layouts from the given ZIP reader. It scans /ppt/slideMasters/ and /ppt/slideLayouts/ inside the ZIP.

func (*MasterManager) LoadFromZipFile 

func (m *MasterManager) LoadFromZipFile(filePath string) error

LoadFromZipFile loads slide masters and layouts from the ZIP file at filePath.

func (*MasterManager) MasterCount 

func (m *MasterManager) MasterCount() int

MasterCount returns the number of slide masters.

type MediaManager 

type MediaManager struct {
	// contains filtered or unexported fields
}

MediaManager maintains a concurrency-safe cache of all media resources in a PPTX file.

func NewMediaManager 

func NewMediaManager() *MediaManager

NewMediaManager creates a new media resource manager.

func (*MediaManager) AddMedia 

func (m *MediaManager) AddMedia(resource *media.MediaResource) string

AddMedia adds a media resource to the cache. Returns the resource rID; if the resource already exists the existing rID is returned.

func (*MediaManager) AddMediaAuto 

func (m *MediaManager) AddMediaAuto(fileName string, data []byte) (string, *media.MediaResource)

AddMediaAuto infers the MIME type and generates an auto-incremented rID. If identical content already exists (based on hash), the existing resource is returned (deduplication). Returns the generated rID and the MediaResource.

func (*MediaManager) AddMediaForSlide 

func (m *MediaManager) AddMediaForSlide(slideIndex int, data []byte, fileName string) (string, *media.MediaResource)

AddMediaForSlide adds media for a specific slide with cross-slide deduplication. Returns the slide-local rId and the global media resource.

Example: 

// Insert logo on slide 0
rId1, _ := mediaManager.AddMediaForSlide(0, logoData, "logo.png")
// Returns: rId1="rId1", global storage: image1.png

// Insert the same logo on slide 1
rId2, _ := mediaManager.AddMediaForSlide(1, logoData, "logo.png")
// Returns: rId2="rId1" (local rId for that slide), reuses image1.png

// The final ZIP contains a single image1.png; both slides reference it
// via their own local rIds.

func (*MediaManager) AddMediaWithBytes 

func (m *MediaManager) AddMediaWithBytes(rID, fileName, contentType, target string, data []byte) *media.MediaResource

AddMediaWithBytes creates a media resource from raw bytes and adds it to the cache.

func (*MediaManager) AddMediaWithReader 

func (m *MediaManager) AddMediaWithReader(rID, fileName, contentType, target string, reader io.Reader, size int64) *media.MediaResource

AddMediaWithReader creates a media resource from an io.Reader and adds it to the cache.

func (*MediaManager) AllAudio 

func (m *MediaManager) AllAudio() []*media.MediaResource

AllAudio returns all audio resources.

func (*MediaManager) AllGlobalMedia 

func (m *MediaManager) AllGlobalMedia() []*media.MediaResource

AllGlobalMedia returns all deduplicated global media resources, ordered by target path. The order is stable so callers that materialize the parts (e.g. syncMedia) add them to the package deterministically — without it, ranging the underlying sync.Map yields a different package (and ZIP) layout each save, breaking the byte-identical idempotency RFC §10.1 requires.

func (*MediaManager) AllImages 

func (m *MediaManager) AllImages() []*media.MediaResource

AllImages returns all image resources.

func (*MediaManager) AllMedia 

func (m *MediaManager) AllMedia() []*media.MediaResource

AllMedia returns all media resources as a new slice (thread-safe).

func (*MediaManager) AllMediaByType 

func (m *MediaManager) AllMediaByType(mediaType media.MediaType) []*media.MediaResource

AllMediaByType returns all media resources of the specified type.

func (*MediaManager) AllVideo 

func (m *MediaManager) AllVideo() []*media.MediaResource

AllVideo returns all video resources.

func (*MediaManager) Clear 

func (m *MediaManager) Clear()

Clear removes all media resources from the cache.

func (*MediaManager) Count 

func (m *MediaManager) Count() int64

Count returns the total number of media resources.

func (*MediaManager) CountAudio 

func (m *MediaManager) CountAudio() int64

CountAudio returns the number of audio resources.

func (*MediaManager) CountByType 

func (m *MediaManager) CountByType(mediaType media.MediaType) int64

CountByType returns the number of media resources of the specified type.

func (*MediaManager) CountImages 

func (m *MediaManager) CountImages() int64

CountImages returns the number of image resources.

func (*MediaManager) CountVideo 

func (m *MediaManager) CountVideo() int64

CountVideo returns the number of video resources.

func (*MediaManager) GetDeduplicationStats 

func (m *MediaManager) GetDeduplicationStats() DeduplicationStats

GetDeduplicationStats returns deduplication statistics.

func (*MediaManager) GetGlobalMediaByHash 

func (m *MediaManager) GetGlobalMediaByHash(hash string) *media.MediaResource

GetGlobalMediaByHash returns the global media resource for the given hash.

func (*MediaManager) GetMedia 

func (m *MediaManager) GetMedia(rID string) *media.MediaResource

GetMedia returns the media resource for the given rID.

func (*MediaManager) GetMediaByFileName 

func (m *MediaManager) GetMediaByFileName(fileName string) *media.MediaResource

GetMediaByFileName returns the media resource for the given file name.

func (*MediaManager) GetMediaByHash 

func (m *MediaManager) GetMediaByHash(hash string) *media.MediaResource

GetMediaByHash returns the media resource for the given content hash (for deduplication).

func (*MediaManager) GetMediaByTarget 

func (m *MediaManager) GetMediaByTarget(target string) *media.MediaResource

GetMediaByTarget returns the media resource for the given target path.

func (*MediaManager) GetSlideMediaIndex 

func (m *MediaManager) GetSlideMediaIndex(slideIndex int) *SlideMediaIndex

GetSlideMediaIndex returns the media index for the given slide, or nil if none exists.

func (*MediaManager) GlobalMediaCount 

func (m *MediaManager) GlobalMediaCount() int64

GlobalMediaCount returns the number of deduplicated global media resources.

func (*MediaManager) HasMedia 

func (m *MediaManager) HasMedia(rID string) bool

HasMedia reports whether a media resource with the given rID exists.

func (*MediaManager) HasMediaByFileName 

func (m *MediaManager) HasMediaByFileName(fileName string) bool

HasMediaByFileName reports whether a resource with the given file name exists.

func (*MediaManager) ListFileNames 

func (m *MediaManager) ListFileNames() []string

ListFileNames returns all file names.

func (*MediaManager) ListRIDs 

func (m *MediaManager) ListRIDs() []string

ListRIDs returns all rIDs.

func (*MediaManager) ListTargets 

func (m *MediaManager) ListTargets() []string

ListTargets returns all target paths.

func (*MediaManager) RemoveMedia 

func (m *MediaManager) RemoveMedia(rID string) bool

RemoveMedia removes a media resource from the cache. Returns true if the resource was found and removed.

func (*MediaManager) SeedFileCounter 

func (m *MediaManager) SeedFileCounter(n int64)

SeedFileCounter advances the media file-name counter to at least n, so a deck opened with existing imageN parts allocates fresh names for newly added media instead of colliding with them.

func (*MediaManager) SlideCount 

func (m *MediaManager) SlideCount() int64

SlideCount returns the number of slides that reference at least one media resource.

type Metadata 

type Metadata struct {
	Title   string
	Author  string // dc:creator
	Subject string
}

Metadata is the deck's core document properties (OPC core properties, docProps/core.xml). Any field may be empty.

type Option 

type Option func(*Presentation)

Option configures a Presentation at construction time (pptx.New). Options apply in order, before the scaffold is seeded.

func FromTemplate 

func FromTemplate(brand *Presentation) Option

FromTemplate returns a New option that seeds the presentation from brand: its theme becomes the active theme, and its masters + layouts are adopted (and reachable via Masters()). A nil brand is ignored (the deck falls back to the default scaffold). The brand presentation is not retained or mutated.

func WithFontEmbedding 

func WithFontEmbedding() Option

WithFontEmbedding enables the automatic font-embedding pass (R9.1, D-065). At save, the builder walks every slide's runs, collects the distinct used faces — (family, bold, italic) — in a stable sorted order, and embeds each via the registered FontSource, so a deck themed with a brand display/heading face ships those faces and renders with them on any machine. It is a no-op without a FontSource (use WithFontSource), warns (does not fail) on a face the source cannot resolve, and is idempotent against manual EmbedFont calls. Off, the output is byte-identical to the prior behavior.

func WithFontSource 

func WithFontSource(src FontSource) Option

WithFontSource registers the FontSource used by EmbedFont (D-019). It is the option-form of the SetFontSource setter and the documented registration path.

func WithFormat 

func WithFormat(f Format) Option

WithFormat sets the slide canvas aspect ratio (default Slides16x9).

func WithLogger 

func WithLogger(l *slog.Logger) Option

WithLogger injects a structured logger (RFC §18, D-042). When set, the builder emits a Debug write-boundary event on each write/save, and a read constructor emits a Warn event per non-fatal degradation (a dropped element or skipped part) it also records in ReadWarnings. No logger = no logs (zero-cost). The handler's performance is the caller's concern.

func WithReadPartLimit 

func WithReadPartLimit(n int64) Option

WithReadPartLimit sets the per-part decompressed size ceiling enforced when opening a deck (CLAUDE.md §7): a part larger than n bytes is rejected with an error wrapping opc.ErrPartTooLarge rather than allocated. n <= 0 disables the bound. Unset, the default is 100 MB. It applies only to the read constructors (NewFromBytes, NewFromFile, OpenStream); it is a no-op on New().

func WithTheme 

func WithTheme(t *Theme) Option

WithTheme sets the active theme (default DefaultTheme). The theme drives token resolution; theme-token emission into theme1.xml lands with the Color interface work.

type Paragraph 

type Paragraph struct {
	// contains filtered or unexported fields
}

Paragraph is a line block within a TextFrame.

func (*Paragraph) AddBreak 

func (p *Paragraph) AddBreak()

AddBreak appends a line break to the paragraph. 

func (p *Paragraph) AddHyperlink(text, target string, style RunStyle) *Run

AddHyperlink appends a run whose text links to target (an external URL) and returns it. The run is styled by style like any other run.

func (*Paragraph) AddRun 

func (p *Paragraph) AddRun(text string, style RunStyle) *Run

AddRun appends a styled run and returns it. Token color and typography resolve against the slide's active theme now.

func (*Paragraph) Align 

func (p *Paragraph) Align(a Alignment) *Paragraph

Align sets the paragraph's horizontal alignment and returns it.

func (*Paragraph) Alignment 

func (p *Paragraph) Alignment() Alignment

Alignment returns the paragraph's horizontal alignment — the read inverse of Align (AlignLeft when unset).

func (*Paragraph) Bullet 

func (p *Paragraph) Bullet(kind BulletKind) *Paragraph

Bullet sets the paragraph's bullet style and returns it. A non-none bullet also sets a hanging indent so the marker renders outside the text.

func (*Paragraph) BulletIndent 

func (p *Paragraph) BulletIndent() EMU

BulletIndent returns the paragraph's bullet hanging indent (the marker-to-text offset) in EMU, or 0 when no bullet indent is set — the read inverse of ParagraphOpts.BulletIndent (D-078). A bulleted paragraph reports its marL (0.5" by default, or the BulletIndent override).

func (*Paragraph) BulletStyle 

func (p *Paragraph) BulletStyle() BulletKind

BulletStyle returns the paragraph's bullet style — the read inverse of Bullet (BulletNone when unset or explicitly suppressed).

func (*Paragraph) Indent 

func (p *Paragraph) Indent(level int) *Paragraph

Indent sets the paragraph's outline/indent level (0-based) and returns it.

func (*Paragraph) Level 

func (p *Paragraph) Level() int

Level returns the paragraph's outline/indent level (0-based) — the read inverse of Indent.

func (*Paragraph) LineHeight 

func (p *Paragraph) LineHeight() float64

LineHeight returns the paragraph's line spacing as a percent of single, or 0 when none is set — the read inverse of ParagraphOpts.LineHeight (D-061).

func (*Paragraph) Runs 

func (p *Paragraph) Runs() []*Run

Runs returns the paragraph's text runs in document order — the read inverse of AddRun / AddHyperlink. Line breaks (AddBreak) carry no text and are not returned.

type ParagraphOpts 

type ParagraphOpts struct {
	Align  Alignment
	Level  int
	Bullet BulletKind
	// LineHeight is the paragraph's line spacing as a percent of single
	// (100 = single, 120 = 1.2×); 0 and 100 emit nothing (byte-identical).
	// Emitted as OOXML a:pPr/a:lnSpc/a:spcPct (D-061).
	LineHeight float64
	// BulletIndent overrides a bulleted paragraph's hanging indent (the
	// marker-to-text offset). The zero value keeps the default 0.5" hanging indent
	// (byte-identical); a positive value sets a tighter (or wider) marker gap.
	// Applies only when Bullet is set; emitted as a:pPr/@marL + @indent (D-078).
	BulletIndent EMU
}

ParagraphOpts configures a paragraph at creation time.

type Position 

type Position struct {
	X, Y EMU
}

Position is a point on the slide canvas, in EMU from the top-left origin.

type Presentation 

type Presentation struct {
	// contains filtered or unexported fields
}

Presentation is the top-level PPTX facade.

func New 

func New(opts ...Option) *Presentation

New creates a blank presentation. With no options it is a 16:9 widescreen deck themed with DefaultTheme; pass options (WithFormat, WithFontSource, WithTheme) to configure it (RFC §8.1).

func NewFromBytes 

func NewFromBytes(data []byte, opts ...Option) (*Presentation, error)

NewFromBytes creates a presentation from raw PPTX bytes.

func NewFromFile 

func NewFromFile(path string, opts ...Option) (*Presentation, error)

NewFromFile creates a presentation from a PPTX file path.

func NewWithTemplate 

func NewWithTemplate(name TemplateType) (*Presentation, error)

NewWithTemplate creates a presentation from the named template (e.g. TemplateDefault, TemplateBlank).

func OpenStream 

func OpenStream(path string, opts ...Option) (*Presentation, error)

OpenStream opens a .pptx file using the OPC streaming reader (lazy per-part loading) and returns a Presentation. (RFC §9, §17.2.)

func (*Presentation) AddSection 

func (p *Presentation) AddSection(name string) *Section

AddSection appends a new, empty section and returns it. Sections are emitted in creation order.

func (*Presentation) AddSlide 

func (p *Presentation) AddSlide(layout ...string) *Slide

AddSlide appends a new slide to the presentation. layout is an optional layout name (e.g. "title", "blank", "titleAndContent"). If no layout is specified, a blank layout is used.

Internally this method:

  • Registers a new ID in presentation.xml's <p:sldIdLst>.
  • Allocates a .rels route.
  • Returns a high-level *Slide.

func (*Presentation) AddSlideAt 

func (p *Presentation) AddSlideAt(index int, layout ...string) (*Slide, error)

AddSlideAt inserts a new slide at the specified index.

func (*Presentation) Clone 

func (p *Presentation) Clone() (*Presentation, error)

Clone returns a fully independent deep copy of the presentation.

func (*Presentation) Close 

func (p *Presentation) Close() error

Close releases all resources held by the presentation.

func (*Presentation) EmbedFont 

func (p *Presentation) EmbedFont(name, style string, weight int) error

EmbedFont embeds the named font face: it resolves the bytes via the registered FontSource, writes them as a font-data part, relates the part to presentation.xml, and records it in the embedded-font list so PowerPoint renders with it. Returns ErrNoFontSource if none is registered, or ErrFontNotFound if the source has no such font.

func (*Presentation) GetSlide 

func (p *Presentation) GetSlide(index int) (*Slide, error)

GetSlide returns the slide at the given index.

func (*Presentation) HasLayout 

func (p *Presentation) HasLayout(name string) bool

HasLayout reports whether a layout with the given name exists in the presentation's master/layout registry (e.g. a layout an ingested template defines). Callers — including the scene renderer's LayoutMap — use it to decide whether a layout selection will resolve before adding a slide.

func (*Presentation) MasterCache 

func (p *Presentation) MasterCache() *MasterCache

MasterCache returns the master cache.

func (*Presentation) Masters 

func (p *Presentation) Masters() []*Master

Masters returns the presentation's slide masters and their layouts. It is non-nil only for a deck opened from a file/stream or seeded with FromTemplate; a blank New() deck returns nil (its scaffold master is not surfaced). The returned slice is a copy; the masters themselves are read-only.

func (*Presentation) MediaManager 

func (p *Presentation) MediaManager() *MediaManager

MediaManager returns the media manager.

func (*Presentation) Package 

func (p *Presentation) Package() *opc.Package

Package returns the underlying OPC package (advanced usage).

func (*Presentation) PresentationPart 

func (p *Presentation) PresentationPart() *presentation.PresentationPart

PresentationPart returns the presentation part.

func (*Presentation) ReadWarnings 

func (p *Presentation) ReadWarnings() []ReadWarning

ReadWarnings returns the warnings collected when the deck was opened, in a stable order (by part, then element, then kind). It is nil for a deck pptx-go authored, which round-trips losslessly (D-047).

func (*Presentation) RemoveSlide 

func (p *Presentation) RemoveSlide(index int) error

RemoveSlide removes the slide at the given index.

func (*Presentation) Save 

func (p *Presentation) Save(path string) error

Save serializes the presentation and writes it to a file.

The save path holds the presentation's write lock: prepareForWrite mutates shared builder state (it materializes parts, allocates the embedded-font counter, and rewrites runs for font fallback), so concurrent saves of the *same* *Presentation serialize. Saves of distinct presentations are independent. To serve one deck to many concurrent writers, call WriteToBytes once and share the bytes, or Clone per writer.

func (*Presentation) SaveStream 

func (p *Presentation) SaveStream(path string) error

SaveStream serializes the presentation to a file through the OPC streaming writer. It applies the same syncing and repair-prompt hygiene (D-020) as Save. (RFC §9, §17.2.)

func (*Presentation) Sections 

func (p *Presentation) Sections() []*Section

Sections returns the presentation's sections in creation order.

func (*Presentation) SetFontSource deprecated 

func (p *Presentation) SetFontSource(src FontSource)

SetFontSource registers the FontSource used by EmbedFont.

Deprecated: pass pptx.WithFontSource(src) to pptx.New instead — that is the documented registration path. This setter remains for post-construction use.

func (*Presentation) SetMetadata 

func (p *Presentation) SetMetadata(m Metadata)

SetMetadata writes the deck's core properties (title / author / subject) into docProps/core.xml. Values are XML-escaped; no created/modified timestamps are emitted, so output stays byte-identical for the same input (D-035). It is the builder API behind scene.Scene.Meta (D-042).

func (*Presentation) SetSlideSize 

func (p *Presentation) SetSlideSize(cx, cy int)

SetSlideSize sets the slide dimensions (in EMU).

func (*Presentation) SetSlideSizeStandard 

func (p *Presentation) SetSlideSizeStandard(name string)

SetSlideSizeStandard sets the slide size to a named standard (e.g. "widescreen").

func (*Presentation) SetTheme 

func (p *Presentation) SetTheme(t *Theme)

SetTheme sets the active theme used for token resolution. A nil theme is ignored.

func (*Presentation) SlideCount 

func (p *Presentation) SlideCount() int

SlideCount returns the number of slides.

func (*Presentation) SlideSize 

func (p *Presentation) SlideSize() (int, int)

SlideSize returns the current slide dimensions (in EMU).

func (*Presentation) Slides 

func (p *Presentation) Slides() []*Slide

Slides returns a copy of the slide list.

func (*Presentation) Theme 

func (p *Presentation) Theme() *Theme

Theme returns the active theme (never nil; DefaultTheme by default).

func (*Presentation) Write 

func (p *Presentation) Write(w io.Writer) error

Write serializes the presentation and writes it to an io.Writer (e.g. an HTTP response). Like Save, it holds the write lock for the duration, so concurrent writes of the same *Presentation serialize; for high-concurrency fan-out of a single deck, WriteToBytes once and share the bytes.

func (*Presentation) WriteToBytes 

func (p *Presentation) WriteToBytes() ([]byte, error)

WriteToBytes serializes the presentation and returns it as a byte slice. It holds the write lock (prepareForWrite mutates shared state); concurrent calls on the same *Presentation serialize.

type RGB 

type RGB string

RGB is a 6-hex-digit color string without a leading '#', e.g. "2563EB".

type Radii 

type Radii map[RadiusRole]EMU

Radii maps each radius role to an EMU value.

type RadiusRole 

type RadiusRole int

RadiusRole is a corner-radius step; resolves to EMU (RFC §7.1). 

const (
	RadiusNone RadiusRole = iota
	RadiusSM
	RadiusMD
	RadiusLG
	RadiusFull
)

type ReadWarning 

type ReadWarning struct {
	Kind    ReadWarningKind
	Part    string // the part URI the warning relates to, e.g. "/ppt/slides/slide2.xml"
	Element string // element local-name (WarnDroppedElement); empty otherwise
	Detail  string // human-readable context
}

ReadWarning is one non-fatal degradation noted while reading a (third-party) deck. It carries enough to locate the issue without surfacing any raw OOXML (P3): the part URI, the element local-name (for WarnDroppedElement), and a human-readable detail.

type ReadWarningKind 

type ReadWarningKind int

ReadWarningKind classifies a non-fatal issue encountered while reading a deck. 

const (
	// WarnDroppedElement reports that an unrecognized element was ignored at
	// parse time (e.g. a group shape or mc:AlternateContent in a slide's shape
	// tree). The element is named in ReadWarning.Element.
	WarnDroppedElement ReadWarningKind = iota
	// WarnUnreadablePart reports that a referenced part was missing or could not
	// be parsed, and was skipped rather than failing the open.
	WarnUnreadablePart
)

func (ReadWarningKind) String 

func (k ReadWarningKind) String() string

String renders the kind for logs.

type Rect 

type Rect struct {
	X, Y   int // top-left corner (px)
	Cx, Cy int // width and height (px)
}

Rect represents a rectangular region.

type RepeatedComponent 

type RepeatedComponent struct {
	// contains filtered or unexported fields
}

RepeatedComponent renders a template component once for each item in a data slice.

func NewRepeatedComponent 

func NewRepeatedComponent(count int, template func(index int) Component) *RepeatedComponent

NewRepeatedComponent creates a RepeatedComponent that calls template(i) for i in [0, count) and renders the result.

func (*RepeatedComponent) Render 

func (rc *RepeatedComponent) Render(ctx *SlideContext) error

Render implements Component.

type Run 

type Run struct {
	// contains filtered or unexported fields
}

Run is a styled text span within a Paragraph.

func (*Run) Baseline 

func (r *Run) Baseline() BaselineShift

Baseline returns the run's baseline shift — the read inverse of RunStyle.BaselineRel.

func (*Run) Bold 

func (r *Run) Bold() bool

Bold reports whether the run is bold.

func (*Run) Case 

func (r *Run) Case() TextCase

Case returns the run's case transform, or CaseNone when none is set — the read inverse of the resolved FontSpec.Case / RunStyle.Case (D-062). The run's Text() is unchanged (the transform is a display attribute).

func (*Run) Code 

func (r *Run) Code() bool

Code reports whether the run is styled as inline code — detected by the subtle background tint pptx-go applies for code and nothing else (D-013).

func (*Run) Color 

func (r *Run) Color() (Color, bool)

Color returns the run's text color and true, or nil and false when the run has no explicit color (it inherits). A reopened color is a resolved literal (D-030).

func (*Run) Font 

func (r *Run) Font() string

Font returns the run's Latin typeface, or "" when unset (it inherits).

func (*Run) FontSize 

func (r *Run) FontSize() float64

FontSize returns the run's font size in points, or 0 when unset. 

func (r *Run) Hyperlink() (string, bool)

Hyperlink returns the run's link target (the external URL) and true, or "" and false when the run is not a hyperlink. It is the read inverse of AddHyperlink: the run's <a:hlinkClick r:id> is resolved through the slide's relationships to the verbatim URL the caller supplied (§7 — pptx-go does not validate it).

func (*Run) Italic 

func (r *Run) Italic() bool

Italic reports whether the run is italic.

func (*Run) Strike 

func (r *Run) Strike() Strike

Strike returns the run's strikethrough style — the read inverse of RunStyle.Strike.

func (*Run) Text 

func (r *Run) Text() string

Text returns the run's literal text.

func (*Run) Tracking 

func (r *Run) Tracking() float64

Tracking returns the run's letter-spacing in points (signed), or 0 when the run carries no explicit spacing — the read inverse of the resolved FontSpec.Tracking / RunStyle.Tracking (D-060).

func (*Run) Underline 

func (r *Run) Underline() Underline

Underline returns the run's underline style — the read inverse of RunStyle.Underline.

type RunStyle 

type RunStyle struct {
	TypeRole    TypeRole
	Color       Color
	Bold        bool
	Italic      bool
	Underline   Underline
	Strike      Strike
	BaselineRel BaselineShift
	Code        bool // inline code: monospace + a subtle tint (D-013; Chunk B)
	// Tracking optionally overrides the type role's letter-spacing for this run,
	// in points (signed). nil inherits the role's FontSpec.Tracking; a non-nil
	// value (including 0) wins over the role. Emitted as a:rPr/@spc (D-060).
	Tracking *float64
	// Case optionally overrides the type role's case transform for this run. nil
	// inherits the role's FontSpec.Case; a non-nil value (including CaseNone)
	// wins. Emitted as a:rPr/@cap (D-062).
	Case *TextCase
	// FontScale optionally multiplies the resolved type-role size for this run.
	// The zero value (and 1) leaves the role size unchanged — byte-identical; a
	// value in (0,1) shrinks the run (the scene shrink-to-fit / AutoFit path uses
	// it). The role's size token stays the source of truth (a theme swap re-skins
	// the base, then this scales it), so it does not weaken P2. Emitted as the
	// reduced a:rPr/@sz; the resulting size round-trips via Run.FontSize (D-074).
	FontScale float64
}

RunStyle is the token-typed styling of a Run (RFC §8.4). TypeRole selects the typography scale (size + family); Color is a theme token or literal. The zero RunStyle uses the theme's TypeDisplay role — set TypeRole (e.g. TypeBody) for body text.

type Section 

type Section struct {
	// contains filtered or unexported fields
}

Section is a named, ordered grouping of slides. Create one with Presentation.AddSection and assign slides with Include.

func (*Section) Include 

func (sec *Section) Include(s *Slide)

Include assigns a slide to the section (idempotent). A slide assigned to more than one section is emitted under the first that includes it.

func (*Section) Name 

func (sec *Section) Name() string

Name returns the section's display name.

type Shape 

type Shape struct {
	// contains filtered or unexported fields
}

Shape is a handle to a shape on a slide — either one the builder added or one recovered by Open from a reopened deck (Slide.Shapes, RFC §16). It does not expose the underlying OOXML wire type (P3); read accessors (Geometry, Rotation, Fill, Line, Shadow) map the recovered wire fields back to the public builder types so a reopened shape compares field-equal to the authored one.

Exactly one of the underlying children is set: an auto-shape (sp), a picture (pic), or a graphic frame / table (gf). The builder constructs only sp shapes; Shapes() wraps whichever child it finds so the read accessors land on a common handle (text/table/image read arrive in later read chunks).

func (*Shape) Box 

func (sh *Shape) Box() Box

Box returns the shape's position and size in EMU.

func (*Shape) Fill 

func (sh *Shape) Fill() Fill

Fill returns the shape's interior fill, or nil when the shape has no explicit fill (it inherits its style fill). A reopened fill surfaces resolved literal colors (D-030); inspect it via Fill.Kind / SolidColor / Gradient. It is the read inverse of WithFill.

func (*Shape) Geometry 

func (sh *Shape) Geometry() ShapeGeometry

Geometry returns the shape's preset geometry — the OOXML prst name (e.g. ShapeRoundRect). It is the empty string for a custom-geometry shape (an icon glyph, custGeom) or one with no geometry (a picture or graphic frame). It is the read inverse of AddShape's geom argument.

func (*Shape) Image 

func (sh *Shape) Image() (*Image, bool)

Image returns the image this shape bears and true, or nil and false when the shape is not a picture. On a reopened deck the returned handle exposes the authored alt text / crop / fit / rotation / opacity and resolves the embedded bytes via Image.Bytes (RFC §16).

func (*Shape) Line 

func (sh *Shape) Line() Line

Line returns the shape's outline, or a zero Line when the shape has no explicit outline (it inherits its style line). It is the read inverse of WithLine.

func (*Shape) Rotation 

func (sh *Shape) Rotation() float64

Rotation returns the shape's clockwise rotation in degrees within [0, 360°), or 0 if unset — the read inverse of WithRotation.

func (*Shape) Shadow 

func (sh *Shape) Shadow() (Elevation, bool)

Shadow returns the shape's drop shadow as an Elevation and true, or a zero Elevation and false when the shape casts none. The OOXML outerShdw stores the offset in polar form (dist/dir); Shadow reconstructs the cartesian OffsetX/OffsetY, so an axis-aligned shadow round-trips exactly and an oblique one to within sub-EMU rounding (D-035). It is the read inverse of WithElevation / WithShadow.

func (*Shape) Table 

func (sh *Shape) Table() (*Table, bool)

Table returns the table this shape bears and true, or nil and false when the shape is not a table (a graphic frame carrying an <a:tbl>). On a reopened deck the returned handle exposes the authored row/column counts, column widths, header/banding intent, and per-cell text / fill / merge via the Table and Cell read accessors (RFC §16).

func (*Shape) TextFrame 

func (sh *Shape) TextFrame() (*TextFrame, bool)

TextFrame returns the shape's rich-text container and true, or nil and false when the shape carries no text body. On a reopened deck the returned frame enumerates paragraphs → runs with their authored style / color / hyperlink / bullet (Slide.Shapes, RFC §16). Table-cell text is reached via the table read accessors, not here.

type ShapeComponent 

type ShapeComponent struct {
	// contains filtered or unexported fields
}

ShapeComponent is the simplest component type: it wraps a single XSp shape.

func NewShapeComponent 

func NewShapeComponent(sp *slide.XSp, x, y int) *ShapeComponent

NewShapeComponent creates a ShapeComponent at the given position (EMU).

func (*ShapeComponent) Bounds 

func (sc *ShapeComponent) Bounds() (x, y, cx, cy int)

Bounds implements ComponentWithSize.

func (*ShapeComponent) Name 

func (sc *ShapeComponent) Name() string

Name implements ComponentWithName.

func (*ShapeComponent) Position 

func (sc *ShapeComponent) Position() (x, y int)

Position implements ComponentWithPosition.

func (*ShapeComponent) Render 

func (sc *ShapeComponent) Render(ctx *SlideContext) error

Render implements Component.

func (*ShapeComponent) SetName 

func (sc *ShapeComponent) SetName(name string)

SetName sets the component's name.

func (*ShapeComponent) SetPosition 

func (sc *ShapeComponent) SetPosition(x, y int)

SetPosition implements ComponentWithPosition.

type ShapeGeometry 

type ShapeGeometry string

ShapeGeometry is a preset shape outline, expressed as its OOXML preset geometry name (ST_ShapeType). Use the Shape* constants. 

const (
	ShapeRect          ShapeGeometry = "rect"
	ShapeRoundRect     ShapeGeometry = "roundRect"
	ShapeEllipse       ShapeGeometry = "ellipse"
	ShapeTriangle      ShapeGeometry = "triangle"
	ShapeDiamond       ShapeGeometry = "diamond"
	ShapeParallelogram ShapeGeometry = "parallelogram"
	ShapeHexagon       ShapeGeometry = "hexagon"
	ShapeChevron       ShapeGeometry = "chevron"
	ShapeRightArrow    ShapeGeometry = "rightArrow"
	ShapeLine          ShapeGeometry = "line"
)

Preset geometries (a curated subset of ST_ShapeType; the value is the OOXML prst attribute).

type ShapeOption 

type ShapeOption func(*shapeConfig)

ShapeOption configures a shape at creation time.

func WithElevation 

func WithElevation(role ElevationRole) ShapeOption

WithElevation casts a drop shadow from the active theme's Elevation token for role (the documented token path — P2, D-043). The token resolves at AddShape time, so a theme swap re-renders the shadow in the brand's elevation. ElevationFlat (and any flat token) emits no effect — byte-identical to a shape with no shadow.

func WithFill 

func WithFill(f Fill) ShapeOption

WithFill sets the shape's interior fill (SolidFill, NoFill, …).

func WithFlipV 

func WithFlipV(flip bool) ShapeOption

WithFlipV mirrors the shape vertically (OOXML <a:xfrm flipV>). It lets a directional shape — e.g. a ShapeLine — draw from the bottom-left to the top-right of its (positive-extent) box, so an upward diagonal line is expressible without a negative extent. Byte-identical when not set.

func WithImageFill 

func WithImageFill(src ImageSource) ShapeOption

WithImageFill fills the shape's interior with an image (a `<a:blipFill>`) instead of a solid/gradient fill — a photo-as-surface for cards and panels (R14.1). The image is cover-fit: scaled to fill the shape and center-cropped on the overflowing axis (computed from the image's format-header dimensions — §7/D-046, not pixel data — so there is no distortion at any aspect; an unreadable header falls back to a plain stretch). It wins over WithFill. The shape's geometry/corner-radius still clips the fill, so an image-filled roundRect keeps its rounded corners. A nil source or an unreadable image leaves the prior fill unchanged.

func WithLine 

func WithLine(l Line) ShapeOption

WithLine sets the shape's outline.

func WithRadius 

func WithRadius(role RadiusRole) ShapeOption

WithRadius sets a rounded-corner radius from a theme radius token (P2). It applies to ShapeRoundRect only — the corner radius is OOXML's roundRect adjust handle — and is ignored for other geometries. The token resolves against the active theme at AddShape time, so a theme swap re-rounds the same input; RadiusFull yields a full capsule (pill).

func WithRotation 

func WithRotation(deg float64) ShapeOption

WithRotation rotates the shape clockwise by deg degrees about its centre (OOXML <a:xfrm rot>, D-041). The angle is normalized to [0, 360°).

func WithShadow 

func WithShadow(e Elevation) ShapeOption

WithShadow casts a drop shadow from a literal Elevation (the escape hatch; the documented path is WithElevation). A flat Elevation (IsFlat) emits no effect.

type Size 

type Size struct {
	W, H EMU
}

Size is a width/height extent in EMU.

type Slide 

type Slide struct {
	// contains filtered or unexported fields
}

Slide is the high-level slide object.

func (*Slide) AddAutoShape 

func (s *Slide) AddAutoShape(x, y, cx, cy int, presetID string) *slide.XSp

AddAutoShape adds an auto shape to the slide. x, y are the position (EMU); cx, cy are the size (EMU). presetID is the preset shape type (e.g. "rectangle", "ellipse", "roundRect").

func (*Slide) AddBlockArc 

func (s *Slide) AddBlockArc(box Box, startDeg, sweepDeg, innerRatio float64, opts ...ShapeOption) *Shape

AddBlockArc adds a block-arc — an annular (ring) sector — positioned by box, a native preset geometry (<a:prstGeom prst="blockArc">). It sweeps clockwise from startDeg by sweepDeg degrees (OOXML angle convention: 0° at 3 o'clock, increasing clockwise; use 270° for 12 o'clock) at the given innerRatio (the ring's inner radius as a fraction of the outer, 0..1 — e.g. 0.6 = a thin ring). It is the native primitive behind donut/ring and gauge micro-charts (R14.8). Fills/lines resolve against the active theme like AddShape (P2).

func (*Slide) AddChartRel 

func (s *Slide) AddChartRel(targetURI string) string

AddChartRel adds a chart relationship to the slide.

func (*Slide) AddComponent 

func (s *Slide) AddComponent(c Component) error

AddComponent adds a component to the slide. Any value implementing the Component interface (text, picture, chart, etc.) is accepted. A SlideContext is created internally and c.Render(ctx) is called.

func (*Slide) AddComponents 

func (s *Slide) AddComponents(components ...Component) error

AddComponents adds multiple components to the slide in one call.

func (*Slide) AddEllipse 

func (s *Slide) AddEllipse(x, y, cx, cy int) *slide.XSp

AddEllipse adds an ellipse to the slide.

func (*Slide) AddIcon 

func (s *Slide) AddIcon(svg []byte, box Box, opts ...ShapeOption) (*Shape, error)

AddIcon adds a single-path SVG glyph as a native custom-geometry shape, positioned by box. By default it fills with the accent token (P2); pass WithFill to override the color, or WithLine to add an outline. It errors if the SVG violates the translator constraints (the same check as ValidateIcon).

func (*Slide) AddImage 

func (s *Slide) AddImage(src ImageSource, box Box) (*Image, error)

AddImage places an image on the slide, positioned by box (EMU), and returns a handle for optional alt text / crop / fit. Identical bytes across the deck are written once (dedup). It errors if the source can't be read or the bytes are not a recognized image (§7). (RFC §8.6.)

func (*Slide) AddImageRel 

func (s *Slide) AddImageRel(targetURI string) string

AddImageRel adds an image relationship to the slide.

func (*Slide) AddMediaRel 

func (s *Slide) AddMediaRel(targetURI string) string

AddMediaRel adds a media relationship to the slide.

func (*Slide) AddPicture 

func (s *Slide) AddPicture(x, y, cx, cy int, imageRId string) *slide.XPicture

AddPicture adds a picture to the slide. x, y are the position (EMU); cx, cy are the size (EMU). imageRId is the relationship ID of the image.

func (*Slide) AddPictureFromBytes 

func (s *Slide) AddPictureFromBytes(x, y, cx, cy int, fileName string, data []byte) (*slide.XPicture, error)

AddPictureFromBytes adds a picture from raw bytes. The media bytes are deduplicated across the deck and written to the package once; the slide receives its own image relationship. The extension of fileName selects the stored media extension (defaulting to .png).

func (*Slide) AddPictureFromFile 

func (s *Slide) AddPictureFromFile(x, y, cx, cy int, path string) (*slide.XPicture, error)

AddPictureFromFile adds a picture from a file path.

func (*Slide) AddRectangle 

func (s *Slide) AddRectangle(x, y, cx, cy int) *slide.XSp

AddRectangle adds a rectangle to the slide.

func (*Slide) AddRoundRect 

func (s *Slide) AddRoundRect(x, y, cx, cy int) *slide.XSp

AddRoundRect adds a rounded rectangle to the slide.

func (*Slide) AddShape 

func (s *Slide) AddShape(geom ShapeGeometry, box Box, opts ...ShapeOption) *Shape

AddShape adds a preset-geometry shape positioned by box (EMU) and returns a handle to it. Fills and lines are resolved against the presentation's active theme at this point, so a theme token reflects the theme in force now — the mechanism behind theme swaps (P2). This is the token-aware shape API (RFC §8.2/§8.3); the older Add* helpers remain for convenience.

func (*Slide) AddTable 

func (s *Slide) AddTable(box Box, rows, cols int) *Table

AddTable adds a rows×cols table positioned by box (EMU) with equal column widths, and returns a handle (RFC §8.5).

func (*Slide) AddTextBox 

func (s *Slide) AddTextBox(x, y, cx, cy int, text string) *slide.XSp

AddTextBox adds a text box to the slide. x, y are the position (EMU); cx, cy are the size (EMU); text is the content.

func (*Slide) AddTextFrame 

func (s *Slide) AddTextFrame(box Box) *TextFrame

AddTextFrame adds an (initially empty) text-box shape positioned by box (EMU) and returns its TextFrame for authoring (RFC §8.4).

func (*Slide) Builder 

func (s *Slide) Builder() *SlideBuilder

Builder returns the slide builder.

func (*Slide) ChartPlaceholder 

func (s *Slide) ChartPlaceholder(box Box, opts ...ShapeOption) *Shape

ChartPlaceholder draws a labeled chart slot at box — a rounded rect with a dashed accent border and a centered "Chart" label — and returns the slot shape. It commits no chart bytes; it is the visible stand-in for a chart whose raster is unresolved or not yet rendered. Fills/line resolve against the active theme (P2); pass ShapeOptions to override the default border/fill.

func (*Slide) CheckBoundary 

func (s *Slide) CheckBoundary(x, y, cx, cy int) BoundaryCheckResult

CheckBoundary checks whether an element is within the slide viewport. x, y are the top-left coordinates (px); cx, cy are the dimensions (px). Returns a BoundaryCheckResult with overflow and visibility information.

func (*Slide) GetImageRId 

func (s *Slide) GetImageRId(targetURI string) string

GetImageRId returns the rId for a target URI, adding it if absent.

func (*Slide) HasImage 

func (s *Slide) HasImage(targetURI string) bool

HasImage reports whether a relationship for the given target URI already exists.

func (*Slide) HasSpeakerNotes 

func (s *Slide) HasSpeakerNotes() bool

HasSpeakerNotes reports whether the slide carries speaker notes.

func (*Slide) Index 

func (s *Slide) Index() int

Index returns the zero-based slide index.

func (*Slide) IsInsideBoundary 

func (s *Slide) IsInsideBoundary(x, y, cx, cy int) bool

IsInsideBoundary reports whether an element is fully within the slide viewport.

func (*Slide) IsVisible 

func (s *Slide) IsVisible(x, y, cx, cy int) bool

IsVisible reports whether any part of an element is within the slide viewport.

func (*Slide) Layout 

func (s *Slide) Layout() string

Layout returns the name of the current layout.

func (*Slide) NewContext 

func (s *Slide) NewContext() *SlideContext

NewContext creates a SlideContext for manual component rendering.

func (*Slide) Part 

func (s *Slide) Part() *slide.SlidePart

Part returns the underlying SlidePart.

func (*Slide) PartURI 

func (s *Slide) PartURI() *opc.PackURI

PartURI returns the part URI.

func (*Slide) SetLayout 

func (s *Slide) SetLayout(layoutName string) bool

SetLayout sets the slide layout by name (e.g. "blank", "title", "titleAndContent"). Returns true if the layout was found and applied.

func (*Slide) SetSpeakerNotes 

func (s *Slide) SetSpeakerNotes(text string)

SetSpeakerNotes is a convenience that replaces the notes with a single plain-text paragraph (themed body text).

func (*Slide) Shapes 

func (s *Slide) Shapes() []*Shape

Shapes returns the slide's shapes in document order — the read-side enumerator (RFC §16). Each shape-tree child is wrapped in a *Shape: an auto-shape, a picture, or a graphic frame (a table). On a reopened pptx-go deck the returned handles expose the authored geometry / rotation / fill / line / shadow via the Shape read accessors (text / table / image read arrive in later read chunks). Group shapes and unrecognized children are skipped.

func (*Slide) SlideSize 

func (s *Slide) SlideSize() (cx, cy int)

SlideSize returns the slide dimensions in pixels.

func (*Slide) SlideSizeEMU 

func (s *Slide) SlideSizeEMU() (cx, cy int)

SlideSizeEMU returns the slide dimensions in EMU (advanced usage).

func (*Slide) SpeakerNotes 

func (s *Slide) SpeakerNotes() *TextFrame

SpeakerNotes returns the slide's speaker-notes text frame, creating it on first use (D-022, RFC §8.8). Author notes through the returned TextFrame just like any other text. The scene IR's SceneSlide.Notes maps onto it.

func (*Slide) Viewport 

func (s *Slide) Viewport() *SlideViewport

Viewport returns the slide viewport.

type SlideBuilder 

type SlideBuilder struct {
	// contains filtered or unexported fields
}

SlideBuilder wraps a SlidePart and provides helper methods for building slide content.

func NewSlideBuilder 

func NewSlideBuilder(slide *slide.SlidePart) *SlideBuilder

NewSlideBuilder creates a SlideBuilder for the given SlidePart.

func (*SlideBuilder) AddAutoShape 

func (b *SlideBuilder) AddAutoShape(x, y, cx, cy int, presetID string) *slide.XSp

AddAutoShape adds an auto shape to the slide. x, y, cx, cy are the position and size in EMU. presetID is the preset shape type (e.g. "rectangle", "ellipse", "roundRect").

func (*SlideBuilder) AddChart 

func (b *SlideBuilder) AddChart(targetURI string) string

AddChart adds a chart relationship and returns its relationship ID.

func (*SlideBuilder) AddCustomShape 

func (b *SlideBuilder) AddCustomShape(x, y, cx, cy int, geom *slide.XCustomGeometry) *slide.XSp

AddCustomShape adds a shape with custom path geometry (an icon glyph). x, y, cx, cy are the position and size in EMU; geom is the translated <a:custGeom>. The caller applies fill/line to the returned shape's properties.

func (*SlideBuilder) AddImage 

func (b *SlideBuilder) AddImage(targetURI string) string

AddImage adds an image relationship and returns its relationship ID.

func (*SlideBuilder) AddMedia 

func (b *SlideBuilder) AddMedia(targetURI string) string

AddMedia adds a media relationship and returns its relationship ID.

func (*SlideBuilder) AddPicture 

func (b *SlideBuilder) AddPicture(x, y, cx, cy int, imageRId string) *slide.XPicture

AddPicture adds an image to the slide. x, y, cx, cy are the position and size in EMU; imageRId is the image relationship ID.

func (*SlideBuilder) AddTable 

func (b *SlideBuilder) AddTable(x, y, cx, cy, rows, cols int) *slide.XGraphicFrame

AddTable adds a table to the slide. x, y, cx, cy are the position and size in EMU; rows and cols are the table dimensions.

func (*SlideBuilder) AddTextBox 

func (b *SlideBuilder) AddTextBox(x, y, cx, cy int, text string) *slide.XSp

AddTextBox adds a text box to the slide. x, y, cx, cy are the position and size in EMU; text is the initial content.

func (*SlideBuilder) GetChartRId 

func (b *SlideBuilder) GetChartRId(targetURI string) string

GetChartRId returns the relationship ID for the given chart URI, creating the relationship if it does not yet exist.

func (*SlideBuilder) GetImageRId 

func (b *SlideBuilder) GetImageRId(targetURI string) string

GetImageRId returns the relationship ID for the given image URI, creating the relationship if it does not yet exist.

func (*SlideBuilder) GetMediaRId 

func (b *SlideBuilder) GetMediaRId(targetURI string) string

GetMediaRId returns the relationship ID for the given media URI, creating the relationship if it does not yet exist.

func (*SlideBuilder) GetOrAddPicture 

func (b *SlideBuilder) GetOrAddPicture(x, y, cx, cy int, imageURI string) *slide.XPicture

GetOrAddPicture adds an image to the slide by URI and returns its XPicture. The image relationship is created automatically.

func (*SlideBuilder) GetRelationshipURI 

func (b *SlideBuilder) GetRelationshipURI(rId string) string

GetRelationshipURI returns the target URI for the relationship with the given ID, or an empty string if it does not exist.

func (*SlideBuilder) HasImage 

func (b *SlideBuilder) HasImage(targetURI string) bool

HasImage reports whether an image relationship for targetURI already exists.

func (*SlideBuilder) HasMedia 

func (b *SlideBuilder) HasMedia(targetURI string) bool

HasMedia reports whether a media relationship for targetURI already exists.

func (*SlideBuilder) SetTableCellText 

func (b *SlideBuilder) SetTableCellText(gf *slide.XGraphicFrame, row, col int, text string)

SetTableCellText sets the text of the cell at (row, col) in the given table.

func (*SlideBuilder) Slide 

func (b *SlideBuilder) Slide() *slide.SlidePart

Slide returns the underlying SlidePart.

type SlideContext 

type SlideContext struct {
	// contains filtered or unexported fields
}

SlideContext carries the resources and capabilities a component needs to render itself onto a slide.

func NewSlideContext 

func NewSlideContext(s *Slide) *SlideContext

NewSlideContext creates a SlideContext for the given slide.

func (*SlideContext) AddAudio 

func (ctx *SlideContext) AddAudio(data []byte, fileName string) (string, error)

AddAudio adds an audio resource.

func (*SlideContext) AddChart 

func (ctx *SlideContext) AddChart(chartType chart.ChartType, data map[string]interface{}) (string, error)

AddChart adds a chart part using a template and the provided data map. Returns the relationship ID and any error.

func (*SlideContext) AddChartRel 

func (ctx *SlideContext) AddChartRel(targetURI string) string

AddChartRel adds a chart relationship and returns its relationship ID.

func (*SlideContext) AddChartXML 

func (ctx *SlideContext) AddChartXML(chartXML []byte) (string, error)

AddChartXML adds a chart part from raw XML bytes. Returns the relationship ID and any error.

This implements the "route C" pattern: the component supplies the chart XML; SlideContext writes a ChartPart into the OPC package and returns the rId.

func (*SlideContext) AddImage 

func (ctx *SlideContext) AddImage(data []byte, fileName string) (string, error)

AddImage adds an image resource. It is an alias for AddMedia with clearer semantics.

func (*SlideContext) AddImageRel 

func (ctx *SlideContext) AddImageRel(targetURI string) string

AddImageRel adds an image relationship and returns its relationship ID.

func (*SlideContext) AddMedia 

func (ctx *SlideContext) AddMedia(data []byte, fileName string) (string, error)

AddMedia adds a media resource (image, audio, or video) to the slide. data is the raw bytes and fileName is used to infer the MIME type. Returns the relationship ID and any error.

func (*SlideContext) AddMediaRel 

func (ctx *SlideContext) AddMediaRel(targetURI string) string

AddMediaRel adds a media relationship and returns its relationship ID.

func (*SlideContext) AddMediaWithMIME 

func (ctx *SlideContext) AddMediaWithMIME(data []byte, fileName, mimeType string) (string, error)

AddMediaWithMIME adds a media resource with an explicit MIME type.

func (*SlideContext) AddVideo 

func (ctx *SlideContext) AddVideo(data []byte, fileName string) (string, error)

AddVideo adds a video resource.

func (*SlideContext) AllocateShapeIDBatch 

func (ctx *SlideContext) AllocateShapeIDBatch(count int) []uint32

AllocateShapeIDBatch allocates a batch of shape IDs at once.

func (*SlideContext) AppendShape 

func (ctx *SlideContext) AppendShape(shape interface{})

AppendShape appends a shape to the slide. shape may be *slide.XSp, *slide.XPicture, *slide.XGraphicFrame, etc.

func (*SlideContext) AppendShapes 

func (ctx *SlideContext) AppendShapes(shapes ...interface{})

AppendShapes appends multiple shapes to the slide in one call.

func (*SlideContext) CurrentShapeID 

func (ctx *SlideContext) CurrentShapeID() uint32

CurrentShapeID returns the most recently allocated shape ID.

func (*SlideContext) EMUToPx 

func (ctx *SlideContext) EMUToPx(emu int) int

EMUToPx converts EMU to pixels at 96 DPI.

func (*SlideContext) HasRelationship 

func (ctx *SlideContext) HasRelationship(rID string) bool

HasRelationship reports whether the given relationship ID was allocated through this context.

func (*SlideContext) IsShapeIDAllocated 

func (ctx *SlideContext) IsShapeIDAllocated(id uint32) bool

IsShapeIDAllocated reports whether the given shape ID has been allocated through this context.

func (*SlideContext) NextShapeID 

func (ctx *SlideContext) NextShapeID() uint32

NextShapeID allocates and returns the next collision-free shape ID. Safe for concurrent use; uses an atomic increment.

func (*SlideContext) Presentation 

func (ctx *SlideContext) Presentation() *Presentation

Presentation returns the owning Presentation (advanced use).

func (*SlideContext) PxToEMU 

func (ctx *SlideContext) PxToEMU(px int) int

PxToEMU converts pixels to EMU at 96 DPI.

func (*SlideContext) RenderComponents 

func (ctx *SlideContext) RenderComponents(components ...Component) error

RenderComponents renders each component in order, stopping on the first error.

func (*SlideContext) SlideIndex 

func (ctx *SlideContext) SlideIndex() int

SlideIndex returns the zero-based index of the slide.

func (*SlideContext) SlidePart 

func (ctx *SlideContext) SlidePart() *slide.SlidePart

SlidePart returns the underlying SlidePart (advanced use).

func (*SlideContext) SlideSize 

func (ctx *SlideContext) SlideSize() (cx, cy int)

SlideSize returns the slide dimensions in EMU (cx, cy).

type SlideMediaIndex 

type SlideMediaIndex struct {
	// contains filtered or unexported fields
}

SlideMediaIndex manages the media references for a single slide.

func NewSlideMediaIndex 

func NewSlideMediaIndex(slideIndex int) *SlideMediaIndex

NewSlideMediaIndex creates a new SlideMediaIndex for the given slide.

func (*SlideMediaIndex) AllLocalRIDs 

func (smi *SlideMediaIndex) AllLocalRIDs() []string

AllLocalRIDs returns all slide-local rIDs.

func (*SlideMediaIndex) GetHashByLocalRID 

func (smi *SlideMediaIndex) GetHashByLocalRID(localRID string) string

GetHashByLocalRID returns the content hash for the given slide-local rId.

func (*SlideMediaIndex) GetLocalRIDByHash 

func (smi *SlideMediaIndex) GetLocalRIDByHash(hash string) string

GetLocalRIDByHash returns the slide-local rId for the given content hash.

func (*SlideMediaIndex) LocalRefCount 

func (smi *SlideMediaIndex) LocalRefCount() int64

LocalRefCount returns the number of media references for this slide.

type SlideSize 

type SlideSize struct {
	Width  int // width (px)
	Height int // height (px)
}

SlideSize represents a slide's dimensions.

type SlideViewport 

type SlideViewport struct {
	// Width is the viewport width (px).
	Width int
	// Height is the viewport height (px).
	Height int
	// SizeName is the optional standard size name.
	SizeName string
}

SlideViewport represents the slide viewport.

func NewSlideViewport 

func NewSlideViewport(width, height int) *SlideViewport

NewSlideViewport creates a slide viewport with the given dimensions.

func NewSlideViewportFromSize 

func NewSlideViewportFromSize(size SlideSize) *SlideViewport

NewSlideViewportFromSize creates a viewport from a SlideSize.

func (*SlideViewport) CheckBoundary 

func (vp *SlideViewport) CheckBoundary(x, y, cx, cy int) BoundaryCheckResult

CheckBoundary checks whether an element is within the viewport. x, y are the top-left coordinates (px); cx, cy are the dimensions (px).

func (*SlideViewport) CheckRect 

func (vp *SlideViewport) CheckRect(rect Rect) BoundaryCheckResult

CheckRect checks whether a Rect is within the viewport.

func (*SlideViewport) IsInside 

func (vp *SlideViewport) IsInside(x, y, cx, cy int) bool

IsInside reports whether an element is fully within the viewport.

func (*SlideViewport) IsVisible 

func (vp *SlideViewport) IsVisible(x, y, cx, cy int) bool

IsVisible reports whether any part of an element is within the viewport.

func (*SlideViewport) Rect 

func (vp *SlideViewport) Rect() Rect

Rect returns the viewport as a Rect.

type SpaceRole 

type SpaceRole int

SpaceRole is a step on the spacing scale; resolves to EMU (RFC §7.1). 

const (
	SpaceXS SpaceRole = iota
	SpaceSM
	SpaceMD
	SpaceLG
	SpaceXL
	Space2XL
)

type Spacing 

type Spacing map[SpaceRole]EMU

Spacing maps each spacing role to an EMU value.

type Strike 

type Strike int

Strike is a run's strikethrough style. 

const (
	StrikeNone Strike = iota
	StrikeSingle
	StrikeDouble
)

type Table 

type Table struct {
	// contains filtered or unexported fields
}

Table is a handle to a table added to a slide.

func (*Table) Cell 

func (t *Table) Cell(row, col int) *Cell

Cell returns the cell at (row, col).

func (*Table) ColCount 

func (t *Table) ColCount() int

ColCount returns the table's number of columns — the read inverse of AddTable's cols argument.

func (*Table) ColumnWidths 

func (t *Table) ColumnWidths() []EMU

ColumnWidths returns the table's column widths (EMU), left to right — the read inverse of SetColumnWidths.

func (*Table) HeaderRow 

func (t *Table) HeaderRow() bool

HeaderRow reports whether the first row is marked as a header — the read inverse of SetHeaderRow.

func (*Table) RowBanding 

func (t *Table) RowBanding() bool

RowBanding reports whether row banding is enabled — the read inverse of SetBanding's rowBand argument.

func (*Table) RowCount 

func (t *Table) RowCount() int

RowCount returns the table's number of rows — the read inverse of AddTable's rows argument.

func (*Table) SetBanding 

func (t *Table) SetBanding(rowBand, colBand bool) *Table

SetBanding toggles row/column banding and restyles. V1 emits alternating row fills for rowBand; colBand sets the intent flag only.

func (*Table) SetColumnWidths 

func (t *Table) SetColumnWidths(widths ...EMU) *Table

SetColumnWidths overrides column widths (EMU), left to right.

func (*Table) SetHeaderRow 

func (t *Table) SetHeaderRow(on bool) *Table

SetHeaderRow marks (or unmarks) the first row as a header and restyles.

type TemplateBuilder 

type TemplateBuilder struct {
	// contains filtered or unexported fields
}

TemplateBuilder builds a PPTX template from scratch.

func NewTemplateBuilder 

func NewTemplateBuilder() *TemplateBuilder

NewTemplateBuilder creates a new TemplateBuilder.

func (*TemplateBuilder) Build 

func (tb *TemplateBuilder) Build() *opc.Package

Build returns the assembled OPC package.

func (*TemplateBuilder) BuildAndRegister 

func (tb *TemplateBuilder) BuildAndRegister(name TemplateType) error

BuildAndRegister assembles the template and registers it with the global manager under name.

func (*TemplateBuilder) Package 

func (tb *TemplateBuilder) Package() *opc.Package

Package returns the underlying OPC package.

type TemplateManager 

type TemplateManager struct {
	// contains filtered or unexported fields
}

TemplateManager handles lazy loading, caching, and cloning of templates.

func NewTemplateManager 

func NewTemplateManager() *TemplateManager

NewTemplateManager creates a new TemplateManager.

func NewTemplateManagerWithDir 

func NewTemplateManagerWithDir(dir string) *TemplateManager

NewTemplateManagerWithDir creates a TemplateManager that searches dir for template files.

func (*TemplateManager) ClearCache 

func (tm *TemplateManager) ClearCache()

ClearCache evicts all cached templates and resets the master cache.

func (*TemplateManager) GetMasterCache 

func (tm *TemplateManager) GetMasterCache() *MasterCache

GetMasterCache returns the cached master/layout data.

func (*TemplateManager) HasTemplate 

func (tm *TemplateManager) HasTemplate(name TemplateType) bool

HasTemplate reports whether the named template is already cached.

func (*TemplateManager) LoadDefault 

func (tm *TemplateManager) LoadDefault() (*opc.Package, error)

LoadDefault loads the default template.

func (*TemplateManager) LoadTemplate 

func (tm *TemplateManager) LoadTemplate(name TemplateType) (*opc.Package, error)

LoadTemplate returns a clone of the named template, loading and caching it from the file system on first use.

func (*TemplateManager) RegisterTemplate 

func (tm *TemplateManager) RegisterTemplate(name TemplateType, path string) error

RegisterTemplate registers the template at the given file path under name.

func (*TemplateManager) RegisterTemplateFromBytes 

func (tm *TemplateManager) RegisterTemplateFromBytes(name TemplateType, data []byte) error

RegisterTemplateFromBytes parses and registers a template from raw bytes.

func (*TemplateManager) RegisterTemplateFromFS 

func (tm *TemplateManager) RegisterTemplateFromFS(fsys fs.FS, name TemplateType, path string) error

RegisterTemplateFromFS registers a template read from the given fs.FS.

func (*TemplateManager) SetDefaultTemplate 

func (tm *TemplateManager) SetDefaultTemplate(name TemplateType)

SetDefaultTemplate sets the template returned by LoadDefault.

func (*TemplateManager) SetTemplateDir 

func (tm *TemplateManager) SetTemplateDir(dir string)

SetTemplateDir sets the directory searched first when loading templates.

type TemplateType 

type TemplateType string

TemplateType identifies a named presentation template. 

const (
	// TemplateBlank is an empty/blank template.
	TemplateBlank TemplateType = "blank.pptx"
	// TemplateDefault is the default 16:9 widescreen template.
	TemplateDefault TemplateType = "default.pptx"
	// TemplateWide is a widescreen template.
	TemplateWide TemplateType = "wide.pptx"
	// TemplateStandard is a standard 4:3 template.
	TemplateStandard TemplateType = "standard.pptx"
)

type TextAnchor 

type TextAnchor int

TextAnchor is a TextFrame's vertical text anchor. 

const (
	AnchorTop TextAnchor = iota
	AnchorMiddle
	AnchorBottom
)

type TextCase 

type TextCase int

TextCase is a type role's case transform, rendered as the OOXML a:rPr/@cap attribute (the run text is preserved; the display is cased). The zero value CaseNone leaves text exactly as authored. 

const (
	CaseNone      TextCase = iota // as authored (no cap attribute)
	CaseUpper                     // all caps — a:rPr cap="all"
	CaseSmallCaps                 // small caps — a:rPr cap="small"
)

type TextColorRole 

type TextColorRole int

TextColorRole is a semantic text color for inline runs (RFC §7.1). 

const (
	TextPrimary TextColorRole = iota
	TextSecondary
	TextTertiary
	TextInverse
	TextMuted
	TextAccent
	TextAccentAlt
	TextSuccess
	TextWarning
	TextError
)

type TextFrame 

type TextFrame struct {
	// contains filtered or unexported fields
}

TextFrame is a shape-level rich-text container (RFC §8.4). Create one with Slide.AddTextFrame.

func (*TextFrame) AddParagraph 

func (tf *TextFrame) AddParagraph(opts ParagraphOpts) *Paragraph

AddParagraph appends a paragraph and returns it.

func (*TextFrame) Anchor 

func (tf *TextFrame) Anchor(v TextAnchor) *TextFrame

Anchor sets the frame's vertical text anchor and returns the frame.

func (*TextFrame) AutoFit 

func (tf *TextFrame) AutoFit(mode AutoFitMode) *TextFrame

AutoFit sets the frame's auto-fit behavior and returns the frame.

func (*TextFrame) AutoFitMode 

func (tf *TextFrame) AutoFitMode() AutoFitMode

AutoFitMode returns the frame's auto-fit behavior — the read inverse of AutoFit. A frame with no explicit autofit child reports AutoFitNone.

func (*TextFrame) Clear 

func (tf *TextFrame) Clear() *TextFrame

Clear removes all paragraphs from the frame and returns it (e.g. to refill a table cell's default body).

func (*TextFrame) MarginInsets 

func (tf *TextFrame) MarginInsets() (top, right, bottom, left EMU)

MarginInsets returns the frame's internal insets (EMU) — the read inverse of Margins. An unset inset (the attribute is omitted) reads as 0.

func (*TextFrame) Margins 

func (tf *TextFrame) Margins(top, right, bottom, left EMU) *TextFrame

Margins sets the frame's internal insets (EMU) and returns the frame.

func (*TextFrame) Paragraphs 

func (tf *TextFrame) Paragraphs() []*Paragraph

Paragraphs returns the frame's paragraphs in document order — the read-side enumerator. Each is addressable through the same Paragraph handle the builder hands out, so its read accessors (Runs / Alignment / Level / BulletStyle) and authoring methods share one type.

func (*TextFrame) VerticalAnchor 

func (tf *TextFrame) VerticalAnchor() TextAnchor

VerticalAnchor returns the frame's vertical text anchor — the read inverse of Anchor. A frame with no explicit anchor reports AnchorTop (the OOXML default).

type Theme 

type Theme struct {
	Name        string
	HeadingFont string
	// DisplayFont, when non-empty, is the family for the TypeDisplay role (the big
	// editorial face), independent of HeadingFont. Empty (the zero value) makes
	// TypeDisplay inherit HeadingFont — byte-identical to a 2-font theme. (D-063.)
	DisplayFont string
	BodyFont    string
	Colors      ColorPalette
	// Accents, when non-empty, is an ordered brand-accent palette (R8.4): the
	// scene renderer's per-element accent cycle (timeline / funnel / cycle /
	// quadrant / tree / image-pin markers) rotates through these literal hues by
	// index instead of the engine's pinned five-role cycle. Empty (the zero
	// value) keeps the pinned cycle, byte-identical. Like DarkColors it has no
	// theme1.xml slot — the resolved accent RGB round-trips, the field does not.
	Accents []RGB
	// DarkColors, when non-nil, supplies soul-driven VariantDark overrides that
	// the scene renderer overlays over its pinned neutral-gray dark default
	// (R8.3). nil (the zero value) keeps the pinned gray, byte-identical. The
	// field has no theme1.xml slot — see DarkPalette.
	DarkColors *DarkPalette
	// Gradients holds named brand gradients (R8.5), each requested by a scene
	// Background's GradientName. nil/empty means no named gradients (the legacy
	// role-based gradient path is byte-identical). Like DarkColors it has no
	// theme1.xml slot — the resolved gradient fill round-trips, the map does not.
	Gradients  map[string]GradientSpec
	Typography Typography
	Spacing    Spacing
	Radii      Radii
	Elevations Elevations
}

Theme is the semantic visual contract. HeadingFont/BodyFont are the theme1.xml major/minor font-scheme faces; the Typography map may override the family per type role.

func DefaultTheme 

func DefaultTheme() *Theme

DefaultTheme returns the V1 default theme: a light surface, a neutral palette, and a system font stack (Calibri / Calibri Light / Consolas) that renders every node legibly with no embedding (RFC §7.5). The returned theme is a fresh copy — callers may mutate it freely.

func LoadTheme 

func LoadTheme(path string) (*Theme, error)

LoadTheme extracts the Theme from a .pptx template file's theme1.xml.

func LoadThemeFromBytes 

func LoadThemeFromBytes(data []byte) (*Theme, error)

LoadThemeFromBytes extracts the Theme from a .pptx file's theme1.xml.

func NewTheme 

func NewTheme(opts ...ThemeOption) *Theme

NewTheme returns a copy of the default theme with the options applied.

func (*Theme) Clone 

func (t *Theme) Clone() *Theme

Clone returns a deep copy of the theme so callers can mutate without affecting the original (themes are reusable artifacts — CLAUDE.md §5).

func (*Theme) Gradient 

func (t *Theme) Gradient(name string) (GradientSpec, bool)

Gradient returns the named brand gradient (R8.5) and whether it is registered.

func (*Theme) ResolveColor 

func (t *Theme) ResolveColor(role ColorRole) RGB

ResolveColor returns the 6-hex RGB for a surface color role.

func (*Theme) ResolveElevation 

func (t *Theme) ResolveElevation(role ElevationRole) Elevation

ResolveElevation returns the Elevation for an elevation role.

func (*Theme) ResolveRadius 

func (t *Theme) ResolveRadius(role RadiusRole) EMU

ResolveRadius returns the EMU for a radius role.

func (*Theme) ResolveSpace 

func (t *Theme) ResolveSpace(role SpaceRole) EMU

ResolveSpace returns the EMU for a spacing role.

func (*Theme) ResolveTextColor 

func (t *Theme) ResolveTextColor(role TextColorRole) RGB

ResolveTextColor returns the 6-hex RGB for a text color role.

func (*Theme) ResolveType 

func (t *Theme) ResolveType(role TypeRole) FontSpec

ResolveType returns the FontSpec for a typography role.

func (*Theme) ThemeXML 

func (t *Theme) ThemeXML() ([]byte, error)

ThemeXML serializes the theme to a theme1.xml byte slice.

type ThemeOption 

type ThemeOption func(*Theme)

ThemeOption customizes a Theme built with NewTheme.

func WithAccent 

func WithAccent(c RGB) ThemeOption

WithAccent overrides the accent surface color.

func WithAccents 

func WithAccents(palette ...RGB) ThemeOption

WithAccents sets the theme's ordered brand-accent palette (R8.4): the scene renderer's per-element accent cycle rotates through these literal hues by index instead of the pinned five-role cycle, so a brand can render 4+ coordinated accent hues across timeline phases, quadrant points, tree nodes, etc. Passing none (or an empty slice) keeps the pinned cycle (byte-identical).

func WithDarkSurface 

func WithDarkSurface(role ColorRole, c RGB) ThemeOption

WithDarkSurface sets a soul-driven VariantDark override for a surface role (R8.3). It lazily allocates Theme.DarkColors; the scene renderer overlays the override over its pinned neutral-gray dark default, so a brand renders its own dark canvas/surface (e.g. deep navy). Setting none leaves the pinned gray default (byte-identical). Composable with WithDarkText and order-independent.

func WithDarkText 

func WithDarkText(role TextColorRole, c RGB) ThemeOption

WithDarkText sets a soul-driven VariantDark override for a text role (R8.3). It lazily allocates Theme.DarkColors; the scene renderer overlays the override over its pinned dark-text default. Setting none leaves the pinned default (byte-identical). Composable with WithDarkSurface and order-independent.

func WithDisplayFont 

func WithDisplayFont(family string) ThemeOption

WithDisplayFont sets a distinct display face for the TypeDisplay role (the big editorial face), independent of the heading face (D-063). Order-independent with WithFonts. Omitting it leaves TypeDisplay on HeadingFont (byte-identical).

func WithFonts 

func WithFonts(heading, body string) ThemeOption

WithFonts overrides the heading and body font families (and updates the Typography families to match).

func WithGradient 

func WithGradient(name string, spec GradientSpec) ThemeOption

WithGradient registers a named brand gradient on the theme (R8.5). A scene Background requests it by name (Background.GradientName) and the renderer feeds it to pptx.LinearGradient / RadialGradient per the spec's Radial flag. Calling it with the same name twice replaces the earlier spec. Themes that register no gradients are byte-identical to the legacy role-based gradient path.

func WithName 

func WithName(name string) ThemeOption

WithName sets the theme name.

func WithPaper 

func WithPaper(c RGB) ThemeOption

WithPaper overrides the ColorPaper surface tint — the faintly tinted off-white "paper" canvas (D-104). Pass a low-chroma off-white (e.g. RGB("FAFAF8")) to give content slides a designed paper tone; the default is white (= ColorCanvas).

type TypeRole 

type TypeRole int

TypeRole is a step on the typography scale (RFC §7.1). 

const (
	TypeDisplay TypeRole = iota
	TypeH1
	TypeH2
	TypeH3
	TypeH4
	TypeH5
	TypeBody
	TypeBodySmall
	TypeCaption
	TypeMono
	TypeCode
)

type Typography 

type Typography map[TypeRole]FontSpec

Typography maps each type role to a resolved FontSpec.

type Underline 

type Underline int

Underline is a run's underline style. 

const (
	UnderlineNone Underline = iota
	UnderlineSingle
	UnderlineDouble
)

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.