examples/repeating.rb @@ -1,3 +1,7 @@ +############################################################# +# Various thoughts on design issues +############################################################# + ************************************* * Overarching Design Principles ************************************* @@ -28,3 +32,16 @@ PDF::SimpleTable XHTML? - .table(data = String, opts = {}) + + +************************************* +* API consistency +************************************* + +When placing objects onto the canvas, 2 styles +- func(data, opts) + - 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 + - positioning options can be overridden in opts +- func(x, y, w, h, opts) + - when default positioning can't be sensibly inferred (shapes, text cells, etc) + - forces user to choose details when they call it DESIGN @@ -51,7 +51,7 @@ James Healy <jimmy@deefa.com> * ruby/pango[http://ruby-gnome2.sourceforge.jp/] (optional, required to add text) * ruby/rsvg2[http://ruby-gnome2.sourceforge.jp/] (optional, required for SVG support) * ruby/gdkpixbuf[http://ruby-gnome2.sourceforge.jp/] (optional, required for GIF/JPG support) -* ruby/poppler[http://ruby-gnome2.sourceforge.jp/] (optional, required embedding PDF images) +* ruby/poppler[http://ruby-gnome2.sourceforge.jp/] (optional, required for embedding PDF images) These are all ruby bindings to C libraries. On Debian/Ubuntu based systems (which I develop on) you can get them by running: @@ -69,7 +69,5 @@ JRuby users, you're probably out of luck. Rubinius users, I have no idea. -Ruby1.9 users, the current release of ruby/cairo (1.5.0) doesn't work with 1.9, -but the version in SVN does. Hopefully it will be released soon. The version in -Debian has been patched to work with 1.9 already. PDF::Wrapper itself is 1.9 -compatible. +Ruby1.9 users, the current release of ruby/cairo (1.5.1) added support for 1.9. PDF::Wrapper +itself is 1.9 compatible. README @@ -46,7 +46,6 @@ Rake::RDocTask.new("doc") do |rdoc| rdoc.rdoc_dir = (ENV['CC_BUILD_ARTIFACTS'] || 'doc') + '/rdoc' rdoc.rdoc_files.include('README') rdoc.rdoc_files.include('CHANGELOG') - rdoc.rdoc_files.include('DESIGN') rdoc.rdoc_files.include('lib/**/*.rb') rdoc.options << "--inline-source" end Rakefile @@ -47,7 +47,7 @@ module PDF class Wrapper attr_reader :margin_left, :margin_right, :margin_top, :margin_bottom - attr_reader :page_width, :page_height + attr_reader :page_width, :page_height, :page # borrowed from PDF::Writer PAGE_SIZES = { # :value {...}: @@ -124,6 +124,10 @@ module PDF default_color(:black) default_font("Sans Serif") default_font_size(16) + + # maintain a count of pages and array of repeating elements to add to each page + @page = 1 + @repeating = [] # move the cursor to the top left of the usable canvas reset_cursor @@ -257,6 +261,7 @@ module PDF # TODO: raise an error if any unrecognised options were supplied # TODO: add padding between border and text # TODO: how do we handle a single word that is too long for the width? + # TODO: add an option to draw a border with rounded corners options = default_text_options options.merge!({:border => "tblr", :border_width => 1, :border_color => :black, :bgcolor => nil}) @@ -354,6 +359,7 @@ module PDF # <tt>:spacing</tt>:: Space between lines in PDF points def text(str, opts={}) # TODO: add support for pango markup (see http://ruby-gnome2.sourceforge.jp/hiki.cgi?pango-markup) + # TODO: add converters from various markup languages to pango markup. (bluecloth, redcloth, markdown, textile, etc) # TODO: add a wrap option so wrapping can be disabled # TODO: raise an error if any unrecognised options were supplied # @@ -584,9 +590,45 @@ module PDF @context.move_to(margin_left,margin_top) end + # add the same elements to multiple pages. Useful for adding items like headers, footers and + # watermarks. + # + # arguments: + # <tt>spec</tt>:: Which pages to add the items to. :all, :odd, :even, etc. NOT IMPLEMENTED YET + # + # To add a circle to the middle of every page + # pdf.add_repeating_element(:all) do + # pdf.circle(pdf.absolute_x_middle, pdf.absolute_y_middle, 100) + # end + def add_repeating_element(spec = :all, &block) + # TODO: implement spec to allow repeating elements to only appear on selected pages + # TODO: add basic templating variables so things like page numbers can be used + + # add it to the current page + block.call + + # store it so we can add it to future pages + @repeating << block + end + # move to the next page - def start_new_page + # + # arguments: + # <tt>pageno</tt>:: If specified, the current page number will be set to that. By default, the page number will just increment. + def start_new_page(pageno = nil) @context.show_page + if pageno + @page = pageno.to_i + else + @page += 1 + end + + # apply the appropriate repeating elements to the new page + @repeating.each do |repeat| + repeat.call + end + + # move the cursor to the top left of our page body reset_cursor end @@ -651,6 +693,16 @@ module PDF return layout end + def default_positioning_options + # TODO: use these defaults in appropriate places + x, y = current_point + { :left => x, + :top => y, + :width => points_to_right_margin(x), + :height => points_to_bottom_margin(y) + } + end + def default_text_options { :font => @default_font, :font_size => @default_font_size, lib/pdf/wrapper.rb a44f0e1a8010ee144023d682c9129067e1d39a0e yob yob@e919c1b1-765b-490e-99a9-442fb257b346 http://github.com/yob/pdf-wrapper/commit/25e36b81305f65e03706792e51d1d39bc684be16 25e36b81305f65e03706792e51d1d39bc684be16 2008-01-13T06:44:50-08:00 2008-01-13T06:44:50-08:00 - added support for repeating elements that occur on multiple pages - small doc tweaks git-svn-id: svn://rubyforge.org/var/svn/pdf-wrapper@28 e919c1b1-765b-490e-99a9-442fb257b346 5691f5ccb6ea1b3c9c5c70c5c11d29c865a3ca6c yob yob@e919c1b1-765b-490e-99a9-442fb257b346