The Artima Developer Community
Sponsored Link

Ruby Code & Style
Creating Printable Documents with Ruby
by Austin Ziegler
October 10, 2005

<<  Page 2 of 4  >>


More Text

The PDF::Writer#text method takes care of all text wrapping for you, the writer. That means that if your text will not fit on a single line, then it will be wrapped. If your text will not fit on a single page, then a new page will automatically be created. The layout engine in PDF::Writer is extensive and somewhat extensible. By no means is it capable of replacing a professional layout program (or even a simple word processor), but it is very good at what it does. Sometimes, however, it is necessary for the author of a document generation program to indicate precisely where text should go.

This is when PDF::Writer#add_text and PDF::Writer#add_text_wrap are useful. The former will take a string and place it starting at specific (x, y) coordinates. If the text exceeds the size of the page, it will not stop. The latter also accepts a text width and writes only as much text from the original string as will fit in the specified width. The portion of the text that does not fit will be returned. Both of these methods also accept a font size (by default, the current PDF::Writer#font_size will be used) and a text angle. The following code puts our “Hello, Ruby” text in a different location on the page and at an angle.

      require "pdf/writer"

      pdf =
      pdf.select_font "Times-Roman"
      x = pdf.absolute_left_margin
      y = pdf.absolute_bottom_margin
      pdf.add_text(x, y, "Hello, Ruby.", 72, 45)
Hello, Ruby, tilted.
Figure 2. Hello, Ruby, angled text PDF example

A Brief Explanation of PDF Units and Coordinate Spaces

Measurements in PDF documents are by default in points (about 1/72”, or 1/3mm). The coordinate space can be rotated, scaled, and translated, so all measurements are in “userspace units”. The origin coordinate, (0, 0) in PDF is not at the upper left-hand corner, but instead is in the lower left-hand corner of the page. The PDF::Writer text layout engine assumes the default coordinate space size and orientation.

All angular measurements in PDF::Writer (for both text and graphics) are counter-clockwise. The following table shows the approximate degree measurement of hours on a twelve-hour clock face.


More Than Text

Text documents are useful, but sometimes, as the cliché says, “a picture is worth a thousand words.” PDF fundamentally supports both “sampled” (that is, bitmapped) and drawn vector graphics. PDF::Writer exposes this functionality to the Ruby developer.

Inserting Images

PDF::Writer only supports the insertion of JPEG and PNG format images, and there is limited support for some of the PNG format’s features. Other formats can be supported by conversion, possibly through RMagick[11] Images may either be placed at specific points on the page canvas (with PDF::Writer::Graphics#add_image and PDF::Writer::Graphics#add_image_from_file) or flowed onto the page relative to the vertical text writing pointer with PDF::Writer::Graphics#image.

Images are inserted using one pixel per PDF unit. This means that images are generally inserted with 72 DPI (dots per inch)[12] and must be scaled for higher quality printing images. With #add_image and #add_image_from_file this means specifying an image display size; #image allows for relative scaling. The following table shows what an image of 320×240 pixels would need to be at various DPI resolutions and the corresponding approximate physical image size. Most computer displays are 72 or 96 DPI; “photo-quality” printed images are usually 300 DPI or better.

DPIScalePixel SizePhysical Size
72100% (1.0)320×24041/2”×31/4” (113mm × 85mm)
9675% (0.75)240×18031/3”×21/2” (85mm × 631/2mm)
30024% (0.24)77×581”×0.8” (27mm × 201/2mm)

This demo uses the automatic positioning of #image to insert similar images. Notice that all three image methods return the image object that was added to the document so that it can be reused (as it is in the third case). In all three inserts, the images will be scaled to 75% of their native size, treating them as 96 DPI.

      # This code is demo/chunkybacon.rb
      require "pdf/writer"

      pdf =
      pdf.select_font "Times-Roman"
      pdf.text "Chunky Bacon!!", :font_size => 72, :justification => :center

      # PDF::Writer#image returns the image object that was added.
      i0 = pdf.image "../images/chunkybacon.jpg", :resize => 0.75
      pdf.image "../images/chunkybacon.png", :justification => :center, :resize => 0.75

      # It can reinsert an image if wanted.
      pdf.image i0, :justification => :right, :resize => 0.75

      pdf.text "Chunky Bacon!!", :font_size => 72, :justification => :center

Chunky bacon!
Figure 3. Chunky Bacon PDF Example

<<  Page 2 of 4  >>

Sponsored Links

Copyright © 1996-2014 Artima, Inc. All Rights Reserved. - Privacy Policy - Terms of Use - Advertise with Us