Method: Prawn::Text::Formatted::Box#initialize

Defined in:

lib/prawn/text/formatted/box.rb

#initialize(formatted_text, options = {}) ⇒ Box

See Prawn::Text#text_box for valid options

Parameters:

• formatted_text (Array<Hash{Symbol => any}>) —

  Formatted text is an array of hashes, where each hash defines text and format information. The following hash options are supported:

  • :text — the text to format according to the other hash options.

  • :styles — an array of styles to apply to this text. Available styles include :bold, :italic, :underline, :strikethrough, :subscript, and :superscript.

  • :size —a number denoting the font size to apply to this text.

  • :character_spacing — a number denoting how much to increase or decrease the default spacing between characters.

  • :font — the name of a font. The name must be an AFM font with the desired faces or must be a font that is already registered using Document#font_families.

  • :color — anything compatible with Graphics::Color#fill_color and Graphics::Color#stroke_color.

  • :link` — a URL to which to create a link. A clickable link will be created to that URL. Note that you must explicitly underline and color using the appropriate tags if you which to draw attention to the link.

  • :anchor — a destination that has already been or will be registered using ‘PDF::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.

  • :local — a file or application to be opened locally. A clickable link will be created to the provided local file or application. If the file is another PDF, it will be opened in a new window. Note that you must explicitly underline and color using the appropriate options if you which to draw attention to the link.

  • :draw_text_callback — if provided, this Proc will be called instead of Document#draw_text! once per fragment for every low-level addition of text to the page.

  • :callback — an object (or array of such objects) with two methods: render_behind and render_in_front, which are called immediately prior to and immediately after rendering the text fragment and which are passed the fragment as an argument.

• options (Hash{Symbol => any}) (defaults to: {})
• option (Hash) —

  a customizable set of options

Options Hash (options):

• :document (Prawn::Document) —

  Owning document.

• :kerning (Boolean) — default: value of document.default_kerning? —

  Whether or not to use kerning (if it is available with the current font).

• :size (Number) — default: current font size —

  The font size to use.

• :character_spacing (Number) — default: 0 —

  The amount of space to add to or remove from the default character spacing.

• :disable_wrap_by_char (Boolean) — default: false —

  Whether or not to prevent mid-word breaks when text does not fit in box.

• :mode (Symbol) — default: :fill —

  The text rendering mode. See documentation for Document#text_rendering_mode for a list of valid options.

• :width (Number) — default: bounds.right - at[0] —

  The width of the box.

• :height (Number) — default: default_height() —

  The height of the box.

• :direction (:ltr, :rtl) — default: value of document.text_direction —

  Direction of the text (left-to-right or right-to-left).

• :fallback_fonts (Array<String>) —

  An array of font names. Each name must be the name of an AFM font or the name that was used to register a family of external fonts (see Document#font_families). If present, then each glyph will be rendered using the first font that includes the glyph, starting with the current font and then moving through :fallback_fonts.

• :align (:left, :center, :right, :justify) — default: :left if direction is :ltr, :right if direction is :rtl —

  Alignment within the bounding box.

• :valign (:top, :center, :bottom) — default: :top —

  Vertical alignment within the bounding box.

• :rotate (Number) —

  The angle to rotate the text.

• :rotate_around (Object) —

  :center, :upper_left, :upper_right, :lower_right, :lower_left

  (:upper_left) The point around which to rotate the text.

• :leading (Number) — default: value of document.default_leading —

  Additional space between lines.

• :single_line (Boolean) — default: false —

  If true, then only the first line will be drawn.

• :overflow (:truncate, :shrink_to_fit, :expand) — default: :truncate —

  This controls the behavior when the amount of text exceeds the available space.

• :min_font_size (Number) — default: 5 —

  The minimum font size to use when :overflow is set to :shrink_to_fit (that is the font size will not be reduced to less than this value, even if it means that some text will be cut off).

# File 'lib/prawn/text/formatted/box.rb', line 173

def initialize(formatted_text, options = {})
  @inked = false
  Prawn.verify_options(valid_options, options)
  options = options.dup

  self.class.extensions.reverse_each { |e| extend(e) }

  @overflow = options[:overflow] || :truncate
  @disable_wrap_by_char = options[:disable_wrap_by_char]

  self.original_text = formatted_text
  @text = nil

  @document = options[:document]
  @direction = options[:direction] || @document.text_direction
  @fallback_fonts = options[:fallback_fonts] ||
    @document.fallback_fonts
  @at = (
    options[:at] || [@document.bounds.left, @document.bounds.top]
  ).dup
  @width = options[:width] ||
    (@document.bounds.right - @at[0])
  @height = options[:height] || default_height
  @align = options[:align] ||
    (@direction == :rtl ? :right : :left)
  @vertical_align = options[:valign] || :top
  @leading = options[:leading] || @document.default_leading
  @character_spacing = options[:character_spacing] ||
    @document.character_spacing
  @mode = options[:mode] || @document.text_rendering_mode
  @rotate = options[:rotate] || 0
  @rotate_around = options[:rotate_around] || :upper_left
  @single_line = options[:single_line]
  @draw_text_callback = options[:draw_text_callback]

  # if the text rendering mode is :unknown, force it back to :fill
  if @mode == :unknown
    @mode = :fill
  end

  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 = default_height
    @overflow = :truncate
  end
  @min_font_size = options[:min_font_size] || 5
  if options[:kerning].nil?
    options[:kerning] = @document.default_kerning?
  end
  @options = {
    kerning: options[:kerning],
    size: options[:size],
    style: options[:style],
  }

  super(formatted_text, options)
end