module Prawn
  class Document
    
    # 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, for the purposes
    # of simplifying coordinate math.
    #
    # 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 text drawing position will be moved to
    # the bottom of the bounding box (y - height). Currently, Prawn allows
    # text to overflow the bottom border of the bounding box, so it is up to
    # the user to ensure the text provided will fit within the height of the
    # bounding box.
    #
    # 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
    #
    # 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.polygon [0,250], [0,0], [150,100]
    #     pdf.polygon [100,0], [150,100], [200,0]
    #   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.
    #
    def bounding_box(*args, &block)
      parent_box = @bounding_box
      @bounding_box = BoundingBox.new(self, *args)
      self.y = @bounding_box.absolute_top
      
      block.call
      
      self.y = @bounding_box.absolute_bottom
      @bounding_box = parent_box
    end
 
    # A shortcut to produce a bounding box which is mapped to the document's
    # absolute coordinates
    #
    #   pdf.canvas do
    #     pdf.line pdf.bounds.bottom_left, pdf.bounds.top_right
    #   end
    #
    def canvas(&block)
      bounding_box( [0, page_dimensions[3]], 
       :width  => page_dimensions[2], :height => page_dimensions[3], &block)
    end
    
    class BoundingBox
      
      def initialize(parent, point, options={}) #:nodoc:
        @parent = parent
        @x, @y = point
        @width, @height = options[:width], options[:height]
      end
       
      # The translated origin (x,y-height) which describes the location
      # of the bottom left corner of the bounding box in absolute terms.
      #
      def anchor
        [@x, @y - height]
      end
      
      # Relative left x-coordinate of the bounding box. (Always 0)
      #
      def left
        0
      end
      
      # Relative right x-coordinate of the bounding box. (Equal to the box width)
      #
      def right
        @width
      end
      
      # Relative top y-coordinate of the bounding box. (Equal to the box height)
      #
      def top
        height
      end
      
      # Relative bottom y-coordinate of the bounding box (Always 0)
      #
      def bottom
        0
      end
 
      # Relative top-left point of the bounding_box
      #
      def top_left
        [left,top]
      end
 
      # Relative top-right point of the bounding box
      #
      def top_right
        [right,top]
      end
 
      # Relative bottom-right point of the bounding box
      #
      def bottom_right
        [right,bottom]
      end
 
      # Relative bottom-left point of the bounding box
      #
      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
        if @height.nil?
          absolute_top - @parent.y
        else
          @height
        end
      end
    end
  end
end