Method: Prawn::Text#formatted_text

Defined in:: lib/prawn/text.rb

#formatted_text(array, options = {}) ⇒ `void`

This method returns an undefined value.

Draws formatted text to the page.

Formatted text is an array of hashes, where each hash defines text and format information.

Examples:

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

Parameters:

array (Array<Hash>) —

array of text fragments. See Prawn::Text::Formatted#formatted_text_box for more information on the structure of this array.
options (Hash{Symbol => any}) (defaults to: {})
option (Hash) —

a customizable set of options

Options Hash (options):

:inline_format (Boolean) —
If ‘true`, then the string parameter is interpreted as a HTML-esque string that recognizes the following tags (assuming the default text formatter is used):
- “Prawn::Text.::.language-html — bold style.
- “Prawn::Text.::.language-html — italic style.
- ‘`Prawn::Text.::.language-html — underline.
- ‘<strikethrough></strikethrough>`Prawn::Text.::.language-html — strikethrough.
- ‘`Prawn::Text.::.language-html — subscript.
- ‘`Prawn::Text.::.language-html — superscript.
- ‘`Prawn::Text.::.language-html — with the following attributes (using double or single quotes):
 - ‘name=“Helvetica”`Prawn::Text.::.language-html — the font. The font name must be an AFM font with the desired faces or must be a font that is already registered using Document#font_families.
 - ‘size=“24”`Prawn::Text.::.language-html — attribute for setting size.
 - ‘character_spacing=“2.5”`Prawn::Text.::.language-html — character spacing.
- ‘<color></color>`Prawn::Text.::.language-html — text color
 - ‘rgb=“ffffff”`Prawn::Text.::.language-html or `rgb=“#ffffff”`Prawn::Text.::.language-html — RGB color
 - ‘c=“100” m=“100” y=“100” k=“100”`Prawn::Text.::.language-html — CMYK color
- ‘<link></link>`Prawn::Text.::.language-html - link, with the following attributes:
 - ‘href=“example.com”`Prawn::Text.::.language-html — an external link. Note that you must explicitly underline and color using the appropriate tags if you which to draw attention to the link.
: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 ofnt size —

The font size to use.
:color (Color)
:character_spacing (Number) — default: 0 —

The amount of space to add to or remove from the default character spacing.
:style (Symbol) — default: current style —

The style to use. The requested style must be part of the current font family.
:indent_paragraphs (Number) —

The amount to indent the first line of each paragraph. Omit this option if you do not want indenting.
:direction (:ltr, :rtl) — default: value of document.text_direction —

Direction of the text.
: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 TTF 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`.
:valign (:top, :center, :bottom) — default: :top —

Vertical alignment within the bounding box.
:leading (Object) — default: Number —

(value of document.default_leading) Additional space between lines.
:final_gap (Boolean) — default: true —

If ‘true`, then the space between each line is included below the last line; otherwise, Document#y is placed just below the descender of the last line printed.
:mode (Symbol) — default: :fill —
The text rendering mode to use. Use this to specify if the text should render with the fill color, stroke color or both.
- ‘:fill` - fill text (default)
- ‘:stroke` - stroke text
- ‘:fill_stroke` - fill, then stroke text
- ‘:invisible` - invisible text
- ‘:fill_clip` - fill text then add to path for clipping
- ‘:stroke_clip` - stroke text then add to path for clipping
- ‘:fill_stroke_clip` - fill then stroke text, then add to path for clipping
- ‘:clip` - add text to path for clipping

Raises:

(ArgumentError) —

if ‘:at` option included
(Prawn::Errrors::CannotFit) —

if not wide enough to print any text

See Also:

for a list of valid text rendering modes.

# File 'lib/prawn/text.rb', line 263

def formatted_text(array, options = {})
  options = inspect_options_for_text(options.dup)

  color = options.delete(:color)
  if color
    array =
      array.map { |fragment|
        fragment[:color] ? fragment : fragment.merge(color: color)
      }
  end

  if @indent_paragraphs
    text_formatter.array_paragraphs(array).each do |paragraph|
      remaining_text = draw_indented_formatted_line(paragraph, options)

      if @no_text_printed && !@all_text_printed
        @bounding_box.move_past_bottom
        remaining_text = draw_indented_formatted_line(paragraph, options)
      end

      unless @all_text_printed
        remaining_text = fill_formatted_text_box(remaining_text, options)
        draw_remaining_formatted_text_on_new_pages(remaining_text, options)
      end
    end
  else
    remaining_text = fill_formatted_text_box(array, options)
    draw_remaining_formatted_text_on_new_pages(remaining_text, options)
  end
end

Method: Prawn::Text#formatted_text

#formatted_text(array, options = {}) ⇒ void

Examples:

#formatted_text(array, options = {}) ⇒ `void`