prawn 0.15.0 → 1.0.0.rc1

data/lib/prawn/graphics/cap_style.rb

@@ -1,4 +1,4 @@
-# encoding: utf-8
+# encoding: utf-8   
 
 # cap_style.rb : Implements stroke cap styling
 #
@@ -9,7 +9,6 @@
 module Prawn
   module Graphics
     module CapStyle
-      # @group Stable API
 
       CAP_STYLES = { :butt => 0, :round => 1, :projecting_square => 2 }
 
@@ -31,11 +30,11 @@ module Prawn
 
       private
 
-      def current_cap_style
+      def current_cap_style  
         graphic_state.cap_style
       end
 
-      def current_cap_style=(style)
+      def current_cap_style=(style)  
         graphic_state.cap_style = style
       end
 

data/lib/prawn/graphics/color.rb

@@ -9,7 +9,6 @@
 module Prawn
   module Graphics
     module Color
-      # @group Stable API
 
       # Sets or returns the fill color.
       #
@@ -96,14 +95,7 @@ module Prawn
         when String
           :RGB
         when Array
-          case color.length
-          when 3
-            :RGB
-          when 4
-            :CMYK
-          else
-            raise ArgumentError, "Unknown type of color: #{color.inspect}"
-          end
+          :CMYK
         end
       end
 
@@ -167,7 +159,7 @@ module Prawn
         if options[:pattern]
           set_color_space type, :Pattern
           add_content "/#{color} #{operator}"
-        else
+        else          
           set_color_space type, color_space(color)
           color = color_to_s(color)
           write_color(color, operator)
@@ -175,7 +167,7 @@ module Prawn
       end
 
       def set_fill_color(color = nil)
-        set_color :fill, color || current_fill_color
+        set_color :fill, color || current_fill_color        
       end
 
       def set_stroke_color(color = nil)
@@ -193,7 +185,7 @@ module Prawn
         graphic_state.color_space[type]
       end
 
-      def set_current_color_space(color_space, type)
+      def set_current_color_space(color_space, type)                
         save_graphics_state if graphic_state.nil?
         graphic_state.color_space[type] = color_space
       end
@@ -202,7 +194,7 @@ module Prawn
         graphic_state.fill_color
       end
 
-      def current_fill_color=(color)
+      def current_fill_color=(color)        
         graphic_state.fill_color = color
       end
 

data/lib/prawn/graphics/dash.rb

@@ -1,4 +1,4 @@
-# encoding: utf-8
+# encoding: utf-8   
 
 # dash.rb : Implements stroke dashing
 #
@@ -9,59 +9,35 @@
 module Prawn
   module Graphics
     module Dash
-      # @group Stable API
 
-      # Sets the dash pattern for stroked lines and curves or return the
-      # current dash pattern setting if +length+ is nil.
+      # Sets the dash pattern for stroked lines and curves
       #
-      # There are two ways to set the dash pattern:
+      #   length is the length of the dash. If options is not present,
+      #   or options[:space] is nil, then length is also the length of
+      #   the space between dashes
       #
-      # * If the parameter +length+ is an Integer/Float, it specifies
-      #   the length of the dash and of the gap. The length of the gap
-      #   can be customized by setting the :space option.
+      #   options may contain :space and :phase
+      #      :space is the space between the dashes
+      #      :phase is where in the cycle to begin dashing. For
+      #             example, a phase of 0 starts at the beginning of
+      #             the dash; whereas, if the phase is equal to the
+      #             length of the dash, then stroking will begin at
+      #             the beginning of the space. Default is 0
       #
-      #   Examples:
+      #   integers or floats may be used for length and the options
       #
-      #     length = 3
-      #       3 on, 3 off, 3 on, 3 off, ...
-      #     length = 3, :space =2
-      #       3 on, 2 off, 3 on, 2 off, ...
-      #
-      # * If the parameter +length+ is an array, it specifies the
-      #   lengths of alternating dashes and gaps. The :space option is
-      #   ignored in this case.
-      #
-      #   Examples:
-      #
-      #     length = [2, 1]
-      #       2 on, 1 off, 2 on, 1 off, ...
-      #     length = [3, 1, 2, 3]
-      #       3 on, 1 off, 2 on, 3 off, 3 on, 1 off, ...
-      #
-      # Options may contain the keys :space and :phase
-      #
-      # :space:: The space between the dashes (only used when +length+
-      #          is not an array)
-      #
-      # :phase:: The distance into the dash pattern at which to start
-      #          the dash. For example, a phase of 0 starts at the
-      #          beginning of the dash; whereas, if the phase is equal
-      #          to the length of the dash, then stroking will begin at
-      #          the beginning of the space. Default is 0.
-      #
-      # Integers or Floats may be used for length and the option values.
-      # Dash units are in PDF points (1/72 inch).
-      #
-      def dash(length=nil, options={})
-        return current_dash_state if length.nil?
+      #   dash units are in PDF points ( 1/72 in )
+      #   
+      def dash(length=nil, options={})        
+        return current_dash_state || undash_hash if length.nil?
 
-        self.current_dash_state = { :dash  => length,
-                  :space => length.kind_of?(Array) ? nil : options[:space] || length,
+        self.current_dash_state = { :dash  => length, 
+                  :space => options[:space] || length, 
                   :phase => options[:phase] || 0 }
 
         write_stroke_dash
       end
-
+      
       alias_method :dash=, :dash
 
       # Stops dashing, restoring solid stroked lines and curves
@@ -70,35 +46,37 @@ module Prawn
         self.current_dash_state = undashed_setting
         write_stroke_dash
       end
-
+      
       # Returns when stroke is dashed, false otherwise
       #
       def dashed?
         current_dash_state != undashed_setting
       end
-
-      private
-
+      
       def write_stroke_dash
         add_content dash_setting
       end
 
+    private
+      
       def undashed_setting
         { :dash => nil, :space => nil, :phase => 0 }
       end
-
-      def current_dash_state=(dash_options)
+      
+      private 
+        
+      def current_dash_state=(dash_options)  
         graphic_state.dash = dash_options
       end
-
+      
       def current_dash_state
         graphic_state.dash
       end
-
+      
       def dash_setting
         graphic_state.dash_setting
       end
-
+      
     end
   end
 end

data/lib/prawn/graphics/gradient.rb

@@ -0,0 +1,84 @@
+# encoding: utf-8
+
+# gradient.rb : Implements axial gradient
+#
+# Contributed by Wojciech Piekutowski. November, 2009
+#
+# This is free software. Please see the LICENSE and COPYING files for details.
+#
+module Prawn
+  module Graphics
+    module Gradient
+      # Sets the fill gradient from color1 to color2.
+      #
+      # It accepts CMYK and RGB colors, like #fill_color. Both colors must be
+      # of the same type.
+      #
+      # point, width and height define a bounding box in which the gradient
+      # will be rendered. For example, if you want to have page full of text
+      # with gradually changing color:
+      #
+      #   pdf.fill_gradient [0, pdf.bounds.height], pdf.bounds.width,
+      #     pdf.bounds.height, 'FF0000', '0000FF'
+      #   pdf.text 'lots of text'*1000
+      #
+      # <tt>:stroke_bounds</tt> - draw gradient bounds
+      def fill_gradient(point, width, height, color1, color2, options = {})
+        set_gradient(:fill, point, width, height, color1, color2, options)
+      end
+
+      # Sets the stroke gradient from color1 to color2.
+      #
+      # See #fill_gradient for details.
+      def stroke_gradient(point, width, height, color1, color2, options = {})
+        set_gradient(:stroke, point, width, height, color1, color2, options)
+      end
+
+      private
+
+      def set_gradient(type, point, width, height, color1, color2, options)
+        if options[:stroke_bounds]
+          stroke_color 0, 0, 0, 100
+          stroke_rectangle point, width, height
+        end
+
+        if color_type(color1) != color_type(color2)
+          raise ArgumentError, 'both colors must be of the same type: RGB or CMYK'
+        end
+
+        process_color color1
+        process_color color2
+
+        shader = ref!({
+          :FunctionType => 2,
+          :Domain => [0.0, 1.0],
+          :C0 => normalize_color(color1),
+          :C1 => normalize_color(color2),
+          :N => 1,
+        })
+
+        shading = ref!({
+          :ShadingType => 2, # axial shading
+          :ColorSpace => color_type(color1) == :RGB ? :DeviceRGB : :DeviceCMYK,
+          :Coords => [0.0, 0.0, 1.0, 0.0],
+          :Function => shader,
+          :Extend => [true, true],
+        })
+
+        x, y = *point
+        shading_pattern = ref!({
+          :PatternType => 2, # shading pattern
+          :Shading => shading,
+          :Matrix => [0,-height, -width, 0, x, y],
+        })
+
+        patterns = page.resources[:Pattern] ||= {}
+        id = patterns.empty? ? 'SP1' : patterns.keys.sort.last.succ
+        patterns[id] = shading_pattern
+
+        set_color type, id, :pattern => true
+      end
+    end
+  end
+end
+

data/lib/prawn/graphics/join_style.rb

@@ -1,4 +1,4 @@
-# encoding: utf-8
+# encoding: utf-8   
 
 # join_style.rb : Implements stroke join styling
 #
@@ -10,9 +10,7 @@ module Prawn
   module Graphics
     module JoinStyle
       JOIN_STYLES = { :miter => 0, :round => 1, :bevel => 2 }
-
-      # @group Stable API
-
+      
       # Sets the join style for stroked lines and curves
       #
       # style is one of :miter, :round, or :bevel
@@ -27,19 +25,19 @@ module Prawn
 
         write_stroke_join_style
       end
-
+      
       alias_method :join_style=, :join_style
 
       private
-
-      def current_join_style
+      
+      def current_join_style  
         graphic_state.join_style
       end
 
-      def current_join_style=(style)
+      def current_join_style=(style)  
         graphic_state.join_style = style
       end
-
+      
 
       def write_stroke_join_style
         add_content "#{JOIN_STYLES[current_join_style]} j"

data/lib/prawn/graphics/transformation.rb

@@ -1,7 +1,7 @@
 # encoding: utf-8
 #
 # transformation.rb: Implements rotate, translate, skew, scale and a generic
-#                     transformation_matrix
+#                     transformation_matrix 
 #
 # Copyright January 2010, Michael Witrant. All Rights Reserved.
 #
@@ -10,8 +10,7 @@
 module Prawn
   module Graphics
     module Transformation
-      # @group Stable API
-
+      
       # Rotate the user space.  If a block is not provided, then you must save
       # and restore the graphics state yourself.
       #
@@ -23,7 +22,7 @@ module Prawn
       # provided, but no block is given
       #
       # Example without a block:
-      #
+      #   
       #   save_graphics_state
       #   rotate 30
       #   text "rotated text"
@@ -63,7 +62,7 @@ module Prawn
       # 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"
@@ -83,7 +82,7 @@ module Prawn
       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.
       #
@@ -95,7 +94,7 @@ module Prawn
       # provided, but no block is given
       #
       # Example without a block:
-      #
+      #   
       #   save_graphics_state
       #   scale 1.5
       #   text "scaled text"
@@ -127,7 +126,7 @@ module Prawn
           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
@@ -138,7 +137,7 @@ module Prawn
       #                         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
@@ -151,7 +150,7 @@ module Prawn
           restore_graphics_state
         end
       end
-
+      
     end
   end
 end

data/lib/prawn/graphics/transparency.rb

@@ -30,8 +30,6 @@ module Prawn
     #
     module Transparency
 
-      # @group Stable API
-
       # Sets the <tt>opacity</tt> and <tt>stroke_opacity</tt> for all
       # the content within the <tt>block</tt>
       # If <tt>stroke_opacity</tt> is not provided, then it takes on
@@ -88,7 +86,7 @@ module Prawn
                                     )
 
           dictionary_name = "Tr#{next_opacity_dictionary_id}"
-          opacity_dictionary_registry[key] = { :name => dictionary_name,
+          opacity_dictionary_registry[key] = { :name => dictionary_name, 
                                                :obj  => dictionary }
         end
 

data/lib/prawn/images.rb

@@ -6,16 +6,18 @@
 # This is free software. Please see the LICENSE and COPYING files for details.
 
 require 'digest/sha1'
-require 'pathname'
 
 module Prawn
 
   module Images
-    # @group Stable API
 
     # Add the image at filename to the current page. Currently only
-    # JPG and PNG files are supported. (Note that processing PNG
-    # images with alpha channels can be processor and memory intensive.)
+    # JPG and PNG files are supported.
+    #
+    # NOTE: Prawn is very slow at rendering PNGs with alpha channels.  The
+    # workaround for those who don't mind installing RMagick is to use:
+    #
+    # http://github.com/amberbit/prawn-fast-png
     #
     # Arguments:
     # <tt>file</tt>:: path to file or an object that responds to #read
@@ -23,22 +25,22 @@ module Prawn
     # Options:
     # <tt>:at</tt>:: an array [x,y] with the location of the top left corner of the image.
     # <tt>:position</tt>::  One of (:left, :center, :right) or an x-offset
-    # <tt>:vposition</tt>::  One of (:top, :center, :center) or an y-offset
+    # <tt>:vposition</tt>::  One of (:top, :center, :center) or an y-offset    
     # <tt>:height</tt>:: the height of the image [actual height of the image]
     # <tt>:width</tt>:: the width of the image [actual width of the image]
     # <tt>:scale</tt>:: scale the dimensions of the image proportionally
     # <tt>:fit</tt>:: scale the dimensions of the image proportionally to fit inside [width,height]
+    # 
+    #   Prawn::Document.generate("image2.pdf", :page_layout => :landscape) do     
+    #     pigs = "#{Prawn::BASEDIR}/data/images/pigs.jpg" 
+    #     image pigs, :at => [50,450], :width => 450                                      
     #
-    #   Prawn::Document.generate("image2.pdf", :page_layout => :landscape) do
-    #     pigs = "#{Prawn::DATADIR}/images/pigs.jpg"
-    #     image pigs, :at => [50,450], :width => 450
-    #
-    #     dice = "#{Prawn::DATADIR}/images/dice.png"
-    #     image dice, :at => [50, 450], :scale => 0.75
-    #   end
+    #     dice = "#{Prawn::BASEDIR}/data/images/dice.png"
+    #     image dice, :at => [50, 450], :scale => 0.75 
+    #   end   
     #
     # If only one of :width / :height are provided, the image will be scaled
-    # proportionally.  When both are provided, the image will be stretched to
+    # proportionally.  When both are provided, the image will be stretched to 
     # fit the dimensions without maintaining the aspect ratio.
     #
     #
@@ -52,16 +54,16 @@ module Prawn
     #
     #   require "open-uri"
     #
-    #   Prawn::Document.generate("remote_images.pdf") do
+    #   Prawn::Document.generate("remote_images.pdf") do 
     #     image open("http://prawn.majesticseacreature.com/media/prawn_logo.png")
     #   end
     #
     # This method returns an image info object which can be used to check the
-    # dimensions of an image object if needed.
+    # dimensions of an image object if needed. 
     # (See also: Prawn::Images::PNG , Prawn::Images::JPG)
-    #
+    # 
     def image(file, options={})
-      Prawn.verify_options [:at, :position, :vposition, :height,
+      Prawn.verify_options [:at, :position, :vposition, :height, 
                             :width, :scale, :fit], options
 
       pdf_obj, info = build_image_object(file)
@@ -70,14 +72,17 @@ module Prawn
       info
     end
 
-
     # Builds an info object (Prawn::Images::*) and a PDF reference representing
     # the given image. Return a pair: [pdf_obj, info].
     #
-    # @private
     def build_image_object(file)
-      io = verify_and_open_image(file)
-      image_content = io.read
+      if file.respond_to?(:read)
+        image_content = file.read
+      else
+        raise ArgumentError, "#{file} not found" unless File.file?(file)  
+        image_content = File.binread(file)
+      end
+      
       image_sha1 = Digest::SHA1.hexdigest(image_content)
 
       # if this image has already been embedded, just reuse it
@@ -86,7 +91,11 @@ module Prawn
         image_obj = image_registry[image_sha1][:obj]
       else
         # Build the image object
-        info = Prawn.image_handler.find(image_content).new(image_content)
+        klass = case Image.detect_image_format(image_content)
+                when :jpg then Prawn::Images::JPG
+                when :png then Prawn::Images::PNG
+                end
+        info = klass.new(image_content)
 
         # Bump PDF version if the image requires it
         min_version(info.min_pdf_version) if info.respond_to?(:min_pdf_version)
@@ -104,16 +113,15 @@ module Prawn
     # build_image_object), embed the image according to the <tt>options</tt>
     # given.
     #
-    # @private
     def embed_image(pdf_obj, info, options)
-      # find where the image will be placed and how big it will be
+      # find where the image will be placed and how big it will be  
       w,h = info.calc_image_dimensions(options)
 
-      if options[:at]
-        x,y = map_to_absolute(options[:at])
-      else
-        x,y = image_position(w,h,options)
-        move_text_position h
+      if options[:at]     
+        x,y = map_to_absolute(options[:at]) 
+      else                  
+        x,y = image_position(w,h,options) 
+        move_text_position h   
       end
 
       # add a reference to the image object to the current page
@@ -125,30 +133,22 @@ module Prawn
       instruct = "\nq\n%.3f 0 0 %.3f %.3f %.3f cm\n/%s Do\nQ"
       add_content instruct % [ w, h, x, y - h, label ]
     end
-
-    private
-
-    def verify_and_open_image(io_or_path)
-      # File or IO
-      if io_or_path.respond_to?(:rewind)
-        io = io_or_path
-        # Rewind if the object we're passed is an IO, so that multiple embeds of
-        # the same IO object will work
-        io.rewind
-        # read the file as binary so the size is calculated correctly
-        # guard binmode because some objects acting io-like don't implement it
-        io.binmode if io.respond_to?(:binmode)
-        return io
-      end
-      # String or Pathname
-      io_or_path = Pathname.new(io_or_path)
-      raise ArgumentError, "#{io_or_path} not found" unless io_or_path.file?
-      io = io_or_path.open('rb')
-      io
-    end
+    
+    private   
 
     def image_position(w,h,options)
       options[:position] ||= :left
+      
+      x = case options[:position] 
+      when :left
+        bounds.absolute_left
+      when :center
+        bounds.absolute_left + (bounds.width - w) / 2.0 
+      when :right
+        bounds.absolute_right - w
+      when Numeric
+        options[:position] + bounds.absolute_left
+      end
 
       y = case options[:vposition]
       when :top
@@ -162,30 +162,20 @@ module Prawn
       else
         determine_y_with_page_flow(h)
       end
-
-      x = case options[:position]
-      when :left
-        bounds.left_side
-      when :center
-        bounds.left_side + (bounds.width - w) / 2.0
-      when :right
-        bounds.right_side - w
-      when Numeric
-        options[:position] + bounds.left_side
-      end
-
       return [x,y]
-    end
-
+    end 
+    
     def determine_y_with_page_flow(h)
       if overruns_page?(h)
-        bounds.move_past_bottom
+        start_new_page
+        bounds.absolute_top 
+      else
+        self.y
       end
-      self.y
-    end
-
+    end 
+    
     def overruns_page?(h)
-      (self.y - h) < reference_bounds.absolute_bottom
+      (self.y - h) < reference_bounds.absolute_bottom 
     end
 
     def image_registry