Module: Prawn::Text

Includes:
PDF::Core::Text, Formatted
Included in:
Document
Defined in:
lib/prawn/text.rb,
lib/prawn/text/box.rb,
lib/prawn/text/formatted/box.rb,
lib/prawn/text/formatted/wrap.rb,
lib/prawn/text/formatted/parser.rb,
lib/prawn/text/formatted/arranger.rb,
lib/prawn/text/formatted/fragment.rb,
lib/prawn/text/formatted/line_wrap.rb

Defined Under Namespace

Modules: Formatted Classes: Box

Constant Summary collapse

NBSP =

No-Break Space

"\u00A0"
ZWSP =

Zero Width Space (indicate word boundaries without a space)

"\u200B"
SHY =

Soft Hyphen (invisible, except when causing a line break)

"\u00AD"

Stable API collapse

Methods included from Formatted

#formatted_text_box

Instance Method Details

#draw_text(text, options) ⇒ Object

Draws text on the page, beginning at the point specified by the :at option the string is assumed to be pre-formatted to properly fit the page.

pdf.draw_text "Hello World", :at => [100,100]
pdf.draw_text "Goodbye World", :at => [50,50], :size => 16

If your font contains kerning pair data that Prawn can parse, the text will be kerned by default. You can disable kerning by including a false :kerning option. If you want to disable kerning on an entire document, set default_kerning = false for that document

Text Positioning Details:

Prawn will position your text by the left-most edge of its baseline, and flow along a single line. (This means that :align will not work)

Rotation

Text can be rotated before it is placed on the canvas by specifying the :rotate option with a given angle. Rotation occurs counter-clockwise.

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 [])

:at

[x, y](required). The position at which to start the text

:kerning

boolean. Whether or not to use kerning (if it is available with the current font)

value of default_kerning?
:size

number. The font size to use. [current font size]

:style

The style to use. The requested style must be part of the current font familly. [current style]

:rotate

number. The angle to which to rotate text

Exceptions

Raises ArgumentError if :at option omitted

Raises ArgumentError if :align option included



276
277
278
279
280
281
282
283
284
285
286
 
# File 'lib/prawn/text.rb', line 276

def draw_text(text, options)
  options = inspect_options_for_draw_text(options.dup)

  # dup because normalize_encoding changes the string
  text = text.to_s.dup
  save_font do
    process_text_options(options)
    text = font.normalize_encoding(text)
    font_size(options[:size]) { draw_text!(text, options) }
  end
end

#draw_text!(text, options) ⇒ Object

Low level text placement method. All font and size alterations should already be set



291
292
293
294
295
296
297
298
299
300
301
302
303
304
 
# File 'lib/prawn/text.rb', line 291

def draw_text!(text, options)
  unless font.unicode? || font.class.hide_m17n_warning || text.ascii_only?
    warn "PDF's built-in fonts have very limited support for " \
         "internationalized text.\nIf you need full UTF-8 support, " \
         "consider using an external font instead.\n\nTo disable this " \
         "warning, add the following line to your code:\n" \
         "Prawn::Fonts::AFM.hide_m17n_warning = true\n"

    font.class.hide_m17n_warning = true
  end

  x, y = map_to_absolute(options[:at])
  add_text_content(text, x, y, options)
end

#formatted_text(array, options = {}) ⇒ Object

Draws formatted text to the page. Formatted text is comprised of an array of hashes, where each hash defines text and format information. See Text::Formatted#formatted_text_box for more information on the structure of this array

Example

text([{ :text => "hello" },
      { :text => "world",
        :size => 24,
        :styles => [:bold, :italic] }])

Options

Accepts the same options as #text

Exceptions

Same as for #text



190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
 
# File 'lib/prawn/text.rb', line 190

def formatted_text(array, options = {})
  options = inspect_options_for_text(options.dup)

  color = options.delete(:color)
  if color
    array =
      array.map do |fragment|
        fragment[:color] ? fragment : fragment.merge(color: color)
      end
  end

  if @indent_paragraphs
    text_formatter.array_paragraphs(array).each do |paragraph|
      remaining_text = draw_indented_formatted_line(paragraph, options)

      if @no_text_printed && !@all_text_printed
        @bounding_box.move_past_bottom
        remaining_text = draw_indented_formatted_line(paragraph, options)
      end

      unless @all_text_printed
        remaining_text = fill_formatted_text_box(remaining_text, options)
        draw_remaining_formatted_text_on_new_pages(remaining_text, options)
      end
    end
  else
    remaining_text = fill_formatted_text_box(array, options)
    draw_remaining_formatted_text_on_new_pages(remaining_text, options)
  end
end

#height_of(string, options = {}) ⇒ Object

Gets height of text in PDF points. Same options as #text, except as noted. Not compatible with :indent_paragraphs option

Example

height_of("hello\nworld")

Exceptions

Raises NotImplementedError if :indent_paragraphs option included

Raises Prawn::Errrors::CannotFit if not wide enough to print any text



322
323
324
 
# File 'lib/prawn/text.rb', line 322

def height_of(string, options = {})
  height_of_formatted([{ text: string }], options)
end

#height_of_formatted(array, options = {}) ⇒ Object

Gets height of formatted text in PDF points. See documentation for #height_of.

Example

height_of_formatted([{ :text => "hello" },
                     { :text => "world",
                       :size => 24,
                       :styles => [:bold, :italic] }])



336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
 
# File 'lib/prawn/text.rb', line 336

def height_of_formatted(array, options = {})
  if options[:indent_paragraphs]
    raise NotImplementedError,
      ':indent_paragraphs option not available with height_of'
  end
  process_final_gap_option(options)
  box = Text::Formatted::Box.new(
    array,
    options.merge(height: 100_000_000, document: self)
  )
  box.render(dry_run: true)

  height = box.height
  height += box.line_gap + box.leading if @final_gap
  height
end

#text(string, options = {}) ⇒ Object

If you want text to flow onto a new page or between columns, this is the method to use. If, instead, if you want to place bounded text outside of the flow of a document (for captions, labels, charts, etc.), use Text::Box or its convenience method text_box.

Draws text on the page. Prawn attempts to wrap the text to fit within your current bounding box (or margin_box if no bounding box is being used). Text will flow onto the next page when it reaches the bottom of the bounding box. Text wrap in Prawn does not re-flow linebreaks, so if you want fully automated text wrapping, be sure to remove newlines before attempting to draw your string.

Examples

pdf.text "Will be wrapped when it hits the edge of your bounding box"
pdf.text "This will be centered", :align => :center
pdf.text "This will be right aligned", :align => :right
pdf.text "This <i>includes <b>inline</b></i> <font size='24'>" +
         "formatting</font>", :inline_format => true

If your font contains kerning pair data that Prawn can parse, the text will be kerned by default. You can disable kerning by including a false :kerning option. If you want to disable kerning on an entire document, set default_kerning = false for that document

Text Positioning Details

The text is positioned at font.ascender below the baseline, making it easy to use this method within bounding boxes and spans.

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 [])

:inline_format

boolean. If true, then the string parameter is interpreted as a HTML-esque string that recognizes the following tags (assuming the default text formatter is used):

<b></b>

bold

<i></i>

italic

<u></u>

underline

<strikethrough></strikethrough>

strikethrough

<sub></sub>

subscript

<sup></sup>

superscript

<font></font>

with the following attributes (using double or single quotes)

<tt>size="24"</tt>::
    attribute for setting size
<tt>character_spacing="2.5"</tt>::
    attribute for setting character spacing
<tt>name="Helvetica"</tt>::
    attribute for setting the font. The font 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></color>

with the following attributes

<tt>rgb="ffffff" or rgb="#ffffff"</tt>::
<tt>c="100" m="100" y="100" k="100"</tt>::
<link></link>

with the following attributes

<tt>href="http://example.com"</tt>:: an external link

Note that you must explicitly underline and color using the appropriate tags if you which to draw attention to the link

: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]

:color

an RGB color (“ff0000”) or CMYK array [10, 20, 30, 40].

:character_spacing

number. The amount of space to add to or remove from the default character spacing. [0]

:style

The style to use. The requested style must be part of the current font familly. [current style]

:indent_paragraphs

number. The amount to indent the first line of each paragraph. Omit this option if you do not want indenting.

: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]

:leading

number. Additional space between lines [value of document.default_leading]

:final_gap

boolean. If true, then the space between each line is included below the last line; otherwise, document.y is placed just below the descender of the last line printed [true]

:mode

The text rendering mode to use. Use this to specify if the text should render with the fill color, stroke color or both. See the comments to text_rendering_mode() to see a list of valid options. [0]

Exceptions

Raises ArgumentError if :at option included

Raises Prawn::Errrors::CannotFit if not wide enough to print any text



152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
 
# File 'lib/prawn/text.rb', line 152

def text(string, options = {})
  return false if string.nil?

  # we modify the options. don't change the user's hash
  options = options.dup

  p = options[:inline_format]
  if p
    p = [] unless p.is_a?(Array)
    options.delete(:inline_format)
    array = text_formatter.format(string, *p)
  else
    array = [{ text: string }]
  end

  formatted_text(array, options)
end

#text_box(string, options = {}) ⇒ Object

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]

:disable_wrap_by_char

boolean Whether

or not to prevent mid-word breaks when text does not fit in box. [false]

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

Exceptions

Raises Prawn::Errors::CannotFit if not wide enough to print any text



106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
 
# File 'lib/prawn/text/box.rb', line 106

def text_box(string, options = {})
  options = options.dup
  options[:document] = self

  box =
    if options[:inline_format]
      p = options.delete(:inline_format)
      p = [] unless p.is_a?(Array)
      array = text_formatter.format(string, *p)
      Text::Formatted::Box.new(array, options)
    else
      Text::Box.new(string, options)
    end

  box.render
end