# encoding: utf-8
# text/rectangle.rb : Implements text boxes
#
# Copyright November 2009, Daniel Nelson. All Rights Reserved.
#
# This is free software. Please see the LICENSE and COPYING files for details.
#
require_relative "formatted/box"
module Prawn
module Text
# @group Stable API
# 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[0]]
# :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
#
def text_box(string, options={})
options = options.dup
options[:document] = self
box = if p = options.delete(:inline_format)
p = [] unless p.is_a?(Array)
array = self.text_formatter.format(string, *p)
Text::Formatted::Box.new(array, options)
else
Text::Box.new(string, options)
end
box.render
end
# @group Experimental API
# Generally, one would use the Prawn::Text#text_box convenience
# method. However, using Text::Box.new in conjunction with
# #render(:dry_run=> true) enables one to do look-ahead calculations prior
# to placing text on the page, or to determine how much vertical space was
# consumed by the printed text
#
class Box < Prawn::Text::Formatted::Box
def initialize(string, options={})
super([{ :text => string }], options)
end
def render(flags={})
leftover = super(flags)
leftover.collect { |hash| hash[:text] }.join
end
end
end
end