Generally, one would use the text_box convenience method. However, using Text::Box.new in conjunction with render() enables one to do look-ahead calculations prior to placing text on the page, or to determine how much vertical space was consumed by the printed text
See Prawn::Text#text_box for valid options
# File lib/prawn/text/box.rb, line 127 def initialize(string, options={}) @inked = false Prawn.verify_options(VALID_OPTIONS, options) options = options.dup @overflow = options[:overflow] || :truncate @original_string = string @text = nil @document = options[:document] @at = options[:at] || [@document.bounds.left, @document.bounds.top] @width = options[:width] || @document.bounds.right - @at[0] @height = options[:height] || @at[1] - @document.bounds.bottom @align = options[:align] || :left @vertical_align = options[:valign] || :top @leading = options[:leading] || 0 @rotate = options[:rotate] || 0 @rotate_around = options[:rotate_around] || :upper_left @single_line = options[:single_line] @skip_encoding = options[:skip_encoding] || @document.skip_encoding if @overflow == :expand # if set to expand, then we simply set the bottom # as the bottom of the document bounds, since that # is the maximum we should expand to @height = @at[1] - @document.bounds.bottom @overflow = :truncate end @min_font_size = options[:min_font_size] || 5 @line_wrap = options [:line_wrap] || @document.default_line_wrap @options = @document.text_options.merge(:kerning => options[:kerning], :size => options[:size], :style => options[:style]) end
The height actually used during the previous render
# File lib/prawn/text/box.rb, line 202 def height return 0 if @baseline_y.nil? || @descender.nil? # baseline is already pushed down one line below the current # line, so we need to subtract line line_height and leading, # but we need to add in the descender since baseline is # above the descender @baseline_y.abs + @descender - @line_height - @leading end
Render text to the document based on the settings defined in initialize.
In order to facilitate look-ahead calculations, render accepts a :dry_run => true option. If provided then everything is executed as if rendering, with the exception that nothing is drawn on the page. Useful for look-ahead computations of height, unprinted text, etc.
Returns any text that did not print under the current settings
# File lib/prawn/text/box.rb, line 174 def render(flags={}) # dup because normalize_encoding changes the string string = @original_string.dup unprinted_text = '' @document.save_font do process_options unless @skip_encoding @document.font.normalize_encoding!(string) end @document.font_size(@font_size) do shrink_to_fit(string) if @overflow == :shrink_to_fit process_vertical_alignment(string) @inked = true unless flags[:dry_run] if @rotate != 0 && @inked unprinted_text = render_rotated(string) else unprinted_text = _render(string) end @inked = false end end unprinted_text end
Generated with the Darkfish Rdoc Generator 2.