Module: Prawn::Text::Formatted

Included in:

Prawn::Text

Defined in:

lib/prawn/text/formatted.rb,
lib/prawn/text/formatted/box.rb,
lib/prawn/text/formatted/wrap.rb,
lib/prawn/text/formatted/parser.rb,
lib/prawn/text/formatted/arranger.rb,
lib/prawn/text/formatted/fragment.rb,
lib/prawn/text/formatted/line_wrap.rb

Overview

Fancy pretty text.

Defined Under Namespace

Classes: Box, Parser

Stable API

• #formatted_text_box(array, options = {}) ⇒ Array<Hash>

  Draws the requested formatted text into a box.

Instance Method Details

#formatted_text_box(array, options = {}) ⇒ Array<Hash>

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.

Examples:

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

Parameters:

• 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 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`Prawn::Text::Formatted.::.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 Prawn::Text#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`Prawn::Text::Formatted.::.language-plain and `#render_in_front`Prawn::Text::Formatted.::.language-plain, 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: {}) —

  Accepts the same options as Box.

Returns:

• (Array<Hash>) —

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

Raises:

• (Prawn::Text::Formatted::Arranger::BadFontFamily) —

  If no font family is defined for the current font.

• (Prawn::Errors::CannotFit) —

  If not wide enough to print any text.

# 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