prawn 0.11.1 → 0.15.0

data/manual/table/position.rb

@@ -0,0 +1,29 @@
+# encoding: utf-8
+#
+# The <code>table()</code> method accepts a <code>:position</code> argument to
+# determine horizontal position of the table within its bounding box. It can be
+# <code>:left</code> (the default), <code>:center</code>, <code>:right</code>,
+# or a number specifying a distance in PDF points from the left side.
+#
+require File.expand_path(File.join(File.dirname(__FILE__),
+                                   %w[.. example_helper]))
+
+filename = File.basename(__FILE__).gsub('.rb', '.pdf')
+Prawn::Example.generate(filename) do
+  data = [["The quick brown fox jumped over the lazy dogs."]] * 2
+
+  text "Left:"
+  table data, :position => :left
+  move_down 10
+
+  text "Center:"
+  table data, :position => :center
+  move_down 10
+
+  text "Right:"
+  table data, :position => :right
+  move_down 10
+
+  text "100pt:"
+  table data, :position => 100
+end

data/manual/table/row_colors.rb

@@ -0,0 +1,20 @@
+# encoding: utf-8
+#
+# One of the most common table styling techniques is to stripe the rows with
+# alternating colors.
+#
+# There is one helper just for that. Just provide the <code>:row_colors</code>
+# option an array with color values.
+#
+require File.expand_path(File.join(File.dirname(__FILE__),
+                                   %w[.. example_helper]))
+
+filename = File.basename(__FILE__).gsub('.rb', '.pdf')
+Prawn::Example.generate(filename) do
+  data = [["This row should have one color"],
+          ["And this row should have another"]]
+  
+  data += [["..."]] * 10
+  
+  table(data, :row_colors => ["F0F0F0", "FFFFCC"])
+end

data/manual/table/span.rb

@@ -0,0 +1,30 @@
+# encoding: utf-8
+#
+# Table cells can span multiple columns, rows, or both. When building a cell,
+# use the hash argument constructor with a <code>:colspan</code> and/or
+# <code>:rowspan</code> argument. Row or column spanning must be specified when
+# building the data array; you can't set the span in the table's initialization
+# block. This is because cells are laid out in the grid before that block is
+# called, so that references to row and column numbers make sense.
+#
+# Cells are laid out in the order given, skipping any positions spanned by
+# previously instantiated cells. Therefore, a cell with <code>rowspan: 2</code>
+# will be missing at least one cell in the row below it. See the code and table
+# below for an example.
+#
+# It is illegal to overlap cells via spanning. A
+# <code>Prawn::Errors::InvalidTableSpan</code> error will be raised if spans
+# would cause cells to overlap.
+#
+require File.expand_path(File.join(File.dirname(__FILE__),
+                                   %w[.. example_helper]))
+
+filename = File.basename(__FILE__).gsub('.rb', '.pdf')
+Prawn::Example.generate(filename) do
+  table([
+    ["A", {:content => "2x1", :colspan => 2}, "B"],
+    [{:content => "1x2", :rowspan => 2}, "C", "D", "E"],
+    [{:content => "2x2", :colspan => 2, :rowspan => 2}, "F"],
+    ["G", "H"]
+  ])
+end

data/manual/table/style.rb

@@ -0,0 +1,22 @@
+# encoding: utf-8
+#
+# We've seen how to apply styles to a selection of cells by setting the
+# individual properties. Another option is to use the <code>style</code> method
+#
+# <code>style</code> lets us define multiple properties at once with a hash. It
+# also accepts a block that will be called for each cell and can be used for
+# some complex styling.
+#
+require File.expand_path(File.join(File.dirname(__FILE__),
+                                   %w[.. example_helper]))
+
+filename = File.basename(__FILE__).gsub('.rb', '.pdf')
+Prawn::Example.generate(filename) do
+  table([[""] * 8] * 8) do
+    cells.style(:width => 24, :height => 24)
+    
+    cells.style do |c| 
+      c.background_color = ((c.row + c.column) % 2).zero? ? '000000' : 'ffffff'
+    end
+  end
+end

data/manual/table/table.rb

@@ -0,0 +1,52 @@
+# encoding: utf-8
+#
+# Examples for tables.
+#
+require File.expand_path(File.join(File.dirname(__FILE__),
+                                   %w[.. example_helper]))
+
+Prawn::Example.generate("table.pdf", :page_size => "FOLIO") do
+  
+  package "table" do |p|
+    
+    p.section "Basics" do |s|
+      s.example "creation"
+      s.example "content_and_subtables"
+      s.example "flow_and_header"
+      s.example "position"
+    end
+    
+    p.section "Styling" do |s|
+      s.example "column_widths"
+      s.example "width"
+      s.example "row_colors"
+      s.example "cell_dimensions"
+      s.example "cell_borders_and_bg"
+      s.example "cell_border_lines"
+      s.example "cell_text"
+      s.example "image_cells"
+      s.example "span"
+      s.example "before_rendering_page"
+    end
+    
+    p.section "Initializer Block" do |s|
+      s.example "basic_block"
+      s.example "filtering"
+      s.example "style"
+    end
+    
+    p.intro do
+      prose("Prawn comes with table support out of the box. Tables can be styled in whatever way you see fit. The whole table, rows, columns and cells can be styled independently from each other.
+
+      The examples show:")
+
+      list( "How to create tables",
+            "What content can be placed on tables",
+            "Subtables (or tables within tables)",
+            "How to style the whole table",
+            "How to use initializer blocks to style only specific portions of the table"
+          )
+    end
+    
+  end
+end

data/manual/table/width.rb

@@ -0,0 +1,27 @@
+# encoding: utf-8
+#
+# The default table width depends on the content provided. It will expand up
+# to the current bounding box width to fit the content. If you want the table to
+# have a fixed width no matter the content you may use the <code>:width</code>
+# option to manually set the width.
+#
+require File.expand_path(File.join(File.dirname(__FILE__),
+                                   %w[.. example_helper]))
+
+filename = File.basename(__FILE__).gsub('.rb', '.pdf')
+Prawn::Example.generate(filename) do
+  text "Normal width:"
+  table [%w[A B C]]
+  move_down 20
+  
+  text "Fixed width:"
+  table([%w[A B C]], :width => 300)
+  move_down 20
+
+  text "Normal width:"
+  table([["A", "Blah " * 20, "C"]])
+  move_down 20
+  
+  text "Fixed width:"
+  table([["A", "Blah " * 20, "C"]], :width => 300)
+end

data/manual/text/alignment.rb

@@ -0,0 +1,44 @@
+# encoding: utf-8
+#
+# Horizontal text alignment can be achieved by supplying the <code>:align</code>
+# option to the text methods. Available options are <code>:left</code>
+# (default), <code>:right</code>, <code>:center</code>, and
+# <code>:justify</code>.
+#
+# Vertical text alignment can be achieved using the <code>:valign</code> option
+# with the text methods. Available options are <code>:top</code> (default),
+# <code>:center</code>, and <code>:bottom</code>.
+#
+# Both forms of alignment will be evaluated in the context of the current
+# bounding_box.
+#
+require File.expand_path(File.join(File.dirname(__FILE__),
+                                   %w[.. example_helper]))
+
+filename = File.basename(__FILE__).gsub('.rb', '.pdf')
+Prawn::Example.generate(filename) do
+  text "This text should be left aligned"
+  text "This text should be centered",      :align => :center
+  text "This text should be right aligned", :align => :right
+
+  bounding_box([0, 220], :width => 250, :height => 220) do
+    text "This text is flowing from the left. "   * 4
+
+    move_down 15
+    text "This text is flowing from the center. " * 3, :align => :center
+
+    move_down 15
+    text "This text is flowing from the right. "  * 4, :align => :right
+
+    move_down 15
+    text "This text is justified. "  * 6, :align => :justify
+    transparent(0.5) { stroke_bounds }
+  end
+
+  bounding_box([300, 220], :width => 250, :height => 220) do
+    text "This text should be vertically top aligned"
+    text "This text should be vertically centered",       :valign => :center
+    text "This text should be vertically bottom aligned", :valign => :bottom
+    transparent(0.5) { stroke_bounds }
+  end
+end

data/manual/text/color.rb

@@ -0,0 +1,24 @@
+# encoding: utf-8
+#
+# The <code>:color</code> attribute can give a block of text a default color,
+# in RGB hex format or 4-value CMYK.
+#
+require File.expand_path(File.join(File.dirname(__FILE__),
+                                   %w[.. example_helper]))
+
+filename = File.basename(__FILE__).gsub('.rb', '.pdf')
+Prawn::Example.generate(filename) do
+  text "Default color is black"
+  move_down 25
+
+  text "Changed to red", :color => "FF0000"
+  move_down 25
+
+  text "CMYK color", :color => [22, 55, 79, 30]
+  move_down 25
+
+  text "Also works with <color rgb='ff0000'>inline</color> formatting",
+       :color => "0000FF",
+       :inline_format => true
+end
+

data/manual/text/column_box.rb

@@ -0,0 +1,32 @@
+# encoding: utf-8
+#
+# The <code>column_box</code> method allows you to define columns that flow
+# their contents from one section to the next. You can have a number of columns
+# on the page, and only when the last column overflows will a new page be
+# created.
+#
+require File.expand_path(File.join(File.dirname(__FILE__),
+                                   %w[.. example_helper]))
+
+filename = File.basename(__FILE__).gsub('.rb', '.pdf')
+Prawn::Example.generate(filename) do
+  text "The Prince",          :align => :center, :size => 18
+  text "Niccolò Machiavelli", :align => :center, :size => 14
+  move_down 12
+
+  column_box([0, cursor], :columns => 2, :width => bounds.width) do
+    text((<<-END.gsub(/\s+/, ' ') + "\n\n") * 3)
+      All the States and Governments by which men are or ever have been ruled,
+      have been and are either Republics or Princedoms. Princedoms are either
+      hereditary, in which the sovereignty is derived through an ancient line
+      of ancestors, or they are new. New Princedoms are either wholly new, as
+      that of Milan to Francesco Sforza; or they are like limbs joined on to
+      the hereditary possessions of the Prince who acquires them, as the
+      Kingdom of Naples to the dominions of the King of Spain. The States thus
+      acquired have either been used to live under a Prince or have been free;
+      and he who acquires them does so either by his own arms or by the arms of
+      others, and either by good fortune or by merit.
+    END
+  end
+end
+

data/manual/text/fallback_fonts.rb

@@ -0,0 +1,37 @@
+# encoding: utf-8
+#
+# Prawn enables the declaration of fallback fonts for those glyphs that may not
+# be present in the desired font. Use the <code>:fallback_fonts</code> option
+# with any of the text or text box methods, or set fallback_fonts document-wide.
+#
+require File.expand_path(File.join(File.dirname(__FILE__),
+                                   %w[.. example_helper]))
+
+filename = File.basename(__FILE__).gsub('.rb', '.pdf')
+Prawn::Example.generate(filename) do
+  file = "#{Prawn::DATADIR}/fonts/gkai00mp.ttf"
+  font_families["Kai"] = {
+    :normal => { :file => file, :font => "Kai" }
+  }
+  
+  file = "#{Prawn::DATADIR}/fonts/Action Man.dfont"
+  font_families["Action Man"] = {
+    :normal => { :file => file, :font => "ActionMan" },
+  }
+  
+  font("Action Man") do
+    text("When fallback fonts are included, each glyph will be rendered " +
+         "using the first font that includes the glyph, starting with the " +
+         "current font and then moving through the fallback fonts from left " +
+         "to right." +
+         "\n\n" +
+         "hello ƒ 你好\n再见 ƒ goodbye",
+         :fallback_fonts => ["Times-Roman", "Kai"])
+  end
+  move_down 20
+
+  formatted_text([ { :text => "Fallback fonts can even override" },
+                   { :text => "fragment fonts (你好)", :font => "Times-Roman" },
+                 ],
+                 :fallback_fonts => ["Times-Roman", "Kai"])
+end

data/manual/text/font.rb

@@ -0,0 +1,41 @@
+# encoding: utf-8
+# 
+# The <code>font</code> method can be used in three different ways.
+#
+# If we don't pass it any arguments it will return the current font being used
+# to render text.
+#
+# If we just pass it a font name it will use that font for rendering text
+# through the rest of the document.
+#
+# It can also be used by passing a font name and a block. In this case the
+# specified font will only be used to render text inside the block.
+#
+# The default font is Helvetica.
+#
+require File.expand_path(File.join(File.dirname(__FILE__),
+                                   %w[.. example_helper]))
+
+filename = File.basename(__FILE__).gsub('.rb', '.pdf')
+Prawn::Example.generate(filename) do
+  text "Let's see which font we are using: #{font.inspect}"
+  
+  move_down 20
+  font "Times-Roman"
+  text "Written in Times."
+  
+  move_down 20
+  font("Courier") do
+    text "Written in Courier because we are inside the block."
+  end
+  
+  move_down 20
+  text "Written in Times again as we left the previous block."
+  
+  move_down 20
+  text "Let's see which font we are using again: #{font.inspect}"
+  
+  move_down 20
+  font "Helvetica"
+  text "Back to normal."
+end

data/manual/text/font_size.rb

@@ -0,0 +1,45 @@
+# encoding: utf-8
+# 
+# The <code>font_size</code> method works just like the <code>font</code>
+# method.
+#
+# In fact we can even use <code>font</code> with the <code>:size</code> option
+# to declare which size we want.
+#
+# Another way to change the font size is by supplying the <code>:size</code>
+# option to the text methods.
+#
+# The default font size is <code>12</code>.
+#
+require File.expand_path(File.join(File.dirname(__FILE__),
+                                   %w[.. example_helper]))
+
+filename = File.basename(__FILE__).gsub('.rb', '.pdf')
+Prawn::Example.generate(filename) do
+  text "Let's see which is the current font_size: #{font_size.inspect}"
+  
+  move_down 10
+  font_size 16
+  text "Yeah, something bigger!"
+  
+  move_down 10
+  font_size(25) { text "Even bigger!" }
+  
+  move_down 10
+  text "Back to 16 again."
+  
+  move_down 10
+  text "Single line on 20 using the :size option.", :size => 20
+  
+  move_down 10
+  text "Back to 16 once more."
+  
+  move_down 10
+  font("Courier", :size => 10) do
+    text "Yeah, using Courier 10 courtesy of the font method."
+  end
+  
+  move_down 10
+  font("Helvetica", :size => 12)
+  text "Back to normal"
+end

data/manual/text/font_style.rb

@@ -0,0 +1,23 @@
+# encoding: utf-8
+# 
+# Most font families come with some styles other than normal. Most common are
+# <code>bold</code>, <code>italic</code> and <code>bold_italic</code>.
+#
+# The style can be set the using the <code>:style</code> option, with either the
+# <code>font</code> method which will set the font and style for rest of the
+# document, or with the inline text methods.
+#
+require File.expand_path(File.join(File.dirname(__FILE__),
+                                   %w[.. example_helper]))
+
+filename = File.basename(__FILE__).gsub('.rb', '.pdf')
+Prawn::Example.generate(filename) do
+  ["Courier", "Helvetica", "Times-Roman"].each do |example_font|
+    move_down 20
+    
+    [:bold, :bold_italic, :italic, :normal].each do |style|
+      font example_font, :style => style
+      text "I'm writing in #{example_font} (#{style})"
+    end
+  end
+end

data/manual/text/formatted_callbacks.rb

@@ -0,0 +1,60 @@
+# encoding: utf-8
+#
+# The <code>:callback</code> option is also available for the formatted text
+# methods.
+#
+# This option accepts an object (or array of objects) on which two methods
+# will be called if defined: <code>render_behind</code> and
+# <code>render_in_front</code>. They are called before and after rendering the
+# text fragment and are passed the fragment as an argument.
+#
+# This example defines two new callback classes and provide callback objects
+# for the formatted_text
+#
+require File.expand_path(File.join(File.dirname(__FILE__),
+                                   %w[.. example_helper]))
+
+filename = File.basename(__FILE__).gsub('.rb', '.pdf')
+Prawn::Example.generate(filename) do
+  class HighlightCallback
+    def initialize(options)
+      @color    = options[:color]
+      @document = options[:document]
+    end
+
+    def render_behind(fragment)
+      original_color       = @document.fill_color
+      @document.fill_color = @color
+      @document.fill_rectangle(fragment.top_left, fragment.width,
+                                                  fragment.height)
+      @document.fill_color = original_color
+    end
+  end
+
+  class ConnectedBorderCallback
+    def initialize(options)
+      @radius   = options[:radius]
+      @document = options[:document]
+    end
+
+    def render_in_front(fragment)
+      @document.stroke_polygon(fragment.top_left, fragment.top_right,
+                               fragment.bottom_right, fragment.bottom_left)
+      
+      @document.fill_circle(fragment.top_left,     @radius)
+      @document.fill_circle(fragment.top_right,    @radius)
+      @document.fill_circle(fragment.bottom_right, @radius)
+      @document.fill_circle(fragment.bottom_left,  @radius)
+    end
+  end
+
+  highlight = HighlightCallback.new(:color => 'ffff00', :document => self)
+  border    = ConnectedBorderCallback.new(:radius => 2.5, :document => self)
+  
+  formatted_text [ { :text => "hello", :callback => highlight },
+                   { :text => "     " },
+                   { :text => "world", :callback => border },
+                   { :text => "     " },
+                   { :text => "hello world", :callback => [highlight, border] }
+                 ], :size => 20
+end

data/manual/text/formatted_text.rb

@@ -0,0 +1,54 @@
+# encoding: utf-8
+#
+# There are two other text methods available: <code>formatted_text</code> and
+# <code>formatted_text_box</code>.
+#
+# These are useful when the provided text has numerous portions that need to be
+# formatted differently. As you might imply from their names the first should
+# be used for free flowing text just like the <code>text</code> method and the
+# last should be used for positioned text just like <code>text_box</code>.
+#
+# The main difference between these methods and the <code>text</code> and
+# <code>text_box</code> methods is how the text is provided. The
+# <code>formatted_text</code> and <code>formatted_text_box</code> methods accept
+# an array of hashes. Each hash must provide a <code>:text</code> option which
+# is the text string and may provide the following options: <code>:styles</code>
+# (an array of symbols), <code>:size</code> (the font size),
+# <code>:character_spacing</code> (additional space between the characters),
+# <code>:font</code> (the name of a registered font), <code>:color</code> (the
+# same input accepted by <code>fill_color</code> and <code>stroke_color</code>),
+# <code>:link</code> (an URL to create a link), <code>:anchor</code> (a
+# destination inside the document), and <code>:local</code> (a link to a local
+# file).
+#
+require File.expand_path(File.join(File.dirname(__FILE__),
+                                   %w[.. example_helper]))
+
+filename = File.basename(__FILE__).gsub('.rb', '.pdf')
+Prawn::Example.generate(filename) do
+  formatted_text [ { :text => "Some bold. ",      :styles => [:bold] },
+                   { :text => "Some italic. ",    :styles => [:italic] },
+                   { :text => "Bold italic. ",    :styles => [:bold, :italic] },
+                   { :text => "Bigger Text. ",    :size  => 20 },
+                   { :text => "More spacing. ",   :character_spacing => 3 },
+                   { :text => "Different Font. ", :font => "Courier" },
+                   { :text => "Some coloring. ",  :color => "FF00FF" },
+                   { :text => "Link to the wiki. ",
+                     :color => "0000FF",
+                     :link => "https://github.com/prawnpdf/prawn/wiki" },
+                   { :text => "Link to the Text Reference. "  ,
+                     :color => "0000FF",
+                     :anchor => "Text Reference" },
+                   { :text => "Link to a local file. ",
+                     :color => "0000FF",
+                     :local => "./local_file.txt" }
+                 ]
+  
+  formatted_text_box [ { :text => "Just your regular" },
+                       { :text => " text_box ", :font => "Courier" },
+                       { :text => "with some additional formatting options " +
+                                  "added to the mix.",
+                         :color => [50, 100, 0, 0],
+                         :styles => [:italic] }
+                     ], :at => [100, 100], :width => 200, :height => 100
+end

data/manual/text/free_flowing_text.rb

@@ -0,0 +1,51 @@
+# encoding: utf-8
+#
+# Text rendering can be as simple or as complex as you want.
+#
+# This example covers the most basic method: <code>text</code>. It is meant for
+# free flowing text. The provided string will flow according to the current
+# bounding box width and height. It will also flow onto the next page if the
+# bottom of the bounding box is reached.
+#
+# The text will start being rendered on the current cursor position. When it
+# finishes rendering, the cursor is left directly below the text.
+#
+# This example also shows text flowing across pages following the margin box and
+# other bounding boxes.
+#
+require File.expand_path(File.join(File.dirname(__FILE__),
+                                   %w[.. example_helper]))
+
+filename = File.basename(__FILE__).gsub('.rb', '.pdf')
+Prawn::Example.generate(filename) do
+  move_cursor_to 50
+  text "This text will flow to the next page. " * 20
+  
+  y_position = cursor - 50
+  bounding_box([0, y_position], :width => 200, :height => 150) do
+    transparent(0.5) { stroke_bounds }
+    text "This text will flow along this bounding box we created for it. " * 5
+  end
+  
+  bounding_box([300, y_position], :width => 200, :height => 150) do
+    transparent(0.5) { stroke_bounds }  # This will stroke on one page
+    
+    text "Now look what happens when the free flowing text reaches the end " +
+         "of a bounding box that is narrower than the margin box." +
+         " . " * 200 +
+         "It continues on the next page as if the previous bounding box " +
+         "was cloned. If we want it to have the same border as the one on " +
+         "the previous page we will need to stroke the boundaries again."
+    
+    transparent(0.5) { stroke_bounds }  # And this will stroke on the next
+  end
+  
+  move_cursor_to 200
+  span(350, :position => :center) do
+    text "Span is a different kind of bounding box as it lets the text " +
+         "flow gracefully onto the next page. It doesn't matter if the text " +
+         "started on the middle of the previous page, when it flows to the " +
+         "next page it will start at the beginning." + " _ " * 500 +
+         "I told you it would start on the beginning of this page."
+  end
+end

data/manual/text/group.rb

@@ -0,0 +1,31 @@
+# encoding: utf-8
+#
+# <strong>NOTE: This feature is currently not working correctly</strong>
+#
+# Sometimes free flowing text might look ugly, specially when a paragraph is
+# split between two pages. Using a positioned text box just to overcome this
+# nuisance is not the right choice.
+#
+# You probably want to use the <code>group</code> method instead. It will try
+# to render the block within the current page. If the content would fall to a
+# new page it just renders everything on the following page. If the block cannot
+# be executed on a single blank page a <code>CannotGroup</code> exception will
+# be raised.
+#
+# So if you can split your text blocks in paragraphs you can have every
+# paragraph contained on a single page.
+#
+require File.expand_path(File.join(File.dirname(__FILE__),
+                                   %w[.. example_helper]))
+
+filename = File.basename(__FILE__).gsub('.rb', '.pdf')
+Prawn::Example.generate(filename) do
+  move_cursor_to 80
+  text "Let's move to the end of the page so that you can see group in action."
+  
+  group do
+    text "This block of text was too big to be rendered on the bottom of the " +
+         " previous page. So it was rendered entirely on this new page. " +
+         " _ " * 200
+  end
+end