Method: Prawn::Text#text

Defined in:

lib/prawn/text.rb

#text(string, options = {}) ⇒ void

This method returns an undefined value.

Draws text on the page.

If you want text to flow onto a new page or between columns, this is the method to use. If, instead, you want to place bounded text outside of the flow of a document (for captions, labels, charts, etc.), use Box or its convenience method #text_box.

Prawn attempts to wrap the text to fit within your current bounding box (or ‘margin_box` if no bounding box is being used). Text will flow onto the next page when it reaches the bottom of the bounding box. Text wrap in Prawn does not re-flow line breaks, so if you want fully automated text wrapping, be sure to remove newlines before attempting to draw your string.

#### Examples

“‘ruby pdf.text “Will be wrapped when it hits the edge of your bounding box” pdf.text “This will be centered”, align: :center pdf.text “This will be right aligned”, align: :right pdf.text “This includes inline <font size=’24’>formatting</font>”, inline_format: true “‘

If your font contains kerning pair data that Prawn can parse, the text will be kerned by default. You can disable kerning by including a ‘false` `:kerning` option. If you want to disable kerning on an entire document, set `default_kerning = false` for that document.

#### Text Positioning Details

The text is positioned at ‘font.ascender` below the baseline, making it easy to use this method within bounding boxes and spans.

#### Encoding

Note that strings passed to this function should be encoded as UTF-8. If you get unexpected characters appearing in your rendered document, check this.

If the current font is a built-in one, although the string must be encoded as UTF-8, only characters that are available in WinAnsi are allowed.

If an empty box is rendered to your PDF instead of the character you wanted it usually means the current font doesn’t include that character.

Parameters:

• string (String)
• 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.

  • ‘<u></u>`Prawn::Text.::.language-html — underline.

  • ‘<strikethrough></strikethrough>`Prawn::Text.::.language-html — strikethrough.

  • ‘`Prawn::Text.::.language-html — subscript.

  • ‘`Prawn::Text.::.language-html — superscript.

  • ‘<font></font>`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 151

def text(string, options = {})
  return false if string.nil?

  # we modify the options. don't change the user's hash
  options = options.dup

  p = options[:inline_format]
  if p
    p = [] unless p.is_a?(Array)
    options.delete(:inline_format)
    array = text_formatter.format(string, *p)
  else
    array = [{ text: string }]
  end

  formatted_text(array, options)
end