### Home Classes Methods

### In Files

- lib/prawn/repeater.rb
- lib/prawn/document.rb
- lib/prawn/outline.rb
- lib/prawn/document/column_box.rb
- lib/prawn/document/internals.rb
- lib/prawn/document/snapshot.rb
- lib/prawn/document/span.rb
- lib/prawn/document/annotations.rb
- lib/prawn/document/destinations.rb
- lib/prawn/document/bounding_box.rb
- lib/prawn/document/graphics_state.rb
- lib/prawn/document/page_geometry.rb
- lib/prawn/font.rb

### Parent

Object

### Namespace

- MODULE Prawn::Document::Annotations
- MODULE Prawn::Document::Destinations
- MODULE Prawn::Document::GraphicsState
- MODULE Prawn::Document::Internals
- MODULE Prawn::Document::PageGeometry
- MODULE Prawn::Document::Snapshot
- CLASS Prawn::Document::BoundingBox
- CLASS Prawn::Document::ColumnBox

### Methods

- ::extensions
- ::generate
- ::new
- #bounding_box
- #bounds
- #bounds=
- #canvas
- #column_box
- #compression_enabled?
- #cursor
- #define_outline
- #float
- #font
- #font_families
- #font_size
- #go_to_page
- #group
- #indent
- #move_cursor_to
- #move_down
- #move_up
- #number_pages
- #outline
- #outline_root
- #pad
- #pad_bottom
- #pad_top
- #page_count
- #page_number
- #render
- #render_file
- #repeat
- #repeaters
- #save_font
- #span
- #start_new_page
- #width_of
- #y=

### Included Modules

- Prawn::Document::Internals
- Prawn::Document::Annotations
- Prawn::Document::Destinations
- Prawn::Document::Snapshot
- Prawn::Document::GraphicsState
- Prawn::Text
- Prawn::Graphics
- Prawn::Images
- Prawn::Stamp

### Files

- COPYING
- HACKING
- LICENSE
- README

### Class/Module Index

Quicksearch

- Prawn
- Prawn::Core
- Prawn::Document
- Prawn::Document::Annotations
- Prawn::Document::BoundingBox
- Prawn::Document::ColumnBox
- Prawn::Document::Destinations
- Prawn::Document::GraphicsState
- Prawn::Document::Internals
- Prawn::Document::PageGeometry
- Prawn::Document::Snapshot
- Prawn::Encoding
- Prawn::Errors
- Prawn::Font
- Prawn::Font::AFM
- Prawn::Font::DFont
- Prawn::Font::TTF
- Prawn::Graphics
- Prawn::Graphics::CapStyle
- Prawn::Graphics::Color
- Prawn::Graphics::Dash
- Prawn::Graphics::JoinStyle
- Prawn::Graphics::Transformation
- Prawn::Graphics::Transparency
- Prawn::Images
- Prawn::Images::JPG
- Prawn::Images::PNG
- Prawn::Measurements
- Prawn::Outline
- Prawn::Stamp
- Prawn::Text
- Prawn::Text::Box
- Prawn::Text::LineWrap
- File
- Numeric

No matching classes.

# Prawn::Document

The Prawn::Document class is how you start creating a PDF document.

There are three basic ways you can instantiate PDF Documents in Prawn, they are through assignment, implicit block or explicit block. Below is an exmple of each type, each example does exactly the same thing, makes a PDF document with all the defaults and puts in the default font "Hello There" and then saves it to the current directory as "example.pdf"

For example, assignment can be like this:

    pdf = Prawn::Document.new
    pdf.text "Hello There"
    pdf.render_file "example.pdf"

Or you can do an implied block form:

    Prawn::Document.generate "example.pdf" do
      text "Hello There"
    end

Or if you need to access a variable outside the scope of the block, the explicit block form:

    words = "Hello There"
    Prawn::Document.generate "example.pdf" do |pdf|
      pdf.text words
    end

Usually, the block forms are used when you are simply creating a PDF document that you want to immediately save or render out.

See the new and generate methods for further details on the above.

### Attributes

default_line_wrap[RW]
font_size[W]
margin_box[RW]
margins[R]
page[RW]
pages[R]
store[R]
y[R]

### Public Class Methods

extensions() click to toggle source

Any module added to this array will be included into instances of Prawn::Document at the per-object level. These will also be inherited by any subclasses.

Example:

    module MyFancyModule

      def party!
        text "It's a big party!"
      end

    end

    Prawn::Document.extensions << MyFancyModule

    Prawn::Document.generate("foo.pdf") do
      party!
    end

    # File lib/prawn/document.rb, line 93
    def self.extensions
      @extensions ||= []
    end

generate(filename,options={},&block) click to toggle source

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

    # File lib/prawn/document.rb, line 128
    def self.generate(filename,options={},&block)
      pdf = new(options,&block)
      pdf.render_file(filename)
    end

new(options={},&block) click to toggle source

Creates a new PDF Document. The following options are available (with the default values marked in [])

`:page_size` | One of the Document::PageGeometry sizes [LETTER]
`:page_layout` | Either `:portrait` or `:landscape`
`:margin` | Sets the margin on all sides in points [0.5 inch]
`:left_margin` | Sets the left margin in points [0.5 inch]
`:right_margin` | Sets the right margin in points [0.5 inch]
`:top_margin` | Sets the top margin in points [0.5 inch]
`:bottom_margin` | Sets the bottom margin in points [0.5 inch]
`:skip_page_creation` | Creates a document without starting the first page [false]
`:compress` | Compresses content streams before rendering them [false]
`:optimize_objects` | Reduce number of PDF objects in output, at expense of render time [false]
`:background` | An image path to be used as background on all pages [nil]
`:info` | Generic hash allowing for custom metadata properties [nil]
`:text_options` | A set of default options to be handed to text(). Be careful with this.

Setting e.g. the :margin to 100 points and the :left_margin to 50 will result in margins of 100 points on every side except for the left, where it will be 50.

The :margin can also be an array much like CSS shorthand:

    # Top and bottom are 20, left and right are 100.
    :margin => [20, 100]
    # Top is 50, left and right are 100, bottom is 20.
    :margin => [50, 100, 20]
    # Top is 10, right is 20, bottom is 30, left is 40.
    :margin => [10, 20, 30, 40]

Additionally, :page_size can be specified as a simple two value array giving the width and height of the document you need in PDF Points.

Usage:

    # New document, US Letter paper, portrait orientation
    pdf = Prawn::Document.new

    # New document, A4 paper, landscaped
    pdf = Prawn::Document.new(:page_size => "A4", :page_layout => :landscape)

    # New document, Custom size
    pdf = Prawn::Document.new(:page_size => [200, 300])

    # New document, with background
    pdf = Prawn::Document.new(:background => "#{Prawn::BASEDIR}/data/images/pigs.jpg")

    # File lib/prawn/document.rb, line 179
    def initialize(options={},&block)
       Prawn.verify_options [:page_size, :page_layout, :margin, :left_margin,
         :right_margin, :top_margin, :bottom_margin, :skip_page_creation,
         :compress, :skip_encoding, :text_options, :background, :info,
         :optimize_objects], options

       # need to fix, as the refactoring breaks this
       # raise NotImplementedError if options[:skip_page_creation]

       self.class.extensions.reverse_each { |e| extend e }

       options[:info] ||= {}
       options[:info][:Creator] ||= "Prawn"
       options[:info][:Producer] = "Prawn"

       options[:info].keys.each do |key|
         if options[:info][key].kind_of?(String)
           options[:info][key] = Prawn::LiteralString.new(options[:info][key])
         end
       end

       @version = 1.3
       @store = Prawn::Core::ObjectStore.new(options[:info])
       @trailer = {}

       @before_render_callbacks = []
       @on_page_create_callback = nil

       @compress         = options[:compress] || false
       @optimize_objects = options.fetch(:optimize_objects, false)
       @skip_encoding    = options[:skip_encoding]
       @background       = options[:background]
       @font_size        = 12

       @pages            = []
       @page             = nil

       @bounding_box  = nil
       @margin_box    = nil

       @text_options = options[:text_options] || {}
       @default_line_wrap = Prawn::Text::LineWrap.new

       @page_number = 0

       options[:size] = options.delete(:page_size)
       options[:layout] = options.delete(:page_layout)

       if options[:skip_page_creation]
         start_new_page(options.merge(:orphan => true))
       else
         start_new_page(options)
       end

       @bounding_box = @margin_box

       if block
         block.arity < 1 ? instance_eval(&block) : block[self]
       end
     end

### Public Instance Methods

bounding_box(point, options={}, &block) click to toggle source

A bounding box serves two important purposes:

- Provide bounds for flowing text, starting at a given point

- Translate the origin (0,0) for graphics primitives

A point and :width must be provided. :height is optional. (See stretchyness below)

## Positioning

Bounding boxes are positioned relative to their top left corner and the width measurement is towards the right and height measurement is downwards.

Usage:

- Bounding box 100pt x 100pt in the absolute bottom left of the containing box:

  pdf.bounding_box(, :width => 100, :height => 100)

      stroke_bounds

  end

- Bounding box 200pt x 400pt high in the center of the page:

  x_pos = ((bounds.width / 2) - 150) y_pos = ((bounds.height / 2) + 200) pdf.bounding_box([x_pos, y_pos], :width => 300, :height => 400) do

      stroke_bounds

  end

## Flowing Text

When flowing text, the usage of a bounding box is simple. Text will begin at the point specified, flowing the width of the bounding box. After the block exits, the cursor position will be moved to the bottom of the bounding box (y - height). If flowing text exceeds the height of the bounding box, the text will be continued on the next page, starting again at the top-left corner of the bounding box.

Usage:

    pdf.bounding_box([100,500], :width => 100, :height => 300) do
      pdf.text "This text will flow in a very narrow box starting" +
       "from [100,500]. The pointer will then be moved to [100,200]" +
       "and return to the margin_box"
    end

Note, this is a low level tool and is designed primarily for building other abstractions. If you just need to flow text on the page, you will want to look at span() and text_box() instead

## Translating Coordinates

When translating coordinates, the idea is to allow the user to draw relative to the origin, and then translate their drawing to a specified area of the document, rather than adjust all their drawing coordinates to match this new region.

Take for example two triangles which share one point, drawn from the origin:

    pdf.polygon [0,250], [0,0], [150,100]
    pdf.polygon [100,0], [150,100], [200,0]

It would be easy enough to translate these triangles to another point, e.g [200,200]

    pdf.polygon [200,450], [200,200], [350,300]
    pdf.polygon [300,200], [350,300], [400,200]

However, each time you want to move the drawing, you'd need to alter every point in the drawing calls, which as you might imagine, can become tedious.

If instead, we think of the drawing as being bounded by a box, we can see that the image is 200 points wide by 250 points tall.

To translate it to a new origin, we simply select a point at (x,y+height)

Using the [200,200] example:

    pdf.bounding_box([200,450], :width => 200, :height => 250) do
      pdf.stroke do
        pdf.polygon [0,250], [0,0], [150,100]
        pdf.polygon [100,0], [150,100], [200,0]
      end
    end

Notice that the drawing is still relative to the origin. If we want to move this drawing around the document, we simply need to recalculate the top-left corner of the rectangular bounding-box, and all of our graphics calls remain unmodified.

## Nesting Bounding Boxes

At the top level, bounding boxes are specified relative to the document's margin_box (which is itself a bounding box). You can also nest bounding boxes, allowing you to build components which are relative to each other

Usage:

    pdf.bounding_box([200,450], :width => 200, :height => 250) do
      pdf.stroke_bounds   # Show the containing bounding box
      pdf.bounding_box([50,200], :width => 50, :height => 50) do
        # a 50x50 bounding box that starts 50 pixels left and 50 pixels down
        # the parent bounding box.
        pdf.stroke_bounds
      end
    end

## Stretchyness

If you do not specify a height to a bounding box, it will become stretchy and its height will be calculated automatically as you stretch the box downwards.

    pdf.bounding_box([100,400], :width => 400) do
      pdf.text("The height of this box is #{pdf.bounds.height}")
      pdf.text('this is some text')
      pdf.text('this is some more text')
      pdf.text('and finally a bit more')
      pdf.text("Now the height of this box is #{pdf.bounds.height}")
    end

## Absolute Positioning

If you wish to position the bounding boxes at absolute coordinates rather than relative to the margins or other bounding boxes, you can use canvas()

    pdf.bounding_box([50,500], :width => 200, :height => 300) do
      pdf.stroke_bounds
      pdf.canvas do
        Positioned outside the containing box at the 'real' (300,450)
        pdf.bounding_box([300,450], :width => 200, :height => 200) do
          pdf.stroke_bounds
        end
      end
    end

Of course, if you use canvas, you will be responsible for ensuring that you remain within the printable area of your document.

    # File lib/prawn/document/bounding_box.rb, line 156
    def bounding_box(*args, &block)
      init_bounding_box(block) do |_|
        map_to_absolute!(args[0])
        @bounding_box = BoundingBox.new(self, *args)
      end
    end

bounds() click to toggle source

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

    # File lib/prawn/document.rb, line 408
    def bounds
      @bounding_box
    end

bounds=(bounding_box) click to toggle source

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.

    # File lib/prawn/document.rb, line 417
    def bounds=(bounding_box)
      @bounding_box = bounding_box
    end

canvas(&block) click to toggle source

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

    # File lib/prawn/document/bounding_box.rb, line 170
    def canvas(&block)
      init_bounding_box(block, :hold_position => true) do |_|
        @bounding_box = BoundingBox.new(self, [0,page.dimensions[3]],
          :width => page.dimensions[2],
          :height => page.dimensions[3]
        )
      end
    end

column_box(*args, &block) click to toggle source

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.

Defaults are :columns = 3 and :spacer = font_size

Under PDF::Writer, "spacer" was known as "gutter"

    # File lib/prawn/document/column_box.rb, line 23
    def column_box(*args, &block)
      init_column_box(block) do |_|
        map_to_absolute!(args[0])
        @bounding_box = ColumnBox.new(self, *args)
      end
    end

compression_enabled?() click to toggle source

Returns true if content streams will be compressed before rendering, false otherwise

    # File lib/prawn/document.rb, line 555
    def compression_enabled?
      !!@compress
    end

cursor() click to toggle source

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

    # File lib/prawn/document.rb, line 331
    def cursor
      y - bounds.absolute_bottom
    end

define_outline(&block) click to toggle source

See Outline#define below for documentation

    # File lib/prawn/outline.rb, line 13
    def define_outline(&block)
      outline.define(&block)
    end

float() click to toggle source

Executes a block and then restores the original y position

    pdf.text "A"

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

    pdf.text "B"

    # File lib/prawn/document.rb, line 353
    def float
      mask(:y) { yield }
    end

font(name=nil, options={}) click to toggle source

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("Chalkboard.ttf") do
        text "Using TTF font from file Chalkboard.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.

    # File lib/prawn/font.rb, line 47
    def font(name=nil, options={})
      return((defined?(@font) && @font) || font("Helvetica")) if name.nil?

      raise Errors::NotOnPage if pages.empty? && !page.in_stamp_stream?
      new_font = find_font(name, options)

      if block_given?
        save_font do
          set_font(new_font, options[:size])
          yield
        end
      else
        set_font(new_font, options[:size])
      end

      @font
    end

font_families() click to toggle source

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".

You probably want to provide those four styles, but are free to define custom ones, like :thin, and use them in font calls.

    # File lib/prawn/font.rb, line 177
    def font_families
      @font_families ||= Hash.new { |h,k| h[k] = {} }.merge!(
        { "Courier"     => { :bold        => "Courier-Bold",
                             :italic      => "Courier-Oblique",
                             :bold_italic => "Courier-BoldOblique",
                             :normal      => "Courier" },

          "Times-Roman" => { :bold         => "Times-Bold",
                             :italic       => "Times-Italic",
                             :bold_italic  => "Times-BoldItalic",
                             :normal       => "Times-Roman" },

          "Helvetica"   => { :bold         => "Helvetica-Bold",
                             :italic       => "Helvetica-Oblique",
                             :bold_italic  => "Helvetica-BoldOblique",
                             :normal       => "Helvetica" }
        })
    end

font_size(points=nil) click to toggle source

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.

    # File lib/prawn/font.rb, line 88
    def font_size(points=nil)
      return @font_size unless points
      size_before_yield = @font_size
      @font_size = points
      block_given? ? yield : return
      @font_size = size_before_yield
    end

go_to_page(k) click to toggle source

Re-opens the page with the given (1-based) page number so that you can draw on it. Does not restore page state such as margins, page orientation, or paper size, so you'll have to handle that yourself.

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

    # File lib/prawn/document.rb, line 318
    def go_to_page(k)
      @page_number = k
      self.page = pages[k-1]
    end

group(second_attempt=false) click to toggle source

Attempts to group the given block vertically within the current context. First attempts to render it in the current position on the current page. If that attempt overflows, it is tried anew after starting a new context (page or column).

Raises CannotGroup if the provided content is too large to fit alone in the current page or column.

    # File lib/prawn/document.rb, line 509
    def group(second_attempt=false)
      old_bounding_box = @bounding_box
      @bounding_box = SimpleDelegator.new(@bounding_box)

      def @bounding_box.move_past_bottom
        raise RollbackTransaction
      end

      success = transaction { yield }

      unless success
        raise Prawn::Errors::CannotGroup if second_attempt
        old_bounding_box.move_past_bottom
        group(second_attempt=true) { yield }
      end

      @bounding_box = old_bounding_box
    end

indent(x, &block) click to toggle source

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"

    # File lib/prawn/document.rb, line 486
    def indent(x, &block)
      bounds.indent(x, &block)
    end

move_cursor_to(new_y) click to toggle source

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

    # File lib/prawn/document.rb, line 338
    def move_cursor_to(new_y)
      self.y = new_y + bounds.absolute_bottom
    end

move_down(n) click to toggle source

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

    # File lib/prawn/document.rb, line 431
    def move_down(n)
      self.y -= n
    end

move_up(n) click to toggle source

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

    # File lib/prawn/document.rb, line 424
    def move_up(n)
      self.y += n
    end

number_pages(string, position) click to toggle source

Specify a template 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 doucment.

Example:

    Prawn::Document.generate("page_with_numbering.pdf") do
      text "Hai"
      start_new_page
      text "bai"
      start_new_page
      text "-- Hai again"
      number_pages "<page> in a total of <total>", [bounds.right - 50, 0]
    end

    # File lib/prawn/document.rb, line 544
    def number_pages(string, position)
      page_count.times do |i|
        go_to_page(i+1)
        str = string.gsub("<page>","#{i+1}").gsub("<total>","#{page_count}")
        draw_text str, :at => position
      end
    end

outline() click to toggle source

Lazily instantiates an Outline object for document. This is used as point of entry to methods to build the outline tree.

    # File lib/prawn/outline.rb, line 26
    def outline
      @outline ||= Outline.new(self)
    end

outline_root(outline_root) click to toggle source

The Outline dictionary (12.3.3) for this document. It is lazily initialized, so that documents that do not have an outline do not incur the additional overhead.

    # File lib/prawn/outline.rb, line 20
    def outline_root(outline_root)
      @store.root.data[:Outlines] ||= ref!(outline_root)
    end

pad(y) click to toggle source

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"

    # File lib/prawn/document.rb, line 470
    def pad(y)
      move_down(y)
      yield
      move_down(y)
    end

pad_bottom(y) click to toggle source

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"

    # File lib/prawn/document.rb, line 456
    def pad_bottom(y)
      yield
      move_down(y)
    end

pad_top(y) click to toggle source

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"

    # File lib/prawn/document.rb, line 443
    def pad_top(y)
      move_down(y)
      yield
    end

page_count() click to toggle source

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

    # File lib/prawn/document.rb, line 301
    def page_count
      pages.length
    end

page_number() click to toggle source

Returns the 1-based page number of the current page. Returns 0 if the document has no pages.

    # File lib/prawn/document.rb, line 308
    def page_number
      @page_number
    end

render() click to toggle source

Renders the PDF document to string

    # File lib/prawn/document.rb, line 359
    def render
      output = StringIO.new
      finalize_all_page_contents

      render_header(output)
      render_body(output)
      render_xref(output)
      render_trailer(output)
      str = output.string
      str.force_encoding("ASCII-8BIT") if str.respond_to?(:force_encoding)
      str
    end

render_file(filename) click to toggle source

Renders the PDF document to file.

    pdf.render_file "foo.pdf"

    # File lib/prawn/document.rb, line 376
    def render_file(filename)
      Kernel.const_defined?("Encoding") ? mode = "wb:ASCII-8BIT" : mode = "wb"
      File.open(filename,mode) { |f| f << render }
    end

repeat(page_filter, options={}, &block) click to toggle source

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

    # File lib/prawn/repeater.rb, line 75
    def repeat(page_filter, options={}, &block)
      repeaters << Prawn::Repeater.new(self, page_filter, !!options[:dynamic], &block)
    end

repeaters() click to toggle source

A list of all repeaters in the document. See Document#repeat for details

    # File lib/prawn/repeater.rb, line 17
    def repeaters
      @repeaters ||= []
    end

save_font() click to toggle source

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

    # File lib/prawn/font.rb, line 107
    def save_font
      @font ||= find_font("Helvetica")
      original_font = @font
      original_size = @font_size

      yield
    ensure
      set_font(original_font, original_size) if original_font
    end

span(width, options={}) click to toggle source

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

    # File lib/prawn/document/span.rb, line 26
        def span(width, options={})
          Prawn.verify_options [:position], options
          original_position = self.y

          # FIXME: Any way to move this upstream?
          left_boundary = case(options[:position] || :left)
          when :left
            margin_box.absolute_left
          when :center
            margin_box.absolute_left + margin_box.width / 2.0 - width /2.0
          when :right
            margin_box.absolute_right - width
          when Numeric
            margin_box.absolute_left + options[:position]
          else
            raise ArgumentError, "Invalid option for :position"
          end

          # we need to bust out of whatever nested bounding boxes we're in.
          canvas do
            bounding_box([left_boundary,
                          margin_box.absolute_top], :width => width) do
              self.y = original_position
              yield
            end
          end
        end
      end
    end

start_new_page(options = {}) click to toggle source

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)

    # File lib/prawn/document.rb, line 251
     def start_new_page(options = {})
       if last_page = page
         last_page_size    = last_page.size
         last_page_layout  = last_page.layout
         last_page_margins = last_page.margins
       end

       self.page = Prawn::Core::Page.new(self,
         :size    => options[:size]   || last_page_size,
         :layout  => options[:layout] || last_page_layout,
         :margins => last_page_margins )

       apply_margin_option(options) if options[:margin]

       [:left,:right,:top,:bottom].each do |side|
         if margin = options[:"#{side}_margin"]
           page.margins[side] = margin
         end
       end

       generate_margin_box

       update_colors
       undash if dashed?

       unless options[:orphan]
         pages.insert(@page_number, page)
         @store.pages.data[:Kids].insert(@page_number, page.dictionary)
         @store.pages.data[:Count] += 1
         @page_number += 1

         save_graphics_state

         canvas { image(@background, :at => bounds.top_left) } if @background
         @y = @bounding_box.absolute_top

         float do
           @on_page_create_callback.call(self) if @on_page_create_callback
         end
       end
    end

width_of(string, options={}) click to toggle source

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.

    # File lib/prawn/font.rb, line 215
    def width_of(string, options={})
      font.compute_width_of(string, options)
    end

y=(new_y) click to toggle source

    # File lib/prawn/document.rb, line 323
    def y=(new_y)
      @y = new_y
      bounds.update_height
    end

[Validate]

Generated with the Darkfish Rdoc Generator 2.