prawn-git 2.0.1

data/manual/repeatable_content/stamp.rb

@@ -0,0 +1,41 @@
+# encoding: utf-8
+#
+# Stamps should be used when you have content that will be included multiple
+# times in a document. Its advantages over creating the content anew each time
+# are:
+#   1.  Faster document creation
+#   2.  Smaller final document
+#   3.  Faster display on subsequent displays of the repeated
+# element because the viewer application can cache the rendered
+# results
+#
+# The <code>create_stamp</code> method does just what it says. Pass it a block
+# with the content that should be generated and the stamp will be created.
+#
+# There are two methods to render the stamp on a page <code>stamp</code> and
+# <code>stamp_at</code>. The first will render the stamp as is while the
+# second accepts a point to serve as an offset to the stamp content.
+#
+require File.expand_path(File.join(File.dirname(__FILE__),
+                                   %w[.. example_helper]))
+
+filename = File.basename(__FILE__).gsub('.rb', '.pdf')
+Prawn::ManualBuilder::Example.generate(filename) do
+  create_stamp("approved") do
+    rotate(30, :origin => [-5, -5]) do
+      stroke_color "FF3333"
+      stroke_ellipse [0, 0], 29, 15
+      stroke_color "000000"
+
+      fill_color "993333"
+      font("Times-Roman") do
+        draw_text "Approved", :at => [-23, -3]
+      end
+      fill_color "000000"
+    end
+  end
+
+  stamp "approved"
+
+  stamp_at "approved", [200, 200]
+end

data/manual/security/encryption.rb

@@ -0,0 +1,31 @@
+# encoding: utf-8
+#
+# The <code>encrypt_document</code> method, as you might have already guessed,
+# is used to encrypt the PDF document.
+#
+# Once encrypted whoever is using the document will need the user password to
+# read the document. This password can be set with the
+# <code>:user_password</code> option. If this is not set the document will be
+# encrypted but a password will not be needed to read the document.
+#
+# There are some caveats when encrypting your PDFs. Be sure to read the source
+# documentation (you can find it here:
+# https://github.com/prawnpdf/prawn/blob/master/lib/prawn/security.rb ) before
+# using this for anything super serious.
+#
+require File.expand_path(File.join(File.dirname(__FILE__),
+                                   %w[.. example_helper]))
+
+
+# Bare encryption. No password needed.
+Prawn::ManualBuilder::Example.generate("bare_encryption.pdf") do
+  text "See, no password was asked but the document is still encrypted."
+  encrypt_document
+end
+
+
+# Simple password. All permissions granted.
+Prawn::ManualBuilder::Example.generate("simple_password.pdf") do
+  text "You was asked for a password."
+  encrypt_document(:user_password => 'foo', :owner_password => 'bar')
+end

data/manual/security/permissions.rb

@@ -0,0 +1,38 @@
+# encoding: utf-8
+#
+# Some permissions may be set for the regular user with the following options:
+# <code>:print_document</code>, <code>:modify_contents</code>,
+# <code>:copy_contents</code>, <code>:modify_annotations</code>. All this
+# options default to true, so if you'd like to revoke just set them to false.
+#
+# A user may bypass all permissions if he provides the owner password which
+# may be set with the <code>:owner_password</code> option. This option may be
+# set to <code>:random</code> so that users will never be able to bypass
+# permissions.
+#
+# There are some caveats when encrypting your PDFs. Be sure to read the source
+# documentation (you can find it here:
+# https://github.com/prawnpdf/prawn/blob/master/lib/prawn/security.rb ) before
+# using this for anything super serious.
+#
+require File.expand_path(File.join(File.dirname(__FILE__),
+                                   %w[.. example_helper]))
+
+
+# User cannot print the document.
+Prawn::ManualBuilder::Example.generate("cannot_print.pdf") do
+  text "If you used the user password you won't be able to print the doc."
+  encrypt_document(:user_password => 'foo', :owner_password => 'bar',
+                   :permissions => { :print_document => false })
+end
+
+
+# All permissions revoked and owner password set to random
+Prawn::ManualBuilder::Example.generate("no_permissions.pdf") do
+  text "You may only view this and won't be able to use the owner password."
+  encrypt_document(:user_password => 'foo', :owner_password => :random,
+                   :permissions => { :print_document     => false,
+                                     :modify_contents    => false,
+                                     :copy_contents      => false,
+                                     :modify_annotations => false })
+end

data/manual/security/security.rb

@@ -0,0 +1,28 @@
+# encoding: utf-8
+#
+# Examples for document encryption.
+#
+require File.expand_path(File.join(File.dirname(__FILE__),
+                                   %w[.. example_helper]))
+
+Prawn::ManualBuilder::Example.generate("security.pdf", :page_size => "FOLIO") do
+
+  package "security" do |p|
+
+    p.example "encryption",  :eval_source => false, :full_source => true
+    p.example "permissions", :eval_source => false, :full_source => true
+
+    p.intro do
+      prose("Security lets you control who can read the document by defining a password.
+
+      The examples include:")
+
+      list( "How to encrypt the document without the need for a password",
+            "How to configure the regular user permissions",
+            "How to require a password for the regular user",
+            "How to set a owner password that bypass the document permissions"
+          )
+    end
+
+  end
+end

data/manual/table.rb

@@ -0,0 +1,16 @@
+# encoding: UTF-8
+
+require_relative "example_helper"
+
+filename = File.basename(__FILE__).gsub('.rb', '.pdf')
+
+Prawn::ManualBuilder::Example.generate(filename) do
+  header("Prawn::Table")
+
+  prose <<-END_TEXT
+    As of Prawn 1.2.0, Prawn::Table has been extracted into its own
+    semi-officially supported gem.
+
+    Please see https://github.com/prawnpdf/prawn-table for more details.
+  END_TEXT
+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::ManualBuilder::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::ManualBuilder::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::ManualBuilder::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::ManualBuilder::Example.generate(filename) do
+  file = "#{Prawn::DATADIR}/fonts/gkai00mp.ttf"
+  font_families["Kai"] = {
+    :normal => { :file => file, :font => "Kai" }
+  }
+
+  file = "#{Prawn::DATADIR}/fonts/Panic+Sans.dfont"
+  font_families["Panic Sans"] = {
+    :normal => { :file => file, :font => "PanicSans" },
+  }
+
+  font("Panic Sans") 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::ManualBuilder::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::ManualBuilder::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::ManualBuilder::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::ManualBuilder::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