Class: Prawn::Document

Inherits:
Object
  • Object
show all
Includes:
Annotations, Destinations, Internals, PageGeometry, Text, Graphics, Images
Defined in:
lib/prawn/document.rb,
lib/prawn/font.rb,
lib/prawn/document/span.rb,
lib/prawn/document/text.rb,
lib/prawn/document/text/box.rb,
lib/prawn/document/internals.rb,
lib/prawn/document/column_box.rb,
lib/prawn/document/annotations.rb,
lib/prawn/document/bounding_box.rb,
lib/prawn/document/destinations.rb,
lib/prawn/document/page_geometry.rb,
lib/prawn/document/text/wrapping.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: Annotations, Destinations, Internals, PageGeometry, Text Classes: BoundingBox, ColumnBox

Constant Summary

Constants included from Graphics

Graphics::KAPPA

Constants included from Destinations

Destinations::NAME_TREE_CHILDREN_LIMIT

Constants included from PageGeometry

PageGeometry::SIZES

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Methods included from Images

#image

Methods included from Graphics

#circle_at, #curve, #curve_to, #ellipse_at, #fill, #fill_and_stroke, #horizontal_line, #horizontal_rule, #line, #line_to, #line_width, #line_width=, #move_to, #polygon, #rectangle, #stroke, #stroke_bounds, #vertical_line

Methods included from Graphics::Color

#fill_color, hex2rgb, #method_missing, rgb2hex, #stroke_color

Methods included from 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 Annotations

#annotate, #link_annotation, #text_annotation

Methods included from Internals

#add_content, #names, #page_fonts, #page_resources, #page_xobjects, #proc_set, #ref

Methods included from PageGeometry

#page_dimensions

Methods included from Text

#text, #text_options

Methods included from Text::Wrapping

#height_of, #naive_wrap

Constructor Details

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

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



129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
 
# File 'lib/prawn/document.rb', line 129

def initialize(options={},&block)   
  Prawn.verify_options [:page_size, :page_layout, :left_margin, 
    :right_margin, :top_margin, :bottom_margin, :skip_page_creation, 
    :compress, :skip_encoding, :text_options, :background, :info], options
 
  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
  @objects = []
  @info    = ref(options[:info])
  @pages   = ref(:Type => :Pages, :Count => 0, :Kids => [])
  @root    = ref(:Type => :Catalog, :Pages => @pages)
  @page_size       = options[:page_size]   || "LETTER"
  @page_layout     = options[:page_layout] || :portrait
  @compress        = options[:compress] || false
  @skip_encoding   = options[:skip_encoding]
  @background      = options[:background]
  @font_size       = 12

  text_options.update(options[:text_options] || {})

  @margins = { :left   => options[:left_margin]   || 36,
               :right  => options[:right_margin]  || 36,
               :top    => options[:top_margin]    || 36,
               :bottom => options[:bottom_margin] || 36  }

  generate_margin_box

  @bounding_box = @margin_box

  start_new_page unless options[:skip_page_creation]

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

Dynamic Method Handling

This class handles dynamic methods through the method_missing method in the class Prawn::Graphics::Color

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.



71
72
73
74
75
76
77
 
# File 'lib/prawn/font.rb', line 71

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.



62
63
64
 
# File 'lib/prawn/document.rb', line 62

def margin_box
  @margin_box
end

#margins ⇒ Object (readonly)

Returns the value of attribute margins.



63
64
65
 
# File 'lib/prawn/document.rb', line 63

def margins
  @margins
end

#page_layout ⇒ Object (readonly)

Returns the value of attribute page_layout.



63
64
65
 
# File 'lib/prawn/document.rb', line 63

def page_layout
  @page_layout
end

#page_size ⇒ Object (readonly)

Returns the value of attribute page_size.



63
64
65
 
# File 'lib/prawn/document.rb', line 63

def page_size
  @page_size
end

#y ⇒ Object

Returns the value of attribute y.



62
63
64
 
# File 'lib/prawn/document.rb', line 62

def y
  @y
end

Class Method Details

.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"
  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.text content, :at => [200,720], :size => 32
end



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

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

Instance Method Details

#bounding_box(*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, for the purposes

of simplifying coordinate math.

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 absolutle bottom left of the containing

box:

pdf.bounding_box([0,100], :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

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

By default, 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 boundng box, it will become stretchy and it’s height will be calculated according to the last drawing position within the bounding box:

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
    pdf.bounding_box([300,450], :width => 200, :height => 200) do
      # Positioned outside the containing box at the 'real' (300,450)
      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.



151
152
153
154
155
156
 
# File 'lib/prawn/document/bounding_box.rb', line 151

def bounding_box(*args, &block)    
  init_bounding_box(block) do |_|
    translate!(args[0])     
    @bounding_box = BoundingBox.new(self, *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



283
284
285
 
# File 'lib/prawn/document.rb', line 283

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 existing bounding box code blocks is good enough.



292
293
294
 
# File 'lib/prawn/document.rb', line 292

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



165
166
167
168
169
170
171
172
 
# File 'lib/prawn/document/bounding_box.rb', line 165

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) ⇒ 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.

Defaults are :columns = 3 and :spacer = font_size

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



23
24
25
26
27
28
 
# File 'lib/prawn/document/column_box.rb', line 23

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

#compression_enabled? ⇒ Boolean

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

Returns:

  • (Boolean) 


364
365
366
 
# File 'lib/prawn/document.rb', line 364

def compression_enabled?
  !!@compress
end

#cursor ⇒ Object

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



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

def cursor
  y - bounds.absolute_bottom
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. ++



115
116
117
118
119
120
121
122
123
124
125
126
127
 
# File 'lib/prawn/font.rb', line 115

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

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

Without arguments, this returns the currently selected font. Otherwise, it sets the current font.

The single 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.

pdf.font "Times-Roman"
pdf.font "Chalkboard.ttf"

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.

Raises:



30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
 
# File 'lib/prawn/font.rb', line 30

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

  raise Errors::NotOnPage unless @current_page
  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 ⇒ 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.



155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
 
# File 'lib/prawn/font.rb', line 155

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_registry ⇒ Object

Hash of Font objects keyed by names



131
132
133
 
# File 'lib/prawn/font.rb', line 131

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

#mask(*fields) ⇒ Object

:nodoc:



351
352
353
354
355
356
357
358
359
 
# File 'lib/prawn/document.rb', line 351

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_down(n) ⇒ Object

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



306
307
308
 
# File 'lib/prawn/document.rb', line 306

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.



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

def move_up(n)
  self.y += n
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"



345
346
347
348
349
 
# File 'lib/prawn/document.rb', line 345

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"



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

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"



318
319
320
321
 
# File 'lib/prawn/document.rb', line 318

def pad_top(y)
  move_down(y)
  yield
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



213
214
215
 
# File 'lib/prawn/document.rb', line 213

def page_count
  @pages.data[:Count]
end

#render ⇒ Object

Renders the PDF document to string, useful for example in a Rails application where you want to stream out the PDF to a web browser:

def show
  pdf = Prawn::Document.new do
    text "Putting PDF generation code in a controller is _BAD_"
  end
  send(pdf.render, :filename => 'silly.pdf', :type => 'application/pdf', :disposition => 'inline)
end



234
235
236
237
238
239
240
241
242
243
244
245
 
# File 'lib/prawn/document.rb', line 234

def render
  output = StringIO.new
  finish_page_content

  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) ⇒ Object

Renders the PDF document to file.

pdf.render_file "foo.pdf"



251
252
253
254
 
# File 'lib/prawn/document.rb', line 251

def render_file(filename)
  Kernel.const_defined?("Encoding") ? mode = "wb:ASCII-8BIT" : mode = "wb"
  File.open(filename,mode) { |f| f << render }
end

#save_font ⇒ Object

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



88
89
90
91
92
93
94
95
96
 
# File 'lib/prawn/font.rb', line 88

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.



81
82
83
84
 
# File 'lib/prawn/font.rb', line 81

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: How many effing times do I want to write this same code?
  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)



183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
 
# File 'lib/prawn/document.rb', line 183

def start_new_page(options = {})
   @page_size   = options[:size] if options[:size]
   @page_layout = options[:layout] if options[:layout]

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

   finish_page_content if @page_content
   build_new_page_content

   @pages.data[:Kids] << @current_page
   @pages.data[:Count] += 1

   add_content "q"

   @y = @bounding_box.absolute_top

   image(@background, :at => [0,@y]) if @background
end

#text_box(text, options) ⇒ Object

Defines an invisible rectangle which you can flow text in. When the text overflows the box, you can either display :ellipses, :truncate the text, or allow it to overflow the bottom boundary with :expand.

text_box "Oh hai text box. " * 200, 
  :width    => 300, :height => font.height * 5,
  :overflow => :ellipses, 
  :at       => [100,bounds.top]



21
22
23
 
# File 'lib/prawn/document/text/box.rb', line 21

def text_box(text,options)
  Text::Box.new(text, options.merge(:for => self)).render
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. ++



193
194
195
 
# File 'lib/prawn/font.rb', line 193

def width_of(string, options={})
  font.compute_width_of(string, options)
end