module Prawn::Text::Formatted

# File lib/prawn/text/formatted.rb, line 73
def formatted_text_box(array, options = {})
  Text::Formatted::Box.new(array, options.merge(document: self)).render
end

Draws the requested formatted text into a box.

When the text overflows the rectangle shrink to fit or truncate the text. Text boxes are independent of the document y position.

@example

formatted_text_box([{ :text => "hello" },
                    { :text => "world",
                      :size => 24,
                      :styles => [:bold, :italic] }])

@param array [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
  {Prawn::Document#font_families}.
- `:color` --- anything compatible with
  {Prawn::Graphics::Color#fill_color} and
  {Prawn::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`{:.language-plain}. 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 {#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`{:.language-plain} and
  `#render_in_front`{:.language-plain}, which are called immediately
  prior to and immediately after rendering the text fragment and which
  are passed the fragment as an argument.

@param options [Hash{Symbol => any}]

Accepts the same options as {Text::Box}.

@return [Array<Hash>]

A formatted text array representing any text that did not print under
the current settings.

@raise [Prawn::Text::Formatted::Arranger::BadFontFamily]

If no font family is defined for the current font.

@raise [Prawn::Errors::CannotFit]

If not wide enough to print any text.