Class: Prawn::Document

Inherits:
Object
  • Object
show all
Includes:
PDF::Core::Annotations, PDF::Core::Destinations, GraphicsState, Internals, Security, Snapshot, Graphics, Images, SoftMask, Stamp, Text
Defined in:
lib/prawn/document.rb,
lib/prawn/font.rb,
lib/prawn/table.rb,
lib/prawn/outline.rb,
lib/prawn/repeater.rb,
lib/prawn/security.rb,
lib/prawn/table/cell.rb,
lib/prawn/layout/grid.rb,
lib/prawn/document/span.rb,
lib/prawn/document/snapshot.rb,
lib/prawn/document/internals.rb,
lib/prawn/document/column_box.rb,
lib/prawn/document/bounding_box.rb,
lib/prawn/document/graphics_state.rb

Overview

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.

Defined Under Namespace

Modules: GraphicsState, Internals, Security, Snapshot Classes: BoundingBox, Box, ColumnBox, Grid, MultiBox

Constant Summary collapse

VALID_OPTIONS =

NOTE: We probably need to rethink the options validation system, but this constant temporarily allows for extensions to modify the list.

[:page_size, :page_layout, :margin, :left_margin,
:right_margin, :top_margin, :bottom_margin, :skip_page_creation,
:compress, :skip_encoding, :background, :info,
:optimize_objects, :text_formatter, :print_scaling]

Constants included from Graphics

Graphics::KAPPA

Constants included from Graphics::JoinStyle

Graphics::JoinStyle::JOIN_STYLES

Constants included from Graphics::CapStyle

Graphics::CapStyle::CAP_STYLES

Constants included from Text

Text::NBSP, Text::SHY, Text::ZWSP

Constants included from PDF::Core::Text

PDF::Core::Text::MODES

Constants included from Snapshot

Snapshot::RollbackTransaction

Constants included from PDF::Core::Destinations

PDF::Core::Destinations::NAME_TREE_CHILDREN_LIMIT

Instance Attribute Summary collapse

Attributes included from PDF::Core::Text

#skip_encoding

Class Method Summary collapse

Instance Method Summary collapse

Methods included from SoftMask

#soft_mask

Methods included from Stamp

#create_stamp, #stamp, #stamp_at

Methods included from Images

#build_image_object, #embed_image, #image

Methods included from Graphics

#circle, #circle_at, #close_and_stroke, #close_path, #curve, #curve_to, #ellipse, #ellipse_at, #fill, #fill_and_stroke, #horizontal_line, #horizontal_rule, #line, #line_to, #line_width, #line_width=, #move_to, #polygon, #rectangle, #rounded_polygon, #rounded_rectangle, #rounded_vertex, #stroke, #stroke_axis, #stroke_bounds, #vertical_line

Methods included from Graphics::Patterns

#fill_gradient, #stroke_gradient

Methods included from Graphics::Transformation

#rotate, #scale, #transformation_matrix, #translate

Methods included from Graphics::Transparency

#transparent

Methods included from Graphics::JoinStyle

#join_style

Methods included from Graphics::CapStyle

#cap_style

Methods included from Graphics::Dash

#dash, #dashed?, #undash, #write_stroke_dash

Methods included from Graphics::Color

#fill_color, hex2rgb, rgb2hex, #stroke_color

Methods included from Text

#draw_text, #formatted_text, #height_of, #height_of_formatted, #text, #text_box

Methods included from Text::Formatted

#formatted_text_box

Methods included from PDF::Core::Text

#character_spacing, #default_kerning, #default_kerning?, #default_leading, #draw_text!, #fallback_fonts, #forget_text_rendering_mode!, #process_text_options, #text_direction, #text_rendering_mode, #word_spacing

Methods included from Security

#encrypt_document, encrypt_string

Methods included from PDF::Core

EncryptedPdfObject, PdfObject, Reference, string_to_hex, utf8_to_utf16

Methods included from GraphicsState

#close_graphics_state, #graphic_stack, #graphic_state, #open_graphics_state, #restore_graphics_state, #save_graphics_state

Methods included from Snapshot

#rollback, #transaction

Methods included from PDF::Core::Destinations

#add_dest, #dest_fit, #dest_fit_bounds, #dest_fit_bounds_horizontally, #dest_fit_bounds_vertically, #dest_fit_horizontally, #dest_fit_rect, #dest_fit_vertically, #dest_xyz, #dests

Methods included from PDF::Core::Annotations

#annotate, #link_annotation, #text_annotation

Methods included from Internals

#add_content, #before_render, #deref, #names, #names?, #on_page_create, #ref, #ref!

Constructor Details

#initialize(options = {}, &block) ⇒ Document

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]

:background_scale

Backgound image scale [1] [nil]

:info

Generic hash allowing for custom metadata properties [nil]

:text_formatter: The text formatter to use for :inline_formatted text [Prawn::Text::Formatted::Parser]

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::DATADIR}/images/pigs.jpg")



180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
 
# File 'lib/prawn/document.rb', line 180

def initialize(options={},&block)
  options = options.dup

  Prawn.verify_options VALID_OPTIONS, options

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

  self.class.extensions.reverse_each { |e| extend e }
  @internal_state = PDF::Core::DocumentState.new(options)
  @internal_state.populate_pages_from_store(self)
  min_version(state.store.min_version) if state.store.min_version

  min_version(1.6) if options[:print_scaling] == :none

  @background = options[:background]
  @background_scale = options[:background_scale] || 1
  @font_size  = 12

  @bounding_box  = nil
  @margin_box    = nil

  @page_number = 0

  @text_formatter = options.delete(:text_formatter) || Text::Formatted::Parser

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

  initialize_first_page(options)

  @bounding_box = @margin_box

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

Instance Attribute Details

#font_size(points = nil) ⇒ Object

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.



93
94
95
96
97
98
99
 
# File 'lib/prawn/font.rb', line 93

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

#margin_box ⇒ Object

Returns the value of attribute margin_box.



218
219
220
 
# File 'lib/prawn/document.rb', line 218

def margin_box
  @margin_box
end

#margins ⇒ Object (readonly)

Returns the value of attribute margins.



219
220
221
 
# File 'lib/prawn/document.rb', line 219

def margins
  @margins
end

#page_number ⇒ Object

Returns the value of attribute page_number.



221
222
223
 
# File 'lib/prawn/document.rb', line 221

def page_number
  @page_number
end

#text_formatter ⇒ Object

Returns the value of attribute text_formatter.



222
223
224
 
# File 'lib/prawn/document.rb', line 222

def text_formatter
  @text_formatter
end

#y ⇒ Object

Returns the value of attribute y.



219
220
221
 
# File 'lib/prawn/document.rb', line 219

def y
  @y
end

Class Method Details

.extensions ⇒ Object

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



93
94
95
 
# File 'lib/prawn/document.rb', line 93

def self.extensions
  @extensions ||= []
end

.generate(filename, options = {}, &block) ⇒ Object

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



128
129
130
131
 
# File 'lib/prawn/document.rb', line 128

def self.generate(filename,options={},&block)
  pdf = new(options,&block)
  pdf.render_file(filename)
end

.inherited(base) ⇒ Object

:nodoc:



97
98
99
 
# File 'lib/prawn/document.rb', line 97

def self.inherited(base) #:nodoc:
  extensions.each { |e| base.extensions << e }
end

.move_past_bottom ⇒ Object

Raises:



524
525
526
 
# File 'lib/prawn/document.rb', line 524

def @bounding_box.move_past_bottom
  raise RollbackTransaction
end

Instance Method Details

#bounding_box(pt, *args, &block) ⇒ Object

:call-seq:

bounding_box(point, options={}, &block)

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.



157
158
159
160
161
162
 
# File 'lib/prawn/document/bounding_box.rb', line 157

def bounding_box(pt, *args, &block)
  init_bounding_box(block) do |parent_box|
    pt = map_to_absolute(pt)
    @bounding_box = BoundingBox.new(self, parent_box, pt, *args)
  end
end

#bounds ⇒ Object

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



409
410
411
 
# File 'lib/prawn/document.rb', line 409

def bounds
  @bounding_box
end

#bounds=(bounding_box) ⇒ Object

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.



424
425
426
 
# File 'lib/prawn/document.rb', line 424

def bounds=(bounding_box)
  @bounding_box = bounding_box
end

#canvas(&block) ⇒ Object

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



171
172
173
174
175
176
177
178
179
 
# File 'lib/prawn/document/bounding_box.rb', line 171

def canvas(&block)
  init_bounding_box(block, :hold_position => true) do |_|
    # Canvas bbox acts like margin_box in that its parent bounds are unset.
    @bounding_box = BoundingBox.new(self, nil, [0,page.dimensions[3]],
      :width => page.dimensions[2],
      :height => page.dimensions[3]
    )
  end
end

#cell(options = {}) ⇒ Object

Instantiates and draws a cell on the document.

cell(:content => "Hello world!", :at => [12, 34])

See Prawn::Table::Cell.make for full options.



19
20
21
22
23
 
# File 'lib/prawn/table/cell.rb', line 19

def cell(options={})
  cell = Table::Cell.make(self, options.delete(:content), options)
  cell.draw
  cell
end

#column_box(*args, &block) ⇒ Object

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”



27
28
29
30
31
32
 
# File 'lib/prawn/document/column_box.rb', line 27

def column_box(*args, &block)
  init_column_box(block) do |parent_box|
    map_to_absolute!(args[0])
    @bounding_box = ColumnBox.new(self, parent_box, *args)
  end
end

#compression_enabled? ⇒ Boolean

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

Returns:

  • (Boolean) 


642
643
644
 
# File 'lib/prawn/document.rb', line 642

def compression_enabled?
  !!state.compress
end

#cursor ⇒ Object

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



324
325
326
 
# File 'lib/prawn/document.rb', line 324

def cursor
  y - bounds.absolute_bottom
end

#define_grid(options = {}) ⇒ Object

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



8
9
10
 
# File 'lib/prawn/layout/grid.rb', line 8

def define_grid(options = {})
  @grid = Grid.new(self, options)
end

#find_font(name, options = {}) ⇒ Object

Looks up the given font using the given criteria. Once a font has been found by that matches the criteria, it will be cached to subsequent lookups for that font will return the same object. – Challenges involved: the name alone is not sufficient to uniquely identify a font (think dfont suitcases that can hold multiple different fonts in a single file). Thus, the :name key is included in the cache key.

It is further complicated, however, since fonts in some formats (like the dfont suitcases) can be identified either by numeric index, OR by their name within the suitcase, and both should hash to the same font object (to avoid the font being embedded multiple times). This is not yet implemented, which means if someone selects a font both by name, and by index, the font will be embedded twice. Since we do font subsetting, this double embedding won’t be catastrophic, just annoying. ++



138
139
140
141
142
143
144
145
146
147
148
 
# File 'lib/prawn/font.rb', line 138

def find_font(name, options={}) #:nodoc:
  if font_families.key?(name)
    family, name = name, font_families[name][options[:style] || :normal]
    if name.is_a?(::Hash)
      options = options.merge(name)
      name = options[:file]
    end
  end
  key = "#{name}:#{options[:font] || 0}"
  font_registry[key] ||= Font.load(self, name, options.merge(:family => family))
end

#float ⇒ Object

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"



347
348
349
350
351
352
353
 
# File 'lib/prawn/document.rb', line 347

def float
  original_page = page_number
  original_y = y
  yield
  go_to_page(original_page) unless page_number == original_page
  self.y = original_y
end

#font(name = nil, options = {}) ⇒ Object

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.



49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
 
# File 'lib/prawn/font.rb', line 49

def font(name=nil, options={})
  return((defined?(@font) && @font) || font("Helvetica")) if name.nil?

  if state.pages.empty? && !state.page.in_stamp_stream?
    raise Prawn::Errors::NotOnPage
  end

  new_font = find_font(name.to_s, 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 ⇒ Object

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.



181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
 
# File 'lib/prawn/font.rb', line 181

def font_families
  @font_families ||= {}.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_registry ⇒ Object

Hash of Font objects keyed by names



152
153
154
 
# File 'lib/prawn/font.rb', line 152

def font_registry #:nodoc:
  @font_registry ||= {}
end

#go_to_page(k) ⇒ Object

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.



309
310
311
312
313
314
 
# File 'lib/prawn/document.rb', line 309

def go_to_page(k)
  @page_number = k
  state.page = state.pages[k-1]
  generate_margin_box
  @y = @bounding_box.absolute_top
end

#grid(*args) ⇒ Object

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 box at [0,1]
@pdf.grid([0,1], [1,2])   # Get a multi-box spanning from [0,1] to [1,2]



19
20
21
22
23
24
25
26
27
28
29
30
31
32
 
# File 'lib/prawn/layout/grid.rb', line 19

def grid(*args)
  @boxes ||= {}
  @boxes[args] ||= if args.empty?
    @grid
  else
    g1, g2 = args
    if(g1.class == Array && g2.class == Array &&
      g1.length == 2 && g2.length == 2)
      multi_box(single_box(*g1), single_box(*g2))
    else
      single_box(g1, g2)
    end
  end
end

#group(second_attempt = false) ⇒ Object

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). Returns a logically true value if the content fits in one page/column, false if a new page or column was needed.

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



520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
 
# File 'lib/prawn/document.rb', line 520

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 }

  @bounding_box = old_bounding_box

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

  success
end

#indent(left, right = 0, &block) ⇒ Object

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



496
497
498
 
# File 'lib/prawn/document.rb', line 496

def indent(left, right = 0, &block)
  bounds.indent(left, right, &block)
end

#initialize_first_page(options) ⇒ Object 



232
233
234
235
236
237
238
 
# File 'lib/prawn/document.rb', line 232

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

#make_cell(content, options = {}) ⇒ Object

Set up, but do not draw, a cell. Useful for creating cells with formatting options to be inserted into a Table. Call draw on the resulting Cell to ink it.

See the documentation on Prawn::Cell for details on the arguments.



31
32
33
 
# File 'lib/prawn/table/cell.rb', line 31

def make_cell(content, options={})
  Prawn::Table::Cell.make(self, content, options)
end

#make_table(data, options = {}, &block) ⇒ Object

Set up, but do not draw, a table. Useful for creating subtables to be inserted into another Table. Call draw on the resulting Table to ink it.

See the documentation on Prawn::Table for details on the arguments.



38
39
40
 
# File 'lib/prawn/table.rb', line 38

def make_table(data, options={}, &block)
  Table.new(data, self, options, &block)
end

#mask(*fields) ⇒ Object

:nodoc:



501
502
503
504
505
506
507
508
509
 
# File 'lib/prawn/document.rb', line 501

def mask(*fields) # :nodoc:
 # Stores the current state of the named attributes, executes the block, and
 # then restores the original values after the block has executed.
 # -- I will remove the nodoc if/when this feature is a little less hacky
  stored = {}
  fields.each { |f| stored[f] = send(f) }
  yield
  fields.each { |f| send("#{f}=", stored[f]) }
end

#move_cursor_to(new_y) ⇒ Object

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



330
331
332
 
# File 'lib/prawn/document.rb', line 330

def move_cursor_to(new_y)
  self.y = new_y + bounds.absolute_bottom
end

#move_down(n) ⇒ Object

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



438
439
440
 
# File 'lib/prawn/document.rb', line 438

def move_down(n)
  self.y -= n
end

#move_up(n) ⇒ Object

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



431
432
433
 
# File 'lib/prawn/document.rb', line 431

def move_up(n)
  self.y += n
end

#number_pages(string, options = {}) ⇒ Object

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



576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
 
# File 'lib/prawn/document.rb', line 576

def number_pages(string, options={})
  opts = options.dup
  start_count_at = opts.delete(:start_count_at).to_i
  page_filter = if opts.has_key?(:page_filter)
    opts.delete(:page_filter)
  else
    :all
  end
  total_pages = opts.delete(:total_pages)
  txtcolor = opts.delete(:color)
  # An explicit height so that we can draw page numbers in the margins
  opts[:height] = 50 unless opts.has_key?(:height)

  start_count = false
  pseudopage = 0
  (1..page_count).each do |p|
    unless start_count
      pseudopage = case start_count_at
                   when 0
                     1
                   else
                     start_count_at.to_i
                   end
    end
    if page_match?(page_filter, p)
      go_to_page(p)
      # have to use fill_color here otherwise text reverts back to default fill color
      fill_color txtcolor unless txtcolor.nil?
      total_pages = total_pages.nil? ? page_count : total_pages
      str = string.gsub("<page>","#{pseudopage}").gsub("<total>","#{total_pages}")
      text_box str, opts
      start_count = true  # increment page count as soon as first match found
    end
    pseudopage += 1 if start_count
  end
end

#outline ⇒ Object

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



16
17
18
 
# File 'lib/prawn/outline.rb', line 16

def outline
  @outline ||= PDF::Core::Outline.new(self)
end

#pad(y) ⇒ Object

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"



477
478
479
480
481
 
# File 'lib/prawn/document.rb', line 477

def pad(y)
  move_down(y)
  yield
  move_down(y)
end

#pad_bottom(y) ⇒ Object

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"



463
464
465
466
 
# File 'lib/prawn/document.rb', line 463

def pad_bottom(y)
  yield
  move_down(y)
end

#pad_top(y) ⇒ Object

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"



450
451
452
453
 
# File 'lib/prawn/document.rb', line 450

def pad_top(y)
  move_down(y)
  yield
end

#page ⇒ Object 



228
229
230
 
# File 'lib/prawn/document.rb', line 228

def page
  state.page
end

#page_count ⇒ Object

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



300
301
302
 
# File 'lib/prawn/document.rb', line 300

def page_count
  state.page_count
end

#page_match?(page_filter, page_number) ⇒ Boolean

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

Returns:

  • (Boolean) 


623
624
625
626
627
628
629
630
631
632
633
634
635
636
 
# File 'lib/prawn/document.rb', line 623

def page_match?(page_filter, page_number)
  case page_filter
  when :all
    true
  when :odd
    page_number % 2 == 1
  when :even
    page_number % 2 == 0
  when Range, Array
    page_filter.include?(page_number)
  when Proc
    page_filter.call(page_number)
  end
end

#reference_bounds ⇒ Object

Returns the innermost non-stretchy bounding box.



415
416
417
 
# File 'lib/prawn/document.rb', line 415

def reference_bounds
  @bounding_box.reference_bounds
end

#render(output = StringIO.new) ⇒ Object

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



358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
 
# File 'lib/prawn/document.rb', line 358

def render(output = StringIO.new)
  finalize_all_page_contents

  render_header(output)
  render_body(output)
  render_xref(output)
  render_trailer(output)
  if output.instance_of?(StringIO)
    str = output.string
    str.force_encoding(::Encoding::ASCII_8BIT)
    return str
  else
    return nil
  end
end

#render_file(filename) ⇒ Object

Renders the PDF document to file.

pdf.render_file "foo.pdf"



378
379
380
 
# File 'lib/prawn/document.rb', line 378

def render_file(filename)
  File.open(filename, "wb") { |f| render(f) }
end

#repeat(page_filter, options = {}, &block) ⇒ Object

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



76
77
78
 
# File 'lib/prawn/repeater.rb', line 76

def repeat(page_filter, options={}, &block)
  repeaters << Prawn::Repeater.new(self, page_filter, !!options[:dynamic], &block)
end

#repeaters ⇒ Object

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



18
19
20
 
# File 'lib/prawn/repeater.rb', line 18

def repeaters
  @repeaters ||= []
end

#save_font ⇒ Object

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



112
113
114
115
116
117
118
119
120
 
# File 'lib/prawn/font.rb', line 112

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

#set_font(font, size = nil) ⇒ Object

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



104
105
106
107
 
# File 'lib/prawn/font.rb', line 104

def set_font(font, size=nil) # :nodoc:
  @font = font
  @font_size = size if size
end

#span(width, options = {}) ⇒ Object

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



27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
 
# File 'lib/prawn/document/span.rb', line 27

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

#start_new_page(options = {}) ⇒ Object

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)



250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
 
# File 'lib/prawn/document.rb', line 250

def start_new_page(options = {})
  if last_page = state.page
    last_page_size    = last_page.size
    last_page_layout  = last_page.layout
    last_page_margins = last_page.margins
  end

  page_options = {:size => options[:size] || last_page_size,
                  :layout  => options[:layout] || last_page_layout,
                  :margins => last_page_margins}
  if last_page
    new_graphic_state = last_page.graphic_state.dup  if last_page.graphic_state
    #erase the color space so that it gets reset on new page for fussy pdf-readers
    new_graphic_state.color_space = {} if new_graphic_state
    page_options.merge!(:graphic_state => new_graphic_state)
  end

  state.page = PDF::Core::Page.new(self, page_options)

  apply_margin_options(options)
  generate_margin_box

  # Reset the bounding box if the new page has different size or layout
  if last_page && (last_page.size != state.page.size ||
                   last_page.layout != state.page.layout)
    @bounding_box = @margin_box
  end

  use_graphic_settings

  unless options[:orphan]
    state.insert_page(state.page, @page_number)
    @page_number += 1

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

    float do
      state.on_page_create_action(self)
    end
  end
end

#state ⇒ Object 



224
225
226
 
# File 'lib/prawn/document.rb', line 224

def state
  @internal_state
end

#table(data, options = {}, &block) ⇒ Object

Set up and draw a table on this document. A block can be given, which will be run after cell setup but before layout and drawing.

See the documentation on Prawn::Table for details on the arguments.



27
28
29
30
31
 
# File 'lib/prawn/table.rb', line 27

def table(data, options={}, &block)
  t = Table.new(data, self, options, &block)
  t.draw
  t
end

#width_of(string, options = {}) ⇒ Object

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



219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
 
# File 'lib/prawn/font.rb', line 219

def width_of(string, options={})
  if p = options[:inline_format]
    p = [] unless p.is_a?(Array)

    # Build up an Arranger with the entire string on one line, finalize it,
    # and find its width.
    arranger = Prawn::Text::Formatted::Arranger.new(self, options)
    arranger.consumed = self.text_formatter.format(string, *p)
    arranger.finalize_line

    arranger.line_width
  else
    width_of_string(string, options)
  end
end