Class: Prawn::Document
- Inherits:
-
Object
- Object
- Prawn::Document
- Includes:
- Annotations, Destinations, Internals, PageGeometry, Text, Graphics, Images
- Defined in:
- lib/prawn/font.rb,
lib/prawn/document.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/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
Defined Under Namespace
Modules: Annotations, Destinations, Internals, PageGeometry, Text Classes: BoundingBox
Constant Summary
Constants included from Graphics
Constants included from Destinations
Destinations::NAME_TREE_CHILDREN_LIMIT
Constants included from PageGeometry
Instance Attribute Summary collapse
-
#font_size(points = nil) ⇒ Object
When called with no argument, returns the current font size.
-
#margin_box ⇒ Object
Returns the value of attribute margin_box.
-
#margins ⇒ Object
readonly
Returns the value of attribute margins.
-
#page_layout ⇒ Object
readonly
Returns the value of attribute page_layout.
-
#page_size ⇒ Object
readonly
Returns the value of attribute page_size.
-
#y ⇒ Object
Returns the value of attribute y.
Class Method Summary collapse
-
.generate(filename, options = {}, &block) ⇒ Object
Creates and renders a PDF document.
Instance Method Summary collapse
-
#bounding_box(*args, &block) ⇒ Object
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.
-
#bounds ⇒ Object
Returns the current BoundingBox object, which is by default the box represented by the margin box.
-
#bounds=(bounding_box) ⇒ Object
Sets Document#bounds to the BoundingBox provided.
-
#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.
-
#compression_enabled? ⇒ Boolean
Returns true if content streams will be compressed before rendering, false otherwise.
-
#cursor ⇒ Object
The current y drawing position relative to the innermost bounding box, or to the page margins at the top level.
-
#find_font(name, options = {}) ⇒ Object
Looks up the given font using the given criteria.
-
#font(name = nil, options = {}) ⇒ Object
Without arguments, this returns the currently selected font.
-
#font_families ⇒ Object
Hash that maps font family names to their styled individual font names.
-
#font_registry ⇒ Object
Hash of Font objects keyed by names.
-
#initialize(options = {}, &block) ⇒ Document
constructor
Creates a new PDF Document.
-
#mask(*fields) ⇒ Object
:nodoc:.
-
#move_down(n) ⇒ Object
Moves down the document by n point.
-
#move_up(n) ⇒ Object
Moves up the document by n points.
-
#pad(y) ⇒ Object
Moves down the document by y, executes a block, then moves down the document by y again.
-
#pad_bottom(y) ⇒ Object
Executes a block then moves down the document.
-
#pad_top(y) ⇒ Object
Moves down the document and then executes a block.
-
#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.
-
#render ⇒ Object
Renders the PDF document to string.
-
#render_file(filename) ⇒ Object
Renders the PDF document to file.
-
#save_font ⇒ Object
Saves the current font, and then yields.
-
#set_font(font, size = nil) ⇒ Object
Sets the font directly, given an actual Font object and size.
-
#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.
-
#start_new_page(options = {}) ⇒ Object
Creates and advances to a new page in the document.
-
#text_box(text, options) ⇒ Object
Defines an invisible rectangle which you can flow text in.
-
#width_of(string, options = {}) ⇒ Object
Returns the width of the given string using the given font.
Methods included from Images
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
Methods included from Text
Methods included from Text::Wrapping
Constructor Details
#initialize(options = {}, &block) ⇒ Document
Creates a new PDF Document. The following options are available:
:page_size
-
One of the Document::PageGeometry::SIZES [LETTER]
:page_layout
-
Either
:portrait
or:landscape
: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]
:background
-
An image path to be used as background on all pages [nil]
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, with background
pdf = Prawn::Document.new(:background => "#{Prawn::BASEDIR}/data/images/pigs.jpg")
85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 |
# File 'lib/prawn/document.rb', line 85 def initialize(={},&block) Prawn. [:page_size, :page_layout, :left_margin, :right_margin, :top_margin, :bottom_margin, :skip_page_creation, :compress, :skip_encoding, :text_options, :background ], @objects = [] @info = ref(:Creator => "Prawn", :Producer => "Prawn") @pages = ref(:Type => :Pages, :Count => 0, :Kids => []) @root = ref(:Type => :Catalog, :Pages => @pages) @page_size = [:page_size] || "LETTER" @page_layout = [:page_layout] || :portrait @compress = [:compress] || false @skip_encoding = [:skip_encoding] @background = [:background] @font_size = 12 .update([:text_options] || {}) @margins = { :left => [:left_margin] || 36, :right => [:right_margin] || 36, :top => [:top_margin] || 36, :bottom => [:bottom_margin] || 36 } generate_margin_box @bounding_box = @margin_box start_new_page unless [: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.
29 30 31 |
# File 'lib/prawn/document.rb', line 29 def margin_box @margin_box end |
#margins ⇒ Object (readonly)
Returns the value of attribute margins.
30 31 32 |
# File 'lib/prawn/document.rb', line 30 def margins @margins end |
#page_layout ⇒ Object (readonly)
Returns the value of attribute page_layout.
30 31 32 |
# File 'lib/prawn/document.rb', line 30 def page_layout @page_layout end |
#page_size ⇒ Object (readonly)
Returns the value of attribute page_size.
30 31 32 |
# File 'lib/prawn/document.rb', line 30 def page_size @page_size end |
#y ⇒ Object
Returns the value of attribute y.
29 30 31 |
# File 'lib/prawn/document.rb', line 29 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 "foo.pdf" do
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 "foo.pdf" do |pdf|
pdf.font "Times-Roman"
pdf.text content, :at => [200,720], :size => 32
end
57 58 59 60 |
# File 'lib/prawn/document.rb', line 57 def self.generate(filename,={},&block) pdf = new(,&block) pdf.render_file(filename) end |
Instance Method Details
#bounding_box(*args, &block) ⇒ Object
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.
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.
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
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.polygon [0,250], [0,0], [150,100]
pdf.polygon [100,0], [150,100], [200,0]
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.
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
pdf.bouding_box(, :width => 200, :height => 250) do
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.
end
end
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.canvas do
pdf.bounding_box([200,450], :width => 200, :height => 250) do
# positioned at 'real' (200,450)
end
end
Of course, if you use canvas, you will be responsible for ensuring that you remain within the printable area of your document.
91 92 93 94 95 96 |
# File 'lib/prawn/document/bounding_box.rb', line 91 def bounding_box(*args, &block) init_bounding_box(block) do |_| translate!(args[0]) @bounding_box = BoundingBox.new(self, *args) end end |
#bounds ⇒ Object
Returns the current BoundingBox object, which is by default the box represented by the margin box. When called from within a bounding_box
block, the box defined by that call will be used.
197 198 199 |
# File 'lib/prawn/document.rb', line 197 def bounds @bounding_box end |
#bounds=(bounding_box) ⇒ Object
Sets Document#bounds to the BoundingBox provided. If you don’t know why you’d need to do this, chances are, you can ignore this feature
204 205 206 |
# File 'lib/prawn/document.rb', line 204 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
105 106 107 108 109 110 111 112 |
# File 'lib/prawn/document/bounding_box.rb', line 105 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 |
#compression_enabled? ⇒ Boolean
Returns true if content streams will be compressed before rendering, false otherwise
274 275 276 |
# File 'lib/prawn/document.rb', line 274 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.
164 165 166 |
# File 'lib/prawn/document.rb', line 164 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, ={}) #:nodoc: if font_families.key?(name) family, name = name, font_families[name][[:style] || :normal] if name.is_a?(Hash) = .merge(name) name = [:file] end end key = "#{name}:#{[:font] || 0}" font_registry[key] ||= Font.load(self, name, .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.
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, ={}) return @font || font("Helvetica") if name.nil? raise Errors::NotOnPage unless @current_page new_font = find_font(name, ) if block_given? save_font do set_font(new_font, [:size]) yield end else set_font(new_font, [: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:
261 262 263 264 265 266 267 268 269 |
# File 'lib/prawn/document.rb', line 261 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 point
216 217 218 |
# File 'lib/prawn/document.rb', line 216 def move_down(n) self.y -= n end |
#move_up(n) ⇒ Object
Moves up the document by n points
210 211 212 |
# File 'lib/prawn/document.rb', line 210 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"
255 256 257 258 259 |
# File 'lib/prawn/document.rb', line 255 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"
241 242 243 244 |
# File 'lib/prawn/document.rb', line 241 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"
228 229 230 231 |
# File 'lib/prawn/document.rb', line 228 def pad_top(y) move_down(y) yield end |
#page_count ⇒ Object
157 158 159 |
# File 'lib/prawn/document.rb', line 157 def page_count @pages.data[:Count] end |
#render ⇒ Object
Renders the PDF document to string
170 171 172 173 174 175 176 177 178 179 180 181 |
# File 'lib/prawn/document.rb', line 170 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"
187 188 189 190 |
# File 'lib/prawn/document.rb', line 187 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, ={}) Prawn. [:position], original_position = self.y # FIXME: How many effing times do I want to write this same code? left_boundary = case([: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 + [: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(:size => "LEGAL", :layout => :landscape)
pdf.start_new_page(:left_margin => 50, :right_margin => 50)
127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 |
# File 'lib/prawn/document.rb', line 127 def start_new_page( = {}) @page_size = [:size] if [:size] @page_layout = [:layout] if [:layout] [:left,:right,:top,:bottom].each do |side| if [:"#{side}_margin"] @margins[side] = [:"#{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.
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,) Text::Box.new(text, .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, ={}) font.compute_width_of(string, ) end |