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 collapse

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. 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 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: {}) —

    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.

Source Code
lib/prawn/text/formatted.rb, line 73
73
def formatted_text_box(array, options = {})

74
  Text::Formatted::Box.new(array, options.merge(document: self)).render

75
end