### Home Classes Methods

### In Files

- lib/prawn/text.rb
- lib/prawn/text/box.rb
- lib/prawn/text/formatted/fragment.rb
- lib/prawn/text/formatted/parser.rb
- lib/prawn/text/formatted/box.rb

### Namespace

- MODULE Prawn::Text::Formatted
- CLASS Prawn::Text::Box

### Methods

- #draw_text
- #formatted_text
- #height_of
- #height_of_formatted
- #text
- #text_box

### Included Modules

- Prawn::Text::Formatted

### Files

- COPYING
- GPLv2
- GPLv3
- LICENSE

### Class/Module Index

Quicksearch

- Prawn
- Prawn::Core
- Prawn::Core::Page
- Prawn::Core::Page::GraphicsState
- Prawn::Core::Reference
- Prawn::Document
- Prawn::Document::BoundingBox
- Prawn::Document::ColumnBox
- Prawn::Document::GraphicsState
- Prawn::Document::Grid
- Prawn::Document::Internals
- Prawn::Document::PageGeometry
- Prawn::Document::Security
- Prawn::Document::Snapshot
- Prawn::Encoding
- Prawn::Errors
- Prawn::Font
- Prawn::Font::AFM
- Prawn::Font::DFont
- Prawn::Font::TTF
- Prawn::GraphicState
- Prawn::GraphicStateStack
- Prawn::Graphics
- Prawn::Graphics::CapStyle
- Prawn::Graphics::Color
- Prawn::Graphics::Dash
- Prawn::Graphics::Gradient
- Prawn::Graphics::JoinStyle
- Prawn::Graphics::Transformation
- Prawn::Graphics::Transparency
- Prawn::Images
- Prawn::Images::JPG
- Prawn::Images::PNG
- Prawn::Layout
- Prawn::Measurements
- Prawn::Outline
- Prawn::Stamp
- Prawn::Table
- Prawn::Table::Cell
- Prawn::Table::Cell::InTable
- Prawn::Table::Cell::Subtable
- Prawn::Table::Cell::Text
- Prawn::Table::Cells
- Prawn::Text
- Prawn::Text::Box
- Prawn::Text::Formatted
- Prawn::Text::Formatted::Box
- Prawn::Text::Formatted::Fragment
- Prawn::Text::Formatted::Parser
- Arcfour
- Numeric

No matching classes.

# Prawn::Text

### Constants

NBSP
SHY
ZWSP

### Public Instance Methods

draw_text(text, options) click to toggle source

Draws text on the page, beginning at the point specified by the :at option the string is assumed to be pre-formatted to properly fit the page.

    pdf.draw_text "Hello World", :at => [100,100]
    pdf.draw_text "Goodbye World", :at => [50,50], :size => 16

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:

Prawn will position your text by the left-most edge of its baseline, and flow along a single line. (This means that :align will not work)

## Rotation

Text can be rotated before it is placed on the canvas by specifying the `:rotate` option with a given angle. Rotation occurs counter-clockwise.

## 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.

## Options (default values marked in [])

`:at` | `[x, y]`(required). The position at which to start the text

`:kerning`

`boolean`. Whether or not to use kerning (if it is available with the current font)

value of default_kerning?

`:size` | `number`. The font size to use. [current font size]
`:style` | The style to use. The requested style must be part of the current font familly. [current style]
`:rotate` | `number`. The angle to which to rotate text

## Exceptions

Raises `ArgumentError` if `:at` option omitted

Raises `ArgumentError` if `:align` option included

    # File lib/prawn/text.rb, line 269
    def draw_text(text, options)
      options = inspect_options_for_draw_text(options.dup)

      # dup because normalize_encoding changes the string
      text = text.to_s.dup
      save_font do
        process_text_options(options)
        font.normalize_encoding!(text) unless @skip_encoding
        font_size(options[:size]) { draw_text!(text, options) }
      end
    end

formatted_text(array, options={}) click to toggle source

Draws formatted text to the page. Formatted text is comprised of an array of hashes, where each hash defines text and format information. See Text::Formatted#formatted_text_box for more information on the structure of this array

## Example

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

## Options

Accepts the same options as text

## Exceptions

Same as for text

    # File lib/prawn/text.rb, line 187
    def formatted_text(array, options={})
      options = inspect_options_for_text(options.dup)

      if @indent_paragraphs
        Text::Formatted::Parser.array_paragraphs(array).each do |paragraph|
          options[:skip_encoding] = false
          remaining_text = draw_indented_formatted_line(paragraph, options)
          options[:skip_encoding] = true

          if @no_text_printed
            # unless this paragraph was an empty line
            unless @all_text_printed
              @bounding_box.move_past_bottom
              options[:skip_encoding] = false
              remaining_text = draw_indented_formatted_line(paragraph, options)
              options[:skip_encoding] = true
            end
          end

          remaining_text = fill_formatted_text_box(remaining_text, options)
          draw_remaining_formatted_text_on_new_pages(remaining_text, options)
        end
      else
        remaining_text = fill_formatted_text_box(array, options)
        options[:skip_encoding] = true
        draw_remaining_formatted_text_on_new_pages(remaining_text, options)
      end
    end

height_of(string, options={}) click to toggle source

Gets height of text in PDF points. Same options as text, except as noted. Not compatible with :indent_paragraphs option

## Example

    height_of("hello\nworld")

## Exceptions

Raises `NotImplementedError` if `:indent_paragraphs` option included

Raises `Prawn::Errrors::CannotFit` if not wide enough to print any text

    # File lib/prawn/text.rb, line 297
    def height_of(string, options={})
      height_of_formatted([{ :text => string }], options)
    end

height_of_formatted(array, options={}) click to toggle source

Gets height of formatted text in PDF points. See documentation for height_of.

## Example

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

    # File lib/prawn/text.rb, line 311
    def height_of_formatted(array, options={})
      if options[:indent_paragraphs]
        raise NotImplementedError, ":indent_paragraphs option not available" +
          "with height_of"
      end
      process_final_gap_option(options)
      box = Text::Formatted::Box.new(array,
                          options.merge(:height   => 100000000,
                                        :document => self))
      printed = box.render(:dry_run => true)

      height = box.height
      height += box.line_gap + box.leading if @final_gap
      height
    end

text(string, options={}) click to toggle source

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

Draws text on the page. 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 linebreaks, so if you want fully automated text wrapping, be sure to remove newlines before attempting to draw your string.

## Examples

    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 <i>includes <b>inline</b></i> <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.

## Options (default values marked in [])

`:inline_format`

`boolean`. If true, then the string parameter is interpreted as a HTML-esque string that recognizes the following tags:

`<b></b>` | bold
`<i></i>` | italic
`<u></u>` | underline
`<strikethrough></strikethrough>` | strikethrough
`<sub></sub>` | subscript
`<sup></sup>` | superscript

`<font></font>`

with the following attributes (using double or single quotes)

    <tt>size="24"</tt>::
        attribute for setting size
    <tt>character_spacing="2.5"</tt>::
        attribute for setting character spacing
    <tt>name="Helvetica"</tt>::
        attribute for setting the font. The font 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></color>`

with the following attributes

    <tt>rgb="ffffff" or rgb="#ffffff"</tt>::
    <tt>c="100" m="100" y="100" k="100"</tt>::

`<link></link>`

with the following attributes

    <tt>href="http://example.com"</tt>:: an external link
    <tt>anchor="ToC"</tt>::
        where the value of the anchor attribute is the name of a
        destination that has already been or will be registered
        using Prawn::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

`:kerning`

`boolean`. Whether or not to use kerning (if it is available with the current font)

value of document.default_kerning?

`:size` | `number`. The font size to use. [current font size]
`:character_spacing` | `number`. The amount of space to add to or remove from the default character spacing. [0]
`:style` | The style to use. The requested style must be part of the current font familly. [current style]
`: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`, Direction of the text (left-to-right or right-to-left) [value of document.text_direction]
`:fallback_fonts` | 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 Prawn::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 from left to right.

`:align`

`:left`, `:center`, `:right`, or `:justify` Alignment within the bounding box

:left if direction is :ltr, :right if direction is :rtl

`:valign` | `:top`, `:center`, or `:bottom`. Vertical alignment within the bounding box [:top]
`:leading` | `number`. Additional space between lines [value of document.default_leading]
`:final_gap` | `boolean`. 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 [true]
`:mode` | The text rendering mode to use. Use this to specify if the text should render with the fill color, stroke color or both. See the comments to text_rendering_mode() to see a list of valid options. [0]

## Exceptions

Raises `ArgumentError` if `:at` option included

Raises `Prawn::Errrors::CannotFit` if not wide enough to print any text

    # File lib/prawn/text.rb, line 152
    def text(string, options={})
      # we modify the options. don't change the user's hash
      options = options.dup

      if options[:inline_format]
        options.delete(:inline_format)
        array = Text::Formatted::Parser.to_array(string)
      else
        array = [{ :text => string }]
      end

      formatted_text(array, options)
    end

text_box(string, options={}) click to toggle source

Draws the requested text into a box. When the text overflows the rectangle, you shrink to fit, or truncate the text. Text boxes are independent of the document y position.

## 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.

## Options (default values marked in [])

`:kerning`

`boolean`. Whether or not to use kerning (if it is available with the current font)

value of document.default_kerning?

`:size` | `number`. The font size to use. [current font size]
`:character_spacing` | `number`. The amount of space to add to or remove from the default character spacing. [0]
`:mode` | `symbol`. The text rendering mode. See documentation for Prawn::Document#text_rendering_mode for a list of valid options. [:fill]
`:style` | The style to use. The requested style must be part of the current font familly. [current style]

`:at`

`[x, y]`. The upper left corner of the box

@document.bounds.left, @document.bounds.top

`:width` | `number`. The width of the box [@document.bounds.right - @at]
`:height` | `number`. The height of the box [default_height()]
`:direction` | `:ltr`, `:rtl`, Direction of the text (left-to-right or right-to-left) [value of document.text_direction]
`:fallback_fonts` | 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 Prawn::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 from left to right.

`:align`

`:left`, `:center`, `:right`, or `:justify` Alignment within the bounding box

:left if direction is :ltr, :right if direction is :rtl

`:valign` | `:top`, `:center`, or `:bottom`. Vertical alignment within the bounding box [:top]
`:rotate` | `number`. The angle to rotate the text
`:rotate_around` | `:center`, `:upper_left`, `:upper_right`, `:lower_right`, or `:lower_left`. The point around which to rotate the text [:upper_left]
`:leading` | `number`. Additional space between lines [value of document.default_leading]
`:single_line` | `boolean`. If true, then only the first line will be drawn [false]
`:skip_encoding` | `boolean` [false]
`:overflow` | `:truncate`, `:shrink_to_fit`, or `:expand` This controls the behavior when the amount of text exceeds the available space. [:truncate]
`:min_font_size` | `number`. The minimum font size to use when :overflow is set to :shrink_to_fit (that is the font size will not be reduced to less than this value, even if it means that some text will be cut off). [5]

## Returns

Returns any text that did not print under the current settings.

NOTE: if an AFM font is used, then the returned text is encoded in WinAnsi. Subsequent calls to text_box that pass this returned text back into text box must include a :skip_encoding => true option. This is unnecessary when using TTF fonts because those operate on UTF-8 encoding.

## Exceptions

Raises `Prawn::Errrors::CannotFit` if not wide enough to print any text

    # File lib/prawn/text/box.rb, line 106
    def text_box(string, options={})
      Text::Box.new(string, options.merge(:document => self)).render
    end

[Validate]

Generated with the Darkfish Rdoc Generator 2.