prawn 0.12.0 → 0.13.0

data/manual/example_package.rb

@@ -0,0 +1,53 @@
+# encoding: utf-8
+
+module Prawn
+  
+  # The Prawn::ExamplePackage class is a utility class to handle the packaging
+  # of individual examples within a hierarchy when building the manual
+  #
+  class ExamplePackage
+    attr_reader :intro_block, :folder_name
+    
+    def initialize(folder_name)
+      @folder_name = folder_name
+      @hierarchy = []
+    end
+    
+    # Stores a new ExampleSection in the hierarchy and yields it to a block
+    #
+    def section(name)
+      s = ExampleSection.new(self, name)
+      yield s
+      @hierarchy << s
+    end
+    
+    # Stores a new ExampleFile in the hierarchy
+    #
+    def example(filename, options={})
+      @hierarchy << ExampleFile.new(self, "#{filename}.rb", options)
+    end
+    
+    # Stores a block with code to be evaluated when rendering the package cover
+    #
+    def intro(&block)
+      @intro_block = block
+    end
+    
+    # Returns a human friendly version of the package name
+    #
+    def name
+      @name ||= @folder_name.gsub("_", " ").capitalize
+    end
+    
+    # Renders a cover page for the package to a pdf and iterates the examples
+    # hierarchy delegating the examples and sections to be rendered as well
+    #
+    def render(pdf)
+      pdf.render_package_cover(self)
+      
+      @hierarchy.each do |node|
+        node.render(pdf)
+      end
+    end
+  end
+end

data/manual/example_section.rb

@@ -0,0 +1,46 @@
+# encoding: utf-8
+
+module Prawn
+  
+  # The Prawn::ExampleSection class is a utility class to handle sections
+  # of related examples within an ExamplePackage
+  #
+  class ExampleSection
+    attr_reader :name
+    
+    def initialize(package, name)
+      @package  = package
+      @name     = name
+      @examples = []
+    end
+    
+    # Stores a new ExampleFile in the examples list
+    #
+    def example(filename, options={})
+      @examples << ExampleFile.new(self, "#{filename}.rb", options)
+    end
+
+    # Returns this example's package original folder name
+    #
+    def folder_name
+      @package.folder_name
+    end
+    
+    # Returns the human friendly version of this section's package name
+    #
+    def package_name
+      @package.name
+    end
+    
+    # Renders the section to a pdf and iterates the examples list delegating the
+    # examples to be rendered as well
+    #
+    def render(pdf)
+      pdf.render_section(self)
+      
+      @examples.each do |example|
+        example.render(pdf)
+      end
+    end
+  end
+end

data/manual/graphics/circle_and_ellipse.rb

@@ -0,0 +1,22 @@
+# encoding: utf-8
+#
+# To define a <code>circle</code> all you need is the center point and the
+# radius.
+#
+# To define an <code>ellipse</code> you provide the center point and two radii
+# (or axes) values. If the second radius value is ommitted, both radii will be
+# equal and you will end up drawing a circle.
+#
+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_circle [100, 300], 100
+    
+  fill_ellipse [200, 100], 100, 50
+    
+  fill_ellipse [400, 100], 50
+end

data/manual/graphics/color.rb

@@ -0,0 +1,24 @@
+# encoding: utf-8
+#
+# We can change the stroke and fill colors providing an HTML rgb 6 digit color
+# code string ("AB1234") or 4 values for CMYK.
+#
+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 with Yellow using RGB
+  fill_color "FFFFCC"
+  fill_polygon [50, 150], [150, 200], [250, 150],
+               [250, 50], [150, 0], [50, 50]
+  
+  # Stroke with Purple using CMYK
+  stroke_color 50, 100, 0, 0
+  stroke_rectangle [300, 300], 200, 100
+  
+  # Both together
+  fill_and_stroke_circle [400, 100], 50
+end

data/manual/graphics/common_lines.rb

@@ -0,0 +1,28 @@
+# encoding: utf-8
+#
+# Prawn provides helpers for drawing some commonly used lines:
+#
+# <code>vertical_line</code> and <code>horizontal_line</code> do just what their
+# names imply. Specify the start and end point at a fixed coordinate to define
+# the line.
+#
+# <code>horizontal_rule</code> draws a horizontal line on the current bounding
+# box from border to border, using the current y position.
+#
+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
+    # just lower the current y position
+    move_down 50  
+    horizontal_rule
+    
+    vertical_line   100, 300, :at => 50
+  
+    horizontal_line 200, 500, :at => 150
+  end
+end

data/manual/graphics/fill_and_stroke.rb

@@ -0,0 +1,42 @@
+# encoding: utf-8
+#
+# There are two drawing primitives in Prawn: <code>fill</code> and
+# <code>stroke</code>.
+#
+# These are the methods that actually draw stuff on the document. All the other
+# drawing shapes like <code>rectangle</code>, <code>circle</code> or
+# <code>line_to</code> define drawing paths. These paths need to be either
+# stroked or filled to gain form on the document.
+#
+# Calling these methods without a block will act on the drawing path that
+# has been defined prior to the call.
+#
+# Calling with a block will act on the drawing path set within the
+# block.
+#
+# Most of the methods which define drawing paths have methods of the same name
+# starting with stroke_ and fill_ which create the drawing path and then stroke
+# or fill it.
+#
+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
+  
+  # No block
+  line [0, 200], [100, 150]
+  stroke
+  
+  rectangle [0, 100], 100, 100
+  fill
+  
+  # With block
+  stroke { line [200, 200], [300, 150] }
+  fill   { rectangle [200, 100], 100, 100 }
+  
+  # Method hook
+  stroke_line [400, 200], [500, 150]
+  fill_rectangle [400, 100], 100, 100
+end

data/manual/graphics/fill_rules.rb

@@ -0,0 +1,37 @@
+# encoding: utf-8
+#
+# Prawn's fill operators (<code>fill</code> and <code>fill_and_stroke</code>
+# both accept a <code>:fill_rule</code> option. These rules determine which
+# parts of the page are counted as "inside" vs. "outside" the path. There are
+# two fill rules:
+#
+# * <code>:nonzero_winding_number</code> (default): a point is inside the path
+# if a ray from that point to infinity crosses a nonzero "net number" of path
+# segments, where path segments intersecting in one direction are counted as
+# positive and those in the other direction negative.
+#
+# * <code>:even_odd</code>: A point is inside the path if a ray from that point
+# to infinity crosses an odd number of path segments, regardless of direction.
+#
+# The differences between the fill rules only come into play with complex
+# paths; they are identical for simple shapes.
+#
+require File.expand_path(File.join(File.dirname(__FILE__),
+                                   %w[.. example_helper]))
+
+filename = File.basename(__FILE__).gsub('.rb', '.pdf')
+Prawn::Example.generate(filename) do
+  pentagram = [[181, 95], [0, 36], [111, 190], [111, 0], [0, 154]]
+
+  stroke_color 'ff0000'
+  line_width 2
+
+  text_box "Nonzero Winding Number", :at => [50, 215], :width => 170,
+           :align => :center
+  polygon(*pentagram.map { |x, y| [x+50, y] })
+  fill_and_stroke
+
+  text_box "Even-Odd", :at => [330, 215], :width => 170, :align => :center
+  polygon(*pentagram.map { |x, y| [x+330, y] })
+  fill_and_stroke(:fill_rule => :even_odd)
+end

data/manual/graphics/gradients.rb

@@ -0,0 +1,37 @@
+# encoding: utf-8
+#
+# Note that because of the way PDF renders radial gradients in order to get
+# solid fill your start circle must be fully inside your end circle.
+# Otherwise you will get triangle fill like illustrated in the example below.
+
+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 = 10
+
+  fill_gradient [50, 300], [150, 200], 'ff0000', '0000ff'
+  fill_rectangle [50, 300], 100, 100
+
+  stroke_gradient [200, 200], [300, 300], '00ffff', 'ffff00'
+  stroke_rectangle [200, 300], 100, 100
+
+  fill_gradient [350, 300], [450, 200], 'ff0000', '0000ff'
+  stroke_gradient [350, 200], [450, 300], '00ffff', 'ffff00'
+  fill_and_stroke_rectangle [350, 300], 100, 100
+
+  fill_gradient [100, 100], 0, [100, 100], 70.71, 'ff0000', '0000ff'
+  fill_rectangle [50, 150], 100, 100
+
+  stroke_gradient [250, 100], 45, [250, 100], 70.71, '00ffff', 'ffff00'
+  stroke_rectangle [200, 150], 100, 100
+
+  stroke_gradient [400, 100], 45, [400, 100], 70.71, '00ffff', 'ffff00'
+  fill_gradient [400, 100], 0, [400, 100], 70.71, 'ff0000', '0000ff'
+  fill_and_stroke_rectangle [350, 150], 100, 100
+
+  fill_gradient [500, 300], 15, [500, 50], 0, 'ff0000', '0000ff'
+  fill_rectangle [485, 300], 30, 250
+end

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