nurettin-prawn 1.0.0.rc1

data/manual/text/rotation.rb

@@ -0,0 +1,43 @@
+# encoding: utf-8
+#
+# Rotating text is best avoided on free flowing text, so this example
+# will only use the <code>text_box</code> method as we can have much more
+# control over its output.
+#
+# To rotate text all we need to do is use the <code>:rotate</code> option
+# passing an angle in degrees and an optional <code>:rotate_around</code> to
+# indicate the origin of the rotation (the default is <code>:upper_left</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
+  width  = 100
+  height = 60
+  angle  = 30
+  x      = 200
+  y      = cursor - 30
+
+  stroke_rectangle [0, y], width, height
+  text_box("This text was not rotated",
+           :at => [0, y], :width => width, :height => height)
+  
+  stroke_rectangle [0, y - 100], width, height
+  text_box("This text was rotated around the center",
+           :at => [0, y - 100], :width => width, :height => height,
+           :rotate => angle, :rotate_around => :center)
+  
+  [:lower_left, :upper_left,
+   :lower_right, :upper_right].each_with_index do |corner, index|
+    
+    y = y - 100 if index == 2
+    stroke_rectangle [x + (index % 2) * 200, y], width, height
+    text_box("This text was rotated around the #{corner} corner.",
+             :at     => [x + (index % 2) * 200, y],
+             :width  => width,
+             :height => height,
+             :rotate => angle,
+             :rotate_around => corner)
+  end
+end

data/manual/text/single_usage.rb

@@ -0,0 +1,37 @@
+# encoding: utf-8
+#
+# The PDF format has some built-in font support. If you want to use other fonts
+# in Prawn you need to embed the font file.
+#
+# Doing this for a single font is extremely simple. Remember the Styling font
+# example? Another use of the <code>font</code> method is to provide a font file
+# path and the font will be embedded in the document and set as the current
+# font.
+#
+# This is reasonable if a font is used only once, but, if a font used several
+# times, providing the path each time it is used becomes cumbersome. The example
+# on the next page shows a better way to deal with fonts which are used several
+# times in a document.
+#
+require File.expand_path(File.join(File.dirname(__FILE__),
+                                   %w[.. example_helper]))
+
+filename = File.basename(__FILE__).gsub('.rb', '.pdf')
+Prawn::Example.generate(filename) do
+  # Using a TTF font file
+  font("#{Prawn::DATADIR}/fonts/Chalkboard.ttf") do
+    text "Written with the Chalkboard TTF font."
+  end
+  move_down 20
+  
+  text "Written with the default font."
+  move_down 20
+  
+  # Using an DFONT font file
+  font("#{Prawn::DATADIR}/fonts/Action Man.dfont") do
+    text "Written with the Action Man DFONT font"
+  end
+  move_down 20
+
+  text "Written with the default font once more."
+end

data/manual/text/text.rb

@@ -0,0 +1,75 @@
+# encoding: utf-8
+#
+# Examples for text rendering.
+#
+require File.expand_path(File.join(File.dirname(__FILE__),
+                                   %w[.. example_helper]))
+
+Prawn::Example.generate("text.pdf", :page_size => "FOLIO") do
+  
+  package "text" do |p|
+    
+    p.section "Basics" do |s|
+      s.example "free_flowing_text"
+      s.example "positioned_text"
+      s.example "text_box_overflow"
+      s.example "text_box_excess"
+      s.example "group"
+      s.example "column_box"
+    end
+    
+    p.section "Styling" do |s|
+      s.example "font"
+      s.example "font_size"
+      s.example "font_style"
+      s.example "color"
+      s.example "alignment"
+      s.example "leading"
+      s.example "kerning_and_character_spacing"
+      s.example "paragraph_indentation"
+      s.example "rotation"
+    end
+    
+    p.section "Advanced Styling" do |s|
+      s.example "inline"
+      s.example "formatted_text"
+      s.example "formatted_callbacks"
+      s.example "rendering_and_color"
+      s.example "text_box_extensions"
+    end
+    
+    p.section "External Fonts" do |s|
+      s.example "single_usage"
+      s.example "registering_families"
+    end
+    
+    p.section "M17n" do |s|
+      s.example "utf8"
+      s.example "line_wrapping"
+      s.example "right_to_left_text"
+      s.example "fallback_fonts"
+      s.example "win_ansi_charset"
+    end
+    
+    p.intro do
+      prose("This is probably the feature people will use the most. There is no shortage of options when it comes to text. You'll be hard pressed to find a use case that is not covered by one of the text methods and configurable options.
+
+      The examples show:")
+
+      list( "Text that flows from page to page automatically starting new pages when necessary",
+            "How to use text boxes and place them on specific positions",
+            "What to do when a text box is too small to fit its content",
+            "How to proceed when you want to prevent paragraphs from splitting between pages",
+            "Flowing text in columns",
+            "How to change the text style configuring font, size, alignment and many other settings",
+            "How to style specific portions of a text with inline styling and formatted text",
+            "How to define formatted callbacks to reuse common styling definitions",
+            "How to use the different rendering modes available for the text methods",
+            "How to create your custom text box extensions",
+            "How to use external fonts on your pdfs",
+            "What happens when rendering text in different languages"
+          )
+    end
+    
+  end
+end

data/manual/text/text_box_excess.rb

@@ -0,0 +1,32 @@
+# encoding: utf-8
+#
+# Whenever the <code>text_box</code> method truncates text, this truncated bit
+# is not lost, it is the method return value and we can take advantage of that.
+#
+# We just need to take some precautions.
+#
+# This example renders as much of the text as will fit in a larger font inside
+# one text_box and then proceeds to render the remaining text in the default
+# size in a second text_box.
+#
+require File.expand_path(File.join(File.dirname(__FILE__),
+                                   %w[.. example_helper]))
+
+filename = File.basename(__FILE__).gsub('.rb', '.pdf')
+Prawn::Example.generate(filename) do
+  string = "This is the beginning of the text. It will be cut somewhere and " +
+           "the rest of the text will procede to be rendered this time by " +
+           "calling another method." + " . " * 50
+
+  y_position = cursor - 20
+  excess_text = text_box string,
+                         :width    => 300,
+                         :height   => 50,
+                         :overflow => :truncate,
+                         :at       => [100, y_position],
+                         :size     => 18
+  
+  text_box excess_text,
+           :width    => 300,
+           :at       => [100, y_position - 100]
+end

data/manual/text/text_box_extensions.rb

@@ -0,0 +1,45 @@
+# encoding: utf-8
+#
+# We've already seen one way of using text boxes with the <code>text_box</code>
+# method. Turns out this method is just a convenience for using the
+# <code>Prawn::Text::Box</code> class as it creates a new object and call
+# <code>render</code> on it.
+#
+# Knowing that any extensions we add to <code>Prawn::Text::Box</code> will take
+# effect when we use the <code>text_box</code> method. To add an extension all
+# we need to do is append the <code>Prawn::Text::Box.extensions</code> array
+# with a module.
+#
+require File.expand_path(File.join(File.dirname(__FILE__),
+                                   %w[.. example_helper]))
+
+filename = File.basename(__FILE__).gsub('.rb', '.pdf')
+Prawn::Example.generate(filename) do
+  module TriangleBox
+    def available_width
+      height + 25
+    end
+  end
+
+  y_position = cursor - 10
+  width      = 100
+  height     = 100
+  
+  Prawn::Text::Box.extensions << TriangleBox
+  stroke_rectangle([0, y_position], width, height)
+  text_box("A" * 100,
+           :at => [0, y_position],
+           :width => width,
+           :height => height)
+  
+  Prawn::Text::Formatted::Box.extensions << TriangleBox
+  stroke_rectangle([200, y_position], width, height)
+  formatted_text_box([:text => "A" * 100, :color => "009900"],
+                     :at => [200, y_position],
+                     :width => width,
+                     :height => height)
+
+  # Here we clear the extensions array
+  Prawn::Text::Box.extensions.clear
+  Prawn::Text::Formatted::Box.extensions.clear
+end

data/manual/text/text_box_overflow.rb

@@ -0,0 +1,44 @@
+# encoding: utf-8
+#
+# The <code>text_box</code> method accepts both <code>:width</code> and
+# <code>:height</code> options. So what happens if the text doesn't fit the box?
+#
+# The default behavior is to truncate the text but this can be changed with
+# the <code>:overflow</code> option. Available modes are <code>:expand</code>
+# (the box will increase to fit the text) and <code>:shrink_to_fit</code>
+# (the text font size will be shrunk to fit).
+#
+# If <code>:shrink_to_fit</code> mode is used with the
+# <code>:min_font_size</code> option set. The font size will not be reduced to
+# less than the value provided even if it means truncating some text.
+#
+require File.expand_path(File.join(File.dirname(__FILE__),
+                                   %w[.. example_helper]))
+
+filename = File.basename(__FILE__).gsub('.rb', '.pdf')
+Prawn::Example.generate(filename) do
+  string = "This is the sample text used for the text boxes. See how it " +
+           "behave with the various overflow options used."
+
+  text string
+  
+  y_position = cursor - 20
+  [:truncate, :expand, :shrink_to_fit].each_with_index do |mode, i|
+    text_box string, :at => [i * 150, y_position],
+             :width => 100, :height => 50,
+             :overflow => mode
+  end
+  
+  string = "If the box is too small for the text, :shrink_to_fit " +
+           "can render the text in a really small font size."
+  
+  move_down 120
+  text string
+  y_position = cursor - 20
+  [nil, 8, 10, 12].each_with_index do |value, index|
+    text_box string, :at => [index * 150, y_position],
+             :width => 50, :height => 50,
+             :overflow => :shrink_to_fit,
+             :min_font_size => value
+  end
+end

data/manual/text/utf8.rb

@@ -0,0 +1,28 @@
+# encoding: utf-8
+# 
+# Multilingualization isn't much of a problem on Prawn as its default encoding
+# is UTF-8. The only thing you need to worry about is if the font support the
+# glyphs of your language.
+#
+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 "Take this example, a simple Euro sign:"
+  text "€", :size => 32
+  move_down 20
+  
+  text "Seems ok. Now let's try something more complex:"
+  text "ὕαλον ϕαγεῖν δύναμαι· τοῦτο οὔ με βλάπτει."
+  move_down 20
+  
+  text "Looks like the current font (#{font.inspect}) doesn't support those."
+  text "Let's try them with another font."
+  move_down 20
+  
+  font("#{Prawn::DATADIR}/fonts/DejaVuSans.ttf") do
+    text "ὕαλον ϕαγεῖν δύναμαι· τοῦτο οὔ με βλάπτει."
+    text "There you go."
+  end
+end

data/manual/text/win_ansi_charset.rb

@@ -0,0 +1,59 @@
+# encoding: utf-8
+#
+# Prints a list of all of the glyphs that can be rendered by Adobe's built
+# in fonts, along with their character widths and WinAnsi codes.  Be sure
+# to pass these glyphs as UTF-8, and Prawn will transcode them for you.
+#
+require File.expand_path(File.join(File.dirname(__FILE__),
+                                   %w[.. example_helper]))
+
+filename = File.basename(__FILE__).gsub('.rb', '.pdf')
+Prawn::Example.generate(filename) do
+  FONT_SIZE = 9.5
+
+  x = 0
+  y = bounds.top
+
+  fields = [[20, :right], [8, :left], [12, :center], [30, :right], [8, :left],
+            [0, :left]]
+
+  font "Helvetica", :size => FONT_SIZE
+
+  move_down 30
+  text "(See next page for WinAnsi table)", :align => :center
+  start_new_page
+
+  Prawn::Encoding::WinAnsi::CHARACTERS.each_with_index do |name, index|
+    next if name == ".notdef"
+    y -= FONT_SIZE
+
+    if y < FONT_SIZE
+      y = bounds.top - FONT_SIZE
+      x += 170
+    end
+
+    code = "%d." % index
+    char = index.chr
+
+    width = 1000 * width_of(char, :size => FONT_SIZE) / FONT_SIZE
+    size  = "%d" % width
+
+    data = [code, nil, char, size, nil, name]
+    dx   = x
+    fields.zip(data).each do |(total_width, align), field|
+      if field
+        width = width_of(field, :size => FONT_SIZE)
+
+        case align
+        when :left   then offset = 0
+        when :right  then offset = total_width - width
+        when :center then offset = (total_width - width)/2
+        end
+
+        text_box(field, :at => [dx + offset, y], :skip_encoding => true)
+      end
+
+      dx += total_width
+    end
+  end
+end

data/prawn.gemspec

@@ -0,0 +1,46 @@
+Gem::Specification.new do |spec|
+  spec.name = "nurettin-prawn"
+  spec.version = File.read(File.expand_path('VERSION', File.dirname(__FILE__))).strip
+  spec.platform = Gem::Platform::RUBY
+  spec.summary = "A fast and nimble PDF generator for Ruby"
+  spec.files =  Dir.glob("{examples,lib,spec,data,manual}/**/**/*") +
+    ["Rakefile", "prawn.gemspec", "COPYING", "LICENSE", "GPLv2", "GPLv3",
+     "Gemfile"]
+  spec.require_path = "lib"
+  spec.required_ruby_version = '>= 1.8.7'
+  spec.required_rubygems_version = ">= 1.3.6"
+
+  spec.test_files = Dir[ "spec/*_spec.rb" ]
+  spec.extra_rdoc_files = %w{README.md LICENSE COPYING GPLv2 GPLv3}
+  spec.rdoc_options << '--title' << 'Prawn Documentation' <<
+                       '--main'  << 'README.md' << '-q'
+  spec.authors = ["Gregory Brown","Brad Ediger","Daniel Nelson","Jonathan Greenberg","James Healy"]
+  spec.email = ["gregory.t.brown@gmail.com","brad@bradediger.com","dnelson@bluejade.com","greenberg@entryway.net","jimmy@deefa.com"]
+  spec.rubyforge_project = "prawn"
+  spec.add_dependency('pdf-reader', '>=0.9.0', '<2.0')
+  spec.add_dependency('ttfunk', '~>1.0.3')
+  spec.add_dependency('ruby-rc4')
+  spec.add_dependency('afm')
+  spec.add_development_dependency('pdf-inspector', '~> 1.0.1')
+  spec.add_development_dependency('coderay', '~> 1.0.7')
+  spec.add_development_dependency('rdoc')
+  spec.homepage = "http://prawn.majesticseacreature.com"
+  spec.description = <<END_DESC
+  Prawn is a fast, tiny, and nimble PDF generator for Ruby
+END_DESC
+  spec.post_install_message = <<END_DESC
+
+  ********************************************
+
+
+  A lot has changed recently in Prawn.
+
+  Please read the changelog for details:
+
+  https://github.com/prawnpdf/prawn/wiki/CHANGELOG
+
+
+  ********************************************
+
+END_DESC
+end

data/spec/annotations_spec.rb

@@ -0,0 +1,90 @@
+# encoding: utf-8
+
+require File.join(File.expand_path(File.dirname(__FILE__)), "spec_helper")  
+                               
+class PageAnnotations
+  attr_reader :pages
+
+  def self.parse(document)
+    receiver = new
+    PDF::Reader.string(document.render, receiver)
+    return receiver
+  end
+
+  def initialize
+    @pages = []
+  end
+
+  def begin_page(params)
+    @pages << params
+  end
+end
+
+describe "When creating annotations" do 
+ 
+  before(:each) { create_pdf }
+  
+  it "should append annotation to current page" do 
+    @pdf.start_new_page
+    @pdf.annotate(:Rect => [0,0,10,10], :Subtype => :Text, :Contents => "Hello world!")
+    obj = PageAnnotations.parse(@pdf)
+    obj.pages[0][:Annots].nil?.should == true
+    obj.pages[1][:Annots].length.should == 1
+  end
+
+  it "should force :Type to be :Annot" do
+    opts = @pdf.annotate(:Rect => [0,0,10,10], :Subtype => :Text, :Contents => "Hello world!")
+    opts[:Type].should == :Annot
+    opts = @pdf.annotate(:Type => :Bogus, :Rect => [0,0,10,10], :Subtype => :Text, :Contents => "Hello world!")
+    opts[:Type].should == :Annot
+  end
+
+end
+
+describe "When creating text annotations" do
+ 
+  before(:each) do
+    @rect = [0,0,10,10]
+    @content = "Hello, world!"
+    create_pdf
+  end
+  
+  it "should build appropriate annotation" do 
+    opts = @pdf.text_annotation(@rect, @content)
+    opts[:Type].should == :Annot
+    opts[:Subtype].should == :Text
+    opts[:Rect].should == @rect
+    opts[:Contents].should == @content
+  end
+
+  it "should merge extra options" do 
+    opts = @pdf.text_annotation(@rect, @content, :Open => true, :Subtype => :Bogus)
+    opts[:Subtype].should == :Text
+    opts[:Open].should == true
+  end
+
+end
+
+describe "When creating link annotations" do
+ 
+  before(:each) do
+    @rect = [0,0,10,10]
+    @dest = "home"
+    create_pdf
+  end
+  
+  it "should build appropriate annotation" do 
+    opts = @pdf.link_annotation(@rect, :Dest => @dest)
+    opts[:Type].should == :Annot
+    opts[:Subtype].should == :Link
+    opts[:Rect].should == @rect
+    opts[:Dest].should == @dest
+  end
+
+  it "should merge extra options" do 
+    opts = @pdf.link_annotation(@rect, :Dest => @dest, :Subtype => :Bogus)
+    opts[:Subtype].should == :Link
+    opts[:Dest].should == @dest
+  end
+
+end