class Prawn::Text::Formatted::Box

# File lib/prawn/text/formatted/box.rb, line 391
def self.extensions
  @extensions ||= []
end

Text box extensions.

Example:

“‘ruby module MyWrap

def wrap(array)
  initialize_wrap([{ text: 'all your base are belong to us' }])
  @line_wrap.wrap_line(
    document: @document,
    kerning: @kerning,
    width: 10000,
    arranger: @arranger
  )
  fragment = @arranger.retrieve_fragment
  format_and_draw_fragment(fragment, 0, @line_wrap.width, 0)
  []
end

end

Prawn::Text::Formatted::Box.extensions << MyWrap

box = Prawn::Text::Formatted::Box.new(‘hello world’) box.render(“why can’t I print anything other than” +

'"all your base are belong to us"?')

“‘

See {Prawn::Text::Formatted::Wrap} for what is required of the wrap method if you want to override the default wrapping algorithm.

@return [Array<Module>]

# File lib/prawn/text/formatted/box.rb, line 396
def self.inherited(base)
  super
  extensions.each { |e| base.extensions << e }
end

@private

# File lib/prawn/text/formatted/box.rb, line 173
def initialize(formatted_text, options = {})
  @inked = false
  Prawn.verify_options(valid_options, options)
  options = options.dup

  self.class.extensions.reverse_each { |e| extend(e) }

  @overflow = options[:overflow] || :truncate
  @disable_wrap_by_char = options[:disable_wrap_by_char]

  self.original_text = formatted_text
  @text = nil

  @document = options[:document]
  @direction = options[:direction] || @document.text_direction
  @fallback_fonts = options[:fallback_fonts] ||
    @document.fallback_fonts
  @at = (
    options[:at] || [@document.bounds.left, @document.bounds.top]
  ).dup
  @width = options[:width] ||
    (@document.bounds.right - @at[0])
  @height = options[:height] || default_height
  @align = options[:align] ||
    (@direction == :rtl ? :right : :left)
  @vertical_align = options[:valign] || :top
  @leading = options[:leading] || @document.default_leading
  @character_spacing = options[:character_spacing] ||
    @document.character_spacing
  @mode = options[:mode] || @document.text_rendering_mode
  @rotate = options[:rotate] || 0
  @rotate_around = options[:rotate_around] || :upper_left
  @single_line = options[:single_line]
  @draw_text_callback = options[:draw_text_callback]

  # if the text rendering mode is :unknown, force it back to :fill
  if @mode == :unknown
    @mode = :fill
  end

  if @overflow == :expand
    # if set to expand, then we simply set the bottom
    # as the bottom of the document bounds, since that
    # is the maximum we should expand to
    @height = default_height
    @overflow = :truncate
  end
  @min_font_size = options[:min_font_size] || 5
  if options[:kerning].nil?
    options[:kerning] = @document.default_kerning?
  end
  @options = {
    kerning: options[:kerning],
    size: options[:size],
    style: options[:style],
  }

  super(formatted_text, options)
end

See Prawn::Text#text_box for valid options

@param formatted_text [Array<Hash{Symbol => any}>]

Formatted text is an array of hashes, where each hash defines text
and format information. The following hash options are supported:

- `:text` --- the text to format according to the other hash
  options.
- `:styles` --- an array of styles to apply to this text. Available
  styles include `:bold`, `:italic`, `:underline`, `:strikethrough`,
  `:subscript`, and `:superscript`.
- `:size` ---a number denoting the font size to apply to this text.
- `:character_spacing` --- a number denoting how much to increase or
  decrease the default spacing between characters.
- `:font` --- the name of a font. The 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` --- anything compatible with
  {Prawn::Graphics::Color#fill_color} and
  {Prawn::Graphics::Color#stroke_color}.
- :link` --- a URL to which to create a link. A clickable link will
  be created to that URL. Note that you must explicitly underline
  and color using the appropriate tags if you which to draw
  attention to the link.
- `:anchor` --- a destination that has already been or will be
  registered using `PDF::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.
- `:local` --- a file or application to be opened locally.
  A clickable link will be created to the provided local file or
  application. If the file is another PDF, it will be opened in
  a new window. Note that you must explicitly underline and color
  using the appropriate options if you which to draw attention to
  the link.
- `:draw_text_callback` --- if provided, this Proc will be called
  instead of {Prawn::Document#draw_text!} once per fragment for
  every low-level addition of text to the page.
- `:callback` --- an object (or array of such objects) with two
  methods: `render_behind` and `render_in_front`, which are called
  immediately prior to and immediately after rendering the text
  fragment and which are passed the fragment as an argument.

@param options [Hash{Symbol => any}] @option options :document [Prawn::Document] Owning document. @option options :kerning [Boolean]

(value of document.default_kerning?)
Whether or not to use kerning (if it is available with the current
font).

@option options :size [Number] (current font size)

The font size to use.

@option options :character_spacing [Number] (0)

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

@option options :disable_wrap_by_char [Boolean] (false)

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

@option options :mode [Symbol] (:fill)

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

@option option :style [Symbol] (current style)

The style to use. The requested style must be part of the current
font family.

@option option :at [Array(Number, Number)] (bounds top left corner)

The upper left corner of the box.

@option options :width [Number] (bounds.right - at)

The width of the box.

@option options :height [Number] (default_height())

The height of the box.

@option options :direction [:ltr, :rtl]

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

@option options :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
{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`.

@option options :align [:left, :center, :right, :justify]

(:left if direction is :ltr, :right if direction is :rtl)
Alignment within the bounding box.

@option options :valign [:top, :center, :bottom] (:top)

Vertical alignment within the bounding box.

@option options :rotate [Number]

The angle to rotate the text.

@option options :rotate_around

[:center, :upper_left, :upper_right, :lower_right, :lower_left]
(:upper_left)
The point around which to rotate the text.

@option options :leading [Number] (value of document.default_leading)

Additional space between lines.

@option options :single_line [Boolean] (false)

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

@option options :overflow [:truncate, :shrink_to_fit, :expand]

(:truncate)
This controls the behavior when the amount of text exceeds the
available space.

@option options :min_font_size [Number] (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/formatted/box.rb, line 285
def available_width
  @width
end

The width available at this point in the box.

@return [Number]

# File lib/prawn/text/formatted/box.rb, line 304
def draw_fragment(
  fragment, accumulated_width = 0, line_width = 0, word_spacing = 0
)
  case @align
  when :left
    x = @at[0]
  when :center
    x = @at[0] + (@width * 0.5) - (line_width * 0.5)
  when :right
    x = @at[0] + @width - line_width
  when :justify
    x =
      if @direction == :ltr
        @at[0]
      else
        @at[0] + @width - line_width
      end
  else
    raise ArgumentError,
      'align must be one of :left, :right, :center or :justify symbols'
  end

  x += accumulated_width

  y = @at[1] + @baseline_y

  y += fragment.y_offset

  fragment.left = x
  fragment.baseline = y

  if @inked
    draw_fragment_underlays(fragment)

    @document.word_spacing(word_spacing) do
      if @draw_text_callback
        @draw_text_callback.call(
          fragment.text,
          at: [x, y],
          kerning: @kerning,
        )
      else
        @document.draw_text!(
          fragment.text,
          at: [x, y],
          kerning: @kerning,
        )
      end
    end

    draw_fragment_overlays(fragment)
  end
end

@private @param fragment [Prawn::Text::Formatted::Fragment] @param accumulated_width [Number] @param line_width [Number] @param word_spacing [Number] @return [void]

# File lib/prawn/text/formatted/box.rb, line 42
def everything_printed?
  @everything_printed
end

True if everything printed (or, if ‘:dry_run` was used, everything would have been successfully printed).

@return [Boolean]

# File lib/prawn/text/formatted/box.rb, line 292
def height
  return 0 if @baseline_y.nil? || @descender.nil?

  (@baseline_y - @descender).abs
end

The height actually used during the previous {render}.

@return [Number]

# File lib/prawn/text/formatted/box.rb, line 69
def line_gap
  line_height - (ascender + descender)
end

Gap between adjacent lines of text.

@return [Number]

# File lib/prawn/text/formatted/box.rb, line 34
def nothing_printed?
  @nothing_printed
end

True if nothing printed (or, if ‘:dry_run` was used, nothing would have been successfully printed).

@return [Boolean]

# File lib/prawn/text/formatted/box.rb, line 251
def render(flags = {})
  unprinted_text = []

  @document.save_font do
    @document.character_spacing(@character_spacing) do
      @document.text_rendering_mode(@mode) do
        process_options

        text = normalized_text(flags)

        @document.font_size(@font_size) do
          shrink_to_fit(text) if @overflow == :shrink_to_fit
          process_vertical_alignment(text)
          @inked = true unless flags[:dry_run]
          unprinted_text =
            if @rotate != 0 && @inked
              render_rotated(text)
            else
              wrap(text)
            end
          @inked = false
        end
      end
    end
  end

  unprinted_text.map do |e|
    e.merge(text: @document.font.to_utf8(e[:text]))
  end
end

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.

@param flags [Hash{Symbol => any}] @option flags :dry_run [Boolean] (false)

Do not draw the text. Everything else is done.

@return [Array<Hash>]

A formatted text array representing any text that did not print
under the current settings.

@raise [Prawn::Text::Formatted::Arranger::BadFontFamily]

If no font family is defined for the current font.

@raise [Prawn::Errors::CannotFit]

If not wide enough to print any text.

# File lib/prawn/text/formatted/box.rb, line 402
def valid_options
  PDF::Core::Text::VALID_OPTIONS + %i[
    at
    height width
    align valign
    rotate rotate_around
    overflow min_font_size
    disable_wrap_by_char
    leading character_spacing
    mode single_line
    document
    direction
    fallback_fonts
    draw_text_callback
  ]
end

@private