prawn-core 0.7.2 → 0.8.4

data/lib/prawn/graphics.rb

@@ -11,6 +11,7 @@ require "prawn/graphics/dash"
 require "prawn/graphics/cap_style"
 require "prawn/graphics/join_style"
 require "prawn/graphics/transparency"
+require "prawn/graphics/transformation"
 
 module Prawn
 
@@ -27,9 +28,10 @@ module Prawn
     include CapStyle
     include JoinStyle
     include Transparency
+    include Transformation
 
     #######################################################################
-    # Low level drawing operations must translate to absolute coords!     #
+    # Low level drawing operations must map the point to absolute coords! #
     #######################################################################
 
     # Moves the drawing position to a given point.  The point can be
@@ -39,7 +41,7 @@ module Prawn
     #   pdf.move_to(100,50)
     #
     def move_to(*point)
-      x,y = translate(point)
+      x,y = map_to_absolute(point)
       add_content("%.3f %.3f m" % [ x, y ])
     end
 
@@ -50,7 +52,7 @@ module Prawn
     #   pdf.line_to(50,50)
     #
     def line_to(*point)
-      x,y = translate(point)
+      x,y = map_to_absolute(point)
       add_content("%.3f %.3f l" % [ x, y ])
     end
 
@@ -64,7 +66,7 @@ module Prawn
          "Bounding points for bezier curve must be specified "+
          "as :bounds => [[x1,y1],[x2,y2]]"
 
-       curve_points = (options[:bounds] << dest).map { |e| translate(e) }
+       curve_points = (options[:bounds] << dest).map { |e| map_to_absolute(e) }
        add_content("%.3f %.3f %.3f %.3f %.3f %.3f c" %
                      curve_points.flatten )
     end
@@ -75,9 +77,21 @@ module Prawn
     #    pdf.rectangle [300,300], 100, 200
     #
     def rectangle(point,width,height)
-      x,y = translate(point)
+      x,y = map_to_absolute(point)
       add_content("%.3f %.3f %.3f %.3f re" % [ x, y - height, width, height ])
     end
+    
+    # Draws a rounded rectangle given <tt>point</tt>, <tt>width</tt> and
+    # <tt>height</tt> and <tt>radius</tt> for the rounded corner. The rectangle 
+    # is bounded by its upper-left corner.
+    #
+    #    pdf.rounded_rectangle [300,300], 100, 200, 10
+    #
+    def rounded_rectangle(point,width,height,radius)
+      x, y = point
+      rounded_polygon(radius, point, [x + width, y], [x + width, y - height], [x, y - height])
+    end
+    
 
     ###########################################################
     #  Higher level functions: May use relative coords        #
@@ -221,6 +235,34 @@ module Prawn
         line_to(*point)
       end
     end
+    
+    # Draws a rounded polygon from specified points using the radius to define bezier curves
+    #
+    #  # draws a rounded filled in polygon
+    #   pdf.fill_and_stroke_rounded_polygon(10, [100, 250], [200, 300], [300, 250],
+    #                 [300, 150], [200, 100], [100, 150])
+    def rounded_polygon(radius, *points)
+      move_to point_on_line(radius, points[1], points[0])
+      sides = points.size
+      points << points[0] << points[1]
+      (sides).times do |i|
+        rounded_vertex(radius, points[i], points[i + 1], points[i + 2])
+      end
+    end
+    
+    
+    # Creates a rounded vertex for a line segment used for building a rounded polygon
+    # requires a radius to define bezier curve and three points. The first two points define
+    # the line segment and the third point helps define the curve for the vertex.
+    def rounded_vertex(radius, *points)
+      x0,y0,x1,y1,x2,y2 = points.flatten
+      radial_point_1 = point_on_line(radius, points[0], points[1])
+      bezier_point_1 = point_on_line((radius - radius*KAPPA), points[0], points[1] )
+      radial_point_2 = point_on_line(radius, points[2], points[1])
+      bezier_point_2 = point_on_line((radius - radius*KAPPA), points[2], points[1])
+      line_to(radial_point_1)
+      curve_to(radial_point_2, :bounds => [bezier_point_1, bezier_point_2])
+    end      
 
     # Strokes and closes the current path. See Graphic::Color for color details
     #
@@ -248,17 +290,32 @@ module Prawn
       yield if block_given?
       add_content "b"
     end
-
+    
     private
 
-    def translate(*point)
+    def map_to_absolute(*point)
       x,y = point.flatten
       [@bounding_box.absolute_left + x, @bounding_box.absolute_bottom + y]
     end
 
-    def translate!(point)
-      point.replace(translate(point))
+    def map_to_absolute!(point)
+      point.replace(map_to_absolute(point))
     end
 
+    def degree_to_rad(angle)
+       angle * Math::PI / 180
+    end
+    
+    # Returns the coordinates for a point on a line that is a given distance away from the second
+    # point defining the line segement
+    def point_on_line(distance_from_end, *points)
+      x0,y0,x1,y1 = points.flatten
+      length = Math.sqrt((x1 - x0)**2 + (y1 - y0)**2)
+      p = (length - distance_from_end) / length
+      xr = x0 + p*(x1 - x0)
+      yr = y0 + p*(y1 - y0)
+      [xr, yr]
+    end
+    
   end
 end

data/lib/prawn/graphics/color.rb

@@ -5,7 +5,7 @@
 # Copyright June 2008, Gregory Brown.  All Rights Reserved.
 #
 # This is free software. Please see the LICENSE and COPYING files for details.
-#
+
 module Prawn
   module Graphics
     module Color

data/lib/prawn/graphics/transformation.rb

@@ -0,0 +1,156 @@
+# encoding: utf-8
+#
+# transformation.rb: Implements rotate, translate, skew, scale and a generic
+#                     transformation_matrix 
+#
+# Copyright January 2010, Michael Witrant. All Rights Reserved.
+#
+# This is free software. Please see the LICENSE and COPYING files for details.
+
+module Prawn
+  module Graphics
+    module Transformation
+      
+      # Rotate the user space.  If a block is not provided, then you must save
+      # and restore the graphics state yourself.
+      #
+      # == Options
+      # <tt>:origin</tt>:: <tt>[number, number]</tt>. The point around which to
+      #                    rotate. A block must be provided if using the :origin
+      #
+      # raises <tt>Prawn::Errors::BlockRequired</tt> if an :origin option is
+      # provided, but no block is given
+      #
+      # Example without a block:
+      #   
+      #   save_graphics_state
+      #   rotate 30
+      #   text "rotated text"
+      #   restore_graphics_state
+      #
+      # Example with a block: rotating a rectangle around its upper-left corner
+      #
+      #   x = 300
+      #   y = 300
+      #   width = 150
+      #   height = 200
+      #   angle = 30
+      #   pdf.rotate(angle, :origin => [x, y]) do
+      #     pdf.stroke_rectangle([x, y], width, height)
+      #   end
+      #
+      def rotate(angle, options={}, &block)
+        Prawn.verify_options(:origin, options)
+        rad = degree_to_rad(angle)
+        cos = Math.cos(rad)
+        sin = Math.sin(rad)
+        if options[:origin].nil?
+          transformation_matrix(cos, sin, -sin, cos, 0, 0, &block)
+        else
+          raise Prawn::Errors::BlockRequired unless block_given?
+          x = options[:origin][0] + bounds.absolute_left
+          y = options[:origin][1] + bounds.absolute_bottom
+          x_prime = x * cos - y * sin
+          y_prime = x * sin + y * cos
+          translate(x - x_prime, y - y_prime) do
+            transformation_matrix(cos, sin, -sin, cos, 0, 0, &block)
+          end
+        end
+      end
+
+      # Translate the user space.  If a block is not provided, then you must save
+      # and restore the graphics state yourself.
+      #
+      # Example without a block: move the text up and over 10
+      #   
+      #   save_graphics_state
+      #   translate(10, 10)
+      #   text "scaled text"
+      #   restore_graphics_state
+      #
+      # Example with a block: draw a rectangle with its upper-left corner at
+      #                       x + 10, y + 10
+      #
+      #   x = 300
+      #   y = 300
+      #   width = 150
+      #   height = 200
+      #   pdf.translate(10, 10) do
+      #     pdf.stroke_rectangle([x, y], width, height)
+      #   end
+      #
+      def translate(x, y, &block)
+        transformation_matrix(1, 0, 0, 1, x, y, &block)
+      end
+      
+      # Scale the user space.  If a block is not provided, then you must save
+      # and restore the graphics state yourself.
+      #
+      # == Options
+      # <tt>:origin</tt>:: <tt>[number, number]</tt>. The point from which to
+      #                    scale. A block must be provided if using the :origin
+      #
+      # raises <tt>Prawn::Errors::BlockRequired</tt> if an :origin option is
+      # provided, but no block is given
+      #
+      # Example without a block:
+      #   
+      #   save_graphics_state
+      #   scale 1.5
+      #   text "scaled text"
+      #   restore_graphics_state
+      #
+      # Example with a block: scale a rectangle from its upper-left corner
+      #
+      #   x = 300
+      #   y = 300
+      #   width = 150
+      #   height = 200
+      #   factor = 1.5
+      #   pdf.scale(angle, :origin => [x, y]) do
+      #     pdf.stroke_rectangle([x, y], width, height)
+      #   end
+      #
+      def scale(factor, options={}, &block)
+        Prawn.verify_options(:origin, options)
+        if options[:origin].nil?
+          transformation_matrix(factor, 0, 0, factor, 0, 0, &block)
+        else
+          raise Prawn::Errors::BlockRequired unless block_given?
+          x = options[:origin][0] + bounds.absolute_left
+          y = options[:origin][1] + bounds.absolute_bottom
+          x_prime = factor * x
+          y_prime = factor * y
+          translate(x - x_prime, y - y_prime) do
+            transformation_matrix(factor, 0, 0, factor, 0, 0, &block)
+          end
+        end
+      end
+      
+      # The following definition of skew would only work in a clearly
+      # predicatable manner when if the document had no margin. don't provide
+      # this shortcut until it behaves in a clearly understood manner
+      #
+      # def skew(a, b, &block)
+      #   transformation_matrix(1,
+      #                         Math.tan(degree_to_rad(a)),
+      #                         Math.tan(degree_to_rad(b)),
+      #                         1, 0, 0, &block)
+      # end
+      
+      # Transform the user space (see notes for rotate regarding graphics state)
+      # Generally, one would use the rotate, scale, translate, and skew
+      # convenience methods instead of calling transformation_matrix directly
+      def transformation_matrix(a, b, c, d, e, f)
+        values = [a, b, c, d, e, f].map { |x| "%.5f" % x }.join(" ")
+        save_graphics_state if block_given?
+        add_content "#{values} cm"
+        if block_given?
+          yield
+          restore_graphics_state
+        end
+      end
+      
+    end
+  end
+end

data/lib/prawn/graphics/transparency.rb

@@ -57,14 +57,10 @@ module Prawn
         opacity        = [[opacity, 0.0].max, 1.0].min
         stroke_opacity = [[stroke_opacity, 0.0].max, 1.0].min
 
-        # push a new graphics context onto the graphics context stack
-        add_content "q"
+        save_graphics_state
         add_content "/#{opacity_dictionary_name(opacity, stroke_opacity)} gs"
-
         yield if block_given?
-
-        # restore the previous graphics context
-        add_content "Q"
+        restore_graphics_state
       end
 
       private
@@ -94,7 +90,7 @@ module Prawn
                                                :obj  => dictionary }
         end
 
-        page_ext_gstates.merge!(dictionary_name => dictionary)
+        page.ext_gstates.merge!(dictionary_name => dictionary)
         dictionary_name
       end
 

data/lib/prawn/images.rb

@@ -91,7 +91,7 @@ module Prawn
       w,h = calc_image_dimensions(info, options)
 
       if options[:at]     
-        x,y = translate(options[:at]) 
+        x,y = map_to_absolute(options[:at]) 
       else                  
         x,y = image_position(w,h,options) 
         move_text_position h   
@@ -100,7 +100,7 @@ module Prawn
       # add a reference to the image object to the current page
       # resource list and give it a label
       label = "I#{next_image_id}"
-      page_xobjects.merge!( label => image_obj )
+      page.xobjects.merge!( label => image_obj )
 
       # add the image to the current page
       instruct = "\nq\n%.3f 0 0 %.3f %.3f %.3f cm\n/%s Do\nQ"
@@ -251,7 +251,7 @@ module Prawn
         # - An array with N elements, where N is two times the number of color
         #   components.
         rgb = png.transparency[:rgb]
-        obj.data[:Mask] = rgb.collect { |val| [val,val] }.flatten
+        obj.data[:Mask] = rgb.collect { |x| [x,x] }.flatten
       elsif png.transparency[:indexed]
         # TODO: broken. I was attempting to us Color Key Masking, but I think
         #       we need to construct an SMask i think. Maybe do it inside
@@ -263,6 +263,7 @@ module Prawn
       # channel mixed in with the main image data. The PNG class seperates
       # it out for us and makes it available via the alpha_channel attribute
       if png.alpha_channel
+        min_version 1.4
         smask_obj = ref!(:Type             => :XObject,
                         :Subtype          => :Image,
                         :Height           => png.height,

data/lib/prawn/images/png.rb

@@ -203,8 +203,8 @@ module Prawn
         # convert the pixel data to seperate strings for colours and alpha
         color_byte_size = self.colors * self.bits / 8
         alpha_byte_size = self.bits / 8
-        pixels.each do |row|
-          row.each do |pixel|
+        pixels.each do |this_row|
+          this_row.each do |pixel|
             @img_data << pixel[0, color_byte_size].pack("C*")
             @alpha_channel << pixel[color_byte_size, alpha_byte_size].pack("C*")
           end

data/lib/prawn/outline.rb

@@ -0,0 +1,278 @@
+# encoding: utf-8
+#
+# generates outline dictionary and items for document
+#
+# Author Jonathan Greenberg
+
+require 'forwardable'
+
+module Prawn
+  
+  class Document
+
+    # See Outline#define below for documentation
+    def define_outline(&block)
+      outline.define(&block)
+    end
+
+    # The Outline dictionary (12.3.3) for this document.  It is
+    # lazily initialized, so that documents that do not have an outline
+    # do not incur the additional overhead.
+    def outline_root(outline_root)
+      @store.root.data[:Outlines] ||= ref!(outline_root)
+    end
+
+    # Lazily instantiates an Outline object for document. This is used as point of entry
+    # to methods to build the outline tree.
+    def outline
+      @outline ||= Outline.new(self)
+    end
+
+  end
+  
+  # The Outline class organizes the outline tree items for the document.
+  # Note that the prev and parent instance variables are adjusted while navigating 
+  # through the nested blocks. These variables along with the presence or absense 
+  # of blocks are the primary means by which the relations for the various
+  # OutlineItems and the OutlineRoot are set. Unfortunately, the best way to
+  # understand how this works is to follow the method calls through a real example.
+  #
+  # Some ideas for the organization of this class were gleaned from name_tree. In 
+  # particular the way in which the OutlineItems are finally rendered into document 
+  # objects in PdfObject through a hash.
+  #
+  class Outline
+    
+    extend Forwardable
+    def_delegator :@document, :page_number
+    
+    attr_accessor :parent
+    attr_accessor :prev
+    attr_accessor :document
+    attr_accessor :outline_root
+    attr_accessor :items
+    
+    def initialize(document)
+      @document = document
+      @outline_root = document.outline_root(OutlineRoot.new)
+      @parent = outline_root
+      @prev = nil
+      @items = {}
+    end
+    
+    # Defines an outline for the document.
+    # The outline is an optional nested index that appears on the side of a PDF 
+    # document usually with direct links to pages. The outline DSL is defined by nested 
+    # blocks involving two methods: section and page.
+    #
+    # section(title, options{}, &block)
+    #   title: the outline text that appears for the section.
+    #   options: page - optional integer defining the page number for a destination link.
+    #                 - currently only :FIT destination supported with link to top of page.
+    #            closed - whether the section should show its nested outline elements.
+    #                   - defaults to false.
+    # page(page, options{})
+    #   page: integer defining the page number for the destination link.
+    #         currently only :FIT destination supported with link to top of page.
+    #         set to nil if destination link is not desired.
+    #   options: title - the outline text that appears for the section.
+    #            closed - whether the section should show its nested outline elements.
+    #                   - defaults to false.
+    #
+    # The syntax is best illustrated with an example:
+    #
+    # Prawn::Document.generate(outlined document) do
+    #   text "Page 1. This is the first Chapter. "
+    #   start_new_page
+    #   text "Page 2. More in the first Chapter. "
+    #   start_new_page
+    #   define_outline do
+    #     section 'Chapter 1', :page => 1, :closed => true do 
+    #       page 1, :title => 'Page 1'
+    #       page 2, :title => 'Page 2'
+    #     end
+    #   end
+    # end
+    # 
+    # It should be noted that not defining a title for a page element will raise
+    # a RequiredOption error
+    #
+    def define(&block)
+      if block
+        block.arity < 1 ? instance_eval(&block) : block[self]
+      end
+    end
+     
+    # Adds an outine section to the outline tree (see define_outline).
+    # Although you will probably choose to exclusively use define_outline so 
+    # that your outline tree is contained and easy to manage, this method
+    # gives you the option to add sections to the outline tree at any point
+    # during document generation. Note that the section will be added at the 
+    # top level at the end of the outline. For more a more flexible API try
+    # using outline.insert_section_after.
+    #
+    # block uses the same DSL syntax as define_outline, for example: 
+    #
+    #   outline.add_section do
+    #     section 'Added Section', :page => 3 do
+    #       page 3, :title => 'Page 3'
+    #     end
+    #   end
+    def add_section(&block)
+      @parent = outline_root
+      @prev = outline_root.data.last
+      if block
+        block.arity < 1 ? instance_eval(&block) : block[self]
+      end      
+    end
+    
+    # Inserts an outline section to the outline tree (see define_outline).
+    # Although you will probably choose to exclusively use define_outline so 
+    # that your outline tree is contained and easy to manage, this method
+    # gives you the option to insert sections to the outline tree at any point
+    # during document generation. Unlike outline.add_section, this method allows 
+    # you to enter a section after any other item at any level in the outline tree. 
+    # Currently the only way to locate the place of entry is with the title for the 
+    # item. If your titles names are not unique consider using define_outline.
+    #
+    # block uses the same DSL syntax as define_outline, for example: 
+    # 
+    #   go_to_page 2
+    #   start_new_page
+    #   text "Inserted Page"
+    #   outline.insert_section_after :title => 'Page 2' do 
+    #     page page_number, :title => "Inserted Page"
+    #   end
+    #
+    def insert_section_after(title, &block)
+      @prev = items[title]
+      if @prev
+        @parent = @prev.data.parent
+        nxt = @prev.data.next
+        if block
+          block.arity < 1 ? instance_eval(&block) : block[self]
+        end
+        adjust_relations(nxt)
+      else
+        raise Prawn::Errors::UnknownOutlineTitle, 
+          "\n No outline item with title: '#{title}' exists in the outline tree"
+      end
+    end
+
+  private
+    
+    def section(title, options = {}, &block)
+      add_outline_item(title, options, &block)
+    end 
+    
+    def page(page = nil, options = {})
+      if options[:title]
+        title = options[:title] 
+        options[:page] = page
+      else
+        raise Prawn::Errors::RequiredOption, 
+          "\nTitle is a required option for page"
+      end
+      add_outline_item(title, options)
+    end
+     
+    def add_outline_item(title, options, &block)
+      outline_item = create_outline_item(title, options)
+      set_relations(outline_item)
+      increase_count
+      set_variables_for_block(outline_item, block)
+      block.call if block
+      reset_parent(outline_item)
+    end
+    
+    def create_outline_item(title, options)
+      outline_item = OutlineItem.new(title, parent, options)
+
+      if options[:page]
+        page_index = options[:page] - 1
+        outline_item.dest = [document.pages[page_index].dictionary, :Fit] 
+      end
+
+      outline_item.prev = prev if @prev
+      items[title] = document.ref!(outline_item)
+    end
+    
+    def set_relations(outline_item)
+      prev.data.next = outline_item if prev
+      parent.data.first = outline_item unless prev
+      parent.data.last = outline_item
+    end
+    
+    def increase_count
+      counting_parent = parent
+      while counting_parent
+        counting_parent.data.count += 1
+        if counting_parent == outline_root
+          counting_parent = nil
+        else
+          counting_parent = counting_parent.data.parent
+        end
+      end
+    end
+    
+    def set_variables_for_block(outline_item, block)
+      self.prev = block ? nil : outline_item
+      self.parent = outline_item if block
+    end
+    
+    def reset_parent(outline_item)
+      if parent == outline_item
+        self.prev = outline_item
+        self.parent = outline_item.data.parent
+      end
+    end
+    
+    def adjust_relations(nxt)
+      if nxt 
+        nxt.data.prev = @prev
+        @prev.data.next = nxt
+        @parent.data.last = nxt
+      else 
+        @parent.data.last = @prev
+      end
+    end
+    
+  end
+  
+  class OutlineRoot #:nodoc:
+    attr_accessor :count, :first, :last
+    
+    def initialize
+      @count = 0
+    end
+        
+    def to_hash
+      {:Type => :Outlines, :Count => count, :First => first, :Last => last}
+    end
+  end
+  
+  class OutlineItem #:nodoc:
+    attr_accessor :count, :first, :last, :next, :prev, :parent, :title, :dest, :closed
+  
+    def initialize(title, parent, options)
+      @closed = options[:closed]
+      @title = title
+      @parent = parent
+      @count = 0
+    end
+  
+    def to_hash
+      hash = { :Title => Prawn::LiteralString.new(title),
+               :Parent => parent,
+               :Count => closed ? -count : count }
+      [{:First => first}, {:Last => last}, {:Next => @next}, 
+       {:Prev => prev}, {:Dest => dest}].each do |h|
+        unless h.values.first.nil?
+          hash.merge!(h)
+        end
+      end
+      hash 
+    end
+  end    
+end
+