prawn 0.12.0 → 0.13.0

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,29 @@
+# encoding: utf-8
+#
+# 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

data/manual/text/inline.rb

@@ -0,0 +1,43 @@
+# encoding: utf-8
+# 
+# Inline formatting gives you the option to format specific portions of a text.
+# It uses HTML-esque syntax inside the text string. Supported tags are:
+# <code>b</code> (bold), <code>i</code> (italic), <code>u</code> (underline),
+# <code>strikethrough</code>, <code>sub</code> (subscript), <code>sup</code>
+# (superscript)
+#
+# The following tags accept specific attributes: <code>font</code> accepts
+# <code>size</code>, <code>name</code>, and <code>character_spacing</code>;
+# <code>color</code> accepts <code>rgb</code> and <code>cmyk</code>;
+# <code>link</code> accepts <code>href</code> for external links and
+# <code>anchor</code> for internal links.
+#
+require File.expand_path(File.join(File.dirname(__FILE__),
+                                   %w[.. example_helper]))
+
+filename = File.basename(__FILE__).gsub('.rb', '.pdf')
+Prawn::Example.generate(filename) do
+  %w[b i u strikethrough sub sup].each do |tag|
+    text "Just your regular text <#{tag}>except this portion</#{tag}> " +
+         "is using the #{tag} tag",
+         :inline_format => true
+    move_down 10
+  end
+  
+  text "This <font size='18'>line</font> uses " +
+       "<font name='Courier'>all the font tag</font> attributes in " +
+       "<font character_spacing='2'>a single line</font>. ",
+       :inline_format => true
+  move_down 10
+  
+  text "Coloring in <color rgb='FF00FF'>both RGB</color> " +
+       "<color c='100' m='0' y='0' k='0'>and CMYK</color>",
+       :inline_format => true
+  move_down 10
+  
+  text "This an external link to the " +
+       "<u><link href='https://github.com/prawnpdf/prawn/wiki'>Prawn wiki" +
+       "</link></u> and this is a link to the " +
+       "<u><link anchor='Text Reference'>Text Reference</link></u> anchor",
+       :inline_format => true
+end

data/manual/text/kerning_and_character_spacing.rb

@@ -0,0 +1,39 @@
+# encoding: utf-8
+# 
+# Kerning is the process of adjusting the spacing between characters in a
+# proportional font. It is usually done with specific letter pairs. We can
+# switch it on and off if it is available with the current font. Just pass a
+# boolean value to the <code>:kerning</code> option of the text methods.
+#
+# Character Spacing is the space between characters. It can be increased or
+# decreased and will have effect on the whole text. Just pass a number to the
+# <code>:character_spacing</code> option from the 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
+  font_size(30) do
+    text_box "With kerning:",    :kerning => true,  :at => [0, y - 40]
+    text_box "Without kerning:", :kerning => false, :at => [0, y - 80]
+    
+    text_box "Tomato", :kerning => true,  :at => [250, y - 40]
+    text_box "Tomato", :kerning => false, :at => [250, y - 80]
+    
+    text_box "WAR", :kerning => true,  :at => [400, y - 40]
+    text_box "WAR", :kerning => false, :at => [400, y - 80]
+    
+    text_box "F.", :kerning => true,  :at => [500, y - 40]
+    text_box "F.", :kerning => false, :at => [500, y - 80]
+  end
+  
+  move_down 80
+  
+  string = "What have you done to the space between the characters?"
+  [-2, -1, 0, 0.5, 1, 2].each do |spacing|
+    move_down 20
+    text "#{string} (character_spacing: #{spacing})",
+         :character_spacing => spacing
+  end
+end

data/manual/text/leading.rb

@@ -0,0 +1,25 @@
+# encoding: utf-8
+# 
+# Leading is the additional space between lines of text.
+#
+# The leading can be set using the <code>default_leading</code> method which
+# applies to the rest of the document or until it is changed, or inline in the
+# text methods with the <code>:leading</code> option.
+#
+# The default leading is <code>0</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
+  string = "Hey, what did you do with the space between my lines? " * 10
+  text string, :leading => 0
+  
+  move_down 20
+  default_leading 5
+  text string
+  
+  move_down 20
+  text string, :leading => 10
+end

data/manual/text/line_wrapping.rb

@@ -0,0 +1,41 @@
+# encoding: utf-8
+# 
+# Line wrapping happens on white space or hyphens. Soft hyphens can be used to
+# indicate where words can be hyphenated. Non-breaking spaces can be used to
+# display space without allowing for a break.
+#
+# For writing styles that do not make use of spaces, the zero width space serves
+# to mark word boundaries. Zero width spaces are available only with TTF fonts.
+#
+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 "Hard hyphens:\n" +
+       "Slip-sliding away, slip sliding awaaaay. You know the " +
+       "nearer your destination the more you're slip-sliding away."
+  move_down 20
+
+  shy = Prawn::Text::SHY
+  text "Soft hyphens:\n" +
+       "Slip slid#{shy}ing away, slip slid#{shy}ing away. You know the " +
+       "nearer your destinat#{shy}ion the more you're slip slid#{shy}ing away."
+  move_down 20
+  
+  nbsp = Prawn::Text::NBSP
+  text "Non-breaking spaces:\n" +
+       "Slip#{nbsp}sliding away, slip#{nbsp}sliding awaaaay. You know the " +
+       "nearer your destination the more you're slip#{nbsp}sliding away."
+  move_down 20
+
+  font("#{Prawn::DATADIR}/fonts/gkai00mp.ttf", :size => 16) do
+    long_text = "No word boundaries:\n更可怕的是，同质化竞争对手可以按照URL中后面这个ID来遍历您的DB中的内容，写个小爬虫把你的页面上的关键信息顺次爬下来也不是什么难事，这样的话，你就非常被动了。更可怕的是，同质化竞争对手可以按照URL中后面这个ID来遍历您的DB中的内容，写个小爬虫把你的页面上的关键信息顺次爬下来也不是什么难事，这样的话，你就非常被动了。"
+    text long_text
+    move_down 20
+    
+    zwsp = Prawn::Text::ZWSP
+    long_text = "Invisible word boundaries:\n更#{zwsp}可怕的#{zwsp}是，#{zwsp}同质化#{zwsp}竞争#{zwsp}对#{zwsp}手#{zwsp}可以#{zwsp}按照#{zwsp}URL#{zwsp}中#{zwsp}后面#{zwsp}这个#{zwsp}ID#{zwsp}来#{zwsp}遍历#{zwsp}您的#{zwsp}DB#{zwsp}中的#{zwsp}内容，#{zwsp}写个#{zwsp}小爬虫#{zwsp}把#{zwsp}你的#{zwsp}页面#{zwsp}上的#{zwsp}关#{zwsp}键#{zwsp}信#{zwsp}息顺#{zwsp}次#{zwsp}爬#{zwsp}下来#{zwsp}也#{zwsp}不是#{zwsp}什么#{zwsp}难事，#{zwsp}这样的话，#{zwsp}你#{zwsp}就#{zwsp}非常#{zwsp}被动了。#{zwsp}更#{zwsp}可怕的#{zwsp}是，#{zwsp}同质化#{zwsp}竞争#{zwsp}对#{zwsp}手#{zwsp}可以#{zwsp}按照#{zwsp}URL#{zwsp}中#{zwsp}后面#{zwsp}这个#{zwsp}ID#{zwsp}来#{zwsp}遍历#{zwsp}您的#{zwsp}DB#{zwsp}中的#{zwsp}内容，#{zwsp}写个#{zwsp}小爬虫#{zwsp}把#{zwsp}你的#{zwsp}页面#{zwsp}上的#{zwsp}关#{zwsp}键#{zwsp}信#{zwsp}息顺#{zwsp}次#{zwsp}爬#{zwsp}下来#{zwsp}也#{zwsp}不是#{zwsp}什么#{zwsp}难事，#{zwsp}这样的话，#{zwsp}你#{zwsp}就#{zwsp}非常#{zwsp}被动了。"
+    text long_text
+  end
+end

data/manual/text/paragraph_indentation.rb

@@ -0,0 +1,26 @@
+# encoding: utf-8
+# 
+# Prawn strips all whitespace from the beginning and the end of strings so there
+# are two ways to indent paragraphs:
+#
+# One is to use non-breaking spaces which Prawn won't strip. One shortcut to
+# using them is the <code>Prawn::Text::NBSP</code>.
+#
+# The other is to use the <code>:indent_paragraphs</code> option with the text
+# methods. Just pass a number with the space to indent the first line in each
+# paragraph.
+#
+require File.expand_path(File.join(File.dirname(__FILE__),
+                                   %w[.. example_helper]))
+
+filename = File.basename(__FILE__).gsub('.rb', '.pdf')
+Prawn::Example.generate(filename) do
+  # Using non-breaking spaces
+  text " " * 10 + "This paragraph won't be indented. " * 10 +
+       "\n#{Prawn::Text::NBSP * 10}" + "This one will with NBSP. " * 10
+  
+  move_down 20
+  text "This paragraph will be indented. " * 10 +
+       "\n" + "This one will too. " * 10,
+       :indent_paragraphs => 60
+end

data/manual/text/positioned_text.rb

@@ -0,0 +1,38 @@
+# encoding: utf-8
+#
+# Sometimes we want the text on a specific position on the page. The
+# <code>text</code> method just won't help us.
+#
+# There are two other methods for this task: <code>draw_text</code> and
+# <code>text_box</code>.
+#
+# <code>draw_text</code> is very simple. It will render text starting at the
+# position provided to the <code>:at</code> option. It won't flow to a new line
+# even if it hits the document boundaries so it is best suited for short text.
+#
+# <code>text_box</code> gives us much more control over the output. Just provide
+# <code>:width</code> and <code>:height</code> options and the text will flow
+# accordingly. Even if you don't provide a <code>:width</code> option the text
+# will flow to a new line if it reaches the right border.
+#
+# Given that said, <code>text_box</code> is the better option available.
+#
+require File.expand_path(File.join(File.dirname(__FILE__),
+                                   %w[.. example_helper]))
+
+filename = File.basename(__FILE__).gsub('.rb', '.pdf')
+Prawn::Example.generate(filename) do
+  draw_text "This draw_text line is absolute positioned. However don't " +
+            "expect it to flow even if it hits the document border",
+            :at => [200, 300]
+  
+  text_box "This is a text box, you can control where it will flow by " +
+           "specifying the :height and :width options",
+           :at => [100, 250],
+           :height => 100,
+           :width => 100
+  
+  text_box "Another text box with no :width option passed, so it will " +
+           "flow to a new line whenever it reaches the right margin. ",
+           :at => [200, 100]
+end

data/manual/text/registering_families.rb

@@ -0,0 +1,48 @@
+# encoding: utf-8
+#
+# Registering font families will help you when you want to use a font over and
+# over or if you would like to take advantage of the <code>:style</code> option
+# of the text methods and the <code>b</code> and <code>i</code> tags when using
+# inline formatting.
+#
+# To register a font family update the <code>font_families</code>
+# hash with the font path for each style you want to use.
+#
+require File.expand_path(File.join(File.dirname(__FILE__),
+                                   %w[.. example_helper]))
+
+filename = File.basename(__FILE__).gsub('.rb', '.pdf')
+Prawn::Example.generate(filename) do
+  # Registering a single TTF font
+  font_families.update("Chalkboard" => {
+    :normal => "#{Prawn::DATADIR}/fonts/Chalkboard.ttf"
+  })
+  
+  font("Chalkboard") do
+    text "Using the Chalkboard font providing only its name to the font method"
+  end
+  move_down 20
+  
+  # Registering a DFONT package
+  font_path = "#{Prawn::DATADIR}/fonts/Action Man.dfont"
+  font_families.update("Action Man" => {
+    :normal      => { :file => font_path, :font => "ActionMan" },
+    :italic      => { :file => font_path, :font => "ActionMan-Italic" },
+    :bold        => { :file => font_path, :font => "ActionMan-Bold" },
+    :bold_italic => { :file => font_path, :font => "ActionMan-BoldItalic" }
+  })
+  
+  font "Action Man"
+  text "Also using the Action Man by providing only its name"
+  move_down 20
+  
+  text "Taking <b>advantage</b> of the <i>inline formatting</i>",
+       :inline_format => true
+  move_down 20
+  
+  [:bold, :bold_italic, :italic, :normal].each do |style|
+    text "Using the #{style} style option.",
+         :style => style
+    move_down 10
+  end
+end