Module: Prawn::Document::Text

Included in:
Prawn::Document
Defined in:
lib/prawn/document/text.rb

Instance Method Summary collapse

Instance Method Details

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

Draws text on the page. If a point is specified via the :at option the text will begin exactly at that point, and the string is assumed to be pre-formatted to properly fit the page.

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

When :at is not specified, 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     

Wrapping is done by splitting words by spaces by default.  If your text
does not contain spaces, you can wrap based on characters instead:

 pdf.text "This will be wrapped by character", :wrap => :character

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.

Text Positioning Details:

When using the :at parameter, Prawn will position your text by its baseline, and flow along a single line.

When using automatic text flow, Prawn will position your text exactly font.height below the baseline, and space each line of text by font.height + options (default 0)

Finally, the drawing position will be moved to the baseline of final line of text, plus any additional spacing.

If you wish to position your flowing text by it’s baseline rather than font.height below, simply call move_up font.height before your call to text()

Character Encoding Details:

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 ISO-8859-1 are allowed (transliteration will be attempted).

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.



69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
 
# File 'lib/prawn/document/text.rb', line 69

def text(text,options={})            
  # we'll be messing with the strings encoding, don't change the users
  # original string
  text = text.to_s.dup                      
  
  # we might also mess with the font
  original_font  = font.name   
        
  options = text_options.merge(options)
  process_text_options(options) 
   
  font.normalize_encoding(text) unless @skip_encoding        

  if options[:at]                
    x,y = translate(options[:at])            
    font.size(options[:size]) { add_text_content(text,x,y,options) }
  else
    wrapped_text(text,options)
  end         

  font(original_font) 
end

#text_options ⇒ Object

A hash of configuration options, to be used globally by text().

pdf.text_options.update(:size => 16, :align => :right)   
pdf.text "Hello World" #=> Size 16 w. right alignment



97
98
99
 
# File 'lib/prawn/document/text.rb', line 97

def text_options
  @text_options ||= {}
end