From a72385c20e4d582ad0cbc85004ca41e744aea730 Mon Sep 17 00:00:00 2001 From: Brett Neumeier Date: Fri, 23 Oct 2009 07:52:20 -0500 Subject: [PATCH] Various rdoc fixes and cleanups --- lib/prawn/layout/grid.rb | 22 +++++++------ lib/prawn/layout/page.rb | 2 +- lib/prawn/table.rb | 57 ++++++++++++++++++++++---------- lib/prawn/table/cell.rb | 71 ++++++++++++++++++++++++++-------------- 4 files changed, 99 insertions(+), 53 deletions(-) diff --git a/lib/prawn/layout/grid.rb b/lib/prawn/layout/grid.rb index 0c49a50..340e29a 100644 --- a/lib/prawn/layout/grid.rb +++ b/lib/prawn/layout/grid.rb @@ -1,14 +1,15 @@ module Prawn class Document - # Defines the grid system for a particular document. Takes the number of rows and columns and the - # width to use for the gutter as the keys :rows, :columns, :gutter + # Defines the grid system for a particular document. Takes the number of + # rows and columns and the width to use for the gutter as the keys :rows, + # :columns, :gutter # def define_grid(options = {}) @grid = Grid.new(self, options) end - # A method that can either be used to access a particular grid on the page or interogate the grid - # system directly. + # A method that can either be used to access a particular grid on the page + # or interogate the grid system directly. # # @pdf.grid # Get the Grid directly # @pdf.grid([0,1]) # Get the box at [0,1] @@ -28,8 +29,8 @@ def grid(*args) end end - # A Grid represents the entire grid system of a Page and calculates the column width and row height - # of the base box. + # A Grid represents the entire grid system of a Page and calculates the + # column width and row height of the base box. class Grid attr_reader :pdf, :columns, :rows, :gutter, :row_gutter, :column_gutter # :nodoc @@ -77,9 +78,9 @@ def set_gutter(options) end end - # A Box is a class that represents a bounded area of a page. A Grid object has methods that allow - # easy access to the coordinates of its corners, which can be plugged into most existing prawn - # methods. + # A Box is a class that represents a bounded area of a page. A Grid object + # has methods that allow easy access to the coordinates of its corners, + # which can be plugged into most existing prawn methods. # class Box attr_reader :pdf @@ -90,7 +91,8 @@ def initialize(pdf, i, j) @j = j end - # Mostly diagnostic method that outputs the name of a box as col_num, row_num + # Mostly diagnostic method that outputs the name of a box as col_num, + # row_num def name "#{@i.to_s},#{@j.to_s}" end diff --git a/lib/prawn/layout/page.rb b/lib/prawn/layout/page.rb index 1bb87cd..cbc37b9 100644 --- a/lib/prawn/layout/page.rb +++ b/lib/prawn/layout/page.rb @@ -53,7 +53,7 @@ def padded_box(margin, &block) # Unless :width or :height are specified, the margin_box # width and height are used. # - # header margin_box.top_left do + # header margin_box.top_left do # text "Here's My Fancy Header", :size => 25, :align => :center # stroke_horizontal_rule # end diff --git a/lib/prawn/table.rb b/lib/prawn/table.rb index 36cde96..8460280 100644 --- a/lib/prawn/table.rb +++ b/lib/prawn/table.rb @@ -82,38 +82,59 @@ class Table NUMBER_PATTERN = /^-?(?:0|[1-9]\d*)(?:\.\d+(?:[eE][+-]?\d+)?)?$/ #:nodoc: - # Creates a new Document::Table object. This is generally called - # indirectly through Document#table but can also be used explictly. + # Creates a new Document::Table object. This is generally called indirectly + # through Document#table but can also be used explictly. # # The data argument is a two dimensional array of strings, # organized by row, e.g. [["r1-col1","r1-col2"],["r2-col2","r2-col2"]]. # As with all Prawn text drawing operations, strings must be UTF-8 encoded. + # Hashes can be used instead of Strings, in which case they are + # interpreted as Cell options (see Cell#new), and Cells can be used + # directly in table data as well. # # The following options are available for customizing your tables, with # defaults shown in [] at the end of each description. # - # :headers:: An array of table headers, either strings or Cells. [Empty] - # :align_headers:: Alignment of header text. Specify for entire header (:left) or by column ({ 0 => :right, 1 => :left}). If omitted, the header alignment is the same as the column alignment. + # :headers:: + # An array of table headers, either strings or Cells. [Empty] + # :align_headers:: + # Alignment of header text. Specify for entire header (:left) + # or by column ({ 0 => :right, 1 => :left}). If omitted, the + # header alignment is the same as the column alignment. # :header_text_color:: Sets the text color of the headers # :header_color:: Manually sets the header color - # :font_size:: The font size for the text cells . [12] - # :horizontal_padding:: The horizontal cell padding in PDF points [5] + # :font_size:: The default font size for the text cells. [12] + # :horizontal_padding:: + # The horizontal cell padding in PDF points [5] # :vertical_padding:: The vertical cell padding in PDF points [5] # :padding:: Horizontal and vertical cell padding (overrides both) # :border_width:: With of border lines in PDF points [1] - # :border_style:: If set to :grid, fills in all borders. If set to :underline_header, underline header only. Otherwise, borders are drawn on columns only, not rows + # :border_style:: + # If set to :grid, fills in all borders. If set to :underline_header, + # underline header only. Otherwise, borders are drawn on columns only, + # not rows # :border_color:: Sets the color of the borders. - # :position:: One of :left, :center or n, where n is an x-offset from the left edge of the current bounding box - # :width:: A set width for the table, defaults to the sum of all column widths - # :column_widths:: A hash of indices and widths in PDF points. E.g. { 0 => 50, 1 => 100 } - # :row_colors:: Used to specify background colors for rows. See below for usage. - # :align:: Alignment of text in columns, for entire table (:center) or by column ({ 0 => :left, 1 => :center}) + # :position:: + # One of :left, :center or n, where n + # is an x-offset from the left edge of the current bounding box + # :width:: + # A set width for the table, defaults to the sum of all column widths + # :column_widths:: + # A hash of indices and widths in PDF points. E.g. { 0 => 50, 1 => + # 100 } + # :row_colors:: + # Used to specify background colors for rows. See below for usage. + # :align:: + # Alignment of text in columns, for entire table (:center) or by + # column ({ 0 => :left, 1 => :center}) # # Row colors (:row_colors) are specified as HTML hex color values, # e.g., "ccaaff". They can take several forms: # - # * An array of colors, used cyclically to "zebra stripe" the table: ['ffffff', 'cccccc', '336699']. - # * A hash taking 0-based row numbers to colors: { 0 => 'ffffff', 2 => 'cccccc'}. + # * An array of colors, used cyclically to "zebra stripe" the table: + # ['ffffff', 'cccccc', '336699']. + # * A hash taking 0-based row numbers to colors: { 0 => 'ffffff', 2 => + # 'cccccc'}. # * The symbol :pdf_writer, for PDF::Writer's default color scheme. # # See Document#table for typical usage, as directly using this class is @@ -122,7 +143,8 @@ class Table def initialize(data, document, options={}) unless data.all? { |e| Array === e } raise Prawn::Errors::InvalidTableData, - "data must be a two dimensional array of Prawn::Cells or strings" + "data must be a two dimensional array of Prawn::Table::Cells, " + + "Hashes, and Strings" end @data = data @@ -218,8 +240,8 @@ def fit_within_bounds(manual_widths, width) manual_widths.each { |k,v| @column_widths[k] = v; manual_width += v } if manual_widths - #Ensures that the maximum width of the document is not exceeded - #Takes into consideration the manual widths specified (With full manual + # Ensures that the maximum width of the document is not exceeded. Takes + # into consideration the manual widths specified. (With full manual # widths specified, the width can exceed the document width as manual # widths are taken as gospel) max_width = width || @document.margin_box.width @@ -386,7 +408,6 @@ def draw_page(contents) reset_row_colors end - def next_row_color return if C(:row_colors).is_a?(Hash) diff --git a/lib/prawn/table/cell.rb b/lib/prawn/table/cell.rb index 6744d12..f8176e8 100644 --- a/lib/prawn/table/cell.rb +++ b/lib/prawn/table/cell.rb @@ -32,12 +32,27 @@ class Table class Cell # Creates a new cell object. Generally used indirectly via Document#cell + # (or by passing Strings or Hashes as Table data). # - # Of the available options listed below, :point, :width, - # and :text must be provided. If you are not using the - # Document#cell shortcut, the :document must also be provided. + # Cells can be used standalone, as a kind of limited-purpose bounding + # box for laying out blocks of text, or they can be a single field + # within a Table. # - # :point:: Absolute [x,y] coordinate of the top-left corner of the cell. + # The only initialization option that is always required is + # :text. + # + # When using a Cell by itself, you must specify :point, and + # :width. Also, if creating the Cell directly rather than + # using the Document#cell shortcut, you must provide :document + # as well. + # + # When using a Cell as part of a table, many of the initialization + # options are ignored (:width, :horizontal_padding, + # :vertical_padding, :border_width, + # :border_style, :align). + # + # :point:: + # Absolute [x,y] coordinate of the top-left corner of the cell. # :document:: The Prawn::Document object to render on. # :text:: The text to be flowed within the cell # :text_color:: The color of the text to be displayed @@ -46,42 +61,50 @@ class Cell # :horizontal_padding:: The horizontal padding in PDF points # :vertical_padding:: The vertical padding in PDF points # :padding:: Overrides both horizontal and vertical padding - # :align:: One of :left, :right, :center - # :borders:: An array of sides which should have a border. Any of :top, :left, :right, :bottom + # :align:: + # One of :left, :right, :center + # :borders:: + # An array of sides which should have a border. Any of :top, + # :left, :right, :bottom # :border_width:: The border line width. Defaults to 1. - # :border_style:: One of :all, :no_top, :no_bottom, :sides, :none, :bottom_only. Defaults to :all. + # :border_style:: + # One of :all, :no_top, :no_bottom, + # :sides, :none, :bottom_only. Defaults to + # :all. # :border_color:: The color of the cell border. # :font_size:: The font size for the cell text. # :font_style:: The font style for the cell text. + # :colspan:: + # The number of columns that the cell should occupy in the table. # def initialize(options={}) - @point = options[:point] - @document = options[:document] - @text = options[:text].to_s - @text_color = options[:text_color] - @width = options[:width] - @height = options[:height] - @borders = options[:borders] - @border_width = options[:border_width] || 1 - @border_style = options[:border_style] || :all - @border_color = options[:border_color] - @background_color = options[:background_color] - @align = options[:align] || :left - @font_size = options[:font_size] - @font_style = options[:font_style] - + @point = options[:point] + @document = options[:document] + @text = options[:text].to_s + @text_color = options[:text_color] + @width = options[:width] + @height = options[:height] + @borders = options[:borders] + @border_width = options[:border_width] || 1 + @border_style = options[:border_style] || :all + @border_color = options[:border_color] + @background_color = options[:background_color] + @align = options[:align] || :left + @font_size = options[:font_size] + @font_style = options[:font_style] + @colspan = options[:colspan] @horizontal_padding = options[:horizontal_padding] || 0 @vertical_padding = options[:vertical_padding] || 0 if options[:padding] @horizontal_padding = @vertical_padding = options[:padding] end - end attr_accessor :point, :border_style, :border_width, :background_color, :document, :horizontal_padding, :vertical_padding, :align, - :borders, :text_color, :border_color, :font_size, :font_style + :borders, :text_color, :border_color, :font_size, + :font_style, :colspan attr_writer :height, :width #:nodoc: