Class: Prawn::Text::Box

Inherits:

Formatted::Box

• Object
• Formatted::Box
• Prawn::Text::Box

Defined in:

lib/prawn/text/box.rb

Overview

Text box.

Generally, one would use the #text_box convenience method. However, using Box.new in conjunction with ‘render(dry_run: true)` enables one to do calculations prior to placing text on the page, or to determine how much vertical space was consumed by the printed text.

Experimental API

• #initialize(string, options = {}) ⇒ Box constructor

  A new instance of Box.

• #render(flags = {}) ⇒ String

  Render text to the document based on the settings defined in constructor.

Constructor Details

#initialize(string, options = {}) ⇒ Box

Returns a new instance of Box.

Parameters:

• string (String)
• options (Hash{Symbol => any}) (defaults to: {})
• option (Hash) —

  a customizable set of options

Options Hash (options):

• :document (Prawn::Document) —

  Owning document.

• :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 font size —

  The font size to use.

• :character_spacing (Number) — default: 0 —

  The amount of space to add to or remove from the default character spacing.

• :disable_wrap_by_char (Boolean) — default: false —

  Whether or not to prevent mid-word breaks when text does not fit in box.

• :mode (Symbol) — default: :fill —

  The text rendering mode. See documentation for Document#text_rendering_mode for a list of valid options.

• :width (Number) — default: bounds.right - at[0] —

  The width of the box.

• :height (Number) — default: default_height() —

  The height of the box.

• :direction (:ltr, :rtl) — default: value of document.text_direction —

  Direction of the text (left-to-right or right-to-left).

• :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 external 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`.

• :align (:left, :center, :right, :justify) — default: :left if direction is :ltr, :right if direction is :rtl —

  Alignment within the bounding box.

• :valign (:top, :center, :bottom) — default: :top —

  Vertical alignment within the bounding box.

• :rotate (Number) —

  The angle to rotate the text.

• :rotate_around (Object) —

  :center, :upper_left, :upper_right, :lower_right, :lower_left

  (:upper_left) The point around which to rotate the text.

• :leading (Number) — default: value of document.default_leading —

  Additional space between lines.

• :single_line (Boolean) — default: false —

  If true, then only the first line will be drawn.

• :overflow (:truncate, :shrink_to_fit, :expand) — default: :truncate —

  This controls the behavior when the amount of text exceeds the available space.

• :min_font_size (Number) — default: 5 —

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

# File 'lib/prawn/text/box.rb', line 165

def initialize(string, options = {})
  super([{ text: string }], options)
end

Instance Method Details

#render(flags = {}) ⇒ String

Render text to the document based on the settings defined in constructor.

In order to facilitate look-ahead calculations, this method accepts a ‘dry_run: true` option. If provided, then everything is executed as if rendering, with the exception that nothing is drawn on the page. Useful for look-ahead computations of height, unprinted text, etc.

Parameters:

• flags (Hash{Symbol => any}) (defaults to: {})

Options Hash (flags):

• :dry_run (Boolean) — default: false —

  Do not draw the text. Everything else is done.

Returns:

• (String) —

  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.

# File 'lib/prawn/text/box.rb', line 186

def render(flags = {})
  leftover = super(flags)
  leftover.map { |hash| hash[:text] }.join
end