prawn 1.0.0.rc2 → 1.0.0

data/lib/prawn/document/bounding_box.rb

@@ -8,6 +8,7 @@
 
 module Prawn
   class Document
+    # @group Stable API
 
     # :call-seq:
     #   bounding_box(point, options={}, &block)
@@ -188,10 +189,21 @@ module Prawn
 
       parent_box = @bounding_box
 
+      original_ypos = y
+
       init_block.call(parent_box)
 
       self.y = @bounding_box.absolute_top
       user_block.call
+
+      # If the user actions did not modify the y position
+      # restore the original y position before the bounding
+      # box was created.
+      
+      if y == @bounding_box.absolute_top
+        self.y = original_ypos
+      end
+
       unless options[:hold_position] || @bounding_box.stretchy?
         self.y = @bounding_box.absolute_bottom
       end
@@ -208,7 +220,7 @@ module Prawn
     #
     class BoundingBox
 
-      def initialize(document, parent, point, options={}) #:nodoc:
+      def initialize(document, parent, point, options={}) # @private
         unless options[:width]
           raise ArgumentError, "BoundingBox needs the :width option to be set"
         end
@@ -222,15 +234,22 @@ module Prawn
         @stretched_height = nil
       end
 
+      # @private
+
       attr_reader :document, :parent
+
+      # @private
       # The current indentation of the left side of the bounding box.
       attr_reader :total_left_padding
+
+      # @private
       # The current indentation of the right side of the bounding box.
       attr_reader :total_right_padding
 
       # The translated origin (x,y-height) which describes the location
       # of the bottom left corner of the bounding box
       #
+      # @private
       def anchor
         [@x, @y - height]
       end
@@ -261,6 +280,7 @@ module Prawn
       #    text "indented on both sides"
       #  end
       #
+      # @private
       def indent(left_padding, right_padding = 0, &block)
         add_left_padding(left_padding)
         add_right_padding(right_padding)
@@ -271,6 +291,7 @@ module Prawn
       end
 
       # Increase the left padding of the bounding box.
+      # @private
       def add_left_padding(left_padding)
         @total_left_padding += left_padding
         @x += left_padding
@@ -278,6 +299,7 @@ module Prawn
       end
 
       # Decrease the left padding of the bounding box.
+      # @private
       def subtract_left_padding(left_padding)
         @total_left_padding -= left_padding
         @x -= left_padding
@@ -285,12 +307,14 @@ module Prawn
       end
 
       # Increase the right padding of the bounding box.
+      # @private
       def add_right_padding(right_padding)
         @total_right_padding += right_padding
         @width -= right_padding
       end
 
       # Decrease the right padding of the bounding box.
+      # @private
       def subtract_right_padding(right_padding)
         @total_right_padding -= right_padding
         @width += right_padding
@@ -441,15 +465,19 @@ module Prawn
       end
 
       # an alias for absolute_left
+      # @private
       def left_side
         absolute_left
       end
 
       # an alias for absolute_right
+      # @private
       def right_side
         absolute_right
       end
 
+      # @group Extension API
+
       # Moves to the top of the next page of the document, starting a new page
       # if necessary.
       #
@@ -461,9 +489,6 @@ module Prawn
         end
       end
 
-
-      alias_method :update_height, :height
-
       # Returns +false+ when the box has a defined height, +true+ when the height
       # is being calculated on the fly based on the current vertical position.
       #
@@ -482,9 +507,12 @@ module Prawn
         end
       end
 
+      alias_method :update_height, :height
+
       # Returns a deep copy of these bounds (including all parent bounds but
       # not copying the reference to the Document).
       #
+      # @private
       def deep_copy
         copy = dup
         # Deep-copy the parent bounds
@@ -499,6 +527,7 @@ module Prawn
       # context of the given +document+. Does *not* set the bounds of the
       # document to the resulting BoundingBox, only returns it.
       #
+      # @private
       def self.restore_deep_copy(bounds, document)
         bounds.instance_variable_set("@document", document)
         bounds

data/lib/prawn/document/column_box.rb

@@ -3,23 +3,31 @@
 # column_box.rb: Extends BoundingBox to allow for columns of text
 #
 # Author Paul Ostazeski.
+#
+# This is free software. Please see the LICENSE and COPYING files for details.
+
+require_relative "bounding_box"
 
-require "prawn/document/bounding_box"
 module Prawn
   class Document
 
+    # @group Experimental API
+
     # A column box is a bounding box with the additional property that when
     # text flows past the bottom, it will wrap first to another column on the
     # same page, and only flow to the next page when all the columns are
     # filled.
     #
     # column_box accepts the same parameters as bounding_box, as well as the
-    # number of :columns and a :spacer (in points) between columns.
+    # number of :columns and a :spacer (in points) between columns. If resetting
+    # the top margin is desired on a new page (e.g. to allow for initial page 
+    # wide column titles) the option :reflow_margins => true can be set.
     #
-    # Defaults are :columns = 3 and :spacer = font_size
+    # Defaults are :columns = 3, :spacer = font_size, and 
+    # :reflow_margins => false
     # 
     # Under PDF::Writer, "spacer" was known as "gutter"
-    # 
+    #
     def column_box(*args, &block)
       init_column_box(block) do |parent_box|
         map_to_absolute!(args[0])
@@ -40,7 +48,7 @@ module Prawn
 
       @bounding_box = parent_box
     end
-    
+
     # Implements the necessary functionality to allow Document#column_box to
     # work.
     #
@@ -51,6 +59,7 @@ module Prawn
         @columns = options[:columns] || 3
         @spacer  = options[:spacer]  || @document.font_size
         @current_column = 0
+        @reflow_margins = options[:reflow_margins]
       end
 
       # The column width, not the width of the whole box,
@@ -99,10 +108,13 @@ module Prawn
 
       # Moves to the next column or starts a new page if currently positioned at
       # the rightmost column.
-      def move_past_bottom 
+      def move_past_bottom
         @current_column = (@current_column + 1) % @columns
         @document.y = @y
         if 0 == @current_column
+          if @reflow_margins
+            @y = @parent.absolute_top
+          end
           @document.start_new_page
         end
       end

data/lib/prawn/document/graphics_state.rb

@@ -8,71 +8,8 @@
 #
 
 module Prawn
-  class GraphicStateStack
-    attr_accessor :stack
-    
-    def initialize(previous_state = nil)
-      self.stack = [GraphicState.new(previous_state)]
-    end
-    
-    def save_graphic_state(graphic_state = nil)
-      stack.push(GraphicState.new(graphic_state || current_state))
-    end
-    
-    def restore_graphic_state
-      if stack.empty?
-        raise Prawn::Errors::EmptyGraphicStateStack, 
-          "\n You have reached the end of the graphic state stack" 
-      end
-      stack.pop
-    end
-    
-    def current_state
-      stack.last
-    end
-    
-    def present?
-      stack.size > 0
-    end
-
-    def empty?
-      stack.empty?
-    end
-      
-  end
-  
-  class GraphicState
-    attr_accessor :color_space, :dash, :cap_style, :join_style, :line_width, :fill_color, :stroke_color
-    
-    def initialize(previous_state = nil)
-      @color_space = previous_state ? previous_state.color_space.dup : {}
-      @fill_color = previous_state ? previous_state.fill_color : "000000"
-      @stroke_color = previous_state ? previous_state.stroke_color : "000000"
-      @dash = previous_state ? previous_state.dash : { :dash => nil, :space => nil, :phase => 0 }
-      @cap_style = previous_state ? previous_state.cap_style : :butt
-      @join_style = previous_state ? previous_state.join_style : :miter
-      @line_width = previous_state ? previous_state.line_width : 1
-    end
-    
-    def dash_setting
-      "[#{@dash[:dash]} #{@dash[:space]}] #{@dash[:phase]} d"
-    end
-  end
-  
-  module Core
-    class Page
-      module GraphicsState
-      
-        def graphic_state
-          stack.current_state
-        end
-    
-      end
-    end
-  end
-  
   class Document
-    module GraphicsState
+    module GraphicsState # @private
 
       # Pushes the current graphics state on to the graphics state stack so we
       # can restore it when finished with a change we want to isolate (such as
@@ -93,15 +30,15 @@ module Prawn
       #     text "rotated text"
       #   end
       #
-      
+
       def open_graphics_state
         add_content "q"
       end
-      
+
       def close_graphics_state
         add_content "Q"
       end
-        
+
       def save_graphics_state(graphic_state = nil)
         graphic_stack.save_graphic_state(graphic_state)
         open_graphics_state
@@ -115,22 +52,22 @@ module Prawn
       # restores the state to those values
       def restore_graphics_state
         if graphic_stack.empty?
-          raise Prawn::Errors::EmptyGraphicStateStack, 
-            "\n You have reached the end of the graphic state stack" 
+          raise PDF::Core::Errors::EmptyGraphicStateStack,
+            "\n You have reached the end of the graphic state stack"
         end
-        close_graphics_state 
+        close_graphics_state
         graphic_stack.restore_graphic_state
       end
-      
+
       def graphic_stack
         state.page.stack
       end
-      
+
       def graphic_state
         save_graphics_state unless graphic_stack.current_state
-        graphic_stack.current_state 
+        graphic_stack.current_state
       end
-      
+
     end
   end
 end

data/lib/prawn/document/internals.rb

@@ -7,26 +7,26 @@
 # This is free software. Please see the LICENSE and COPYING files for details.
 
 module Prawn
-  class Document     
-    
+  class Document
+
     # This module exposes a few low-level PDF features for those who want
     # to extend Prawn's core functionality.  If you are not comfortable with
     # low level PDF functionality as defined by Adobe's specification, chances
-    # are you won't need anything you find here.  
+    # are you won't need anything you find here.
     #
-    module Internals    
-      
+    # @private
+    module Internals 
       # Creates a new Prawn::Reference and adds it to the Document's object
-      # list.  The +data+ argument is anything that Prawn::PdfObject() can convert. 
+      # list.  The +data+ argument is anything that Prawn::PdfObject() can convert.
+      #
+      # Returns the identifier which points to the reference in the ObjectStore
       #
-      # Returns the identifier which points to the reference in the ObjectStore   
-      # 
       def ref(data)
         ref!(data).identifier
-      end                                               
+      end
 
       # Like ref, but returns the actual reference instead of its identifier.
-      # 
+      #
       # While you can use this to build up nested references within the object
       # tree, it is recommended to persist only identifiers, and them provide
       # helper methods to look up the actual references in the ObjectStore
@@ -42,21 +42,21 @@ module Prawn
       # of if it's hidden behind a Prawn::Reference, wrap it in deref().
       #
       def deref(obj)
-        obj.is_a?(Prawn::Core::Reference) ? obj.data : obj
+        obj.is_a?(PDF::Core::Reference) ? obj.data : obj
       end
 
       # Appends a raw string to the current page content.
-      #                               
-      #  # Raw line drawing example:           
+      #
+      #  # Raw line drawing example:
       #  x1,y1,x2,y2 = 100,500,300,550
-      #  pdf.add_content("%.3f %.3f m" % [ x1, y1 ])  # move 
+      #  pdf.add_content("%.3f %.3f m" % [ x1, y1 ])  # move
       #  pdf.add_content("%.3f %.3f l" % [ x2, y2 ])  # draw path
-      #  pdf.add_content("S") # stroke                    
+      #  pdf.add_content("S") # stroke
       #
       def add_content(str)
         save_graphics_state if graphic_state.nil?
         state.page.content << str << "\n"
-      end  
+      end
 
       # The Name dictionary (PDF spec 3.6.3) for this document. It is
       # lazily initialized, so that documents that do not need a name
@@ -67,7 +67,7 @@ module Prawn
       end
 
       # Returns true if the Names dictionary is in use for this document.
-      # 
+      #
       def names?
         state.store.root.data[:Names]
       end
@@ -87,8 +87,8 @@ module Prawn
             state.on_page_create_callback = nil
          end
       end
-      
-      private      
+
+      private
 
       # adds a new, empty content stream to each page. Used in templating so
       # that imported content streams can be left pristine
@@ -100,6 +100,7 @@ module Prawn
           apply_margin_options(options)
           generate_margin_box
           use_graphic_settings(options[:template])
+          forget_text_rendering_mode!
         end
       end
 
@@ -156,18 +157,18 @@ module Prawn
       # Write out the PDF Trailer, as per spec 3.4.4
       #
       def render_trailer(output)
-        trailer_hash = {:Size => state.store.size + 1, 
+        trailer_hash = {:Size => state.store.size + 1,
                         :Root => state.store.root,
                         :Info => state.store.info}
         trailer_hash.merge!(state.trailer) if state.trailer
 
         output << "trailer\n"
-        output << Prawn::Core::PdfObject(trailer_hash) << "\n"
-        output << "startxref\n" 
+        output << PDF::Core::PdfObject(trailer_hash) << "\n"
+        output << "startxref\n"
         output << @xref_offset << "\n"
         output << "%%EOF" << "\n"
       end
-                 
+
     end
   end
 end

data/lib/prawn/document/span.rb

@@ -8,8 +8,10 @@
 
 module Prawn
   class Document
-    # A span is a special purpose bounding box that allows a column of 
-    # elements to be positioned relative to the margin_box.  
+    # @group Stable API
+
+    # A span is a special purpose bounding box that allows a column of
+    # elements to be positioned relative to the margin_box.
     #
     # Arguments:
     # +width+:: The width of the column in PDF points
@@ -17,23 +19,23 @@ module Prawn
     # Options:
     # <tt>:position</tt>:: One of :left, :center, :right or an x offset
     #
-    # This method is typically used for flowing a column of text from one 
+    # This method is typically used for flowing a column of text from one
     # page to the next.
     #
     #  span(350, :position => :center) do
     #    text "Here's some centered text in a 350 point column. " * 100
     #  end
-    #  
+    #
     def span(width, options={})
       Prawn.verify_options [:position], options
-      original_position = self.y      
-     
+      original_position = self.y
+
       # FIXME: Any way to move this upstream?
       left_boundary = case(options[:position] || :left)
       when :left
         margin_box.absolute_left
       when :center
-        margin_box.absolute_left + margin_box.width / 2.0 - width /2.0
+        margin_box.absolute_left + margin_box.width / 2.0 - width / 2.0
       when :right
         margin_box.absolute_right - width
       when Numeric
@@ -41,15 +43,15 @@ module Prawn
       else
         raise ArgumentError, "Invalid option for :position"
       end
-      
+
       # we need to bust out of whatever nested bounding boxes we're in.
       canvas do
-        bounding_box([left_boundary, 
+        bounding_box([left_boundary,
                       margin_box.absolute_top], :width => width) do
           self.y = original_position
           yield
         end
-      end          
+      end
     end
   end
 end