prawn 0.11.1 → 0.15.0

data/manual/graphics/graphics.rb

@@ -0,0 +1,58 @@
+# encoding: utf-8
+#
+# Examples for the Graphics package.
+#
+require File.expand_path(File.join(File.dirname(__FILE__),
+                                   %w[.. example_helper]))
+
+Prawn::Example.generate("graphics.pdf", :page_size => "FOLIO") do
+  
+  package "graphics" do |p|
+    
+    p.section "Basics" do |s|
+      s.example "helper"
+      s.example "fill_and_stroke"
+    end
+    
+    p.section "Shapes" do |s|
+      s.example "lines_and_curves"
+      s.example "common_lines"
+      s.example "rectangle"
+      s.example "polygon"
+      s.example "circle_and_ellipse"
+    end
+    
+    p.section "Fill and Stroke settings" do |s|
+      s.example "line_width"
+      s.example "stroke_cap"
+      s.example "stroke_join"
+      s.example "stroke_dash"
+      s.example "color"
+      s.example "gradients"
+      s.example "transparency"
+      s.example "soft_masks"
+      s.example "fill_rules"
+    end
+    
+    p.section "Transformations" do |s|
+      s.example "rotate"
+      s.example "translate"
+      s.example "scale"
+    end
+    
+    p.intro do
+      prose("Here we show all the drawing methods provided by Prawn. Use them to draw the most beautiful imaginable things.
+
+      Most of the content that you'll add to your pdf document will use the graphics package. Even text is rendered on a page just like a rectangle so even if you never use any of the shapes described here you should at least read the basic examples.
+
+      The examples show:")
+
+      list( "All the possible ways that you can fill or stroke shapes on a page",
+            "How to draw all the shapes that Prawn has to offer from a measly line to a mighty polygon or ellipse",
+            "The configuration options for stroking lines and filling shapes",
+            "How to apply transformations to your drawing space"
+          )
+    end
+    
+  end
+end

data/manual/graphics/helper.rb

@@ -0,0 +1,24 @@
+# encoding: utf-8
+#
+# To produce this manual we use the <code>stroke_axis</code> helper method
+# within the examples.
+#
+# <code>stroke_axis</code> prints the x and y axis for the current bounding box
+# with markers in 100 increments. The defaults can be changed with various
+# options.
+#
+# Note that the examples define a custom <code>:height</code> option so that
+# only the example canvas is used (as seen with the output of the first line of
+# the example code).
+#
+require File.expand_path(File.join(File.dirname(__FILE__),
+                                   %w[.. example_helper]))
+
+filename = File.basename(__FILE__).gsub('.rb', '.pdf')
+Prawn::Example.generate(filename) do
+  stroke_axis
+  stroke_axis(:at => [70, 70], :height => 200, :step_length => 50,
+              :negative_axes_length => 5, :color => '0000FF')
+  stroke_axis(:at => [140, 140], :width => 200, :height => cursor.to_i - 140,
+              :step_length => 20, :negative_axes_length => 40, :color => 'FF00')
+end

data/manual/graphics/line_width.rb

@@ -0,0 +1,35 @@
+# encoding: utf-8
+#
+# The <code>line_width=</code> method sets the stroke width for subsequent
+# stroke calls.
+#
+# Since Ruby assumes that an unknown variable on the left hand side of an
+# assignment is a local temporary, rather than a setter method, if you are using
+# the block call to <code>Prawn::Document.generate</code> without passing params
+# you will need to call <code>line_width</code> on self.
+#
+require File.expand_path(File.join(File.dirname(__FILE__),
+                                   %w[.. example_helper]))
+
+filename = File.basename(__FILE__).gsub('.rb', '.pdf')
+Prawn::Example.generate(filename) do
+  stroke_axis
+  
+  y = 250
+  
+  3.times do |i|
+    case i
+    when 0 then line_width = 10        # This call will have no effect
+    when 1 then self.line_width = 10
+    when 2 then self.line_width = 25
+    end
+    
+    stroke do
+      horizontal_line 50, 150, :at => y
+      rectangle [275, y + 25], 50, 50
+      circle [500, y], 25
+    end
+    
+    y -= 100
+  end
+end

data/manual/graphics/lines_and_curves.rb

@@ -0,0 +1,41 @@
+# encoding: utf-8
+#
+# Prawn supports drawing both lines and curves starting either at the current
+# position, or from a specified starting position.
+#
+# <code>line_to</code> and <code>curve_to</code> set the drawing path from the
+# current drawing position to the specified point. The initial drawing position
+# can be set with <code>move_to</code>. They are useful when you want to chain
+# successive calls because the drawing position will be set to the specified
+# point afterwards.
+#
+# <code>line</code> and <code>curve</code> set the drawing path between the two
+# specified points.
+#
+# Both curve methods define a Bezier curve bounded by two aditional points
+# provided as the <code>:bounds</code> param.
+#
+require File.expand_path(File.join(File.dirname(__FILE__),
+                                   %w[.. example_helper]))
+
+filename = File.basename(__FILE__).gsub('.rb', '.pdf')
+Prawn::Example.generate(filename) do
+  stroke_axis
+  
+  # line_to and curve_to
+  stroke do
+    move_to 0, 0
+  
+    line_to 100, 100
+    line_to 0, 100
+  
+    curve_to [150, 250], :bounds => [[20, 200], [120, 200]]
+    curve_to [200, 0],   :bounds => [[150, 200], [450, 10]]
+  end
+  
+  # line and curve
+  stroke do
+    line [300,200], [400,50]
+    curve [500, 0], [400, 200], :bounds => [[600, 300], [300, 390]]
+  end
+end

data/manual/graphics/polygon.rb

@@ -0,0 +1,29 @@
+# encoding: utf-8
+#
+# Drawing polygons in Prawn is easy, just pass a sequence of points to one of
+# the polygon family of methods.
+#
+# Just like <code>rounded_rectangle</code> we also have
+# <code>rounded_polygon</code>. The only difference is the radius param comes
+# before the polygon points.
+#
+require File.expand_path(File.join(File.dirname(__FILE__),
+                                   %w[.. example_helper]))
+
+filename = File.basename(__FILE__).gsub('.rb', '.pdf')
+Prawn::Example.generate(filename) do
+  stroke_axis
+
+  # Triangle
+  stroke_polygon [50, 200], [50, 300], [150, 300]
+  
+  # Hexagon
+  fill_polygon [50, 150], [150, 200], [250, 150],
+               [250, 50], [150, 0], [50, 50]
+  
+  # Pentagram
+  pentagon_points = [500, 100], [430, 5], [319, 41], [319, 159], [430, 195]
+  pentagram_points = [0, 2, 4, 1, 3].map{ |i| pentagon_points[i] }
+  
+  stroke_rounded_polygon(20, *pentagram_points)
+end

data/manual/graphics/rectangle.rb

@@ -0,0 +1,21 @@
+# encoding: utf-8
+#
+# To draw a rectangle, just provide the upper-left corner, width and height to
+# the <code>rectangle</code> method.
+#
+# There's also <code>rounded_rectangle</code>. Just provide an additional radius
+# value for the rounded corners.
+#
+require File.expand_path(File.join(File.dirname(__FILE__),
+                                   %w[.. example_helper]))
+
+filename = File.basename(__FILE__).gsub('.rb', '.pdf')
+Prawn::Example.generate(filename) do
+  stroke_axis
+  
+  stroke do
+    rectangle [100, 300], 100, 200
+    
+    rounded_rectangle [300, 300], 100, 200, 20
+  end
+end

data/manual/graphics/rotate.rb

@@ -0,0 +1,28 @@
+# encoding: utf-8
+#
+# This transformation is used to rotate the user space. Give it an angle
+# and an <code>:origin</code> point about which to rotate and a block.
+# Everything inside the block will be drawn with the rotated coordinates.
+#
+# The angle is in degrees.
+#
+# If you omit the <code>:origin</code> option the page origin will be used.
+#
+require File.expand_path(File.join(File.dirname(__FILE__),
+                                   %w[.. example_helper]))
+
+filename = File.basename(__FILE__).gsub('.rb', '.pdf')
+Prawn::Example.generate(filename) do
+  stroke_axis
+  
+  fill_circle [250, 200], 2
+  
+  12.times do |i|
+    
+    rotate(i * 30, :origin => [250, 200]) do
+      
+      stroke_rectangle [350, 225], 100, 50
+      draw_text "Rotated #{i * 30}°", :size => 10, :at => [360, 205]
+    end
+  end
+end

data/manual/graphics/scale.rb

@@ -0,0 +1,41 @@
+# encoding: utf-8
+#
+# This transformation is used to scale the user space. Give it an scale factor
+# and an <code>:origin</code> point and everything inside the block will be
+# scaled using the origin point as reference.
+#
+# If you omit the <code>:origin</code> option the page origin will be used.
+#
+require File.expand_path(File.join(File.dirname(__FILE__),
+                                   %w[.. example_helper]))
+
+filename = File.basename(__FILE__).gsub('.rb', '.pdf')
+Prawn::Example.generate(filename) do
+  stroke_axis
+  
+  width = 100
+  height = 50
+  
+  x = 50
+  y = 200
+
+  stroke_rectangle [x, y], width, height
+  text_box "reference rectangle", :at => [x + 10, y - 10], :width => width - 20
+  
+  scale(2, :origin => [x, y]) do
+    stroke_rectangle [x, y], width, height
+    text_box "rectangle scaled from upper-left corner",
+              :at => [x, y - height - 5], :width => width
+  end
+
+  x = 350
+
+  stroke_rectangle [x, y], width, height
+  text_box "reference rectangle", :at => [x + 10, y - 10], :width => width - 20
+  
+  scale(2, :origin => [x + width / 2, y - height / 2]) do
+    stroke_rectangle [x, y], width, height
+    text_box "rectangle scaled from center",
+              :at => [x, y - height - 5], :width => width
+  end
+end

data/manual/graphics/soft_masks.rb

@@ -0,0 +1,46 @@
+# encoding: utf-8
+#
+# Soft masks are user for more complex alpha channel manipulations. You can use
+# arbitrary drawing functions for creation of soft masks. The resulting alpha
+# channel is made of greyscale version of the drawing (luminosity channel to be
+# precise). So while you can use any combination of colors for soft masks it's
+# easier to use greyscales. Black will result in full transparency and white
+# will make region fully opaque.
+#
+# Soft mask is a part of page graphic state. So if you want to apply soft mask
+# only to a part of page you need to enclose drawing instructions in
+# <code>save_graphics_state</code> block.
+
+require File.expand_path(File.join(File.dirname(__FILE__),
+                                   %w[.. example_helper]))
+
+filename = File.basename(__FILE__).gsub('.rb', '.pdf')
+Prawn::Example.generate(filename) do
+  save_graphics_state do
+    soft_mask do
+      0.upto 15 do |i|
+        fill_color 0, 0, 0, 100.0 / 16.0 * (15 - i)
+        fill_circle [75 + i * 25, 100], 60
+      end
+    end
+
+    fill_color '009ddc'
+    fill_rectangle [0, 60], 600, 20
+
+    fill_color '963d97'
+    fill_rectangle [0, 80], 600, 20
+
+    fill_color 'e03a3e'
+    fill_rectangle [0, 100], 600, 20
+
+    fill_color 'f5821f'
+    fill_rectangle [0, 120], 600, 20
+
+    fill_color 'fdb827'
+    fill_rectangle [0, 140], 600, 20
+
+    fill_color '61bb46'
+    fill_rectangle [0, 160], 600, 20
+  end
+
+end

data/manual/graphics/stroke_cap.rb

@@ -0,0 +1,31 @@
+# encoding: utf-8
+#
+# The cap style defines how the edge of a line or curve will be drawn. There are
+# three types: <code>:butt</code> (the default), <code>:round</code> and
+# <code>:projecting_square</code>
+#
+# The difference is better seen with thicker lines. With <code>:butt</code>
+# lines are drawn starting and ending at the exact points provided. With both
+# <code>:round</code> and <code>:projecting_square</code> the line is projected
+# beyond the start and end points.
+#
+# Just like <code>line_width=</code> the <code>cap_style=</code> method needs an
+# explicit receiver to work.
+#
+require File.expand_path(File.join(File.dirname(__FILE__),
+                                   %w[.. example_helper]))
+
+filename = File.basename(__FILE__).gsub('.rb', '.pdf')
+Prawn::Example.generate(filename) do
+  stroke_axis
+  
+  self.line_width = 25
+
+  [:butt, :round, :projecting_square].each_with_index do |cap, i|
+    self.cap_style = cap
+    
+    y = 250 - i*100
+    stroke_horizontal_line 100, 300, :at => y
+    stroke_circle [400, y], 15
+  end
+end

data/manual/graphics/stroke_dash.rb

@@ -0,0 +1,48 @@
+# encoding: utf-8
+#
+# This sets the dashed pattern for lines and curves. The (dash) length defines
+# how long each dash will be.
+#
+# The <code>:space</code> option defines the length of the space between the
+# dashes.
+#
+# The <code>:phase</code> option defines the start point of the sequence of
+# dashes and spaces.
+#
+# Complex dash patterns can be specified by using an array with alternating
+# dash/gap lengths for the first parameter (note that the <code>:space</code>
+# option is ignored in this case).
+#
+require File.expand_path(File.join(File.dirname(__FILE__),
+                                   %w[.. example_helper]))
+
+filename = File.basename(__FILE__).gsub('.rb', '.pdf')
+Prawn::Example.generate(filename) do
+  stroke_axis
+
+  dash([1, 2, 3, 2, 1, 5], :phase => 6)
+  stroke_horizontal_line 50, 500, :at => 230
+  dash([1, 2, 3, 4, 5, 6, 7, 8])
+  stroke_horizontal_line 50, 500, :at => 220
+
+  base_y = 210
+
+  24.times do |i|
+    length = (i / 4) + 1
+    space = length            # space between dashes same length as dash
+    phase = 0                 # start with dash
+
+    case i % 4
+    when 0 then base_y -= 5
+    when 1 then phase = length        # start with space between dashes
+    when 2 then space = length * 0.5  # space between dashes half as long as dash
+    when 3
+      space = length * 0.5    # space between dashes half as long as dash
+      phase = length          # start with space between dashes
+    end
+    base_y -= 5
+
+    dash(length, :space => space, :phase => phase)
+    stroke_horizontal_line 50, 500, :at => base_y - (2 * i)
+  end
+end

data/manual/graphics/stroke_join.rb

@@ -0,0 +1,30 @@
+# encoding: utf-8
+#
+# The join style defines how the intersection between two lines is drawn. There
+# are three types: <code>:miter</code> (the default), <code>:round</code> and
+# <code>:bevel</code>
+#
+# Just like <code>cap_style</code>, the difference between styles is better
+# seen with thicker lines.
+#
+require File.expand_path(File.join(File.dirname(__FILE__),
+                                   %w[.. example_helper]))
+
+filename = File.basename(__FILE__).gsub('.rb', '.pdf')
+Prawn::Example.generate(filename) do
+  stroke_axis
+  
+  self.line_width = 25
+  
+  [:miter, :round, :bevel].each_with_index do |style, i|
+    self.join_style = style
+    
+    y = 200 - i*100
+    stroke do
+      move_to(100, y)
+      line_to(200, y + 100)
+      line_to(300, y)
+    end
+    stroke_rectangle [400, y + 75], 50, 50
+  end
+end

data/manual/graphics/translate.rb

@@ -0,0 +1,29 @@
+# encoding: utf-8
+#
+# This transformation is used to translate the user space. Just provide the
+# x and y coordinates for the new origin.
+#
+require File.expand_path(File.join(File.dirname(__FILE__),
+                                   %w[.. example_helper]))
+
+filename = File.basename(__FILE__).gsub('.rb', '.pdf')
+Prawn::Example.generate(filename) do
+  stroke_axis
+  
+  1.upto(3) do |i|
+    
+    x = i * 50
+    y = i * 100
+    translate(x, y) do
+      
+      # Draw a point on the new origin
+      fill_circle [0, 0], 2
+      draw_text "New origin after translation to [#{x}, #{y}]",
+                :at => [5, -2], :size => 8
+      
+      stroke_rectangle [100, 75], 100, 50
+      text_box "Top left corner at [100,75]",
+                :at => [110, 65], :width => 80, :size => 8
+    end
+  end
+end

data/manual/graphics/transparency.rb

@@ -0,0 +1,35 @@
+# encoding: utf-8
+#
+# Although the name of the method is <code>transparency</code>, what we are
+# actually setting is the opacity for fill and stroke. So <code>0</code> means
+# completely transparent and <code>1.0</code> means completely opaque
+#
+# You may call it providing one or two values. The first value sets fill opacity
+# and the second value sets stroke opacity. If the second value is omitted fill
+# and stroke will have the same opacity.
+#
+require File.expand_path(File.join(File.dirname(__FILE__),
+                                   %w[.. example_helper]))
+
+filename = File.basename(__FILE__).gsub('.rb', '.pdf')
+Prawn::Example.generate(filename) do
+  stroke_axis
+
+  self.line_width = 5
+  fill_color "ff0000"
+  fill_rectangle [0, 100], 500, 100
+  
+  fill_color "000000"
+  stroke_color "ffffff"
+  
+  base_x = 100
+  [[0.5, 1], 0.5, [1, 0.5]].each do |args|
+    
+    transparent(*args) do
+      fill_circle [base_x, 100], 50
+      stroke_rectangle [base_x - 20, 100], 40, 80
+    end
+    
+    base_x += 150
+  end
+end

data/manual/images/absolute_position.rb

@@ -0,0 +1,23 @@
+# encoding: utf-8
+#
+# One of the options that the <code>image</code> method accepts is
+# <code>:at</code>. If you've read some of the graphics examples you are
+# probably already familiar with it. Just provide it the upper-left corner where
+# you want the image placed.
+#
+# While sometimes useful this option won't be practical. Notice that the cursor
+# won't be moved after the image is rendered and there is nothing forbidding the
+# text to overlap with the image.
+#
+require File.expand_path(File.join(File.dirname(__FILE__),
+                                   %w[.. example_helper]))
+
+filename = File.basename(__FILE__).gsub('.rb', '.pdf')
+Prawn::Example.generate(filename) do
+  y_position = cursor
+  text "The image won't go below this line of text."
+  
+  image "#{Prawn::DATADIR}/images/fractal.jpg", :at => [200, y_position]
+  
+  text "And this line of text will go just below the previous one."
+end

data/manual/images/fit.rb

@@ -0,0 +1,21 @@
+# encoding: utf-8
+#
+# <code>:fit</code> option is useful when you want the image to have the
+# maximum size within a container preserving the aspect ratio without
+# overlapping.
+#
+# Just provide the container width and height pair.
+#
+require File.expand_path(File.join(File.dirname(__FILE__),
+                                   %w[.. example_helper]))
+
+filename = File.basename(__FILE__).gsub('.rb', '.pdf')
+Prawn::Example.generate(filename) do
+  size = 300
+  
+  text "Using the fit option"
+  bounding_box([0, cursor], :width => size, :height => size) do
+    image "#{Prawn::DATADIR}/images/pigs.jpg", :fit => [size, size]
+    stroke_bounds
+  end
+end

data/manual/images/horizontal.rb

@@ -0,0 +1,25 @@
+# encoding: utf-8
+#
+# The image may be positioned relatively to the current bounding box. The
+# horizontal position may be set with the <code>:position</code> option.
+#
+# It may be <code>:left</code>, <code>:center</code>, <code>:right</code> or a
+# number representing an x-offset from the left boundary.
+#
+require File.expand_path(File.join(File.dirname(__FILE__),
+                                   %w[.. example_helper]))
+
+filename = File.basename(__FILE__).gsub('.rb', '.pdf')
+Prawn::Example.generate(filename) do
+  bounding_box([50, cursor], :width => 400, :height => 450) do
+    stroke_bounds
+    
+    [:left, :center, :right].each do |position|
+      text  "Image aligned to the #{position}."
+      image "#{Prawn::DATADIR}/images/stef.jpg", :position => position
+    end
+    
+    text  "The next image has a 50 point offset from the left boundary"
+    image "#{Prawn::DATADIR}/images/stef.jpg", :position => 50
+  end
+end

data/manual/images/images.rb

@@ -0,0 +1,40 @@
+# encoding: utf-8
+#
+# Examples for embedding images.
+#
+require File.expand_path(File.join(File.dirname(__FILE__),
+                                   %w[.. example_helper]))
+
+Prawn::Example.generate("images.pdf", :page_size => "FOLIO") do
+  
+  package "images" do |p|
+    
+    p.section "Basics" do |s|
+      s.example "plain_image"
+      s.example "absolute_position"
+    end
+    
+    p.section "Relative Positioning" do |s|
+      s.example "horizontal"
+      s.example "vertical"
+    end
+    
+    p.section "Size" do |s|
+      s.example "width_and_height"
+      s.example "scale"
+      s.example "fit"
+    end
+    
+    p.intro do
+      prose("Embedding images on PDF documents is fairly easy. Prawn supports both JPG and PNG images.
+
+      The examples show:")
+
+      list( "How to add an image to a page",
+            "How place the image on a specific position",
+            "How to configure the image dimensions by setting the width and height or by scaling it"
+          )
+    end
+    
+  end
+end

data/manual/images/plain_image.rb

@@ -0,0 +1,18 @@
+# encoding: utf-8
+#
+# To embed images onto your PDF file use the <code>image</code> method.
+# It accepts the file path of the image to be loaded and some optional
+# arguments.
+#
+# If only the image path is provided the image will be rendered starting on
+# the cursor position. No manipulation is done with the image even if it doesn't
+# fit entirely on the page like the following snippet.
+#
+require File.expand_path(File.join(File.dirname(__FILE__),
+                                   %w[.. example_helper]))
+
+filename = File.basename(__FILE__).gsub('.rb', '.pdf')
+Prawn::Example.generate(filename) do
+  text "The image will go right below this line of text."
+  image "#{Prawn::DATADIR}/images/pigs.jpg"
+end

data/manual/images/scale.rb

@@ -0,0 +1,22 @@
+# encoding: utf-8
+#
+# To scale an image use the <code>:scale</code> option.
+#
+# It scales the image proportionally given the provided value.
+#
+require File.expand_path(File.join(File.dirname(__FILE__),
+                                   %w[.. example_helper]))
+
+filename = File.basename(__FILE__).gsub('.rb', '.pdf')
+Prawn::Example.generate(filename) do
+  text  "Normal size"
+  image "#{Prawn::DATADIR}/images/stef.jpg"
+  move_down 20
+  
+  text  "Scaled to 50%"
+  image "#{Prawn::DATADIR}/images/stef.jpg", :scale => 0.5
+  move_down 20
+  
+  text  "Scaled to 200%"
+  image "#{Prawn::DATADIR}/images/stef.jpg", :scale => 2
+end