prawn-core 0.5.0.1 → 0.5.1

data/lib/prawn/document/annotations.rb

@@ -11,16 +11,14 @@ require 'prawn/literal_string'
 module Prawn
   class Document
     
-    # Provides very low-level support for annotations.  Those who are 
-    # interested should check out the text-format branch of sandal/prawn, 
-    # which includes much higher level interfaces to this code currently
-    # being developed by Jamis Buck to be included in a Prawn release soon.
-    #
-    # Feedback is welcome!
-    #
+    # Provides very low-level support for annotations.  These extensions are
+    # mainly for use by prawn-format, so be sure to check that out if all
+    # you need is basic internal or external links.
     module Annotations
+      
       # Adds a new annotation (section 8.4 in PDF spec) to the current page.
       # +options+ must be a Hash describing the annotation.
+      #
       def annotate(options)
         @current_page.data[:Annots] ||= []
         options = sanitize_annotation_hash(options)
@@ -31,6 +29,7 @@ module Prawn
       # A convenience method for creating Text annotations. +rect+ must be an array
       # of four numbers, describing the bounds of the annotation. +contents+ should
       # be a string, to be shown when the annotation is activated.
+      #
       def text_annotation(rect, contents, options={})
         options = options.merge(:Subtype => :Text, :Rect => rect, :Contents => contents)
         annotate(options)
@@ -42,6 +41,7 @@ module Prawn
       # string that has been recorded in the document's Dests tree), or :A (describing
       # an action to perform on clicking the link), or :PA (for describing a URL to
       # link to).
+      #
       def link_annotation(rect, options={})
         options = options.merge(:Subtype => :Link, :Rect => rect)
         annotate(options)
@@ -49,15 +49,16 @@ module Prawn
 
       private
 
-        def sanitize_annotation_hash(options)
-          options = options.merge(:Type => :Annot)
+      def sanitize_annotation_hash(options)
+        options = options.merge(:Type => :Annot)
 
-          if options[:Dest].is_a?(String)
-            options[:Dest] = Prawn::LiteralString.new(options[:Dest])
-          end
-
-          options
+        if options[:Dest].is_a?(String)
+          options[:Dest] = Prawn::LiteralString.new(options[:Dest])
         end
+
+        options
+      end
+      
     end
   end
 end

data/lib/prawn/document/bounding_box.rb

@@ -14,8 +14,7 @@ module Prawn
     #
     # 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.
+    # * Translate the origin (0,0) for graphics primitives
     # 
     # ==Positioning
     # 
@@ -25,20 +24,20 @@ module Prawn
     # 
     # Usage:
     # 
-    # * Bounding box 100pt x 100pt in the absolutle bottom left of the containing
-    # box:
+    # * Bounding box 100pt x 100pt in the absolute bottom left of the 
+    # containing box:
     # 
-    #  pdf.bounding_box([0,100], :width => 100, :height => 100)
-    #    stroke_bounds
-    #  end
+    #   pdf.bounding_box([0,100], :width => 100, :height => 100)
+    #     stroke_bounds
+    #   end
     # 
     # * Bounding box 200pt x 400pt high in the center of the page:
     # 
-    #  x_pos = ((bounds.width / 2) - 150)
-    #  y_pos = ((bounds.height / 2) + 200)
-    #  pdf.bounding_box([x_pos, y_pos], :width => 300, :height => 400) do
-    #    stroke_bounds
-    #  end
+    #   x_pos = ((bounds.width / 2) - 150)
+    #   y_pos = ((bounds.height / 2) + 200)
+    #   pdf.bounding_box([x_pos, y_pos], :width => 300, :height => 400) do
+    #     stroke_bounds
+    #   end
     #
     # ==Flowing Text
     #
@@ -57,6 +56,10 @@ module Prawn
     #      "and return to the margin_box"
     #   end
     #
+    # Note that this is a low level tool and is designed primarily for 
+    # building other abstractions.  If you just want to flow some text on
+    # a page, look into span() or text_box()
+    # 
     # ==Translating Coordinates
     # 
     # When translating coordinates, the idea is to allow the user to draw
@@ -101,7 +104,7 @@ module Prawn
     # 
     # ==Nesting Bounding Boxes
     # 
-    # By default, bounding boxes are specified relative to the document's 
+    # At the top level, 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
     #
@@ -118,8 +121,8 @@ module Prawn
     # 
     # ==Stretchyness
     # 
-    # If you do not specify a height to a boundng box, it will become stretchy
-    # and it's height will be calculated according to the last drawing position
+    # If you do not specify a height to a bounding box, it will become stretchy
+    # and its height will be calculated according to the last drawing position
     # within the bounding box:
     # 
     #  pdf.bounding_box([100,400], :width => 400) do
@@ -184,7 +187,12 @@ module Prawn
 
       @bounding_box = parent_box 
     end   
- 
+
+    # Low level layout helper that simplifies coordinate math.
+    #
+    # See Prawn::Document#bounding_box for a description of what this class
+    # is used for.
+    #
     class BoundingBox
       
       def initialize(parent, point, options={}) #:nodoc:   
@@ -210,6 +218,18 @@ module Prawn
         0
       end
       
+      
+      # Temporarily adjust the @x coordinate to allow for left_padding
+      #
+      def indent(left_padding, &block)
+        @x += left_padding
+        @width -= left_padding
+        yield
+      ensure
+        @x -= left_padding
+        @width += left_padding
+      end
+      
       # Relative right x-coordinate of the bounding box. (Equal to the box width)
       # 
       # Example, position some text 3 pts from the right of the containing box:
@@ -359,18 +379,6 @@ module Prawn
         !@height 
       end
 
-      def left_side
-         absolute_left
-      end
-
-      def right_side
-         absolute_right
-      end
-
-      def move_past_bottom
-         @parent.start_new_page
-      end
-
     end    
     
   end

data/lib/prawn/document/column_box.rb

@@ -40,6 +40,21 @@ module Prawn
 
       @bounding_box = parent_box
     end
+    
+    # Template methods to support ColumnBox extensions
+    class BoundingBox
+      def left_side
+         absolute_left
+      end
+
+      def right_side
+         absolute_right
+      end
+
+      def move_past_bottom
+         @parent.start_new_page
+      end
+    end
 
     class ColumnBox < BoundingBox
 

data/lib/prawn/document/destinations.rb

@@ -17,6 +17,7 @@ module Prawn
       # The Dests name tree in the Name dictionary (see Prawn::Document::Internal#names).
       # This name tree is used to store named destinations (PDF spec 8.2.1).
       # (For more on name trees, see section 3.8.4 in the PDF spec.)
+      #
       def dests
         names.data[:Dests] ||= ref(Prawn::NameTree::Node.new(self, NAME_TREE_CHILDREN_LIMIT))
       end
@@ -24,6 +25,7 @@ module Prawn
       # Adds a new destination to the dests name tree (see #dests). The
       # +reference+ parameter will be converted into a Prawn::Reference if
       # it is not already one.
+      #
       def add_dest(name, reference)
         reference = ref(reference) unless reference.is_a?(Prawn::Reference)
         dests.data.add(name, reference)
@@ -31,48 +33,56 @@ module Prawn
 
       # Return a Dest specification for a specific location (and optional zoom
       # level).
+      #
       def dest_xyz(left, top, zoom=nil, page=@current_page)
         [page, :XYZ, left, top, zoom]
       end
 
       # Return a Dest specification that will fit the given page into the
       # viewport.
+      #
       def dest_fit(page=@current_page)
         [page, :Fit]
       end
 
       # Return a Dest specification that will fit the given page horizontally
       # into the viewport, aligned vertically at the given top coordinate.
+      #
       def dest_fit_horizontally(top, page=@current_page)
         [page, :FitH, top]
       end
 
       # Return a Dest specification that will fit the given page vertically
       # into the viewport, aligned horizontally at the given left coordinate.
+      #
       def dest_fit_vertically(left, page=@current_page)
         [page, :FitV, left]
       end
 
       # Return a Dest specification that will fit the given rectangle into the
       # viewport, for the given page.
+      #
       def dest_fit_rect(left, bottom, right, top, page=@current_page)
         [page, :FitR, left, bottom, right, top]
       end
 
       # Return a Dest specfication that will fit the given page's bounding box
       # into the viewport.
+      #
       def dest_fit_bounds(page=@current_page)
         [page, :FitB]
       end
 
       # Same as #dest_fit_horizontally, but works on the page's bounding box
       # instead of the entire page.
+      #
       def dest_fit_bounds_horizontally(top, page=@current_page)
         [page, :FitBH, top]
       end
 
       # Same as #dest_fit_vertically, but works on the page's bounding box
       # instead of the entire page.
+      #
       def dest_fit_bounds_vertically(left, page=@current_page)
         [page, :FitBV, left]
       end

data/lib/prawn/document/internals.rb

@@ -15,6 +15,7 @@ module Prawn
     # are you won't need anything you find here.  
     #
     module Internals    
+      
       # Creates a new Prawn::Reference and adds it to the Document's object
       # list.  The +data+ argument is anything that Prawn::PdfObject() can convert.    
       # 
@@ -22,6 +23,7 @@ module Prawn
       # out to the PDF document stream. This allows you to do deferred processing
       # on some references (such as fonts, which you might know all the details
       # about until the last page of the document is finished).
+      #
       def ref(data, &block)
         @objects.push(Prawn::Reference.new(@objects.size + 1, data, &block)).last
       end                                               
@@ -58,6 +60,7 @@ module Prawn
       end
        
       # The XObject dictionary for the current page
+      #
       def page_xobjects
         page_resources[:XObject] ||= {}
       end  
@@ -65,6 +68,7 @@ module Prawn
       # The Name dictionary (PDF spec 3.6.3) for this document. It is
       # lazily initialized, so that documents that do not need a name
       # dictionary do not incur the additional overhead.
+      #
       def names
         @root.data[:Names] ||= ref(:Type => :Names)
       end

data/lib/prawn/document/page_geometry.rb

@@ -77,8 +77,7 @@ module Prawn
     # LEGAL:: => 612.00 x 1008.00
     # LETTER:: => 612.00 x 792.00
     # TABLOID:: => 792.00 x 1224.00 
-    
-    
+    #
     module PageGeometry
 
       SIZES = { "4A0" => [4767.87, 6740.79],
@@ -132,7 +131,12 @@ module Prawn
              "LETTER" => [612.00, 792.00],
             "TABLOID" => [792.00, 1224.00] }
 
-      def page_dimensions #:nodoc:
+
+      # Returns the width and height of the current page in PDF points.
+      # Usually, you'll want the dimensions of the bounding_box or 
+      # margin_box instead.
+      #
+      def page_dimensions
         coords = SIZES[page_size] || page_size
         [0,0] + case(page_layout)
         when :portrait

data/lib/prawn/document/text.rb

@@ -52,7 +52,7 @@ module Prawn
       # == Rotation
       #
       # Text can be rotated before it is placed on the canvas by specifying the
-      # :rotate option. Rotation occurs counter-clockwise.
+      # +:rotate+ option with a given angle. Rotation occurs counter-clockwise.
       #
       # == Encoding
       #
@@ -73,7 +73,7 @@ module Prawn
         text = text.to_s.dup                      
         
         save_font do
-          options = text_options.merge(options)
+          options = @text_options.merge(options)
           process_text_options(options) 
            
           font.normalize_encoding!(text) unless @skip_encoding        
@@ -89,21 +89,12 @@ module Prawn
           end         
         end
       end 
-                          
-      # A hash of configuration options, to be used globally by text().
-      # 
-      #   pdf.text_options.update(:size => 16, :align => :right)   
-      #   pdf.text "Hello World" #=> Size 16 w. right alignment
-      #
-      def text_options
-        @text_options ||= {}
-      end 
-                       
+
       private 
-      
+                        
       def process_text_options(options)
         Prawn.verify_options [:style, :kerning, :size, :at, :wrap, 
-                              :spacing, :align, :rotate, :final_gap ], options                               
+                              :leading, :align, :rotate, :final_gap ], options                               
         
         if options[:style]  
           raise "Bad font family" unless font.family
@@ -154,7 +145,7 @@ module Prawn
             
             if i < last_gap_before
               move_text_position(font.line_gap - font.descender)
-              move_text_position(options[:spacing]) if options[:spacing]
+              move_text_position(options[:leading]) if options[:leading]
             end
           end 
         end

data/lib/prawn/document.rb

@@ -17,6 +17,7 @@ require "prawn/document/annotations"
 require "prawn/document/destinations"
 
 module Prawn
+  
   # The Prawn::Document class is how you start creating a PDF document.
   # 
   # There are three basic ways you can instantiate PDF Documents in Prawn, they 
@@ -49,6 +50,7 @@ module Prawn
   # that you want to immediately save or render out.
   # 
   # See the new and generate methods for further details on the above.
+  #
   class Document
 
     include Text
@@ -108,6 +110,7 @@ module Prawn
     # <tt>:compress</tt>:: Compresses content streams before rendering them [false]
     # <tt>:background</tt>:: An image path to be used as background on all pages [nil]
     # <tt>:info</tt>:: Generic hash allowing for custom metadata properties [nil]
+    # <tt>:text_options</tt>:: A set of default options to be handed to text(). Be careful with this.
 
     # Additionally, :page_size can be specified as a simple two value array giving
     # the width and height of the document you need in PDF Points.
@@ -153,7 +156,7 @@ module Prawn
        @background      = options[:background]
        @font_size       = 12
 
-       text_options.update(options[:text_options] || {})
+       @text_options = options[:text_options] || {}
 
        @margins = { :left   => options[:left_margin]   || 36,
                     :right  => options[:right_margin]  || 36,
@@ -347,6 +350,21 @@ module Prawn
       yield
       move_down(y)
     end
+    
+    
+    # Indents the specified number of PDF points for the duration of the block
+    #
+    #  pdf.text "some text"
+    #  pdf.indent(20) do
+    #    pdf.text "This is indented 20 points"
+    #  end
+    #  pdf.text "This starts 20 points left of the above line " +
+    #           "and is flush with the first line"
+    #
+    def indent(x, &block)
+      bounds.indent(x, &block)
+    end
+    
 
     def mask(*fields) # :nodoc:
      # Stores the current state of the named attributes, executes the block, and
@@ -389,7 +407,8 @@ module Prawn
         :height => page_dimensions[-1] - (@margins[:top] + @margins[:bottom])
       )
 
-      # update bounding box if not flowing from the previous page
+      # we must update bounding box if not flowing from the previous page
+      #
       # FIXME: This may have a bug where the old margin is restored
       # when the bounding box exits.
       @bounding_box = @margin_box if old_margin_box == @bounding_box

data/lib/prawn/errors.rb

@@ -1,11 +1,11 @@
 # encoding: utf-8
-
+#
 # errors.rb : Implements custom error classes for Prawn
 #
 # Copyright April 2008, Gregory Brown.  All Rights Reserved.
 #
 # This is free software. Please see the LICENSE and COPYING files for details.
-
+#
 module Prawn
   module Errors
      

data/lib/prawn/font/dfont.rb

@@ -3,11 +3,13 @@ require 'prawn/font/ttf'
 module Prawn
   class Font
     class DFont < TTF
+      
       # Returns a list of the names of all named fonts in the given dfont file.
       # Note that fonts are not required to be named in a dfont file, so the
       # list may be empty even if the file does contain fonts. Also, note that
       # the list is returned in no particular order, so the first font in the
       # list is not necessarily the font at index 0 in the file.
+      #
       def self.named_fonts(file)
         TTFunk::ResourceFile.open(file) do |file|
           return file.resources_for("sfnt")
@@ -15,6 +17,7 @@ module Prawn
       end
 
       # Returns the number of fonts contained in the dfont file.
+      #
       def self.font_count(file)
         TTFunk::ResourceFile.open(file) do |file|
           return file.map["sfnt"][:list].length

data/lib/prawn/font/ttf.rb

@@ -23,6 +23,7 @@ module Prawn
       end
 
       # +string+ must be UTF8-encoded.
+      #
       def compute_width_of(string, options={})
         scale = (options[:size] || size) / 1000.0
         if options[:kerning]
@@ -55,6 +56,7 @@ module Prawn
       # either a string or an array (for kerned text).
       #
       # The +text+ parameter must be UTF8-encoded.
+      #
       def encode_text(text,options={})
         text = text.chomp
 

data/lib/prawn/font.rb

@@ -78,6 +78,7 @@ module Prawn
 
     # Sets the font directly, given an actual Font object
     # and size.
+    #
     def set_font(font, size=nil) # :nodoc:
       @font = font
       @font_size = size if size
@@ -85,6 +86,7 @@ module Prawn
 
     # Saves the current font, and then yields. When the block
     # finishes, the original font is restored.
+    #
     def save_font
       @font ||= find_font("Helvetica")
       original_font = @font

data/lib/prawn/graphics.rb

@@ -6,7 +6,6 @@
 #
 # This is free software. Please see the LICENSE and COPYING files for details.
 
-require "enumerator"
 require "prawn/graphics/color"
 
 module Prawn

data/lib/prawn/images/jpg.rb

@@ -11,7 +11,8 @@ require 'stringio'
 module Prawn
   module Images
     # A convenience class that wraps the logic for extracting the parts
-    # of a PNG image that we need to embed them in a PDF
+    # of a JPG image that we need to embed them in a PDF
+    #
     class JPG 
       attr_reader :width, :height, :bits, :channels
       attr_accessor :scaled_width, :scaled_height

data/lib/prawn/images/png.rb

@@ -9,11 +9,13 @@
 # This is free software. Please see the LICENSE and COPYING files for details.
 
 require 'stringio'
+require 'enumerator'
 
 module Prawn
   module Images
     # A convenience class that wraps the logic for extracting the parts
     # of a PNG image that we need to embed them in a PDF
+    #
     class PNG
       attr_reader :palette, :img_data, :transparency
       attr_reader :width, :height, :bits

data/spec/bounding_box_spec.rb

@@ -128,6 +128,41 @@ describe "drawing bounding boxes" do
   
 end
 
+describe "Indentation" do
+  before(:each) { create_pdf }
+
+  it "should temporarily shift the x coordinate and width" do
+    @pdf.bounding_box([100,100], :width => 200) do
+      @pdf.indent(20) do
+        @pdf.bounds.absolute_left.should == 120
+        @pdf.bounds.width.should == 180
+      end
+    end
+  end
+
+  it "should restore the x coordinate and width after block exits" do
+    @pdf.bounding_box([100,100], :width => 200) do
+      @pdf.indent(20) do
+        # no-op
+      end
+      @pdf.bounds.absolute_left.should == 100
+      @pdf.bounds.width.should == 200
+    end
+  end
+
+  it "should restore the x coordinate and width on error" do
+    @pdf.bounding_box([100,100], :width => 200) do
+      begin
+        @pdf.indent(20) { raise }
+      rescue
+        @pdf.bounds.absolute_left.should == 100
+        @pdf.bounds.width.should == 200
+      end
+    end
+  end
+
+end
+
 describe "A canvas" do
   before(:each) { create_pdf }
   

data/spec/font_spec.rb

@@ -57,8 +57,7 @@ describe "font style support" do
     @pdf.text "In ActionMan-Italic"
 
     text = PDF::Inspector::Text.analyze(@pdf.render)
-    name = text.font_settings.map { |e| e[:name] }.first
-    name = name.unpack("n*")[2..-1].pack("U*")
+    name = text.font_settings.map { |e| e[:name] }.first.to_s
     name = name.sub(/\w+\+/, "subset+")
     name.should == "subset+ActionMan-Italic"
   end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: prawn-core
 version: !ruby/object:Gem::Version 
-  version: 0.5.0.1
+  version: 0.5.1
 platform: ruby
 authors: 
 - Gregory Brown
@@ -9,7 +9,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2009-06-15 00:00:00 -04:00
+date: 2009-09-22 00:00:00 -04:00
 default_executable: 
 dependencies: []
 
@@ -25,8 +25,10 @@ extra_rdoc_files:
 - COPYING
 files: 
 - examples/bounding_box/bounding_boxes.rb
+- examples/bounding_box/indentation.rb
 - examples/bounding_box/russian_boxes.rb
 - examples/column_box/column_box_example.rb
+- examples/example_helper.rb
 - examples/general/background.rb
 - examples/general/canvas.rb
 - examples/general/measurement_units.rb