Struct PdfDocument 

pub struct PdfDocument<W: Write> { /* private fields */ }

High-level API for building PDF documents.

Generic over Write so it works with files (BufWriter<File>), in-memory buffers (Vec<u8>), or any other writer.

Pages are written incrementally: end_page() flushes page data to the writer and frees page content from memory. This keeps memory usage low even for documents with hundreds of pages.

Implementations

impl PdfDocument<BufWriter<File>>

pub fn create<P: AsRef<Path>>(path: P, options: DocumentOptions) -> Result<Self>

Create a new PDF document that writes to a file.

impl<W: Write> PdfDocument<W>

pub fn new(writer: W, options: DocumentOptions) -> Result<Self>

Create a new PDF document that writes to the given writer. Writes the PDF header immediately.

pub fn set_info(&mut self, key: &str, value: &str) -> &mut Self

Set a document info entry (e.g. “Creator”, “Title”).

pub fn set_compression(&mut self, enabled: bool) -> &mut Self

Enable or disable FlateDecode compression for stream objects. When enabled, page content, embedded fonts, and ToUnicode CMaps are compressed, typically reducing file size by 50-80%. Disabled by default.

pub fn load_font_file<P: AsRef<Path>>( &mut self, path: P, ) -> Result<FontRef, String>

Load a TrueType font from a file path. Returns a FontRef that can be used in TextStyle.

pub fn load_font_bytes(&mut self, data: Vec<u8>) -> Result<FontRef, String>

Load a TrueType font from raw bytes. Returns a FontRef that can be used in TextStyle.

pub fn page_count(&self) -> usize

Returns the number of completed pages (pages for which end_page has been called).

pub fn begin_page(&mut self, width: f64, height: f64) -> &mut Self

Begin a new page with the given dimensions in points. If a page is currently open, it is automatically closed.

pub fn open_page(&mut self, page_num: usize) -> Result<()>

Open a completed page for editing (1-indexed).

Used for adding overlay content such as page numbers (“Page X of Y”) after all pages have been written. The overlay content is written as an additional content stream appended to the page’s /Contents array.

If a page is currently open, it is automatically closed first.

Returns an error if page_num is out of range.

pub fn place_text(&mut self, text: &str, x: f64, y: f64) -> &mut Self

Place text at position (x, y) using default 12pt Helvetica.

With Origin::BottomLeft (default), (x, y) is in PDF’s native bottom-left coordinate system. With Origin::TopLeft, y is measured from the top of the page, increasing downward.

pub fn place_text_styled( &mut self, text: &str, x: f64, y: f64, style: &TextStyle, ) -> &mut Self

Place text at position (x, y) with the given style.

With Origin::BottomLeft (default), (x, y) is in PDF’s native bottom-left coordinate system. With Origin::TopLeft, y is measured from the top of the page, increasing downward.

pub fn fit_textflow( &mut self, flow: &mut TextFlow, rect: &Rect, ) -> Result<FitResult>

Fit a TextFlow into a bounding rectangle on the current page.

The flow’s cursor advances so subsequent calls continue where it left off (for multi-page flow). With Origin::TopLeft, (rect.x, rect.y) is the top-left corner of the area.

pub fn fit_row( &mut self, table: &Table, row: &Row, cursor: &mut TableCursor, ) -> Result<FitResult>

Place a single table row on the current page.

cursor tracks the current Y position within the page. Pass the same cursor to successive calls; call cursor.reset() when starting a new page.

Returns:

• Stop — row placed; advance to the next row.
• BoxFull — page full; end the page, begin a new one, reset the cursor, retry.
• BoxEmpty — rect too small for this row even from the top; skip or abort.

pub fn load_image_file<P: AsRef<Path>>( &mut self, path: P, ) -> Result<ImageId, String>

Load an image from a file path. Returns an ImageId that can be used with place_image.

pub fn load_image_bytes(&mut self, data: Vec<u8>) -> Result<ImageId, String>

Load an image from raw bytes (JPEG or PNG). Returns an ImageId that can be used with place_image.

pub fn place_image( &mut self, image: &ImageId, rect: &Rect, fit: ImageFit, ) -> &mut Self

Place an image on the current page within the given bounding rect.

With Origin::TopLeft, (rect.x, rect.y) is the top-left corner and rect.height extends downward. With Origin::BottomLeft (default), rect.y is the bottom edge in PDF space.

pub fn add_text_field( &mut self, name: &str, rect: Rect, ) -> Result<(), FormFieldError>

Add a fillable text field to the current page.

name must be unique across the document. Returns an error if called with no active page or if the name has already been used.

With Origin::TopLeft, (rect.x, rect.y) is the top-left corner.

pub fn set_stroke_color(&mut self, color: Color) -> &mut Self

Set the stroke color (PDF RG operator).

pub fn set_fill_color(&mut self, color: Color) -> &mut Self

Set the fill color (PDF rg operator).

pub fn set_line_width(&mut self, width: f64) -> &mut Self

Set the line width (PDF w operator).

pub fn move_to(&mut self, x: f64, y: f64) -> &mut Self

Move to a point without drawing (PDF m operator).

With Origin::TopLeft, y is measured from the top of the page, increasing downward.

pub fn line_to(&mut self, x: f64, y: f64) -> &mut Self

Draw a line to a point (PDF l operator).

With Origin::TopLeft, y is measured from the top of the page, increasing downward.

pub fn rect(&mut self, x: f64, y: f64, width: f64, height: f64) -> &mut Self

Append a rectangle to the path (PDF re operator).

With Origin::TopLeft, (x, y) is the top-left corner of the rectangle and height extends downward.

pub fn curve_to( &mut self, x1: f64, y1: f64, x2: f64, y2: f64, x3: f64, y3: f64, ) -> &mut Self

Append a cubic Bezier curve to the path (PDF c operator).

(x1, y1) and (x2, y2) are the two control points; (x3, y3) is the endpoint. All y-coordinates are transformed according to the document’s origin setting.

pub fn arc( &mut self, cx: f64, cy: f64, radius: f64, start: Angle, end: Angle, ) -> &mut Self

Append an arc to the current path.

The arc is centered at (cx, cy) with the given radius. Angles follow standard math convention: 0° = right, counter-clockwise positive. Use Angle::degrees or Angle::radians to construct the angle.

The arc is approximated with cubic Bezier segments (up to one per 90°). This method moves to the arc’s start point; the caller is responsible for painting (stroke/fill/fill_stroke).

With Origin::TopLeft, (cx, cy) is measured from the top of the page.

pub fn circle(&mut self, cx: f64, cy: f64, radius: f64) -> &mut Self

Append a full circle to the current path (closed).

The circle is centered at (cx, cy) with the given radius. The path is automatically closed with the h operator; the caller is responsible for painting (stroke/fill/fill_stroke).

With Origin::TopLeft, (cx, cy) is measured from the top of the page.

pub fn close_path(&mut self) -> &mut Self

Close the current subpath (PDF h operator).

pub fn stroke(&mut self) -> &mut Self

Stroke the current path (PDF S operator).

pub fn fill(&mut self) -> &mut Self

Fill the current path (PDF f operator).

pub fn fill_stroke(&mut self) -> &mut Self

Fill and stroke the current path (PDF B operator).

pub fn save_state(&mut self) -> &mut Self

Save the graphics state (PDF q operator).

pub fn restore_state(&mut self) -> &mut Self

Restore the graphics state (PDF Q operator).

pub fn end_page(&mut self) -> Result<()>

End the current page. Writes the content stream to the writer and frees page content from memory. The page dictionary is deferred until end_document() so overlay streams can be added.

pub fn end_document(self) -> Result<W>

Finish the document. Writes page dictionaries, the catalog, pages tree, info dictionary, xref table, and trailer. Consumes self – no further operations are possible.