Prawn::Text

Public Instance Methods

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

Home Classes Methods

In Files

Namespace

Methods