piglop-prawn 0.10.2.1

data/lib/prawn/document/bounding_box.rb

@@ -0,0 +1,425 @@
+# encoding: utf-8
+
+# bounding_box.rb : Implements a mechanism for shifting the coordinate space
+#
+# Copyright May 2008, Gregory Brown. All Rights Reserved.
+#
+# This is free software. Please see the LICENSE and COPYING files for details.
+
+module Prawn
+  class Document
+    
+    # :call-seq: 
+    #   bounding_box(point, options={}, &block) 
+    #
+    # A bounding box serves two important purposes:
+    # * Provide bounds for flowing text, starting at a given point
+    # * Translate the origin (0,0) for graphics primitives
+    #
+    # A point and :width must be provided. :height is optional. 
+    # (See stretchyness below)
+    # 
+    # ==Positioning
+    # 
+    # Bounding boxes are positioned relative to their top left corner and
+    # the width measurement is towards the right and height measurement is
+    # downwards.
+    # 
+    # Usage:
+    # 
+    # * Bounding box 100pt x 100pt in the absolute bottom left of the 
+    #   containing box:
+    # 
+    #   pdf.bounding_box([0,100], :width => 100, :height => 100)
+    #     stroke_bounds
+    #   end
+    # 
+    # * Bounding box 200pt x 400pt high in the center of the page:
+    # 
+    #   x_pos = ((bounds.width / 2) - 150)
+    #   y_pos = ((bounds.height / 2) + 200)
+    #   pdf.bounding_box([x_pos, y_pos], :width => 300, :height => 400) do
+    #     stroke_bounds
+    #   end
+    #
+    # ==Flowing Text
+    #
+    # When flowing text, the usage of a bounding box is simple. Text will
+    # begin at the point specified, flowing the width of the bounding box.
+    # After the block exits, the cursor position will be moved to
+    # the bottom of the bounding box (y - height). If flowing text exceeds
+    # the height of the bounding box, the text will be continued on the next
+    # page, starting again at the top-left corner of the bounding box.
+    #
+    # Usage:
+    #
+    #   pdf.bounding_box([100,500], :width => 100, :height => 300) do
+    #     pdf.text "This text will flow in a very narrow box starting" +
+    #      "from [100,500]. The pointer will then be moved to [100,200]" +
+    #      "and return to the margin_box"
+    #   end
+    #
+    # Note, this is a low level tool and is designed primarily for building
+    # other abstractions.  If you just need to flow text on the page, you
+    # will want to look at text_box() instead
+    #
+    # ==Translating Coordinates
+    # 
+    # When translating coordinates, the idea is to allow the user to draw
+    # relative to the origin, and then translate their drawing to a specified
+    # area of the document, rather than adjust all their drawing coordinates
+    # to match this new region.
+    #
+    # Take for example two triangles which share one point, drawn from the
+    # origin:
+    #
+    #   pdf.polygon [0,250], [0,0], [150,100]
+    #   pdf.polygon [100,0], [150,100], [200,0]
+    #
+    # It would be easy enough to translate these triangles to another point,
+    # e.g [200,200]
+    #
+    #   pdf.polygon [200,450], [200,200], [350,300]
+    #   pdf.polygon [300,200], [350,300], [400,200]
+    #
+    # However, each time you want to move the drawing, you'd need to alter
+    # every point in the drawing calls, which as you might imagine, can become
+    # tedious.
+    #
+    # If instead, we think of the drawing as being bounded by a box, we can
+    # see that the image is 200 points wide by 250 points tall.
+    #
+    # To translate it to a new origin, we simply select a point at (x,y+height)
+    #
+    # Using the [200,200] example:
+    #
+    #   pdf.bounding_box([200,450], :width => 200, :height => 250) do
+    #     pdf.stroke do
+    #       pdf.polygon [0,250], [0,0], [150,100]
+    #       pdf.polygon [100,0], [150,100], [200,0]
+    #     end
+    #   end
+    #
+    # Notice that the drawing is still relative to the origin. If we want to
+    # move this drawing around the document, we simply need to recalculate the
+    # top-left corner of the rectangular bounding-box, and all of our graphics
+    # calls remain unmodified.
+    # 
+    # ==Nesting Bounding Boxes
+    # 
+    # At the top level, bounding boxes are specified relative to the document's 
+    # margin_box (which is itself a bounding box).  You can also nest bounding
+    # boxes, allowing you to build components which are relative to each other
+    #
+    # Usage:
+    # 
+    #  pdf.bounding_box([200,450], :width => 200, :height => 250) do
+    #    pdf.stroke_bounds   # Show the containing bounding box 
+    #    pdf.bounding_box([50,200], :width => 50, :height => 50) do
+    #      # a 50x50 bounding box that starts 50 pixels left and 50 pixels down 
+    #      # the parent bounding box.
+    #      pdf.stroke_bounds
+    #    end
+    #  end
+    # 
+    # ==Stretchyness
+    # 
+    # If you do not specify a height to a bounding box, it will become stretchy
+    # and its height will be calculated automatically as you stretch the box
+    # downwards.
+    # 
+    #  pdf.bounding_box([100,400], :width => 400) do
+    #    pdf.text("The height of this box is #{pdf.bounds.height}")
+    #    pdf.text('this is some text')
+    #    pdf.text('this is some more text')
+    #    pdf.text('and finally a bit more')
+    #    pdf.text("Now the height of this box is #{pdf.bounds.height}")
+    #  end
+    # 
+    # ==Absolute Positioning
+    # 
+    # If you wish to position the bounding boxes at absolute coordinates rather
+    # than relative to the margins or other bounding boxes, you can use canvas()
+    #
+    #  pdf.bounding_box([50,500], :width => 200, :height => 300) do
+    #    pdf.stroke_bounds
+    #    pdf.canvas do
+    #      Positioned outside the containing box at the 'real' (300,450)
+    #      pdf.bounding_box([300,450], :width => 200, :height => 200) do
+    #        pdf.stroke_bounds
+    #      end
+    #    end
+    #  end
+    #
+    # Of course, if you use canvas, you will be responsible for ensuring that
+    # you remain within the printable area of your document.
+    #
+    def bounding_box(*args, &block)    
+      init_bounding_box(block) do |_|
+        map_to_absolute!(args[0])     
+        @bounding_box = BoundingBox.new(self, *args)   
+      end
+    end 
+        
+    # A shortcut to produce a bounding box which is mapped to the document's
+    # absolute coordinates, regardless of how things are nested or margin sizes.
+    #
+    #   pdf.canvas do
+    #     pdf.line pdf.bounds.bottom_left, pdf.bounds.top_right
+    #   end
+    #
+    def canvas(&block)     
+      init_bounding_box(block, :hold_position => true) do |_|
+        @bounding_box = BoundingBox.new(self, [0,page.dimensions[3]], 
+          :width => page.dimensions[2], 
+          :height => page.dimensions[3] 
+        ) 
+      end
+    end  
+        
+    private
+    
+    def init_bounding_box(user_block, options={}, &init_block)
+      parent_box = @bounding_box       
+
+      init_block.call(parent_box)     
+
+      self.y = @bounding_box.absolute_top       
+      user_block.call   
+      self.y = @bounding_box.absolute_bottom unless options[:hold_position]
+
+      created_box, @bounding_box = @bounding_box, parent_box
+
+      return created_box
+    end   
+
+    # Low level layout helper that simplifies coordinate math.
+    #
+    # See Prawn::Document#bounding_box for a description of what this class
+    # is used for.
+    #
+    class BoundingBox
+      
+      def initialize(parent, point, options={}) #:nodoc:   
+        unless options[:width]
+          raise ArgumentError, "BoundingBox needs the :width option to be set"
+        end
+
+        @parent = parent
+        @x, @y = point
+        @width, @height = options[:width], options[:height]
+	      @stretched_height = nil
+      end
+
+      attr_reader :parent
+      
+      # The translated origin (x,y-height) which describes the location
+      # of the bottom left corner of the bounding box
+      #
+      def anchor
+        [@x, @y - height]
+      end
+      
+      # Relative left x-coordinate of the bounding box. (Always 0)
+      # 
+      # Example, position some text 3 pts from the left of the containing box:
+      # 
+      #  draw_text('hello', :at => [(bounds.left + 3), 0])
+      #
+      def left
+        0
+      end
+      
+      
+      # Temporarily adjust the @x coordinate to allow for left_padding
+      #
+      # Example:
+      #
+      #  indent 20 do
+      #     text "20 points in"
+      #     indent 30 do
+      #       text "50 points in"
+      #     end
+      #   end
+      #
+      def indent(left_padding, &block)
+        @x += left_padding
+        @width -= left_padding
+        yield
+      ensure
+        @x -= left_padding
+        @width += left_padding
+      end
+      
+      # Relative right x-coordinate of the bounding box. (Equal to the box width)
+      # 
+      # Example, position some text 3 pts from the right of the containing box:
+      # 
+      #  draw_text('hello', :at => [(bounds.right - 3), 0])
+      #
+      def right
+        @width
+      end
+      
+      # Relative top y-coordinate of the bounding box. (Equal to the box height)
+      #
+      # Example, position some text 3 pts from the top of the containing box:
+      # 
+      #  draw_text('hello', :at => [0, (bounds.top - 3)])
+      #
+      def top
+        height
+      end
+      
+      # Relative bottom y-coordinate of the bounding box (Always 0)
+      #
+      # Example, position some text 3 pts from the bottom of the containing box:
+      # 
+      #  draw_text('hello', :at => [0, (bounds.bottom + 3)])
+      #
+      def bottom
+        0
+      end
+
+      # Relative top-left point of the bounding_box
+      #
+      # Example, draw a line from the top left of the box diagonally to the 
+      # bottom right:
+      # 
+      #  stroke do
+      #    line(bounds., bounds.bottom_right)
+      #  end
+      #
+      def top_left
+        [left,top]
+      end
+
+      # Relative top-right point of the bounding box
+      #
+      # Example, draw a line from the top_right of the box diagonally to the 
+      # bottom left:
+      # 
+      #  stroke do
+      #    line(bounds.top_right, bounds.bottom_left)
+      #  end
+      #
+      def top_right
+        [right,top]
+      end
+
+      # Relative bottom-right point of the bounding box
+      #
+      # Example, draw a line along the right hand side of the page:
+      # 
+      #  stroke do
+      #    line(bounds.bottom_right, bounds.top_right)
+      #  end
+      #
+      def bottom_right
+        [right,bottom]
+      end
+
+      # Relative bottom-left point of the bounding box
+      #
+      # Example, draw a line along the left hand side of the page:
+      # 
+      #  stroke do
+      #    line(bounds.bottom_left, bounds.top_left)
+      #  end
+      #
+      def bottom_left
+        [left,bottom]
+      end
+      
+      # Absolute left x-coordinate of the bounding box
+      #
+      def absolute_left
+        @x
+      end
+      
+      # Absolute right x-coordinate of the bounding box
+      #
+      def absolute_right
+        @x + width
+      end
+      
+      # Absolute top y-coordinate of the bounding box
+      #
+      def absolute_top
+        @y
+      end
+      
+      # Absolute bottom y-coordinate of the bottom box
+      #
+      def absolute_bottom
+        @y - height
+      end
+
+      # Absolute top-left point of the bounding box
+      #
+      def absolute_top_left
+        [absolute_left, absolute_top]
+      end
+
+      # Absolute top-right point of the bounding box
+      #
+      def absolute_top_right
+        [absolute_right, absolute_top]
+      end
+
+      # Absolute bottom-left point of the bounding box
+      #
+      def absolute_bottom_left
+        [absolute_left, absolute_bottom]
+      end
+
+      # Absolute bottom-left point of the bounding box
+      #
+      def absolute_bottom_right
+        [absolute_right, absolute_bottom]
+      end
+      
+      # Width of the bounding box
+      #
+      def width
+        @width
+      end
+      
+      # Height of the bounding box.  If the box is 'stretchy' (unspecified
+      # height attribute), height is calculated as the distance from the top of
+      # the box to the current drawing position.
+      #
+      def height  
+        return @height if @height
+        @stretched_height = [(absolute_top - @parent.y), @stretched_height.to_f].max
+      end    
+
+      # an alias for absolute_left
+      def left_side
+         absolute_left
+      end
+
+      # an alias for absolute_right
+      def right_side
+         absolute_right
+      end
+
+      # starts a new page
+      def move_past_bottom
+         @parent.start_new_page
+      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.
+      #
+      def stretchy?
+        !@height 
+      end
+
+    end    
+    
+  end
+end

data/lib/prawn/document/graphics_state.rb

@@ -0,0 +1,48 @@
+# encoding: utf-8
+#
+# graphics_state.rb: Implements graphics state saving and restoring
+#
+# Copyright January 2010, Michael Witrant. All Rights Reserved.
+#
+# This is free software. Please see the LICENSE and COPYING files for details.
+#
+
+module Prawn
+  class Document
+    module GraphicsState
+
+      # 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
+      # modifying the transformation matrix). Used in pairs with
+      # restore_graphics_state or passed a block
+      #
+      # Example without a block:
+      #
+      #   save_graphics_state
+      #   rotate 30
+      #   text "rotated text"
+      #   restore_graphics_state
+      #
+      # Example with a block:
+      #
+      #   save_graphics_state do
+      #     rotate 30
+      #     text "rotated text"
+      #   end
+      #
+      def save_graphics_state
+        add_content "q"
+        if block_given?
+          yield
+          restore_graphics_state
+        end
+      end
+
+      # Pops the last saved graphics state off the graphics state stack and
+      # restores the state to those values
+      def restore_graphics_state
+        add_content "Q"
+      end
+    end
+  end
+end

data/lib/prawn/document/internals.rb

@@ -0,0 +1,176 @@
+# encoding: utf-8
+#
+# internals.rb : Implements document internals for Prawn
+#
+# Copyright August 2008, Gregory Brown. All Rights Reserved.
+#
+# This is free software. Please see the LICENSE and COPYING files for details.
+
+module Prawn
+  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.  
+    #
+    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. 
+      #
+      # Returns the identifier which points to the reference in the ObjectStore   
+      # 
+      def ref(data)
+        ref!(data).identifier
+      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
+      # if needed.  If you take this approach, Prawn::Document::Snapshot
+      # will probably work with your extension
+      #
+      def ref!(data)
+        state.store.ref(data)
+      end
+
+      # At any stage in the object tree an object can be replaced with an
+      # indirect reference. To get access to the object safely, regardless
+      # 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
+      end
+
+      # Appends a raw string to the current page content.
+      #                               
+      #  # 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 l" % [ x2, y2 ])  # draw path
+      #  pdf.add_content("S") # stroke                    
+      #
+      def add_content(str)
+        state.page.content << str << "\n"
+      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
+      # dictionary do not incur the additional overhead.
+      #
+      def names
+        state.store.root.data[:Names] ||= ref!(:Type => :Names)
+      end
+
+      # Returns true if the Names dictionary is in use for this document.
+      # 
+      def names?
+        state.store.root.data[:Names]
+      end
+
+      # Defines a block to be called just before the document is rendered.
+      #
+      def before_render(&block)
+        state.before_render_callbacks << block
+      end
+
+      def go_to_page(k) # :nodoc:
+        jump_to = @store.pages.data[:Kids][k]
+        @current_page = jump_to.identifier
+        @page_content = jump_to.data[:Contents].identifier
+      end
+
+      # Defines a block to be called just before a new page is started.
+      #
+      def on_page_create(&block)
+         if block_given?
+            state.on_page_create_callback = block
+         else
+            state.on_page_create_callback = nil
+         end
+      end
+      
+      private      
+
+      # adds a new, empty content stream to each page. Used in templating so
+      # that imported content streams can be left pristine
+      #
+      def fresh_content_streams(options={})
+        (1..page_count).each do |i|
+          go_to_page i
+          state.page.new_content_stream
+          apply_margin_options(options)
+          use_graphic_settings
+          save_graphics_state
+        end
+      end
+
+      def finalize_all_page_contents
+        (1..page_count).each do |i|
+          go_to_page i
+          repeaters.each { |r| r.run(i) }
+          restore_graphics_state
+          state.page.finalize
+        end
+      end
+
+      # raise the PDF version of the file we're going to generate.
+      # A private method, designed for internal use when the user adds a feature
+      # to their document that requires a particular version.
+      #
+      def min_version(min)
+        state.version = min if min > state.version
+      end
+
+      # Write out the PDF Header, as per spec 3.4.1
+      #
+      def render_header(output)
+        state.before_render_actions(self)
+
+        # pdf version
+        output << "%PDF-#{state.version}\n"
+
+        # 4 binary chars, as recommended by the spec
+        output << "%\xFF\xFF\xFF\xFF\n"
+      end
+
+      # Write out the PDF Body, as per spec 3.4.2
+      #
+      def render_body(output)
+        state.render_body(output)
+      end
+
+      # Write out the PDF Cross Reference Table, as per spec 3.4.3
+      #
+      def render_xref(output)
+        @xref_offset = output.size
+        output << "xref\n"
+        output << "0 #{state.store.size + 1}\n"
+        output << "0000000000 65535 f \n"
+        state.store.each do |ref|
+          output.printf("%010d", ref.offset)
+          output << " 00000 n \n"
+        end
+      end
+
+      # Write out the PDF Trailer, as per spec 3.4.4
+      #
+      def render_trailer(output)
+        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 << @xref_offset << "\n"
+        output << "%%EOF" << "\n"
+      end
+                 
+    end
+  end
+end