Module: Prawn::Document::Text

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

Constant Summary collapse

DEFAULT_FONT_SIZE = 
12
BUILT_INS =

The built in fonts specified by the Adobe PDF spec.

%w[ Courier Courier-Bold Courier-Oblique Courier-BoldOblique
Helvetica Helvetica-Bold Helvetica-Oblique
Helvetica-BoldOblique Times-Roman Times-Bold Times-Italic
Times-BoldItalic Symbol ZapfDingbats ]

Instance Method Summary collapse

Instance Method Details

#font(name) ⇒ Object

Sets the current font.

The single parameter must be a string. It can be one of the 14 built-in fonts supported by PDF, or the location of a TTF file. The BUILT_INS array specifies the valid built in font values.

pdf.font "Times-Roman"
pdf.font "Chalkboard.ttf"

If a ttf font is specified, the full file will be embedded in the rendered PDF. This should be your preferred option in most cases. It will increase the size of the resulting file, but also make it more portable.



105
106
107
108
109
110
111
112
113
114
115
 
# File 'lib/prawn/document/text.rb', line 105

def font(name)
  proc_set :PDF, :Text
  @font_metrics = Prawn::Font::Metrics[name]
  case(name)
  when /\.ttf$/
    @font = embed_ttf_font(name)
  else
    @font = register_builtin_font(name)
  end
  set_current_font
end

#font_metrics ⇒ Object

Access to low-level font metrics data. This is only necessary for those who require direct access to font attributes, and can be safely ignored otherwise.



87
88
89
 
# File 'lib/prawn/document/text.rb', line 87

def font_metrics 
  @font_metrics ||= Prawn::Font::Metrics["Helvetica"]
end

#font_size(size = nil) ⇒ Object

Sets the default font size for use within a block. Individual overrides can be used as desired. The previous font size will be restored after the block.

Prawn::Document.generate("font_size.pdf") do
 font_size!(16) 
 text "At size 16"

 font_size(10) do
   text "At size 10"
   text "At size 6", :size => 6
   text "At size 10"
 end

 text "At size 16"
end

When called without an argument, this method returns the current font size.



137
138
139
140
141
142
143
 
# File 'lib/prawn/document/text.rb', line 137

def font_size(size=nil)
  return current_font_size unless size
  font_size_before_block = @font_size || DEFAULT_FONT_SIZE
  font_size!(size)
  yield
  font_size!(font_size_before_block)
end

#font_size!(size) ⇒ Object Also known as: font_size=

Sets the default font size. See example in font_size



147
148
149
 
# File 'lib/prawn/document/text.rb', line 147

def font_size!(size)
  @font_size = size unless size == nil
end

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

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 margin_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 "Hello World", :at => [100,100]
pdf.text "Goodbye World", :at => [50,50], :size => 16
pdf.text "Will be wrapped when it hits the edge of your bounding box"

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.

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



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
 
# File 'lib/prawn/document/text.rb', line 47

def text(text,options={})
  # check the string is encoded sanely
  normalize_encoding(text)

  if options.key?(:kerning)
    options[:kerning] = false unless font_metrics.has_kerning_data?
  else
    options[:kerning] = true if font_metrics.has_kerning_data?
  end

  # ensure a valid font is selected
  font "Helvetica" unless fonts[@font]

  return wrapped_text(text,options) unless options[:at]
  
  x,y = translate(options[:at])
  font_size(options[:size] || current_font_size) do
    font_name = font_registry[fonts[@font]]          
    
    text = @font_metrics.convert_text(text,options)    

    add_content %Q{
      BT
      /#{font_name} #{current_font_size} Tf
      #{x} #{y} Td
    }
    
    add_content Prawn::PdfObject(text, true) << 
      " #{options[:kerning] ? 'TJ' : 'Tj'}\n"
    
    add_content %Q{
      ET
    }
  end
end