Add a font to the list of available fonts.

Currently only Type 1 AFM/PFB fonts are supported.

fonts_dir = Application.app_dir(:my_app) |> Path.join("priv", "fonts")

pdf
|> Pdf.add_font(Path.join(fonts_dir, "DejavuSans.afm")
|> Pdf.add_font(Path.join(fonts_dir, "DejavuSans-Bold.afm")

The font can then be set with set_font/3.

You have to add_font/2 all variants you want to use, bold, italic, ...

Add an images (PNG, or JPEG only) at the given coordinates.

Add an images (PNG, or JPEG only) at the given coordinates.

You can specify a :width and :height in the options, the image will then be scaled.

Add a new page to the Pdf with the given page size.

Adds an autoprint action to the Pdf.

This is can be useful for generating a PDF that will automatically open the print dialog in a browser

Fill the current page background with a color.

Example

pdf |> Pdf.background(%{color: {0.95, 0.95, 1.0}})

Builds a PDF document.

Pdf.build([size: :a3], fn pdf ->
  pdf
  |> Pdf.set_font("Helvetica", 12)
  |> Pdf.text_at({100, 100}, "Open")
  |> Pdf.write_to("test.pdf")
end)

is equivalent to

pdf = Pdf.new(size: :a3)
pdf
|> Pdf.set_font("Helvetica", 12)
|> Pdf.text_at({100, 100}, "Open")
|> Pdf.write_to("test.pdf")

No-op. Kept for backwards compatibility.

Set the current path as a clipping boundary.

@spec cm(number()) :: integer()

Convert the given value from cm to Pdf points

Returns the content area %{x, y, width, height} based on margins.

@spec cursor(Pdf.Document.t()) :: number()

Gets the current cursor Y position (vertical).

@spec cursor_xy(Pdf.Document.t()) :: %{x: number(), y: number()}

Gets the current cursor position as %{x: x, y: y}.

Draw a debug grid overlay on the current page.

Options

• :grid — :horizontal, :vertical, or :both (default :both)
• :area — where to draw the grid:
  • :content — inside margins only (default)
  • :page — entire page (0,0 to page width/height)
  • :margins — only in the margin zones (outside content area)
• :spacing — distance between grid lines in points (default 10)
• :color — grid line color (default {0.85, 0.85, 0.85})
• :line_width — grid line width (default 0.25)
• :labels — show coordinate labels (default true)
• :label_every — show a coordinate label every N points (default 50)
• :info — show page/margin info text (default true)
• :margin_border — draw the margin boundary rectangle (default true)
• :cursor_line — draw cursor Y position line (default true)

Examples

pdf |> Pdf.debug_grid()
pdf |> Pdf.debug_grid(%{grid: :horizontal, area: :page})
pdf |> Pdf.debug_grid(%{grid: :vertical, area: :content, spacing: 20})
pdf |> Pdf.debug_grid(%{area: :margins, color: {1.0, 0.9, 0.9}})

Export the Pdf to a binary representation.

This is can be used in eg Phoenix to send a PDF to the browser.

  report =
    pdf
    |> ...
    |> Pdf.export()

 conn
  |> put_resp_content_type("application/pdf")
  |> put_resp_header(
    "content-disposition",
    "attachment; filename="document.pdf""
  )
  |> send_resp(200, report)

@spec fill(Pdf.Document.t()) :: Pdf.Document.t()

Fill the current drawing with the previously set color.

Fill and stroke the current path.

Draw a horizontal line at the current cursor position across the content width.

Example

pdf |> Pdf.horizontal_line()
pdf |> Pdf.horizontal_line(%{color: :gray, line_width: 0.5})

@spec inches(number()) :: integer()

Convert the given value from inches to Pdf points

@spec line(Pdf.Document.t(), coords(), coords()) :: Pdf.Document.t()

Draw a line between 2 points.

@spec line_append(Pdf.Document.t(), coords()) :: Pdf.Document.t()

Draw a line from the last position to the given coordinates.

  pdf
  |> Pdf.move_to({100, 100})
  |> Pdf.line_append({200, 200})

@spec mm(number()) :: integer()

Convert the given value from mm to Pdf points

@spec move_down(Pdf.Document.t(), number()) :: Pdf.Document.t()

Move the cursor amount points down.

@spec move_right(Pdf.Document.t(), number()) :: Pdf.Document.t()

Move the cursor amount points to the right.

@spec move_to(Pdf.Document.t(), coords()) :: Pdf.Document.t()

Move the cursor to the given coordinates.

@spec new(any()) :: Pdf.Document.t()

Create a new Pdf document.

The following options can be given:

There is no standard font selected when creating a new PDF, so set one with set_font/3 before adding text.

Register a page template that runs on every new page.

Supported template names: :header, :footer, :watermark, :background.

The function receives (document, page_info) where page_info is %{number: n}.

Example

pdf
|> Pdf.on_page(:header, fn doc, _info ->
  Pdf.text_at(doc, {40, 820}, "My Header")
end)

Insert a page break. Executes footer template on the current page and header/watermark templates on the new page.

Example

pdf |> Pdf.page_break()
pdf |> Pdf.page_break(:letter)

Returns the current page number.

@spec picas(number()) :: number()

Convert the given value from picas to Pdf points

@spec pixels_to_points(pixels :: number(), dpi :: number()) :: integer()

Convert the given value from pixels to Pdf points

The unit of measurement in a Pdf are points, where 1 point = 1/72 inch. This means that a standard A4 page, 8.27 inch, translates to 595 points.

@spec rectangle(Pdf.Document.t(), coords(), dimension()) :: Pdf.Document.t()

Draw a rectangle from coordinates x,y (lower left corner) for a given width and height.

Register a named style that can be referenced by atom in text/3, horizontal_line/2, etc.

Example

pdf
|> Pdf.register_style(:heading, %{font_size: 24, bold: true, color: :navy})
|> Pdf.register_style(:body, %{font_size: 12, color: :black})
|> Pdf.register_style(:accent, %{font_size: 12, color: :green})
|> Pdf.text("My Title", :heading)
|> Pdf.text("Body text", :body)

Register multiple named styles at once from a map.

Example

Pdf.register_styles(pdf, %{
  heading: %{font_size: 24, bold: true, color: :navy},
  body: %{font_size: 12},
  footer: %{font_size: 8, color: :gray}
})

@spec reset_x(Pdf.Document.t()) :: Pdf.Document.t()

Reset the cursor X position to 0.

@spec restore_state(Pdf.Document.t()) :: Pdf.Document.t()

Restore a previously saved graphics state.

@spec rotate(Pdf.Document.t(), number()) :: Pdf.Document.t()

Rotate the coordinate system by the given angle in degrees. Must be used within save_state/restore_state.

Draw a rounded rectangle.

@spec save_state(Pdf.Document.t()) :: Pdf.Document.t()

Save the current graphics state. Use with restore_state/1 to isolate transformations like rotation, translation, scaling, and opacity changes.

@spec scale(
  Pdf.Document.t(),
  {number(), number()}
) :: Pdf.Document.t()

Scale the coordinate system by {sx, sy}. Must be used within save_state/restore_state.

Sets the author in the PDF information section.

Sets the creator in the PDF information section.

@spec set_cursor(Pdf.Document.t(), number()) :: Pdf.Document.t()

Set the cursor Y position.

@spec set_cursor_x(Pdf.Document.t(), number()) :: Pdf.Document.t()

Set the cursor X position.

@spec set_fill_color(Pdf.Document.t(), color_name() | rgb() | cmyk()) ::
  Pdf.Document.t()

Set the color to use when filling.

This takes either a Pdf.Color.color/1 atom, an RGB tuple or a CMYK tuple.

@spec set_fill_opacity(Pdf.Document.t(), number()) :: Pdf.Document.t()

Set the fill opacity (0.0 fully transparent, 1.0 fully opaque).

@spec set_font(Pdf.Document.t(), binary(), integer() | list()) :: Pdf.Document.t()

Sets the font that will be used for all text from here on. You can either specify the font size, or a list of options:

Sets the font size.

The font has to have been previously set!

@spec set_info(Pdf.Document.t(), info_list()) :: Pdf.Document.t()

Set multiple keys in the PDF information section.

Valid keys

• :author
• :created
• :creator
• :keywords
• :modified
• :producer
• :subject
• :title

Sets the keywords in the PDF information section.

@spec set_line_cap(Pdf.Document.t(), cap_style()) :: Pdf.Document.t()

The line endings to draw, see cap_style/0.

@spec set_line_join(Pdf.Document.t(), join_style()) :: Pdf.Document.t()

The join style to use where lines meet, see join_style/0.

@spec set_line_width(Pdf.Document.t(), number()) :: Pdf.Document.t()

The width to use when drawing lines.

@spec set_opacity(Pdf.Document.t(), number()) :: Pdf.Document.t()

Set both fill and stroke opacity (0.0 fully transparent, 1.0 fully opaque).

Sets the producer in the PDF information section.

@spec set_stroke_color(Pdf.Document.t(), color_name() | rgb() | cmyk()) ::
  Pdf.Document.t()

Set the color to use when drawing lines.

This takes either a Pdf.Color.color/1 atom, an RGB tuple or a CMYK tuple.

@spec set_stroke_opacity(Pdf.Document.t(), number()) :: Pdf.Document.t()

Set the stroke opacity (0.0 fully transparent, 1.0 fully opaque).

Sets the subject in the PDF information section.

Leading is a typography term that describes the distance between each line of text. The name comes from a time when typesetting was done by hand and pieces of lead were used to separate the lines.

Today, leading is often used synonymously with "line height" or "line spacing."

Sets the title in the PDF information section.

Returns a {width, height} for the current page.

Add vertical space by moving the cursor down.

Example

pdf |> Pdf.spacer(20)

@spec stroke(Pdf.Document.t()) :: Pdf.Document.t()

Perform all the previous graphic commands.

Render a styled table at the current cursor position.

Example

Pdf.styled_table(doc, [
  ["Name", "Qty", "Price"],
  ["Widget", "5", "$10.00"]
], %{
  columns: [%{width: 200}, %{width: 80, align: :center}, %{width: 120, align: :right}],
  header: %{bold: true, background: {0.2, 0.3, 0.5}, color: :white, padding: 8},
  row: %{padding: 6, border_bottom: 0.5},
  alt_row: %{background: {0.95, 0.95, 1.0}},
  border: 1,
  border_radius: 6
})

Add a table in the document at the given coordinates.

See Tables for more information on how to use tables.

Add a table in the document at the given coordinates. Raises an exception if the table does not fit the dimensions.

See Tables for more information on how to use tables.

Write styled text at the current cursor position with auto-wrapping. Moves the cursor down after writing.

Example

pdf |> Pdf.text("Hello world")
pdf |> Pdf.text("Bold red", %{bold: true, color: :red, font_size: 16})

Writes the text at the given coordinates. The coordinates are the bottom left of the text.

The text can be either a binary or a list of binaries or annotated binaries. All text will be drawn on the same line, no wrapping will occur, it may overrun the page.

When given a list, you can supply a mix of binaries and annotated binaries. An annotated binary is a tuple {binary, options}, with the options being:

When setting bold: true or italic: true, make sure that your current font supports these or an error will occur. If using an external font, you have to add_font/2 all variants you want to use.

Writes the text at the given coordinates. The coordinates are the bottom left of the text.

Accepts either a keyword list of options or a style map/atom:

pdf |> Pdf.text_at({300, 730}, "BILL TO", %{bold: true, color: :gray})
pdf |> Pdf.text_at({300, 730}, "BILL TO", :label)
pdf |> Pdf.text_at({300, 730}, "BILL TO", kerning: true)

@spec text_lines(Pdf.Document.t(), coords(), list(), keyword()) :: Pdf.Document.t()

This function draws a number of text lines starting at the given coordinates. The list can overrun the page, no errors or wrapping will occur.

Kerning can be set, see text_at/4 for more information.

@spec text_wrap(Pdf.Document.t(), coords(), dimension(), binary() | list()) ::
  {Pdf.Document.t(), :complete | term()}

Writes the text wrapped within the confines of the given dimensions. The {x,y} is the top-left of corner of the box, for this reason it is not wise to try to match it up with text_at on the same line.

The y-coordinate can also be set to :cursor.

The text will break at whitespace, such as, space, soft-hyphen, hyphen, cr, lf, tab, ...

If the text is too large for the box, it may overrun its boundaries, but only horizontally.

This function will return a tuple {pid, :complete} if all text was rendered, or {pid, remaining} if not. It can subsequently be called with the remaining data, after eg starting a new page, until {pid, :complete}.

The text can be either a binary or a list of binaries or annotated binaries. The :kerning option if set will apply to all rendered text.

When given a list, you can supply a mix of binaries and annotated binaries. An annotated binary is a tuple {binary, options}, with the options being:

When choosing :bold or :italic, make sure that your current font supports these or an error will occur. If using an external font, you have to add_font/2 all variants you want to use.

@spec text_wrap(Pdf.Document.t(), coords(), dimension(), binary() | list(), keyword()) ::
  {Pdf.Document.t(), :complete | term()}

This function has the same options as text_wrap/4, but also supports additional options that will be applied to the complete text.

@spec text_wrap!(Pdf.Document.t(), coords(), dimension(), binary() | list()) ::
  Pdf.Document.t()

This function has the same options as text_wrap/4, but if the text is too large for the box, a RuntimeError will be raised.

@spec text_wrap!(
  Pdf.Document.t(),
  coords(),
  dimension(),
  binary() | list(),
  keyword()
) ::
  Pdf.Document.t()

This function has the same options as text_wrap/5, but if the text is too large for the box, a RuntimeError will be raised.

@spec transform(
  Pdf.Document.t(),
  {number(), number(), number(), number(), number(), number()}
) ::
  Pdf.Document.t()

Apply an arbitrary transformation matrix {a, b, c, d, e, f}. Must be used within save_state/restore_state.

@spec translate(
  Pdf.Document.t(),
  {number(), number()}
) :: Pdf.Document.t()

Translate (move) the coordinate origin by {tx, ty}. Must be used within save_state/restore_state.

Add a text watermark to the current page with rotation and opacity.

Example

pdf |> Pdf.watermark("DRAFT", %{opacity: 0.1, rotate: 45, font_size: 60, color: :gray})

Write the PDF to the given path