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 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 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 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456
|
# frozen_string_literal: true
# text.rb : Implements PDF text primitives
#
# Copyright May 2008, Gregory Brown. All Rights Reserved.
#
# This is free software. Please see the LICENSE and COPYING files for details.
require 'zlib'
require_relative 'text/formatted'
require_relative 'text/box'
module Prawn
module Text
include PDF::Core::Text
include Prawn::Text::Formatted
# No-Break Space
NBSP = "\u00A0"
# Zero Width Space (indicate word boundaries without a space)
ZWSP = "\u200B"
# Soft Hyphen (invisible, except when causing a line break)
SHY = "\u00AD"
# @group Stable API
# 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 <tt>:kerning</tt> 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 [])
#
# <tt>:inline_format</tt>::
# <tt>boolean</tt>. 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):
# <tt>\<b></b></tt>:: bold
# <tt>\<i></i></tt>:: italic
# <tt>\<u></u></tt>:: underline
# <tt>\<strikethrough></strikethrough></tt>:: strikethrough
# <tt>\<sub></sub></tt>:: subscript
# <tt>\<sup></sup></tt>:: superscript
# <tt>\<font></font></tt>::
# 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
# <tt>\<color></color></tt>::
# with the following attributes
# <tt>rgb="ffffff" or rgb="#ffffff"</tt>::
# <tt>c="100" m="100" y="100" k="100"</tt>::
# <tt>\<link></link></tt>::
# 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
#
# <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>:color</tt>:: an RGB color ("ff0000") or CMYK array [10, 20, 30, 40].
# <tt>:character_spacing</tt>:: <tt>number</tt>. The amount of space to add
# to or remove from the default character
# spacing. [0]
# <tt>:style</tt>:: The style to use. The requested style must be part of
# the current font familly. [current style]
# <tt>:indent_paragraphs</tt>:: <tt>number</tt>. The amount to indent the
# first line of each paragraph. Omit this
# option if you do not want indenting.
# <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>:leading</tt>::
# <tt>number</tt>. Additional space between lines [value of
# document.default_leading]
# <tt>:final_gap</tt>:: <tt>boolean</tt>. 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]
# <tt>:mode</tt>:: 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 <tt>ArgumentError</tt> if <tt>:at</tt> option included
#
# Raises <tt>Prawn::Errrors::CannotFit</tt> if not wide enough to print
# any text
#
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
# 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
#
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
# unless this paragraph was an empty line
unless @all_text_printed
@bounding_box.move_past_bottom
remaining_text = draw_indented_formatted_line(paragraph, options)
end
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
# 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 <tt>:kerning</tt> 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
# <tt>:rotate</tt> 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 [])
#
# <tt>:at</tt>:: <tt>[x, y]</tt>(required). The position at which to start
# the text
# <tt>:kerning</tt>:: <tt>boolean</tt>. Whether or not to use kerning (if it
# is available with the current font)
# [value of default_kerning?]
# <tt>:size</tt>:: <tt>number</tt>. The font size to use. [current font
# size]
# <tt>:style</tt>:: The style to use. The requested style must be part of
# the current font familly. [current style]
#
# <tt>:rotate</tt>:: <tt>number</tt>. The angle to which to rotate text
#
# == Exceptions
#
# Raises <tt>ArgumentError</tt> if <tt>:at</tt> option omitted
#
# Raises <tt>ArgumentError</tt> if <tt>:align</tt> option included
#
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
# Low level text placement method. All font and size alterations
# should already be set
#
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
# 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 <tt>NotImplementedError</tt> if <tt>:indent_paragraphs</tt>
# option included
#
# Raises <tt>Prawn::Errrors::CannotFit</tt> if not wide enough to print
# any text
#
def height_of(string, options = {})
height_of_formatted([{ text: string }], options)
end
# 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] }])
#
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
private
def draw_remaining_formatted_text_on_new_pages(remaining_text, options)
until remaining_text.empty?
@bounding_box.move_past_bottom
previous_remaining_text = remaining_text
remaining_text = fill_formatted_text_box(remaining_text, options)
break if remaining_text == previous_remaining_text
end
end
def draw_indented_formatted_line(string, options)
gap = if options.fetch(:direction, text_direction) == :ltr
[@indent_paragraphs, 0]
else
[0, @indent_paragraphs]
end
indent(*gap) do
fill_formatted_text_box(string, options.dup.merge(single_line: true))
end
end
def fill_formatted_text_box(text, options)
merge_text_box_positioning_options(options)
box = Text::Formatted::Box.new(text, options)
remaining_text = box.render
@no_text_printed = box.nothing_printed?
@all_text_printed = box.everything_printed?
self.y -= box.height
self.y -= box.line_gap + box.leading if @final_gap
remaining_text
end
def merge_text_box_positioning_options(options)
bottom =
if @bounding_box.stretchy?
@margin_box.absolute_bottom
else
@bounding_box.absolute_bottom
end
options[:height] = y - bottom
options[:width] = bounds.width
options[:at] = [
@bounding_box.left_side - @bounding_box.absolute_left,
y - @bounding_box.absolute_bottom
]
end
def inspect_options_for_draw_text(options)
if options[:at].nil?
raise ArgumentError, 'The :at option is required for draw_text'
elsif options[:align]
raise ArgumentError, 'The :align option does not work with draw_text'
end
if options[:kerning].nil?
options[:kerning] = default_kerning?
end
valid_options = PDF::Core::Text::VALID_OPTIONS + %i[at rotate]
Prawn.verify_options(valid_options, options)
options
end
def inspect_options_for_text(options)
if options[:at]
raise ArgumentError, ':at is no longer a valid option with text.' \
'use draw_text or text_box instead'
end
process_final_gap_option(options)
process_indent_paragraphs_option(options)
options[:document] = self
options
end
def process_final_gap_option(options)
@final_gap = options[:final_gap].nil? || options[:final_gap]
options.delete(:final_gap)
end
def process_indent_paragraphs_option(options)
@indent_paragraphs = options[:indent_paragraphs]
options.delete(:indent_paragraphs)
end
def move_text_position(amount)
bottom =
if @bounding_box.stretchy?
@margin_box.absolute_bottom
else
@bounding_box.absolute_bottom
end
@bounding_box.move_past_bottom if (y - amount) < bottom
self.y -= amount
end
end
end
|