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 pairs data that Prawn can parse, the text will be kerned by
default. You can disable this feature by passing :kerning =>
false
.
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)
Text can be rotated before it is placed on the
canvas by specifying the :rotate
option with a given angle.
Rotation occurs counter-clockwise.
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.
: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) [true]
: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
Raises ArgumentError
if :at
option omitted Raises
ArgumentError
if :align
option included
# File lib/prawn/text.rb, line 184 def draw_text(text, options) # we modify the options. don't change the user's hash options = options.dup inspect_options_for_draw_text(options) # dup because normalize_encoding changes the string text = text.to_s.dup options = @text_options.merge(options) save_font do process_text_options(options) font.normalize_encoding!(text) unless @skip_encoding font_size(options[:size]) { draw_text!(text, options) } end end
Gets height of text in PDF points. Same options as text(), except as noted. Not compatible with :indent_paragraphs option
Raises Prawn::Errors::UnknownOption
if
:indent_paragraphs
option included and debug flag is set
# File lib/prawn/text.rb, line 26 def height_of(string, options={}) process_final_gap_option(options) box = Text::Box.new(string, options.merge(:height => 100000000, :document => self)) box.render(:dry_run => true) height = box.height - box.descender height += box.line_height + box.leading - box.ascender if @final_gap height end
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.
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
If your font contains kerning pairs data that Prawn can parse, the text will be kerned by
default. You can disable this feature by passing :kerning =>
false
.
The text is positioned at font.ascender below the baseline, making it easy to use this method within bounding boxes and spans.
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.
:kerning
boolean
. Whether or not to use kerning (if it is available
with the current font) [true]
: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]
:indent_paragraphs
number
. The amount to indent the first line of each paragraph.
Omit this option if you do not want indenting
:align
:left
, :center
, or :right
. Alignment
within the bounding box [:left]
:valign
:top
, :center
, or :bottom
. Vertical
alignment within the bounding box [:top]
:leading
number
. Additional space between lines [0]
: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]
:wrap_block
proc
. A proc used for custom line wrapping. The proc must
accept a single line
of text and an options
hash
and return the string from that single line that can fit on the line under
the conditions defined by options
. If omitted, the default
wrapping proc is used. The options hash passed into the wrap_block proc
includes the following options:
:width
the width available for the current line of text
:document
the pdf object
:kerning
boolean
:size
the font size
Raises ArgumentError
if :at
option included
# File lib/prawn/text.rb, line 111 def text(string, options={}) # we modify the options. don't change the user's hash options = options.dup inspect_options_for_text(options) if @indent_paragraphs string.split("\n").each do |paragraph| options[:skip_encoding] = false remaining_text = draw_indented_line(paragraph, options) options[:skip_encoding] = true if remaining_text == paragraph # we were too close to the bottom of the page to print even one line @bounding_box.move_past_bottom remaining_text = draw_indented_line(paragraph, options) end remaining_text = fill_text_box(remaining_text, options) draw_remaining_text_on_new_pages(remaining_text, options) end else remaining_text = fill_text_box(string, options) options[:skip_encoding] = true draw_remaining_text_on_new_pages(remaining_text, options) end end
Draws the requested text into a box. When the text overflows the rectangle, you can display ellipses, shrink to fit, or truncate the text. Text boxes are independent of the document y position.
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.
:kerning
boolean
. Whether or not to use kerning (if it is available
with the current font) [true]
: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]
:at
[x, y]
. The upper left corner of the box
:width
number
. The width of the box
:height
number
. The height of the box [@at -
@document.bounds.bottom]
:align
:left
, :center
, or :right
. Alignment
within the bounding box [:left]
: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 [0]
:single_line
boolean
. If true, then only the first line will be drawn
[false]
:skip_encoding
boolean
[false]
:overflow
:truncate
, :shrink_to_fit
, :expand
,
or :ellipses
. This controls the behavior when the amount of
text exceeds the available space
: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]
:line_wrap
object
. An object used for custom line
wrapping on a case by case basis. Note that if you want to change wrapping document-wide, do pdf.default_line_wrap = MyLineWrap.new. Your custom object must have a wrap_line method that accept a single <tt>line</tt> of text and an <tt>options</tt> hash and returns the string from that single line that can fit on the line under the conditions defined by <tt>options</tt>. If omitted, the line wrap object is used. The options hash passed into the wrap_object proc includes the following options: <tt>:width</tt>:: the width available for the current line of text <tt>:document</tt>:: the pdf object <tt>:kerning</tt>:: boolean <tt>:size</tt>:: the font size
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.
# File lib/prawn/text/box.rb, line 92 def text_box(string, options) Text::Box.new(string, options.merge(:document => self)).render end