Namespace

Included Modules

Prawn::Text

Constants

VALID_OPTIONS

Public Instance Methods

draw_text(text, options) click to toggle source

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.

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.

Options (default values marked in [])

: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 185
185:     def draw_text(text, options)
186:       # we modify the options. don't change the user's hash
187:       options = options.dup
188:       inspect_options_for_draw_text(options)
189:       # dup because normalize_encoding changes the string
190:       text = text.to_s.dup
191:       options = @text_options.merge(options)
192:       save_font do
193:         process_text_options(options)
194:         font.normalize_encoding!(text) unless @skip_encoding
195:         font_size(options[:size]) { draw_text!(text, options) }
196:       end
197:     end
height_of(string, options={}) click to toggle source

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 27
27:     def height_of(string, options={})
28:       process_final_gap_option(options)
29:       box = Text::Box.new(string,
30:                           options.merge(:height   => 100000000,
31:                                         :document => self))
32:       box.render(:dry_run => true)
33:       height = box.height - box.descender
34:       height += box.line_height + box.leading - box.ascender if @final_gap
35:       height
36:     end
text(string, options={}) click to toggle source

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.

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 [])

: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 112
112:     def text(string, options={})
113:       # we modify the options. don't change the user's hash
114:       options = options.dup
115:       inspect_options_for_text(options)
116: 
117:       if @indent_paragraphs
118:         string.split("\n").each do |paragraph|
119:           options[:skip_encoding] = false
120:           remaining_text = draw_indented_line(paragraph, options)
121:           options[:skip_encoding] = true
122:           if remaining_text == paragraph
123:             # we were too close to the bottom of the page to print even one line
124:             @bounding_box.move_past_bottom
125:             remaining_text = draw_indented_line(paragraph, options)
126:           end
127:           remaining_text = fill_text_box(remaining_text, options)
128:           draw_remaining_text_on_new_pages(remaining_text, options)
129:         end
130:       else
131:         remaining_text = fill_text_box(string, options)
132:         options[:skip_encoding] = true
133:         draw_remaining_text_on_new_pages(remaining_text, options)
134:       end
135:     end
text_box(string, options) click to toggle source

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.

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 [])

: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

@document.bounds.left, @document.bounds.top
:width

number. The width of the box

@document.bounds.right - @at[0]
:height

number. The height of the box [@at[1] - @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

:truncate
: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 93
93:     def text_box(string, options)
94:       Text::Box.new(string, options.merge(:document => self)).render
95:     end

Private Instance Methods

draw_indented_line(string, options) click to toggle source
     # File lib/prawn/text.rb, line 210
210:     def draw_indented_line(string, options)
211:       indent(@indent_paragraphs) do
212:         fill_text_box(string, options.dup.merge(:single_line => true))
213:       end
214:     end
draw_remaining_text_on_new_pages(remaining_text, options) click to toggle source
     # File lib/prawn/text.rb, line 201
201:     def draw_remaining_text_on_new_pages(remaining_text, options)
202:       while remaining_text.length > 0
203:         @bounding_box.move_past_bottom
204:         previous_remaining_text = remaining_text
205:         remaining_text = fill_text_box(remaining_text, options)
206:         break if remaining_text == previous_remaining_text
207:       end
208:     end
fill_text_box(text, options) click to toggle source
     # File lib/prawn/text.rb, line 216
216:     def fill_text_box(text, options)
217:       bottom = @bounding_box.stretchy? ? @margin_box.absolute_bottom :
218:                                          @bounding_box.absolute_bottom
219: 
220:       options[:height] = y - bottom
221:       options[:width] = bounds.width
222:       options[:at] = [@bounding_box.left_side - @bounding_box.absolute_left,
223:                       y - @bounding_box.absolute_bottom]
224: 
225:       box = Text::Box.new(text, options)
226:       remaining_text = box.render
227: 
228:       self.y -= box.height - box.descender
229:       if @final_gap
230:         self.y -= box.line_height + box.leading - box.ascender
231:       end
232:       remaining_text
233:     end
inspect_options_for_draw_text(options) click to toggle source
     # File lib/prawn/text.rb, line 235
235:     def inspect_options_for_draw_text(options)
236:       if options[:at].nil?
237:         raise ArgumentError, "The :at option is required for draw_text"
238:       elsif options[:align]
239:         raise ArgumentError, "The :align option does not work with draw_text"
240:       end
241:       Prawn.verify_options(VALID_OPTIONS, options)
242:     end
inspect_options_for_text(options) click to toggle source
     # File lib/prawn/text.rb, line 244
244:     def inspect_options_for_text(options)
245:       if options[:at]
246:         raise ArgumentError, ":at is no longer a valid option with text." +
247:                              "use draw_text or text_box instead"
248:       end
249:       process_final_gap_option(options)
250:       process_indent_paragraphs_option(options)
251:       options[:document] = self
252:     end
move_text_position(dy) click to toggle source
     # File lib/prawn/text.rb, line 264
264:     def move_text_position(dy)
265:       bottom = @bounding_box.stretchy? ? @margin_box.absolute_bottom :
266:                                          @bounding_box.absolute_bottom
267: 
268:       @bounding_box.move_past_bottom if (y - dy) < bottom
269: 
270:       self.y -= dy
271:     end
process_final_gap_option(options) click to toggle source
     # File lib/prawn/text.rb, line 254
254:     def process_final_gap_option(options)
255:       @final_gap = options[:final_gap].nil? || options[:final_gap]
256:       options.delete(:final_gap)
257:     end
process_indent_paragraphs_option(options) click to toggle source
     # File lib/prawn/text.rb, line 259
259:     def process_indent_paragraphs_option(options)
260:       @indent_paragraphs = options[:indent_paragraphs]
261:       options.delete(:indent_paragraphs)
262:     end

Disabled; run with --debug to generate this.

[Validate]

Generated with the Darkfish Rdoc Generator 1.1.6.