0
@@ -1,3 +1,7 @@
0
+#############################################################
0
+# Various thoughts on design issues
0
+#############################################################
0
+
0
 *************************************
0
 * Overarching Design Principles
0
 *************************************
0
@@ -28,3 +32,16 @@ PDF::SimpleTable
0
 
0
 XHTML?
0
 - .table(data = String, opts = {})
0
+
0
+
0
+*************************************
0
+* API consistency 
0
+*************************************
0
+
0
+When placing objects onto the canvas, 2 styles
0
+- func(data, opts)
0
+  - positioning details default to sensible defaults. x,y the current cursor location, w,h the distance from the cursor to the right and bottom borders
0
+  - positioning options can be overridden in opts
0
+- func(x, y, w, h, opts)
0
+  - when default positioning can't be sensibly inferred (shapes, text cells, etc)
0
+  - forces user to choose details when they call it

0
@@ -51,7 +51,7 @@ James Healy <jimmy@deefa.com>
0
 * ruby/pango[http://ruby-gnome2.sourceforge.jp/] (optional, required to add text)
0
 * ruby/rsvg2[http://ruby-gnome2.sourceforge.jp/] (optional, required for SVG support)
0
 * ruby/gdkpixbuf[http://ruby-gnome2.sourceforge.jp/] (optional, required for GIF/JPG support)
0
-* ruby/poppler[http://ruby-gnome2.sourceforge.jp/] (optional, required embedding PDF images)
0
+* ruby/poppler[http://ruby-gnome2.sourceforge.jp/] (optional, required for embedding PDF images)
0
 
0
 These are all ruby bindings to C libraries. On Debian/Ubuntu based systems
0
 (which I develop on) you can get them by running:
0
@@ -69,7 +69,5 @@ JRuby users, you're probably out of luck.
0
 
0
 Rubinius users, I have no idea.
0
 
0
-Ruby1.9 users, the current release of ruby/cairo (1.5.0) doesn't work with 1.9,
0
-but the version in SVN does. Hopefully it will be released soon. The version in
0
-Debian has been patched to work with 1.9 already. PDF::Wrapper itself is 1.9
0
-compatible.
0
+Ruby1.9 users, the current release of ruby/cairo (1.5.1) added support for 1.9. PDF::Wrapper
0
+itself is 1.9 compatible.

0
@@ -46,7 +46,6 @@ Rake::RDocTask.new("doc") do |rdoc|
0
   rdoc.rdoc_dir = (ENV['CC_BUILD_ARTIFACTS'] || 'doc') + '/rdoc'
0
   rdoc.rdoc_files.include('README')
0
   rdoc.rdoc_files.include('CHANGELOG')
0
-  rdoc.rdoc_files.include('DESIGN')
0
   rdoc.rdoc_files.include('lib/**/*.rb')
0
   rdoc.options << "--inline-source"
0
 end

0
@@ -47,7 +47,7 @@ module PDF
0
   class Wrapper
0
 
0
     attr_reader :margin_left, :margin_right, :margin_top, :margin_bottom
0
-    attr_reader :page_width, :page_height
0
+    attr_reader :page_width, :page_height, :page
0
 
0
     # borrowed from PDF::Writer
0
     PAGE_SIZES = { # :value {...}:
0
@@ -124,6 +124,10 @@ module PDF
0
       default_color(:black)
0
       default_font("Sans Serif")
0
       default_font_size(16)
0
+
0
+      # maintain a count of pages and array of repeating elements to add to each page
0
+      @page = 1
0
+      @repeating = []
0
       
0
       # move the cursor to the top left of the usable canvas
0
       reset_cursor
0
@@ -257,6 +261,7 @@ module PDF
0
       # TODO: raise an error if any unrecognised options were supplied 
0
       # TODO: add padding between border and text
0
       # TODO: how do we handle a single word that is too long for the width?
0
+      # TODO: add an option to draw a border with rounded corners
0
 
0
       options = default_text_options
0
       options.merge!({:border => "tblr", :border_width => 1, :border_color => :black, :bgcolor => nil})
0
@@ -354,6 +359,7 @@ module PDF
0
     # <tt>:spacing</tt>::  Space between lines in PDF points
0
     def text(str, opts={})
0
       # TODO: add support for pango markup (see http://ruby-gnome2.sourceforge.jp/hiki.cgi?pango-markup)
0
+      # TODO: add converters from various markup languages to pango markup. (bluecloth, redcloth, markdown, textile, etc)
0
       # TODO: add a wrap option so wrapping can be disabled
0
       # TODO: raise an error if any unrecognised options were supplied 
0
       #
0
@@ -584,9 +590,45 @@ module PDF
0
       @context.move_to(margin_left,margin_top)
0
     end
0
 
0
+    # add the same elements to multiple pages. Useful for adding items like headers, footers and 
0
+    # watermarks.
0
+    #
0
+    # arguments:
0
+    # <tt>spec</tt>::     Which pages to add the items to. :all, :odd, :even, etc. NOT IMPLEMENTED YET
0
+    #
0
+    # To add a circle to the middle of every page
0
+    #   pdf.add_repeating_element(:all) do
0
+    #     pdf.circle(pdf.absolute_x_middle, pdf.absolute_y_middle, 100)
0
+    #   end
0
+    def add_repeating_element(spec = :all, &block)
0
+      # TODO: implement spec to allow repeating elements to only appear on selected pages
0
+      # TODO: add basic templating variables so things like page numbers can be used
0
+
0
+      # add it to the current page
0
+      block.call
0
+      
0
+      # store it so we can add it to future pages
0
+      @repeating << block
0
+    end
0
+
0
     # move to the next page
0
-    def start_new_page
0
+    #
0
+    # arguments:
0
+    # <tt>pageno</tt>::    If specified, the current page number will be set to that. By default, the page number will just increment. 
0
+    def start_new_page(pageno = nil)
0
       @context.show_page
0
+      if pageno
0
+        @page = pageno.to_i
0
+      else
0
+        @page += 1
0
+      end
0
+      
0
+      # apply the appropriate repeating elements to the new page
0
+      @repeating.each do |repeat|
0
+        repeat.call
0
+      end
0
+
0
+      # move the cursor to the top left of our page body
0
       reset_cursor
0
     end
0
 
0
@@ -651,6 +693,16 @@ module PDF
0
       return layout
0
     end
0
 
0
+    def default_positioning_options
0
+      # TODO: use these defaults in appropriate places
0
+      x, y = current_point
0
+      { :left   => x,
0
+        :top    => y,
0
+        :width  => points_to_right_margin(x),
0
+        :height => points_to_bottom_margin(y)
0
+      }
0
+    end
0
+
0
     def default_text_options
0
       { :font => @default_font,
0
         :font_size => @default_font_size,