Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Fetching contributors…

Octocat-spinner-32-eaf2f5

Cannot retrieve contributors at this time

file 143 lines (132 sloc) 5.891 kb
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142
# 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.
#

module Prawn
  module Text

    # 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 [])
    #
    # <tt>:kerning</tt>:: <tt>boolean</tt>. Whether or not to use kerning (if it
    # is available with the current font)
    # [value of document.default_kerning?]
    # <tt>:size</tt>:: <tt>number</tt>. The font size to use. [current font
    # size]
    # <tt>:character_spacing</tt>:: <tt>number</tt>. The amount of space to add
    # to or remove from the default character
    # spacing. [0]
    # <tt>:mode</tt>:: <tt>symbol</tt>. The text rendering mode. See
    # documentation for Prawn::Document#text_rendering_mode
    # for a list of valid options. [:fill]
    # <tt>:style</tt>:: The style to use. The requested style must be part of
    # the current font familly. [current style]
    #
    # <tt>:at</tt>::
    # <tt>[x, y]</tt>. The upper left corner of the box
    # [@document.bounds.left, @document.bounds.top]
    # <tt>:width</tt>::
    # <tt>number</tt>. The width of the box [@document.bounds.right - @at[0]]
    # <tt>:height</tt>::
    # <tt>number</tt>. The height of the box [default_height()]
    # <tt>:direction</tt>::
    # <tt>:ltr</tt>, <tt>:rtl</tt>, Direction of the text (left-to-right
    # or right-to-left) [value of document.text_direction]
    # <tt>:fallback_fonts</tt>::
    # 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.
    # <tt>:align</tt>::
    # <tt>:left</tt>, <tt>:center</tt>, <tt>:right</tt>, or
    # <tt>:justify</tt> Alignment within the bounding box
    # [:left if direction is :ltr, :right if direction is :rtl]
    # <tt>:valign</tt>::
    # <tt>:top</tt>, <tt>:center</tt>, or <tt>:bottom</tt>. Vertical
    # alignment within the bounding box [:top]
    #
    # <tt>:rotate</tt>::
    # <tt>number</tt>. The angle to rotate the text
    # <tt>:rotate_around</tt>::
    # <tt>:center</tt>, <tt>:upper_left</tt>, <tt>:upper_right</tt>,
    # <tt>:lower_right</tt>, or <tt>:lower_left</tt>. The point around which
    # to rotate the text [:upper_left]
    # <tt>:leading</tt>::
    # <tt>number</tt>. Additional space between lines [value of
    # document.default_leading]
    # <tt>:single_line</tt>::
    # <tt>boolean</tt>. If true, then only the first line will be drawn [false]
    # <tt>:skip_encoding</tt>::
    # <tt>boolean</tt> [false]
    # <tt>:overflow</tt>::
    # <tt>:truncate</tt>, <tt>:shrink_to_fit</tt>, or <tt>:expand</tt>
    # This controls the behavior when the amount of text
    # exceeds the available space. [:truncate]
    # <tt>:min_font_size</tt>::
    # <tt>number</tt>. 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 <tt>Prawn::Errrors::CannotFit</tt> 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.parser.to_array(string, *p)
              Text::Formatted::Box.new(array, options)
            else
              Text::Box.new(string, options)
            end

      box.render
    end

    # 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
Something went wrong with that request. Please try again.