prawn 0.8.4 → 0.11.1.pre

data/lib/prawn/table/cell/text.rb

@@ -0,0 +1,125 @@
+# encoding: utf-8   
+
+# text.rb: Text table cells.
+#
+# Copyright December 2009, Gregory Brown and Brad Ediger. All Rights Reserved.
+#
+# This is free software. Please see the LICENSE and COPYING files for details.
+module Prawn
+  class Table
+    class Cell
+
+      # A Cell that contains text. Has some limited options to set font family,
+      # size, and style.
+      #
+      class Text < Cell
+
+        TextOptions = [:inline_format, :kerning, :size, :style,
+          :align, :valign, :rotate, :rotate_around, :leading, :single_line,
+          :skip_encoding, :overflow, :min_font_size]
+
+        TextOptions.each do |option|
+          define_method("#{option}=") { |v| @text_options[option] = v }
+          define_method(option) { @text_options[option] }
+        end
+
+        attr_writer :font, :text_color
+
+        def initialize(pdf, point, options={})
+          @text_options = {}
+          super
+          
+          # Sets a reasonable minimum width. If the cell has any content, make
+          # sure we have enough width to be at least one character wide. This is
+          # a bit of a hack, but it should work well enough.
+          min_content_width = [natural_content_width, styled_width_of("M")].min
+          @min_width = padding_left + padding_right + min_content_width
+        end
+
+        # Returns the font that will be used to draw this cell.
+        #
+        def font
+          with_font { @pdf.font }
+        end
+
+        # Returns the width of this text with no wrapping. This will be far off
+        # from the final width if the text is long.
+        #
+        def natural_content_width
+          [styled_width_of(@content), @pdf.bounds.width].min
+        end
+
+        # Returns the natural height of this block of text, wrapped to the
+        # preset width.
+        #
+        def natural_content_height
+          with_font do
+            b = text_box(:width => content_width + FPTolerance)
+            b.render(:dry_run => true)
+            b.height
+          end
+        end
+
+        # Draws the text content into its bounding box.
+        #
+        def draw_content
+          with_font do 
+            @pdf.move_down((@pdf.font.line_gap + @pdf.font.descender)/2)
+            with_text_color do
+              text_box(:width => content_width + FPTolerance, 
+                       :height => content_height + FPTolerance,
+                       :at => [0, @pdf.cursor]).render
+            end
+          end
+        end
+
+        protected
+
+        def with_font
+          @pdf.save_font do
+            options = {}
+            options[:style] = @text_options[:style] if @text_options[:style]
+
+            @pdf.font(@font || @pdf.font.name, options)
+
+            yield
+          end
+        end
+
+        def with_text_color
+          old_color = @pdf.fill_color || '000000'
+          @pdf.fill_color(@text_color) if @text_color
+          yield
+        ensure
+          @pdf.fill_color(old_color)
+        end
+        
+        def text_box(extra_options={})
+          if @text_options[:inline_format]
+            options = @text_options.dup
+            options.delete(:inline_format)
+
+            array = ::Prawn::Text::Formatted::Parser.to_array(@content)
+            ::Prawn::Text::Formatted::Box.new(array,
+              options.merge(extra_options).merge(:document => @pdf))
+          else
+            ::Prawn::Text::Box.new(@content, @text_options.merge(extra_options).
+               merge(:document => @pdf))
+          end
+        end
+
+        # Returns the width of +text+ under the given text options.
+        #
+        def styled_width_of(text)
+          with_font do
+            options = {}
+            options[:size] = @text_options[:size] if @text_options[:size]
+
+            @pdf.font.compute_width_of(text, options)
+          end
+        end
+
+      end
+    end
+  end
+end

data/lib/prawn/table/cells.rb

@@ -0,0 +1,189 @@
+# encoding: utf-8
+
+# cells.rb: Methods for accessing rows, columns, and cells of a Prawn::Table.
+#
+# Copyright December 2009, Brad Ediger. All Rights Reserved.
+#
+# This is free software. Please see the LICENSE and COPYING files for details.
+
+module Prawn
+  class Table
+
+    # Returns a Cells object that can be used to select and style cells. See
+    # the Cells documentation for things you can do with cells.
+    #
+    def cells
+      @cell_proxy ||= Cells.new(@cells)
+    end
+
+    # Selects the given rows (0-based) for styling. Returns a Cells object --
+    # see the documentation on Cells for things you can do with cells.
+    #
+    def rows(row_spec)
+      cells.rows(row_spec)
+    end
+    alias_method :row, :rows
+
+    # Selects the given columns (0-based) for styling. Returns a Cells object
+    # -- see the documentation on Cells for things you can do with cells.
+    #
+    def columns(col_spec)
+      cells.columns(col_spec)
+    end
+    alias_method :column, :columns
+
+    # Represents a selection of cells to be styled. Operations on a CellProxy
+    # can be chained, and cell properties can be set one-for-all on the proxy.
+    #
+    # To set vertical borders only:
+    #
+    #   table.cells.borders = [:left, :right]
+    #
+    # To highlight a rectangular area of the table:
+    #
+    #   table.rows(1..3).columns(2..4).background_color = 'ff0000'
+    #
+    class Cells < Array
+
+      # Limits selection to the given row or rows. +row_spec+ can be anything
+      # that responds to the === operator selecting a set of 0-based row
+      # numbers; most commonly a number or a range.
+      #
+      #   table.row(0)     # selects first row
+      #   table.rows(3..4) # selects rows four and five
+      #
+      def rows(row_spec)
+        index_cells unless @indexed
+        Cells.new(@rows[row_spec] ||= select{ |c| row_spec === c.row })
+      end
+      alias_method :row, :rows
+      
+      # Limits selection to the given column or columns. +col_spec+ can be
+      # anything that responds to the === operator selecting a set of 0-based
+      # column numbers; most commonly a number or a range.
+      #
+      #   table.column(0)     # selects first column
+      #   table.columns(3..4) # selects columns four and five
+      #
+      def columns(row_spec)
+        index_cells unless @indexed
+        Cells.new(@columns[row_spec] ||= select{ |c| row_spec === c.column })
+      end
+      alias_method :column, :columns
+
+      # Allows you to filter the given cells by arbitrary properties.
+      #
+      #   table.column(4).filter { |cell| cell.content =~ /Yes/ }.
+      #     background_color = '00ff00'
+      #
+      def filter(&block)
+        Cells.new(select(&block))
+      end
+
+      # Retrieves a cell based on its 0-based row and column. Returns an
+      # individual Cell, not a Cells collection.
+      # 
+      #   table.cells[0, 0].content # => "First cell content"
+      #
+      def [](row, col)
+        find { |c| c.row == row && c.column == col }
+      end
+
+      # Supports setting multiple properties at once.
+      #
+      #   table.cells.style(:padding => 0, :border_width => 2)
+      #
+      # is the same as:
+      #
+      #   table.cells.padding = 0
+      #   table.cells.border_width = 2
+      #
+      # You can also pass a block, which will be called for each cell in turn.
+      # This allows you to set more complicated properties:
+      #
+      #   table.cells.style { |cell| cell.border_width += 12 }
+      #
+      def style(options={}, &block)
+        each do |cell| 
+          options.each { |k, v| cell.send("#{k}=", v) }
+          block.call(cell) if block
+        end
+      end
+
+      # Returns the total width of all columns in the selected set.
+      #
+      def width
+        column_widths = {}
+        each do |cell| 
+          column_widths[cell.column] = 
+            [column_widths[cell.column], cell.width].compact.max
+        end
+        column_widths.values.inject(0) { |sum, width| sum + width }
+      end
+
+      # Returns minimum width required to contain cells in the set.
+      #
+      def min_width
+        column_min_widths = {}
+        each do |cell| 
+          column_min_widths[cell.column] = 
+            [column_min_widths[cell.column], cell.min_width].compact.max
+        end
+        column_min_widths.values.inject(0) { |sum, width| sum + width }
+      end
+
+      # Returns maximum width that can contain cells in the set.
+      #
+      def max_width
+        column_max_widths = {}
+        each do |cell| 
+          column_max_widths[cell.column] = 
+            [column_max_widths[cell.column], cell.max_width].compact.min
+        end
+        column_max_widths.values.inject(0) { |sum, width| sum + width }
+      end
+
+      # Returns the total height of all rows in the selected set.
+      #
+      def height
+        row_heights = {}
+        each do |cell| 
+          row_heights[cell.row] = 
+            [row_heights[cell.row], cell.height].compact.max
+        end
+        row_heights.values.inject(0) { |sum, width| sum + width }
+      end
+
+      # Supports setting arbitrary properties on a group of cells.
+      #
+      #   table.cells.row(3..6).background_color = 'cc0000'
+      #
+      def method_missing(id, *args, &block)
+        each { |c| c.send(id, *args, &block) }
+      end
+
+      protected
+      
+      # Defers indexing until rows() or columns() is actually called on the
+      # Cells object. Without this, we would needlessly index the leaf nodes of
+      # the object graph, the ones that are only there to be iterated over.
+      #
+      # Make sure to call this before using @rows or @columns.
+      # 
+      def index_cells
+        @rows = {}
+        @columns = {}
+
+        each do |cell|
+          @rows[cell.row] ||= []
+          @rows[cell.row] << cell
+
+          @columns[cell.column] ||= []
+          @columns[cell.column] << cell
+        end
+
+        @indexed = true
+      end
+    end
+  end
+end

data/lib/prawn/text.rb

@@ -0,0 +1,449 @@
+# encoding: utf-8
+
+# text.rb : Implements PDF text primitives
+#
+# Copyright May 2008, Gregory Brown. All Rights Reserved.
+#
+# This is free software. Please see the LICENSE and COPYING files for details.
+require "prawn/core/text"
+require "prawn/core/text/wrap"
+require "prawn/text/box"
+require "prawn/text/formatted"
+require "zlib"
+
+module Prawn
+  module Text
+
+    include Prawn::Core::Text
+    include Prawn::Text::Formatted
+
+    Prawn::Text::NBSP = " "
+
+    # If you want text to flow onto a new page or between columns, this is the
+    # method to use. If, instead, if you want to place bounded text outside of
+    # the flow of a document (for captions, labels, charts, etc.), use Text::Box
+    # or its convenience method text_box.
+    # 
+    # Draws text on the page. Prawn attempts to wrap the text to fit within your
+    # current bounding box (or margin_box if no bounding box is being used).
+    # Text will flow onto the next page when it reaches the bottom of the
+    # bounding box. Text wrap in Prawn does not re-flow linebreaks, so if you
+    # want fully automated text wrapping, be sure to remove newlines before
+    # attempting to draw your string.
+    #
+    # == Examples
+    #
+    #   pdf.text "Will be wrapped when it hits the edge of your bounding box"
+    #   pdf.text "This will be centered", :align => :center
+    #   pdf.text "This will be right aligned", :align => :right
+    #   pdf.text "This <i>includes <b>inline</b></i> <font size='24'>" +
+    #            "formatting</font>", :inline_format => true
+    #
+    # If your font contains kerning pair data that Prawn can parse, the
+    # text will be kerned by default. You can disable kerning by including
+    # a false <tt>:kerning</tt> option. If you want to disable kerning on an
+    # entire document, set default_kerning = false for that document
+    #
+    # === Text Positioning Details
+    # 
+    # The text is positioned at font.ascender below the baseline,
+    # making it easy to use this method within bounding boxes and spans.
+    #
+    # == Encoding
+    #
+    # Note that strings passed to this function should be encoded as UTF-8.
+    # If you get unexpected characters appearing in your rendered document, 
+    # check this.
+    #
+    # If the current font is a built-in one, although the string must be
+    # encoded as UTF-8, only characters that are available in WinAnsi
+    # are allowed.
+    #
+    # If an empty box is rendered to your PDF instead of the character you 
+    # wanted it usually means the current font doesn't include that character.
+    #
+    # == Options (default values marked in [])
+    #
+    # <tt>:inline_format</tt>::
+    #      <tt>boolean</tt>. If true, then the string parameter is interpreted
+    #      as a HTML-esque string that recognizes the following tags:
+    #      <tt>\<b></b></tt>:: bold
+    #      <tt>\<i></i></tt>:: italic
+    #      <tt>\<u></u></tt>:: underline
+    #      <tt>\<strikethrough></strikethrough></tt>:: strikethrough
+    #      <tt>\<sub></sub></tt>:: subscript
+    #      <tt>\<sup></sup></tt>:: superscript
+    #      <tt>\<font></font></tt>::
+    #          with the following attributes (using double or single quotes)
+    #            <tt>size="24"</tt>::
+    #                attribute for setting size
+    #            <tt>character_spacing="2.5"</tt>::
+    #                attribute for setting character spacing
+    #            <tt>name="Helvetica"</tt>::
+    #                attribute for setting the font. The font name must be an
+    #                AFM font with the desired faces or must be a font that is
+    #                already registered using Prawn::Document#font_families
+    #      <tt>\<color></color></tt>::
+    #          with the following attributes
+    #            <tt>rgb="ffffff" or rgb="#ffffff"</tt>::
+    #            <tt>c="100" m="100" y="100" k="100"</tt>::
+    #      <tt>\<link></link></tt>::
+    #          with the following attributes
+    #            <tt>href="http://example.com"</tt>:: an external link
+    #            <tt>anchor="ToC"</tt>::
+    #                where the value of the anchor attribute is the name of a
+    #                destination that has already been or will be registered
+    #                using Prawn::Core::Destinations#add_dest. A clickable link
+    #                will be created to that destination. 
+    #          Note that you must explicitly underline and color using the
+    #          appropriate tags if you which to draw attention to the link
+    #
+    # <tt>:kerning</tt>:: <tt>boolean</tt>. Whether or not to use kerning (if it
+    #                     is available with the current font)
+    #                     [value of default_kerning?]
+    # <tt>:size</tt>:: <tt>number</tt>. The font size to use. [current font
+    #                  size]
+    # <tt>:character_spacing</tt>:: <tt>number</tt>. The amount of space to add
+    #                               to or remove from the default character
+    #                               spacing. [0]
+    # <tt>:style</tt>:: The style to use. The requested style must be part of
+    #                   the current font familly. [current style]
+    # <tt>:indent_paragraphs</tt>:: <tt>number</tt>. The amount to indent the
+    #                               first line of each paragraph. Omit this
+    #                               option if you do not want indenting
+    # <tt>:align</tt>:: <tt>:left</tt>, <tt>:center</tt>, <tt>:right</tt>, or
+    #                   <tt>:justify</tt> Alignment within the bounding box [:left]
+    # <tt>:valign</tt>:: <tt>:top</tt>, <tt>:center</tt>, or <tt>:bottom</tt>.
+    #                    Vertical alignment within the bounding box [:top]
+    # <tt>:leading</tt>:: <tt>number</tt>. Additional space between lines [0]
+    # <tt>:final_gap</tt>:: <tt>boolean</tt>. If true, then the space between
+    #                       each line is included below the last line;
+    #                       otherwise, document.y is placed just below the
+    #                       descender of the last line printed [true]
+    #                        
+    # == Exceptions
+    #
+    # Raises <tt>ArgumentError</tt> if <tt>:at</tt> option included
+    #
+    # Raises <tt>Prawn::Errrors::CannotFit</tt> if not wide enough to print
+    # any text
+    #
+    def text(string, options={})
+      # we modify the options. don't change the user's hash
+      options = options.dup
+
+      if options[:inline_format]
+        options.delete(:inline_format)
+        array = Text::Formatted::Parser.to_array(string)
+        formatted_text(array, options)
+        return
+      end
+
+      inspect_options_for_text(options)
+
+      if @indent_paragraphs
+        string.split("\n").each do |paragraph|
+          options[:skip_encoding] = false
+          remaining_text = draw_indented_line(paragraph, options)
+          options[:skip_encoding] = true
+          if remaining_text == paragraph
+            # we were too close to the bottom of the page to print even one line
+            @bounding_box.move_past_bottom
+            remaining_text = draw_indented_line(paragraph, options)
+          end
+          remaining_text = fill_text_box(remaining_text, options)
+          draw_remaining_text_on_new_pages(remaining_text, options)
+        end
+      else
+        remaining_text = fill_text_box(string, options)
+        options[:skip_encoding] = true
+        draw_remaining_text_on_new_pages(remaining_text, options)
+      end
+    end
+
+
+    # Draws formatted text to the page.
+    # Formatted text is comprised of an array of hashes, where each hash defines
+    # text and format information. See Text::Formatted#formatted_text_box for
+    # more information on the structure of this array
+    #
+    # == Example
+    #
+    #   text([{ :text => "hello" },
+    #         { :text => "world",
+    #           :size => 24,
+    #           :style => [:bold, :italic] }])
+    #
+    # == Options
+    #
+    # Accepts the same options as #text
+    #
+    # == Exceptions
+    #
+    # Same as for #text
+    #
+    def formatted_text(array, options={})
+      # we modify the options. don't change the user's hash
+      options = options.dup
+
+      inspect_options_for_text(options)
+
+      if @indent_paragraphs
+        Text::Formatted::Parser.array_paragraphs(array).each do |paragraph|
+          options[:skip_encoding] = false
+          remaining_text = draw_indented_formatted_line(paragraph, options)
+          options[:skip_encoding] = true
+          if remaining_text == paragraph
+            # we were too close to the bottom of the page to print even one line
+            @bounding_box.move_past_bottom
+            remaining_text = draw_indented_formatted_line(paragraph, options)
+          end
+          remaining_text = fill_formatted_text_box(remaining_text, options)
+          draw_remaining_formatted_text_on_new_pages(remaining_text, options)
+        end
+      else
+        remaining_text = fill_formatted_text_box(array, options)
+        options[:skip_encoding] = true
+        draw_remaining_formatted_text_on_new_pages(remaining_text, options)
+      end
+    end
+
+    # Draws text on the page, beginning at the point specified by the :at option
+    # the string is assumed to be pre-formatted to properly fit the page.
+    # 
+    #   pdf.draw_text "Hello World", :at => [100,100]
+    #   pdf.draw_text "Goodbye World", :at => [50,50], :size => 16
+    #
+    # If your font contains kerning pair data that Prawn can parse, the
+    # text will be kerned by default. You can disable kerning by including
+    # a false <tt>:kerning</tt> option. If you want to disable kerning on an
+    # entire document, set default_kerning = false for that document
+    #
+    # === Text Positioning Details:
+    #
+    # Prawn will position your text by the left-most edge of its baseline, and
+    # flow along a single line.  (This means that :align will not work)
+    #
+    # == Rotation
+    #
+    # Text can be rotated before it is placed on the canvas by specifying the
+    # <tt>:rotate</tt> option with a given angle. Rotation occurs counter-clockwise.
+    #
+    # == Encoding
+    #
+    # Note that strings passed to this function should be encoded as UTF-8.
+    # If you get unexpected characters appearing in your rendered document, 
+    # check this.
+    #
+    # If the current font is a built-in one, although the string must be
+    # encoded as UTF-8, only characters that are available in WinAnsi
+    # are allowed.
+    #
+    # If an empty box is rendered to your PDF instead of the character you 
+    # wanted it usually means the current font doesn't include that character.
+    #
+    # == Options (default values marked in [])
+    #
+    # <tt>:at</tt>:: <tt>[x, y]</tt>(required). The position at which to start the text
+    # <tt>:kerning</tt>:: <tt>boolean</tt>. Whether or not to use kerning (if it
+    #                     is available with the current font)
+    #                     [value of default_kerning?]
+    # <tt>:size</tt>:: <tt>number</tt>. The font size to use. [current font
+    #                  size]
+    # <tt>:style</tt>:: The style to use. The requested style must be part of
+    #                   the current font familly. [current style]
+    #
+    # <tt>:rotate</tt>:: <tt>number</tt>. The angle to which to rotate text
+    #
+    # == Exceptions
+    #
+    # Raises <tt>ArgumentError</tt> if <tt>:at</tt> option omitted
+    #
+    # Raises <tt>ArgumentError</tt> if <tt>:align</tt> option included
+    #
+    def draw_text(text, options)
+      # we modify the options. don't change the user's hash
+      options = options.dup
+      inspect_options_for_draw_text(options)
+      # dup because normalize_encoding changes the string
+      text = text.to_s.dup
+      save_font do
+        process_text_options(options)
+        font.normalize_encoding!(text) unless @skip_encoding
+        font_size(options[:size]) { draw_text!(text, options) }
+      end
+    end
+
+    # Gets height of text in PDF points.
+    # Same options as #text, except as noted.
+    # Not compatible with :indent_paragraphs option
+    #
+    # ==Example
+    #
+    #   height_of("hello\nworld")
+    #
+    # == Exceptions
+    #
+    # Raises <tt>NotImplementedError</tt> if <tt>:indent_paragraphs</tt>
+    # option included
+    #
+    # Raises <tt>Prawn::Errrors::CannotFit</tt> if not wide enough to print
+    # any text
+    #
+    def height_of(string, options={})
+      if options[:indent_paragraphs]
+        raise NotImplementedError, ":indent_paragraphs option not available" +
+          "with height_of"
+      end
+      process_final_gap_option(options)
+      box = Text::Box.new(string,
+                          options.merge(:height   => 100000000,
+                                        :document => self))
+      printed = box.render(:dry_run => true)
+
+      height = box.height - (box.line_height - box.ascender)
+      height += box.line_height + box.leading - box.ascender if @final_gap
+      height
+    end
+
+    # Gets height of formatted text in PDF points.
+    # See documentation for #height_of.
+    #
+    # ==Example
+    #
+    #   height_of_formatted([{ :text => "hello" },
+    #                        { :text => "world",
+    #                          :size => 24,
+    #                          :style => [:bold, :italic] }])
+    #
+    def height_of_formatted(array, options={})
+      if options[:indent_paragraphs]
+        raise NotImplementedError, ":indent_paragraphs option not available" +
+          "with height_of"
+      end
+      process_final_gap_option(options)
+      box = Text::Formatted::Box.new(array,
+                          options.merge(:height   => 100000000,
+                                        :document => self))
+      printed = box.render(:dry_run => true)
+
+      height = box.height - (box.line_height - box.ascender)
+      height += box.line_height + box.leading - box.ascender if @final_gap
+      height
+    end
+
+    private
+
+    def draw_remaining_text_on_new_pages(remaining_text, options)
+      while remaining_text.length > 0
+        @bounding_box.move_past_bottom
+        previous_remaining_text = remaining_text
+        remaining_text = fill_text_box(remaining_text, options)
+        break if remaining_text == previous_remaining_text
+      end
+    end
+
+    def draw_indented_line(string, options)
+      indent(@indent_paragraphs) do
+        fill_text_box(string, options.dup.merge(:single_line => true))
+      end
+    end
+
+    def fill_text_box(text, options)
+      merge_text_box_positioning_options(options)
+
+      box = Text::Box.new(text, options)
+      remaining_text = box.render
+
+      self.y -= box.height - (box.line_height - box.ascender)
+      if @final_gap
+        self.y -= box.line_height + box.leading - box.ascender
+      end
+      remaining_text
+    end
+
+
+
+
+    def draw_remaining_formatted_text_on_new_pages(remaining_text, options)
+      while remaining_text.length > 0
+        @bounding_box.move_past_bottom
+        previous_remaining_text = remaining_text
+        remaining_text = fill_formatted_text_box(remaining_text, options)
+        break if remaining_text == previous_remaining_text
+      end
+    end
+
+    def draw_indented_formatted_line(string, options)
+      indent(@indent_paragraphs) do
+        fill_formatted_text_box(string, options.dup.merge(:single_line => true))
+      end
+    end
+
+    def fill_formatted_text_box(text, options)
+      merge_text_box_positioning_options(options)
+      box = Text::Formatted::Box.new(text, options)
+      remaining_text = box.render
+
+      self.y -= box.height - (box.line_height - box.ascender)
+      if @final_gap
+        self.y -= box.line_height + box.leading - box.ascender
+      end
+      remaining_text
+    end
+
+
+
+    def merge_text_box_positioning_options(options)
+      bottom = @bounding_box.stretchy? ? @margin_box.absolute_bottom :
+                                         @bounding_box.absolute_bottom
+
+      options[:height] = y - bottom
+      options[:width] = bounds.width
+      options[:at] = [@bounding_box.left_side - @bounding_box.absolute_left,
+                      y - @bounding_box.absolute_bottom]
+    end
+
+    def inspect_options_for_draw_text(options)
+      if options[:at].nil?
+        raise ArgumentError, "The :at option is required for draw_text"
+      elsif options[:align]
+        raise ArgumentError, "The :align option does not work with draw_text"
+      end
+      if options[:kerning].nil? then
+        options[:kerning] = default_kerning?
+      end
+      valid_options = Prawn::Core::Text::VALID_OPTIONS + [:at, :rotate]
+      Prawn.verify_options(valid_options, options)
+    end
+
+    def inspect_options_for_text(options)
+      if options[:at]
+        raise ArgumentError, ":at is no longer a valid option with text." +
+                             "use draw_text or text_box instead"
+      end
+      process_final_gap_option(options)
+      process_indent_paragraphs_option(options)
+      options[:document] = self
+    end
+
+    def process_final_gap_option(options)
+      @final_gap = options[:final_gap].nil? || options[:final_gap]
+      options.delete(:final_gap)
+    end
+
+    def process_indent_paragraphs_option(options)
+      @indent_paragraphs = options[:indent_paragraphs]
+      options.delete(:indent_paragraphs)
+    end
+
+    def move_text_position(dy)
+      bottom = @bounding_box.stretchy? ? @margin_box.absolute_bottom :
+                                         @bounding_box.absolute_bottom
+
+      @bounding_box.move_past_bottom if (y - dy) < bottom
+
+      self.y -= dy
+    end
+  end
+end