pdf-writer Documentation

The Sides<T> struct is a helper for writing values that apply to the four sides of a rectangle (before, after, start, end), as required by the PDF specification.

It automatically handles the distinction between a single uniform value and an array of four distinct values.

Creation

• Sides::new(before, after, start, end): Create with specific values.
• Sides::from_array([before, after, start, end]): Create from a 4-element array.
• Sides::uniform(value): Create with the same value for all four sides.

Usage in Writers

Many layout methods accept Sides<T> to simplify writing:

• border_color(color: Sides<[f32; 3]>)
• border_style(style: Sides<LayoutBorderStyle>)
• border_thickness(thickness: Sides<f32>)
• padding(padding: Sides<f32>)
• table_border_style(style: Sides<LayoutBorderStyle>)
• table_padding(padding: Sides<f32>)

// Example: Setting a uniform padding of 10.0
layout_attrs.padding(Sides::uniform(10.0));

// Example: Setting non-uniform padding
layout_attrs.padding(Sides::new(5.0, 10.0, 2.0, 2.0));

For accessibility and structured documents (required for many PDF/A profiles), use StructTreeRoot and StructElement to build a document structure tree.

StructTreeRoot

Created via Catalog::struct_tree_root(). It manages the mapping of elements and their hierarchy:

• child(id: Ref) / children(): Defines the immediate children.
• id_tree(): Maps element identifiers to objects.
• parent_tree(): Maps structure elements to their content items.
• role_map(): Maps custom names to standard roles.
• class_map(): Maps attribute classes.

StructElement

Created via StructTreeRoot::child() or similar. Represents a specific semantic unit (e.g., a paragraph or heading):

• kind(role: StructRole): Sets the semantic role for PDF 1.7 and below.
• kind_2(role: StructRole2, pdf_2_ns: Ref): Sets the role for PDF 2.0 using a namespace.
• custom_kind(name: Name): Sets a custom role name.
• parent(parent: Ref): Sets the parent element (Required).
• id(id: Str): Sets the element identifier.
• title(title: impl TextStrLike): Sets a title for the element.
• lang(lang: TextStr): Sets the language for the element.
• alt(alt: impl TextStrLike): Provides an alternative description (e.g., for screen readers).

The AdditionalActions struct allows you to define event-based actions (like mouse clicks, focus changes, or page visibility) for various PDF components. The available methods depend on the context of the element being configured:

For Annotations

• annot_curser_enter(): Triggered when the cursor enters the active area (/E).
• annot_cursor_exit(): Triggered when the cursor exits the active area (/X).
• annot_mouse_press(): Triggered on mouse button press (/D).
• annot_mouse_release(): Triggered on mouse button release (/U).
• annot_page_open(): Triggered when the page containing the annotation is opened (/PO).
• annot_page_close(): Triggered when the page is closed (/PC).
• annot_page_visible(): Triggered when the page becomes visible (/PV).
• annot_page_invisible(): Triggered when the page is no longer visible (/PI).

For Widget Annotations (Form Fields)

• widget_focus(): Triggered when the annotation receives input focus (/Fo).
• widget_focus_loss(): Triggered when the annotation loses input focus (/Bl).

For Page Objects

• page_open(): Triggered when the page is opened (/O).
• page_close(): Triggered when the page is closed (/C).

For Form Fields

• form_calculate_partial(): Triggered when a character is modified (/K).
• form_format(): Triggered before a field is formatted (/F).
• form_validate(): Triggered when the field's value is changed (/V).
• form_calculate(): Triggered to recalculate the value when another field changes (/C).

For Document Catalog

• cat_before_close(): Before closing the document (/WC).
• cat_before_save(): Before saving the document (/WS).
• cat_after_save(): After saving the document (/DS).
• cat_before_print(): Before printing the document (/WP).
• cat_after_print(): After printing the document (/DP).

To create a PDF, you must define indirect reference IDs using Ref, use the Pdf struct to build the document hierarchy (Catalog, Page Tree, and Pages), and finally call .finish() to generate the byte stream for writing to a file.

This example demonstrates creating a single, empty A4 page (595.0 x 842.0 points) with no resources.

use pdf_writer::{Pdf, Rect, Ref};

// Define some indirect reference ids we'll use.
let catalog_id = Ref::new(1);
let page_tree_id = Ref::new(2);
let page_id = Ref::new(3);

// Write a document catalog and a page tree with one A4 page that uses no resources.
let mut pdf = Pdf::new();
pdf.catalog(catalog_id).pages(page_tree_id);
pdf.pages(page_tree_id).kids([page_id]).count(1);
pdf.page(page_id)
    .parent(page_tree_id)
    .media_box(Rect::new(0.0, 0.0, 595.0, 842.0))
    .resources();

// Finish with cross-reference table and trailer and write to file.
std::fs::write("target/empty.pdf", pdf.finish())?;