Class: Prawn::Document

Creates and renders a PDF document.

When using the implicit block form, Prawn will evaluate the block within an instance of Prawn::Document, simplifying your syntax. However, please note that you will not be able to reference variables from the enclosing scope within this block.

# Using implicit block form and rendering to a file
Prawn::Document.generate "example.pdf" do
  # self here is set to the newly instantiated Prawn::Document
  # and so any variables in the outside scope are unavailable
  font "Times-Roman"
  draw_text "Hello World", :at => [200,720], :size => 32
end

If you need to access your local and instance variables, use the explicit block form shown below. In this case, Prawn yields an instance of PDF::Document and the block is an ordinary closure:

# Using explicit block form and rendering to a file
content = "Hello World"
Prawn::Document.generate "example.pdf" do |pdf|
  # self here is left alone
  pdf.font "Times-Roman"
  pdf.draw_text content, :at => [200,720], :size => 32
end

The bounds method returns the current bounding box you are currently in, which is by default the box represented by the margin box on the document itself. When called from within a created bounding_box block, the box defined by that call will be returned instead of the document margin box.

Another important point about bounding boxes is that all x and y measurements within a bounding box code block are relative to the bottom left corner of the bounding box.

For example:

Prawn::Document.new do
  # In the default "margin box" of a Prawn document of 0.5in along each edge

  # Draw a border around the page (the manual way)
  stroke do
    line(bounds.bottom_left, bounds.bottom_right)
    line(bounds.bottom_right, bounds.top_right)
    line(bounds.top_right, bounds.top_left)
    line(bounds.top_left, bounds.bottom_left)
  end

  # Draw a border around the page (the easy way)
  stroke_bounds
end

Sets Document#bounds to the BoundingBox provided. See above for a brief description of what a bounding box is. This function is useful if you really need to change the bounding box manually, but usually, just entering and exiting bounding box code blocks is good enough.

A shortcut to produce a bounding box which is mapped to the document's absolute coordinates, regardless of how things are nested or margin sizes.

pdf.canvas do
  pdf.line pdf.bounds.bottom_left, pdf.bounds.top_right
end

A column box is a bounding box with the additional property that when text flows past the bottom, it will wrap first to another column on the same page, and only flow to the next page when all the columns are filled.

column_box accepts the same parameters as bounding_box, as well as the number of :columns and a :spacer (in points) between columns. If resetting the top margin is desired on a new page (e.g. to allow for initial page wide column titles) the option :reflow_margins => true can be set.

Defaults are :columns = 3, :spacer = font_size, and :reflow_margins => false

Under PDF::Writer, “spacer” was known as “gutter”

The current y drawing position relative to the innermost bounding box, or to the page margins at the top level.

Defines the grid system for a particular document. Takes the number of rows and columns and the width to use for the gutter as the keys :rows, :columns, :gutter, :row_gutter, :column_gutter

Note that a completely new grid object is built each time define_grid() is called. This means that all subsequent calls to grid() will use the newly defined Grid object – grids are not nestable like bounding boxes are.

Executes a block and then restores the original y position. If new pages were created during this block, it will teleport back to the original page when done.

pdf.text "A"

pdf.float do
  pdf.move_down 100
  pdf.text "C"
end

pdf.text "B"

Without arguments, this returns the currently selected font. Otherwise, it sets the current font. When a block is used, the font is applied transactionally and is rolled back when the block exits.

Prawn::Document.generate("font.pdf") do
  text "Default font is Helvetica"

  font "Times-Roman"
  text "Now using Times-Roman"

  font("DejaVuSans.ttf") do
    text "Using TTF font from file DejaVuSans.ttf"
    font "Courier", :style => :bold
    text "You see this in bold Courier"
  end

  text "Times-Roman, again"
end

The :name parameter must be a string. It can be one of the 14 built-in fonts supported by PDF, or the location of a TTF file. The Font::AFM::BUILT_INS array specifies the valid built in font values.

If a ttf font is specified, the glyphs necessary to render your document will be embedded in the rendered PDF. This should be your preferred option in most cases. It will increase the size of the resulting file, but also make it more portable.

The options parameter is an optional hash providing size and style. To use the :style option you need to map those font styles to their respective font files. See font_families for more information.

Hash that maps font family names to their styled individual font names.

To add support for another font family, append to this hash, e.g:

pdf.font_families.update(
 "MyTrueTypeFamily" => { :bold        => "foo-bold.ttf",
                         :italic      => "foo-italic.ttf",
                         :bold_italic => "foo-bold-italic.ttf",
                         :normal      => "foo.ttf" })

This will then allow you to use the fonts like so:

pdf.font("MyTrueTypeFamily", :style => :bold)
pdf.text "Some bold text"
pdf.font("MyTrueTypeFamily")
pdf.text "Some normal text"

This assumes that you have appropriate TTF fonts for each style you wish to support.

By default the styles :bold, :italic, :bold_italic, and :normal are defined for fonts “Courier”, “Times-Roman” and “Helvetica”. When defining your own font families, you can map any or all of these styles to whatever font files you'd like.

Hash of Font objects keyed by names

When called with no argument, returns the current font size.

When called with a single argument but no block, sets the current font size. When a block is used, the font size is applied transactionally and is rolled back when the block exits. You may still change the font size within a transactional block for individual text segments, or nested calls to font_size.

Prawn::Document.generate("font_size.pdf") do
  font_size 16
  text "At size 16"

  font_size(10) do
    text "At size 10"
    text "At size 6", :size => 6
    text "At size 10"
  end

  text "At size 16"
end

When called without an argument, this method returns the current font size.

Sets the font size

Re-opens the page with the given (1-based) page number so that you can draw on it.

See Prawn::Document#number_pages for a sample usage of this capability.

A method that can either be used to access a particular grid on the page or work with the grid system directly.

@pdf.grid                 # Get the Grid directly
@pdf.grid([0,1])          # Get the GridBox at [0,1]
@pdf.grid([0,1], [1,2])   # Get a multi-box spanning from [0,1] to [1,2]

Indents the specified number of PDF points for the duration of the block

pdf.text "some text"
pdf.indent(20) do
  pdf.text "This is indented 20 points"
end
pdf.text "This starts 20 points left of the above line " +
         "and is flush with the first line"
pdf.indent 20, 20 do
  pdf.text "This line is indented on both sides."
end

Moves to the specified y position in relative terms to the bottom margin.

Moves down the document by n points relative to the current position inside the current bounding box.

Moves up the document by n points relative to the current position inside the current bounding box.

Places a text box on specified pages for page numbering. This should be called towards the end of document creation, after all your content is already in place. In your template string, <page> refers to the current page, and <total> refers to the total amount of pages in the document. Page numbering should occur at the end of your Prawn::Document.generate block because the method iterates through existing pages after they are created.

Parameters are:

string

Template string for page number wording. Should include '<page>' and, optionally, '<total>'.

options

A hash for page numbering and text box options.

:page_filter

A filter to specify which pages to place page numbers on. Refer to the method 'page_match?'

:start_count_at

The starting count to increment pages from.

:total_pages

If provided, will replace <total> with the value given. Useful to override the total number of pages when using the start_count_at option.

:color

Text fill color.

Please refer to Prawn::Text::text_box for additional options concerning text
formatting and placement.

Example: Print page numbers on every page except for the first. Start counting from

       five.

Prawn::Document.generate("page_with_numbering.pdf") do
  number_pages "<page> in a total of <total>",
                                       {:start_count_at => 5,
                                        :page_filter => lambda{ |pg| pg != 1 },
                                        :at => [bounds.right - 50, 0],
                                        :align => :right,
                                        :size => 14}
end

Lazily instantiates a Prawn::Outline object for document. This is used as point of entry to methods to build the outline tree for a document's table of contents.

Moves down the document by y, executes a block, then moves down the document by y again.

pdf.text "some text"
pdf.pad(100) do
  pdf.text "This is 100 points below the previous line of text"
end
pdf.text "This is 100 points below the previous line of text"

Executes a block then moves down the document

pdf.text "some text"
pdf.pad_bottom(100) do
  pdf.text "This text appears right below the previous line of text"
end
pdf.text "This is 100 points below the previous line of text"

Moves down the document and then executes a block.

pdf.text "some text"
pdf.pad_top(100) do
  pdf.text "This is 100 points below the previous line of text"
end
pdf.text "This text appears right below the previous line of text"

Returns the number of pages in the document

pdf = Prawn::Document.new
pdf.page_count #=> 1
3.times { pdf.start_new_page }
pdf.page_count #=> 4

Provides a way to execute a block of code repeatedly based on a page_filter.

Available page filters are:

:all         repeats on every page
:odd         repeats on odd pages
:even        repeats on even pages
some_array   repeats on every page listed in the array
some_range   repeats on every page included in the range
some_lambda  yields page number and repeats for true return values

Renders the PDF document to string. Pass an open file descriptor to render to file.

Renders the PDF document to file.

pdf.render_file "foo.pdf"

Provides a way to execute a block of code repeatedly based on a page_filter. Since Stamp is used under the hood, this method is very space efficient.

Available page filters are:

:all        -- repeats on every page
:odd        -- repeats on odd pages
:even       -- repeats on even pages
some_array  -- repeats on every page listed in the array
some_range  -- repeats on every page included in the range
some_lambda -- yields page number and repeats for true return values

Also accepts an optional second argument for dynamic content which executes the code in the context of the filtered pages without using a Stamp.

Example:

Prawn::Document.generate("repeat.pdf", :skip_page_creation => true) do

  repeat :all do
    draw_text "ALLLLLL", :at => bounds.top_left
  end

  repeat :odd do
    draw_text "ODD", :at => [0,0]
  end

  repeat :even do
    draw_text "EVEN", :at => [0,0]
  end

  repeat [1,2] do
    draw_text "[1,2]", :at => [100,0]
  end

  repeat 2..4 do
    draw_text "2..4", :at => [200,0]
  end

  repeat(lambda { |pg| pg % 3 == 0 }) do
    draw_text "Every third", :at => [250, 20]
  end

  10.times do
    start_new_page
    draw_text "A wonderful page", :at => [400,400]
  end

  repeat(:all, :dynamic => true) do
    text page_number, :at => [500, 0]
  end

end

Saves the current font, and then yields. When the block finishes, the original font is restored.

Sets the font directly, given an actual Font object and size.

A span is a special purpose bounding box that allows a column of elements to be positioned relative to the margin_box.

Arguments:

width

The width of the column in PDF points

Options:

:position

One of :left, :center, :right or an x offset

This method is typically used for flowing a column of text from one page to the next.

span(350, :position => :center) do
  text "Here's some centered text in a 350 point column. " * 100
end

Creates and advances to a new page in the document.

Page size, margins, and layout can also be set when generating a new page. These values will become the new defaults for page creation

pdf.start_new_page #=> Starts new page keeping current values
pdf.start_new_page(:size => "LEGAL", :layout => :landscape)
pdf.start_new_page(:left_margin => 50, :right_margin => 50)
pdf.start_new_page(:margin => 100)

Returns the width of the given string using the given font. If :size is not specified as one of the options, the string is measured using the current font size. You can also pass :kerning as an option to indicate whether kerning should be used when measuring the width (defaults to false).

Note that the string must be encoded properly for the font being used. For AFM fonts, this is WinAnsi. For TTF, make sure the font is encoded as UTF-8. You can use the Font#normalize_encoding method to make sure strings are in an encoding appropriate for the current font. – For the record, this method used to be a method of Font (and still delegates to width computations on Font). However, having the primary interface for calculating string widths exist on Font made it tricky to write extensions for Prawn in which widths are computed differently (e.g., taking formatting tags into account, or the like).

By putting width_of here, on Document itself, extensions may easily override it and redefine the width calculation behavior. ++