prawn 1.0.0.rc1 → 1.0.0.rc2

data/manual/bounding_box/bounds.rb

@@ -0,0 +1,49 @@
+# encoding: utf-8
+# 
+# The <code>bounds</code> method returns the current bounding box. This is
+# useful because the <code>Prawn::BoundinBox</code> exposes some nice boundary
+# helpers.
+#
+# <code>top</code>, <code>bottom</code>, <code>left</code> and
+# <code>right</code> methods return the bounding box boundaries relative to its
+# translated origin. <code>top_left</code>, <code>top_right</code>,
+# <code>bottom_left</code> and <code>bottom_right</code> return those boundaries
+# pairs inside arrays.
+#
+# All these methods have an "absolute" version like <code>absolute_right</code>.
+# The absolute version returns the same boundary relative to the page absolute
+# coordinates.
+#
+# The following snippet shows the boundaries for the margin box side by side
+# with the boundaries for a custom 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
+  def print_coordinates
+    text "top: #{bounds.top}"
+    text "bottom: #{bounds.bottom}"
+    text "left: #{bounds.left}"
+    text "right: #{bounds.right}"
+    
+    move_down 10
+    
+    text "absolute top: #{sprintf "%.2f", bounds.absolute_top}"
+    text "absolute bottom: #{sprintf "%.2f", bounds.absolute_bottom}"
+    text "absolute left: #{sprintf "%.2f", bounds.absolute_left}"
+    text "absolute right: #{sprintf "%.2f", bounds.absolute_right}"
+  end
+  
+  text "Margin box bounds:"
+  move_down 5
+  print_coordinates
+  
+  bounding_box([250, cursor + 140], :width => 200, :height => 150) do
+    text "This bounding box bounds:"
+    move_down 5
+    print_coordinates
+    transparent(0.5) { stroke_bounds }
+  end
+end

data/manual/bounding_box/canvas.rb

@@ -0,0 +1,24 @@
+# encoding: utf-8
+# 
+# The origin example already mentions that a new document already comes with
+# a margin box whose bottom left corner is used as the origin for calculating
+# coordinates.
+#
+# What has not been told is that there is one helper for "bypassing" the margin
+# box: <code>canvas</code>. This method is a shortcut for creating a bounding
+# box mapped to the absolute coordinates and evaluating the code inside it.
+#
+# The following snippet draws a circle on each of the four absolute corners.
+#
+require File.expand_path(File.join(File.dirname(__FILE__),
+                                   %w[.. example_helper]))
+
+filename = File.basename(__FILE__).gsub('.rb', '.pdf')
+Prawn::Example.generate(filename) do
+  canvas do
+    fill_circle [bounds.left, bounds.top],     30
+    fill_circle [bounds.right, bounds.top],    30
+    fill_circle [bounds.right, bounds.bottom], 30
+    fill_circle [0, 0],                        30
+  end
+end

data/manual/bounding_box/creation.rb

@@ -0,0 +1,23 @@
+# encoding: utf-8
+# 
+# If you've read the basic concepts examples you probably know that the origin
+# of a page is on the bottom left corner and that the content flows from top to
+# bottom.
+#
+# You also know that a Bounding Box is a structure for helping the content flow.
+#
+# A bounding box can be created with the <code>bounding_box</code> method. Just
+# provide the top left corner, a required <code>:width</code> option and an
+# optional <code>:height</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
+  bounding_box([200, cursor - 100], :width => 200, :height => 100) do
+    text "Just your regular bounding box"
+    
+    transparent(0.5) { stroke_bounds }
+  end
+end

data/manual/bounding_box/indentation.rb

@@ -0,0 +1,46 @@
+# encoding: utf-8
+# 
+# Sometimes you just need to indent a portion of the contents of a bounding box,
+# and using a nested bounding box is pure overkill. The <code>indent</code>
+# method is what you might need.
+#
+# Just provide a number for it to indent all content generated inside the
+# block. 
+#
+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 "No indentation on the margin box."
+  indent(20) do
+    text "Some indentation inside an indent block."
+  end
+  move_down 20
+  
+  bounding_box([50, cursor], :width => 400, :height => cursor) do
+    transparent(0.5) { stroke_bounds }
+    
+    move_down 10
+    text "No indentation inside this bounding box."
+    indent(40) do
+      text "Inside an indent block. And so is this horizontal line:"
+      
+      stroke_horizontal_rule
+    end
+    move_down 10
+    text "No indentation"
+    
+    move_down 20
+    indent(60) do
+      text "Another indent block."
+      
+      bounding_box([0, cursor], :width => 200) do
+        text "Note that this bounding box coordinates are relative to the " +
+             "indent block"
+        
+        transparent(0.5) { stroke_bounds }
+      end
+    end
+  end
+end

data/manual/bounding_box/nesting.rb

@@ -0,0 +1,45 @@
+# encoding: utf-8
+# 
+# Normally when we provide the top left corner of a bounding box we
+# express the coordinates relative to the margin box. This is not the
+# case when we have nested bounding boxes. Once nested the inner bounding box
+# coordinates are relative to the outter bounding box.
+#
+# This example shows some nested bounding boxes with fixed and stretchy heights.
+# Note how the <code>cursor</code> method returns coordinates relative to
+# 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
+  def box_content(string)
+    text string
+    transparent(0.5) { stroke_bounds }
+  end
+  
+  gap = 20
+  bounding_box([50, cursor], :width => 400, :height => 200) do
+    box_content("Fixed height")
+    
+    bounding_box([gap, cursor - gap], :width => 300) do
+      text "Stretchy height"
+      
+      bounding_box([gap, bounds.top - gap], :width => 100) do
+        text "Stretchy height"
+        transparent(0.5) { dash(1); stroke_bounds; undash }
+      end
+      
+      bounding_box([gap * 7, bounds.top - gap], :width => 100, :height => 50) do
+        box_content("Fixed height")
+      end
+      
+      transparent(0.5) { dash(1); stroke_bounds; undash }
+    end
+    
+    bounding_box([gap, cursor - gap], :width => 300, :height => 50) do
+      box_content("Fixed height")
+    end
+  end
+end

data/manual/bounding_box/russian_boxes.rb

@@ -0,0 +1,40 @@
+# encoding: utf-8
+#
+# This example is mostly just for fun, and shows how nested bounding boxes
+# can simplify calculations. See the "Bounding Box" section of the manual
+# for more basic uses.
+#
+require File.expand_path(File.join(File.dirname(__FILE__),
+                                   %w[.. example_helper]))
+
+filename = File.basename(__FILE__).gsub('.rb', '.pdf')
+Prawn::Example.generate(filename) do
+  def combine(a1, a2)
+    output = []
+    a1.each do |i1|
+      a2.each do |i2|
+        output += [[i1,i2]]
+      end
+    end
+    output
+  end
+
+  def recurse_bounding_box(max_depth=4, depth=1)
+    width = (bounds.width-15)/2
+    height = (bounds.height-15)/2
+    left_top_corners = combine([5, bounds.right-width-5],
+                               [bounds.top-5, height+5])
+    left_top_corners.each do |lt|
+      bounding_box(lt, :width => width, :height => height) do
+        stroke_bounds
+        recurse_bounding_box(max_depth, depth+1) if depth < max_depth
+      end
+    end
+  end
+
+  # Set up a bbox from the dashed line to the bottom of the page
+  bounding_box([0, cursor], :width => bounds.width, :height => cursor) do
+    recurse_bounding_box
+  end
+end
+

data/manual/bounding_box/stretchy.rb

@@ -0,0 +1,31 @@
+# encoding: utf-8
+# 
+# Bounding Boxes accept an optional <code>:height</code> parameter. Unless it
+# is provided the bounding box will be stretchy. It will expand the height to
+# fit all content generated inside it.
+#
+require File.expand_path(File.join(File.dirname(__FILE__),
+                                   %w[.. example_helper]))
+
+filename = File.basename(__FILE__).gsub('.rb', '.pdf')
+Prawn::Example.generate(filename) do
+  y_position = cursor
+  bounding_box([0, y_position], :width => 200, :height => 100) do
+    text "This bounding box has a height of 100. If this text gets too large " +
+         "it will flow to the next page."
+    
+    transparent(0.5) { stroke_bounds }
+  end
+  
+  bounding_box([300, y_position], :width => 200) do
+    text "This bounding box has variable height. No matter how much text is " +
+         "written here, the height will expand to fit."
+    
+    text " _" * 100
+    
+    text " *" * 100
+    
+    transparent(0.5) { stroke_bounds }
+  end
+  
+end

data/manual/document_and_page_options/background.rb

@@ -0,0 +1,27 @@
+# encoding: utf-8
+#
+# Pass an image path to the <code>:background</code> option and it will be used
+# as the background for all pages.
+# This option can only be used on document creation. 
+#
+require File.expand_path(File.join(File.dirname(__FILE__),
+                                   %w[.. example_helper]))
+
+img = "#{Prawn::DATADIR}/images/letterhead.jpg"
+
+Prawn::Document.generate("background.pdf",
+                         :background => img,
+                         :margin => 100
+) do
+  text "My report caption", :size => 18, :align => :right
+
+  move_down font.height * 2
+
+  text "Here is my text explaning this report. " * 20, 
+       :size => 12, :align => :left, :leading => 2
+
+  move_down font.height
+
+  text "I'm using a soft background. " * 40,
+       :size => 12, :align => :left, :leading => 2
+end

data/manual/document_and_page_options/document_and_page_options.rb

@@ -0,0 +1,31 @@
+# encoding: utf-8
+#
+# Examples for stamps and repeaters.
+#
+require File.expand_path(File.join(File.dirname(__FILE__),
+                                   %w[.. example_helper]))
+
+Prawn::Example.generate("document_and_page_options.pdf",
+                        :page_size => "FOLIO") do
+  
+  package "document_and_page_options" do |p|
+    
+    p.example "page_size",    :eval_source => false, :full_source => true
+    p.example "page_margins", :eval_source => false, :full_source => true
+    p.example "background",   :eval_source => false, :full_source => true
+    p.example "metadata",     :eval_source => false, :full_source => true
+    
+    p.intro do
+      prose("So far we've already seen how to create new documents and start new pages. This chapter expands on the previous examples by showing other options avialable. Some of the options are only available when creating new documents.
+
+      The examples show:")
+
+      list( "How to configure page size",
+            "How to configure page margins",
+            "How to use a background image",
+            "How to add metadata to the generated PDF"
+          )
+    end
+    
+  end
+end

data/manual/document_and_page_options/metadata.rb

@@ -0,0 +1,23 @@
+# encoding: utf-8
+#
+# To set the document metadata just pass a hash to the <code>:info</code>
+# option when creating new documents.
+#
+require File.expand_path(File.join(File.dirname(__FILE__),
+                                   %w[.. example_helper]))
+
+Prawn::Document.generate("metadata.pdf",
+  :info => {
+    :Title        => "My title",
+    :Author       => "John Doe",
+    :Subject      => "My Subject",
+    :Keywords     => "test metadata ruby pdf dry",
+    :Creator      => "ACME Soft App", 
+    :Producer     => "Prawn",
+    :CreationDate => Time.now,
+    :Grok         => "Test Property"
+  }) do
+  
+  text "This is a test of setting metadata properties via the info option."
+  text "It allows one to specify non standard properties like 'Grok'."
+end

data/manual/document_and_page_options/page_margins.rb

@@ -0,0 +1,38 @@
+# encoding: utf-8
+#
+# The default margin for pages is 0.5 inch but you can change that with the
+# <code>:margin</code> option or if you'd like to have different margins you
+# can use the <code>:left_margin</code>, <code>:right_margin</code>,
+# <code>:top_margin</code>, <code>:bottom_margin</code> options.
+#
+# These options are available both for starting new pages and creating new
+# documents.
+#
+require File.expand_path(File.join(File.dirname(__FILE__),
+                                   %w[.. example_helper]))
+
+Prawn::Document.generate("page_margins.pdf",
+                         :margin => 100
+) do
+  text "100 pts margins."
+  stroke_bounds
+
+  start_new_page(:left_margin => 300)
+  text "300 pts margin on the left."
+  stroke_bounds
+  
+  start_new_page(:top_margin => 300)
+  text "300 pts margin both on the top and on the left. Notice that whenever " +
+       "you set an option for a new page it will remain the default for the " +
+       "following pages."
+  stroke_bounds
+
+  start_new_page(:margin => 50)
+  text "50 pts margins. Using the margin option will reset previous specific " +
+       "calls to left, right, top and bottom margins."
+  stroke_bounds
+  
+  start_new_page(:margin => [50, 100, 150, 200])
+  text "There is also the shorthand CSS like syntax used here."
+  stroke_bounds
+end

data/manual/document_and_page_options/page_size.rb

@@ -0,0 +1,34 @@
+# encoding: utf-8
+#
+# Prawn comes with support for most of the common page sizes so you'll only need
+# to provide specific values if your intended format is not supported. To see a
+# list with all supported sizes take a look at: https://github.com/prawnpdf/prawn/blob/master/lib/prawn/document/page_geometry.rb
+#
+# To define the size use <code>:page_size</code> when creating new documents
+# and <code>:size</code> when starting new pages. The default page size for new
+# documents is LETTER (612.00 x 792.00).
+#
+# You may also define the orientation of the page to be either portrait
+# (default) or landscape. Use <code>:page_layout</code> when creating new
+# documents and <code>:layout</code> when starting new pages.
+#
+require File.expand_path(File.join(File.dirname(__FILE__),
+                                   %w[.. example_helper]))
+
+Prawn::Document.generate("page_size.pdf",
+                         :page_size   => "EXECUTIVE",
+                         :page_layout => :landscape
+) do
+  text "EXECUTIVE landscape page."
+
+  custom_size = [275, 326]
+  
+  ["A4", "TABLOID", "B7", custom_size ].each do |size|
+    
+    start_new_page(:size => size, :layout => :portrait)
+    text "#{size} portrait page."
+    
+    start_new_page(:size => size, :layout => :landscape)
+    text "#{size} landscape page."
+  end
+end

data/manual/example_file.rb

@@ -0,0 +1,116 @@
+# encoding: utf-8
+
+module Prawn
+  
+  # The Prawn::ExampleFile class is a utility class to ease the manipulation
+  # and extraction of source code and comments from the actual example files
+  #
+  class ExampleFile
+    attr_reader :package, :filename
+    
+    # Stores the file data, filename and parent, which will be either an
+    # ExampleSection or an ExamplePackage.
+    #
+    # Available boolean options are:
+    # 
+    # <tt>:eval_source</tt>:: Evals the example source code (default: true)
+    # <tt>:full_source</tt>:: Extract the full source code when true. Extract
+    # only the code between the generate block when false (default: false)
+    #
+    def initialize(parent, filename, options={})
+      @parent   = parent.is_a?(String) ? ExamplePackage.new(parent) : parent
+      
+      @filename = filename
+      @data     = read_file(@parent.folder_name, filename)
+      
+      @options  = {:eval_source => true, :full_source => false}.merge(options)
+    end
+    
+    # Return the example source code excluding the initial comments and
+    # require calls
+    #
+    def full_source
+      @data.gsub(/# encoding.*?\n.*require.*?\n\n/m, "\n").strip
+    end
+    
+    # Return the example source contained inside the first generate block or
+    # the full source if no generate block is found
+    #
+    def generate_block_source
+      block = @data.slice(/\w+\.generate.*? do\n(.*)end/m, 1)
+        
+      return full_source unless block
+      
+      block.gsub(/^( ){2}/, "")
+    end
+    
+    # Return either the full_source or the generate_block_source according
+    # to the options
+    #
+    def source
+      @options[:full_source] ? full_source : generate_block_source
+    end
+    
+    # Return true if the example source should be evaluated inline within
+    # the manual according to the options
+    #
+    def eval?
+      @options[:eval_source]
+    end
+    
+    # Retrieve the comments between the encoding declaration and the require
+    # call for example_helper.rb
+    #
+    # Then removes the '#' signs, reflows the line breaks and return the result
+    #
+    def introduction_text
+      intro = @data.slice(/# encoding.*?\n(.*)require File\.expand_path/m, 1)
+      intro.gsub!(/\n# (?=\S)/m, ' ')
+      intro.gsub!(/^#/, '')
+      intro.gsub!("\n", "\n\n")
+      intro.rstrip!
+      intro
+    end
+    
+    # Returns a human friendly version of the example file name
+    #
+    def name
+      @name ||= @filename[/(.*)\.rb/, 1].gsub("_", " ").capitalize
+    end
+    
+    # Returns this example's parent original folder name
+    #
+    def parent_folder_name
+      @parent.folder_name
+    end
+    
+    # Returns the human friendly version of this example parent name
+    #
+    def parent_name
+      @parent.name
+    end
+    
+    # Renders this example to a pdf
+    #
+    def render(pdf)
+      pdf.render_example(self)
+    end
+    
+  private
+  
+    # Read the data from a file in a given package
+    #
+    def read_file(folder_name, filename)
+      data = File.read(File.expand_path(File.join(
+        File.dirname(__FILE__), folder_name, filename)))
+      
+      # XXX If we ever have manual files with source encodings other than
+      # UTF-8, we will need to fix this to work on Ruby 1.9.
+      if data.respond_to?(:encode!)
+        data.encode!("UTF-8")
+      end
+      data
+    end
+    
+  end
+end