Method: Prawn::Document#bounding_box

Defined in:

lib/prawn/document/bounding_box.rb

#bounding_box(*args, &block) ⇒ Object

A bounding box serves two important purposes:

• Provide bounds for flowing text, starting at a given point

• Translate the origin (0,0) for graphics primitives, for the purposes

of simplifying coordinate math.

When flowing text, the usage of a bounding box is simple. Text will begin at the point specified, flowing the width of the bounding box. After the block exits, the text drawing position will be moved to the bottom of the bounding box (y - height). Currently, Prawn allows text to overflow the bottom border of the bounding box, so it is up to the user to ensure the text provided will fit within the height of the bounding box.

pdf.bounding_box(, :width => 100, :height => 300) do pdf.text “This text will flow in a very narrow box starting” + “from [100,500]. The pointer will then be moved to [100,200]” + “and return to the margin_box” end

When translating coordinates, the idea is to allow the user to draw relative to the origin, and then translate their drawing to a specified area of the document, rather than adjust all their drawing coordinates to match this new region.

Take for example two triangles which share one point, drawn from the origin:

pdf.polygon [0,250], [0,0], [150,100]
pdf.polygon [100,0], [150,100], [200,0]

It would be easy enough to translate these triangles to another point, e.g [200,200]

pdf.polygon [200,450], [200,200], [350,300]
pdf.polygon [300,200], [350,300], [400,200]

However, each time you want to move the drawing, you’d need to alter every point in the drawing calls, which as you might imagine, can become tedious.

If instead, we think of the drawing as being bounded by a box, we can see that the image is 200 points wide by 250 points tall.

To translate it to a new origin, we simply select a point at (x,y+height)

Using the [200,200] example:

pdf.bounding_box([200,450], :width => 200, :height => 250) do
  pdf.polygon [0,250], [0,0], [150,100]
  pdf.polygon [100,0], [150,100], [200,0]
end

Notice that the drawing is still relative to the origin. If we want to move this drawing around the document, we simply need to recalculate the top-left corner of the rectangular bounding-box, and all of our graphics calls remain unmodified.

By default, bounding boxes are specified relative to the document’s margin_box (which is itself a bounding box). You can also nest bounding boxes, allowing you to build components which are relative to each other

pdf.bouding_box(, :width => 200, :height => 250) do

pdf.bounding_box([50,200], :width => 50, :height => 50) do
  # a 50x50 bounding box that starts 50 pixels left and 50 pixels down 
  # the parent bounding box.
end

end

If you wish to position the bounding boxes at absolute coordinates rather than relative to the margins or other bounding boxes, you can use canvas()

pdf.canvas do
  pdf.bounding_box([200,450], :width => 200, :height => 250) do
    # positioned at 'real' (200,450)
  end
end

Of course, if you use canvas, you will be responsible for ensuring that you remain within the printable area of your document.

# File 'lib/prawn/document/bounding_box.rb', line 86

def bounding_box(*args, &block)    
  init_bounding_box(block) do |parent_box|
    # Offset to relative positions
    top_left = args[0]
    top_left[0] += parent_box.absolute_left
    top_left[1] += parent_box.absolute_bottom

    @bounding_box = BoundingBox.new(self, *args)   
  end
end