prawn 1.0.0.rc1 → 1.0.0.rc2

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/templates/full_template.rb

@@ -0,0 +1,23 @@
+# encoding: utf-8
+#
+# You may load another PDF while creating a new one. Just pass the loaded PDF
+# filename to the <code>:template</code> option when creating/generating the new
+# PDF.
+#
+# The provided PDF will be loaded and the its first page will be set as the
+# current page. If you'd like to resume the document you may take advantage of
+# two helpers: <code>page_count</code> and <code>go_to_page</code>.
+#
+require File.expand_path(File.join(File.dirname(__FILE__),
+                                   %w[.. example_helper]))
+
+filename = "#{Prawn::DATADIR}/pdfs/multipage_template.pdf"
+
+Prawn::Example.generate("full_template.pdf", :template => filename) do
+  go_to_page(page_count)
+  
+  start_new_page
+  
+  text "Previous pages and content imported.", :align => :center
+  text "This page and content is brand new.",  :align => :center
+end

data/manual/templates/page_template.rb

@@ -0,0 +1,47 @@
+# encoding: utf-8
+#
+# If you only need to load some pages from another PDF, you can accomplish it
+# with the <code>start_new_page</code> method. You may pass it a
+# <code>:template</code> option with the path for an existing pdf and a
+# <code>:template_page</code> option to specify which page to load.
+# You can also load a <code>:template</code> using a URI:
+#
+# <code>require 'open-uri'</code>
+#
+# <code>start_new_page(:template => open('url_for_your.pdf'))</code>
+#
+# The following example loads some pages from an existing PDF. If we don't
+# specify the <code>:template_page</code> option, the first page of the template
+# PDF will be loaded. That's what happens on the first load below. Then we load
+# a page by specifying the <code>:template_page</code> option and then we do it
+# again this time adding some content to the loaded 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
+  text "Please scan the next 3 pages to see the page templates in action."
+  move_down 10
+  text "You also might want to look at the pdf used as a template: "
+  url = "https://github.com/prawnpdf/prawn/raw/master/data/pdfs/form.pdf"
+  move_down 10
+  
+  formatted_text [{:text => url, :link => url}]
+  
+  filename = "#{Prawn::DATADIR}/pdfs/form.pdf"
+  start_new_page(:template => filename)
+  
+  start_new_page(:template => filename, :template_page => 2)
+  
+  start_new_page(:template => filename, :template_page => 2)
+  
+  fill_color "FF8888"
+  
+  text_box "John Doe", :at => [75, cursor-75]
+  text_box "john@doe.com", :at => [75, cursor-105]
+  text_box "John Doe inc", :at => [75, cursor-135]
+  text_box "You didn't think I'd tell, did you?", :at => [75, cursor-165]
+  
+  fill_color "000000"
+end

data/manual/templates/templates.rb

@@ -0,0 +1,26 @@
+# encoding: utf-8
+#
+# Examples for loading existing pdfs.
+#
+require File.expand_path(File.join(File.dirname(__FILE__),
+                                   %w[.. example_helper]))
+
+Prawn::Example.generate("templates.pdf", :page_size => "FOLIO") do
+  
+  package "templates" do |p|
+    
+    p.example "full_template", :eval_source => false, :full_source => true
+    p.example "page_template"
+    
+    p.intro do
+      prose("Templates let you embed other PDF documents inside the current one.
+
+      The examples show:")
+
+      list( "How to load the whole content from another PDF",
+            "How to load single pages from another PDF"
+          )
+    end
+    
+  end
+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,50 @@
+# 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), and <code>:anchor</code> (a
+# destination inside the document).
+#
+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" }
+                 ]
+  
+  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