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.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
Overview
rubocop: disable Style/Documentation
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
-
#draw_text(text, options) ⇒ void
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.
-
#draw_text!(text, options) ⇒ void
Low level text placement method.
-
#formatted_text(array, options = {}) ⇒ void
Draws formatted text to the page.
-
#height_of(string, options = {}) ⇒ void
Gets height of text in PDF points.
-
#height_of_formatted(array, options = {}) ⇒ void
Gets height of formatted text in PDF points.
-
#text(string, options = {}) ⇒ void
Draws text on the page.
-
#text_box(string, options = {}) ⇒ String
Draws the requested text into a box.
Methods included from Formatted
Instance Method Details
#draw_text(text, options) ⇒ void
This method returns an undefined value.
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.
“‘ruby 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.
345 346 347 348 349 350 351 352 353 354 355 |
# File 'lib/prawn/text.rb', line 345 def draw_text(text, ) = (.dup) # dup because normalize_encoding changes the string text = text.to_s.dup save_font do () text = font.normalize_encoding(text) font_size([:size]) { draw_text!(text, ) } end end |
#draw_text!(text, options) ⇒ void
This method returns an undefined value.
Low level text placement method.
All font and size alterations should already be set.
375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 |
# File 'lib/prawn/text.rb', line 375 def draw_text!(text, ) 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([:at]) add_text_content(text, x, y, ) end |
#formatted_text(array, options = {}) ⇒ void
This method returns an undefined value.
Draws formatted text to the page.
Formatted text is an array of hashes, where each hash defines text and format information.
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 |
# File 'lib/prawn/text.rb', line 263 def formatted_text(array, = {}) = (.dup) color = .delete(:color) if color array = array.map { |fragment| fragment[:color] ? fragment : fragment.merge(color: color) } end if @indent_paragraphs text_formatter.array_paragraphs(array).each do |paragraph| remaining_text = draw_indented_formatted_line(paragraph, ) if @no_text_printed && !@all_text_printed @bounding_box.move_past_bottom remaining_text = draw_indented_formatted_line(paragraph, ) end unless @all_text_printed remaining_text = fill_formatted_text_box(remaining_text, ) draw_remaining_formatted_text_on_new_pages(remaining_text, ) end end else remaining_text = fill_formatted_text_box(array, ) draw_remaining_formatted_text_on_new_pages(remaining_text, ) end end |
#height_of(string, options = {}) ⇒ void
This method takes the same options as #text, except ‘:indent_paragraphs`.
This method returns an undefined value.
Gets height of text in PDF points.
480 481 482 |
# File 'lib/prawn/text.rb', line 480 def height_of(string, = {}) height_of_formatted([{ text: string }], ) end |
#height_of_formatted(array, options = {}) ⇒ void
This method takes the same options as #text, except ‘:indent_paragraphs`.
This method returns an undefined value.
Gets height of formatted text in PDF points.
575 576 577 578 579 580 581 582 583 584 585 586 587 588 589 590 |
# File 'lib/prawn/text.rb', line 575 def height_of_formatted(array, = {}) if [:indent_paragraphs] raise NotImplementedError, ':indent_paragraphs option not available with height_of' end process_final_gap_option() box = Text::Formatted::Box.new( array, .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 = {}) ⇒ void
This method returns an undefined value.
Draws text on the page.
If you want text to flow onto a new page or between columns, this is the method to use. If, instead, you want to place bounded text outside of the flow of a document (for captions, labels, charts, etc.), use Box or its convenience method #text_box.
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 line breaks, so if you want fully automated text wrapping, be sure to remove newlines before attempting to draw your string.
#### Examples
“‘ruby 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 includes inline <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.
151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 |
# File 'lib/prawn/text.rb', line 151 def text(string, = {}) return false if string.nil? # we modify the options. don't change the user's hash = .dup p = [:inline_format] if p p = [] unless p.is_a?(Array) .delete(:inline_format) array = text_formatter.format(string, *p) else array = [{ text: string }] end formatted_text(array, ) end |
#text_box(string, options = {}) ⇒ String
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.
83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 |
# File 'lib/prawn/text/box.rb', line 83 def text_box(string, = {}) = .dup [:document] = self box = if [:inline_format] p = .delete(:inline_format) p = [] unless p.is_a?(Array) array = text_formatter.format(string, *p) Text::Formatted::Box.new(array, ) else Text::Box.new(string, ) end box.render end |