prawn 1.0.0.rc2 → 1.0.0

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,6 +9,7 @@
 module Prawn
   module Graphics
     module CapStyle
+      # @group Stable API
 
       CAP_STYLES = { :butt => 0, :round => 1, :projecting_square => 2 }
 
@@ -30,11 +31,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,6 +9,7 @@
 module Prawn
   module Graphics
     module Color
+      # @group Stable API
 
       # Sets or returns the fill color.
       #
@@ -166,7 +167,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)
@@ -174,7 +175,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)
@@ -192,7 +193,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
@@ -201,7 +202,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,35 +9,59 @@
 module Prawn
   module Graphics
     module Dash
+      # @group Stable API
 
-      # Sets the dash pattern for stroked lines and curves
+      # Sets the dash pattern for stroked lines and curves or return the
+      # current dash pattern setting if +length+ is nil.
       #
-      #   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
+      # There are two ways to set the dash pattern:
       #
-      #   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
+      # * 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.
       #
-      #   integers or floats may be used for length and the options
+      #   Examples:
       #
-      #   dash units are in PDF points ( 1/72 in )
-      #   
-      def dash(length=nil, options={})        
-        return current_dash_state || undash_hash if length.nil?
+      #     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?
 
-        self.current_dash_state = { :dash  => length, 
-                  :space => options[:space] || length, 
+        self.current_dash_state = { :dash  => length,
+                  :space => length.kind_of?(Array) ? nil : options[:space] || length,
                   :phase => options[:phase] || 0 }
 
         write_stroke_dash
       end
-      
+
       alias_method :dash=, :dash
 
       # Stops dashing, restoring solid stroked lines and curves
@@ -46,37 +70,35 @@ 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
-      
-      private 
-        
-      def current_dash_state=(dash_options)  
+
+      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/join_style.rb

@@ -1,4 +1,4 @@
-# encoding: utf-8   
+# encoding: utf-8
 
 # join_style.rb : Implements stroke join styling
 #
@@ -10,7 +10,9 @@ 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
@@ -25,19 +27,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/patterns.rb

@@ -10,19 +10,14 @@
 module Prawn
   module Graphics
     module Patterns
+      # @group Stable API
 
       # Sets the fill gradient from color1 to color2.
       # old arguments: point, width, height, color1, color2, options = {}
       # new arguments: from, to, color1, color1
       #            or  from, r1, to, r2, color1, color2
       def fill_gradient(*args)
-        if args[1].is_a?(Array) || args[2].is_a?(Array)
-          set_gradient(:fill, *args)
-        else
-          warn "[DEPRECATION] 'fill_gradient(point, width, height,...)' is deprecated in favor of 'fill_gradient(from, to,...)'. " +
-               "Old arguments will be removed in release 1.1"
-          set_gradient :fill, args[0], [args[0].first, args[0].last - args[2]], args[3], args[4]
-        end
+        set_gradient(:fill, *args)
       end
 
       # Sets the stroke gradient from color1 to color2.
@@ -30,13 +25,7 @@ module Prawn
       # new arguments: from, to, color1, color2
       #            or  from, r1, to, r2, color1, color2
       def stroke_gradient(*args)
-        if args[1].is_a?(Array) || args[2].is_a?(Array)
-          set_gradient(:stroke, *args)
-        else
-          warn "[DEPRECATION] 'stroke_gradient(point, width, height,...)' is deprecated in favor of 'stroke_gradient(from, to,...)'. " +
-               "Old arguments will be removed in release 1.1"
-          set_gradient :stroke, args[0], [args[0].first, args[0].last - args[2]], args[3], args[4]
-        end
+        set_gradient(:stroke, *args)
       end
 
       private
@@ -125,7 +114,7 @@ module Prawn
           :Extend => [true, true],
         })
 
-        shading_pattern = ref!({
+        ref!({
           :PatternType => 2, # shading pattern
           :Shading => shading,
           :Matrix => [1, 0,

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,7 +10,8 @@
 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.
       #
@@ -22,7 +23,7 @@ module Prawn
       # provided, but no block is given
       #
       # Example without a block:
-      #   
+      #
       #   save_graphics_state
       #   rotate 30
       #   text "rotated text"
@@ -62,7 +63,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"
@@ -82,7 +83,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.
       #
@@ -94,7 +95,7 @@ module Prawn
       # provided, but no block is given
       #
       # Example without a block:
-      #   
+      #
       #   save_graphics_state
       #   scale 1.5
       #   text "scaled text"
@@ -126,7 +127,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
@@ -137,7 +138,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
@@ -150,7 +151,7 @@ module Prawn
           restore_graphics_state
         end
       end
-      
+
     end
   end
 end

data/lib/prawn/graphics/transparency.rb

@@ -30,6 +30,8 @@ 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
@@ -86,7 +88,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/{layout/grid.rb → grid.rb}

@@ -1,15 +1,28 @@
+# grid.rb: Provides a basic grid layout system for Prawn
+#
+# Contributed by Andrew O'Brien in March 2009
+#
+# This is free software. Please see the LICENSE and COPYING files for details.
+
 module Prawn
   class Document
-    
-    # Defines the grid system for a particular document.  Takes the number of 
-    # rows and columns and the width to use for the gutter as the 
+    # @group Experimental API
+
+    # Defines the grid system for a particular document.  Takes the number of
+    # rows and columns and the width to use for the gutter as the
     # keys :rows, :columns, :gutter, :row_gutter, :column_gutter
     #
+    # Note that a completely new grid object is built each time define_grid()
+    # is called. This means that all subsequent calls to grid() will use
+    # the newly defined Grid object -- grids are not nestable like 
+    # bounding boxes are.
+
     def define_grid(options = {})
+      @boxes = nil
       @grid = Grid.new(self, options)
     end
-  
-    # A method that can either be used to access a particular grid on the page 
+
+    # A method that can either be used to access a particular grid on the page
     # or work with the grid system directly.
     #
     #   @pdf.grid                 # Get the Grid directly
@@ -22,7 +35,7 @@ module Prawn
         @grid
       else
         g1, g2 = args
-        if(g1.class == Array && g2.class == Array && 
+        if(g1.class == Array && g2.class == Array &&
           g1.length == 2 && g2.length == 2)
           multi_box(single_box(*g1), single_box(*g2))
         else
@@ -30,15 +43,17 @@ module Prawn
         end
       end
     end
-  
-    # A Grid represents the entire grid system of a Page and calculates 
+
+    # A Grid represents the entire grid system of a Page and calculates
     # the column width and row height of the base box.
+    #
+    # @private
     class Grid
       attr_reader :pdf, :columns, :rows, :gutter, :row_gutter, :column_gutter
       def initialize(pdf, options = {}) # :nodoc:
         valid_options = [:columns, :rows, :gutter, :row_gutter, :column_gutter]
         Prawn.verify_options valid_options, options
-      
+
         @pdf = pdf
         @columns = options[:columns]
         @rows = options[:rows]
@@ -49,7 +64,7 @@ module Prawn
       def column_width
         @column_width ||= subdivide(pdf.bounds.width, columns, column_gutter)
       end
-    
+
       # Calculates the base height of boxes.
       def row_height
        @row_height ||= subdivide(pdf.bounds.height, rows, row_gutter)
@@ -65,11 +80,11 @@ module Prawn
       end
 
       private
-      
+
       def subdivide(total, num, gutter)
         (total.to_f - (gutter * (num - 1).to_f)) / num.to_f
       end
-      
+
       def set_gutter(options)
         if options.has_key?(:gutter)
           @gutter = options[:gutter].to_f
@@ -81,92 +96,93 @@ module Prawn
         end
       end
     end
-  
-    # A Box is a class that represents a bounded area of a page.  
-    # A Grid object has methods that allow easy access to the coordinates of 
+
+    # A Box is a class that represents a bounded area of a page.
+    # A Grid object has methods that allow easy access to the coordinates of
     # its corners, which can be plugged into most existing prawnmethods.
     #
-    class Box #:nodoc:
+    # @private
+    class GridBox
       attr_reader :pdf
-    
+
       def initialize(pdf, i, j)
         @pdf = pdf
         @i = i
         @j = j
       end
-    
-      # Mostly diagnostic method that outputs the name of a box as 
+
+      # Mostly diagnostic method that outputs the name of a box as
       # col_num, row_num
       #
       def name
         "#{@i.to_s},#{@j.to_s}"
       end
-      
+
       # :nodoc
       def total_height
         pdf.bounds.height.to_f
       end
-      
+
       # Width of a box
       def width
         grid.column_width.to_f
       end
-    
+
       # Height of a box
       def height
         grid.row_height.to_f
       end
-      
+
       # Width of the gutter
       def gutter
         grid.gutter.to_f
       end
-      
+
       # x-coordinate of left side
       def left
         @left ||= (width + grid.column_gutter) * @j.to_f
       end
-    
-      # x-coordinate of right side 
+
+      # x-coordinate of right side
       def right
         @right ||= left + width
       end
-    
+
       # y-coordinate of the top
       def top
         @top ||= total_height - ((height + grid.row_gutter) * @i.to_f)
       end
-    
+
       # y-coordinate of the bottom
       def bottom
         @bottom ||= top - height
       end
-    
+
       # x,y coordinates of top left corner
       def top_left
         [left, top]
       end
-    
-      # x,y coordinates of top right corner    
+
+      # x,y coordinates of top right corner
       def top_right
         [right, top]
       end
-    
+
       # x,y coordinates of bottom left corner
       def bottom_left
         [left, bottom]
       end
-    
+
       # x,y coordinates of bottom right corner
       def bottom_right
         [right, bottom]
       end
-    
+
       # Creates a standard bounding box based on the grid box.
       def bounding_box(&blk)
         pdf.bounding_box(top_left, :width => width, :height => height, &blk)
       end
-    
+
       # Diagnostic method
       def show(grid_color = "CCCCCC")
         self.bounding_box do
@@ -175,28 +191,30 @@ module Prawn
           pdf.stroke_color = grid_color
           pdf.text self.name
           pdf.stroke_bounds
-          
+
           pdf.stroke_color = original_stroke_color
         end
       end
-    
+
       private
       def grid
         pdf.grid
       end
     end
-  
+
     # A MultiBox is specified by 2 Boxes and spans the areas between.
-    class MultiBox < Box #:nodoc:
+    #
+    # @private
+    class MultiBox < GridBox #:nodoc:
       def initialize(pdf, b1, b2)
         @pdf = pdf
         @bs = [b1, b2]
       end
-    
+
       def name
         @bs.map {|b| b.name}.join(":")
       end
-    
+
       def total_height
         @bs[0].total_height
       end
@@ -204,54 +222,54 @@ module Prawn
       def width
         right_box.right - left_box.left
       end
-    
+
       def height
         top_box.top - bottom_box.bottom
       end
-    
+
       def gutter
         @bs[0].gutter
       end
-    
+
       def left
         left_box.left
       end
-    
+
       def right
         right_box.right
       end
-    
+
       def top
         top_box.top
       end
-    
+
       def bottom
         bottom_box.bottom
       end
-    
+
       private
       def left_box
         @left_box ||= @bs.min {|a,b| a.left <=> b.left}
       end
-    
+
       def right_box
         @right_box ||= @bs.max {|a,b| a.right <=> b.right}
       end
-    
+
       def top_box
         @top_box ||= @bs.max {|a,b| a.top <=> b.top}
       end
-    
+
       def bottom_box
         @bottom_box ||= @bs.min {|a,b| a.bottom <=> b.bottom}
       end
     end
-  
+
     private
     def single_box(i, j)
-      Box.new(self, i, j)
+      GridBox.new(self, i, j)
     end
-  
+
     def multi_box(b1, b2)
       MultiBox.new(self, b1, b2)
     end