axlsx 1.1.4 → 1.1.5

data/lib/axlsx/workbook/worksheet/comment.rb~

@@ -0,0 +1,91 @@
+module Axlsx
+
+  # A comment is the text data for a comment
+  class Comment
+
+    # The text to render
+    # @return [String]
+    attr_reader :text
+
+    # The index of the the author for this comment in the owning Comments object
+    # @see Comments
+    # @return [Integer]
+    attr_reader :author_index
+
+    # The owning Comments object
+    # @return [Comments]
+    attr_reader :comments
+
+
+    # The string based cell position reference (e.g. 'A1') that determines the positioning of this comment
+    attr_reader :ref
+
+    # TODO
+    # r (Rich Text Run)
+    # rPh (Phonetic Text Run)
+    # phoneticPr (Phonetic Properties)
+
+    def initialize(comments, options={})
+      raise ArgumentError, "A comment needs a parent comments object" unless comments.is_a?(Comments)
+      @comments = comments
+      options.each do |o|
+        self.send("#{o[0]}=", o[1]) if self.respond_to? "#{o[0]}="
+      end
+      yield self if block_given?
+    end
+
+    def pn
+      "#{COMMENT_PN % (index+1)}"
+    end
+
+    def vml_shape
+      @vml_shape ||= initialize_vml_shape
+    end
+
+    def initialize_vml_shape
+      ws = self.comments.worksheet
+      @vml_shape = VmlShape.new(self, :row => ws[ref].row.index, :column => ws[ref].index) do |vml|
+        vml.left_column = vml.row + 1
+        vml.right_column = vml.column + 4
+        vml.top_row = vml.row
+        vml.bottom_row = vml.row + 4
+      end
+    end
+
+    # The index of this comment
+    # @return [Integer]
+    def index
+      @comments.comment_list.index(self)
+    end
+
+    def ref=(v)
+      Axlsx::DataTypeValidator.validate "Comment.ref", [String, Cell], v
+      @ref = v if v.is_a?(String)
+      @ref = v.r if v.is_a?(Cell)
+    end
+
+    def text=(v)
+      Axlsx::validate_string(v)
+      @text = v
+    end
+
+    def author_index=(v)
+      Axlsx::validate_unsigned_int(v)
+      @author_index = v
+    end
+
+    def to_xml_string(str = "")
+      author = @comments.authors[author_index]
+      str << '<comment ref="' << ref << '" authorId="' << author_index.to_s << '">'
+      str << '<text><r>'
+      str << '<rPr> <b/><color indexed="81"/></rPr>'
+      str << '<t>' << author.to_s << ':
+</t></r>'
+      str << '<r>'
+      str << '<rPr><color indexed="81"/></rPr>'
+      str << '<t>' << text << '</t></r></text>'
+      str << '</comment>'
+    end
+
+  end
+end

data/lib/axlsx/workbook/worksheet/comments.rb

@@ -0,0 +1,77 @@
+# -*- coding: utf-8 -*-
+module Axlsx
+
+  # Comments is a collection of Comment objects for a worksheet
+  class Comments < SimpleTypedList
+
+    # the vml_drawing that holds the shapes for comments
+    # @return [VmlDrawing]
+    attr_reader :vml_drawing
+
+    # The worksheet that these comments belong to
+    # @return [Worksheet]
+    attr_reader :worksheet
+
+    # The index of this collection in the workbook. Effectively the index of the worksheet.
+    # @return [Integer]
+    def index
+      @worksheet.index
+    end
+
+    # The part name for this object
+    # @return [String]
+    def pn
+      "#{COMMENT_PN % (index+1)}"
+    end
+
+    # Creates a new Comments object
+    # @param [Worksheet] worksheet The sheet that these comments belong to.
+    def initialize(worksheet)
+      raise ArgumentError, "you must provide a worksheet" unless worksheet.is_a?(Worksheet)
+      super(Comment)
+      @worksheet = worksheet
+      @vml_drawing = VmlDrawing.new(self)
+    end
+
+    # Adds a new comment to the worksheet that owns these comments.
+    # @note the author, text and ref options are required
+    # @option options [String] author The name of the author for this comment
+    # @option options [String] text The text for this comment
+    # @option options [Stirng|Cell] ref The cell that this comment is attached to.
+    def add_comment(options={})
+      raise ArgumentError, "Comment require an author" unless options[:author]
+      raise ArgumentError, "Comment requires text" unless options[:text]
+      raise ArgumentError, "Comment requires ref" unless options[:ref]
+      @list << Comment.new(self, options)
+      yield @list.last if block_given?
+      @list.last
+    end
+
+    # A sorted list of the unique authors in the contained comments
+    # @return [Array]
+    def authors
+      @list.map { |comment| comment.author.to_s }.uniq.sort
+    end
+
+    # serialize the object
+    # @param [String] str
+    # @return [String]
+    def to_xml_string(str="")
+      str << '<?xml version="1.0" encoding="UTF-8"?>'
+      str << '<comments xmlns="' << XML_NS << '">'
+      str << '<authors>'
+      authors.each do  |author|
+        str << '<author>' << author.to_s << '</author>'
+      end
+      str << '</authors>'
+      str << '<commentList>'
+      @list.each do |comment|
+        comment.to_xml_string str
+      end
+      str << '</commentList></comments>'
+
+    end
+
+  end
+
+end

data/lib/axlsx/workbook/worksheet/comments.rb~

@@ -0,0 +1,86 @@
+module Axlsx
+
+  class Comments
+
+    # a collection of the comment authors
+    # @return [SimpleTypedList]
+    attr_reader :authors
+
+    # a collection of comment objects
+    # @return [SimpleTypedList]
+    attr_reader :comment_list
+
+
+    # The worksheet that these comments belong to
+    # @return [Worksheet]
+    attr_reader :worksheet
+
+    # Creates a new Comments object
+    def initialize(worksheet)
+      raise ArgumentError, "you must provide a worksheet" unless worksheet.is_a?(Worksheet)
+      @worksheet = worksheet
+      @authors = SimpleTypedList.new String
+      @comment_list = SimpleTypedList.new Comment
+    end
+
+    def add_comment(options={})
+      raise ArgumentError, "Comment require an author" unless options[:author]
+      raise ArgumentError, "Comment requires text" unless options[:text]
+      options[:author_index] = @authors.index(options[:author]) || @authors << options[:author]
+      @comment_list << Comment.new(self, options)
+      @comment_list.last
+    end
+
+    def to_xml_string(str="")
+    end
+
+  end
+
+  class Comment
+
+    attr_reader :text
+
+    attr_reader :author_index
+
+    attr_reader :comments
+
+    # TODO
+    # r (Rich Text Run)
+    # rPh (Phonetic Text Run)
+    # phoneticPr (Phonetic Properties)
+    def initialize(comments, options={})
+      raise ArgumentError, "A comment needs a parent comments object" unless comments.is_a?(Comments)
+      @comments = comments
+      options.each do |o|
+        self.send("#{o[0]}=", o[1]) if self.respond_to? "#{o[0]}="
+      end
+      yield self if block_given?
+    end
+
+    def pn
+      "#{COMMENT_PN % (index+1)}"
+    end
+
+    # The index of this comment
+    # @return [Integer]
+    def index
+      @comments.comment_list.index(self)
+    end
+
+
+    def text=(v)
+      Axlsx::validate_string(v)
+      @text = v
+    end
+
+    def author_index=(v)
+      Axlsx::validate_unsigned_int(v)
+      @author_index = v
+    end
+
+    def to_xml_string(str = "")
+    end
+
+  end
+
+end

data/lib/axlsx/workbook/worksheet/page_setup.rb

@@ -0,0 +1,90 @@
+module Axlsx
+  # Page setup settings for printing a worksheet. All settings are optional.
+  #
+  # @note The recommended way to manage print options is via Worksheet#page_setup
+  # @see Worksheet#print_options
+  # @see Worksheet#initialize
+  class PageSetup
+
+    # TODO: Attributes defined by Open XML spec that are not implemented yet:
+    # 
+    # * blackAndWhite
+    # * cellComments
+    # * copies
+    # * draft
+    # * errors
+    # * firstPageNumber
+    # * horizontalDpi
+    # * pageOrder
+    # * paperSize
+    # * useFirstPageNumber
+    # * usePrinterDefaults
+    # * verticalDpi
+    
+    # Number of vertical pages to fit on.
+    # @return [Integer]
+    attr_reader :fit_to_height
+
+    # Number of horizontal pages to fit on.
+    # @return [Integer]
+    attr_reader :fit_to_width
+
+    # Orientation of the page (:default, :landscape, :portrait)
+    # @return [Symbol]
+    attr_reader :orientation 
+    
+    # Height of paper (string containing a number followed by a unit identifier: "297mm", "11in")
+    # @return [String]
+    attr_reader :paper_height
+
+    # Width of paper (string containing a number followed by a unit identifier: "210mm", "8.5in")
+    # @return [String]
+    attr_reader :paper_width
+    
+    # Print scaling (percent value, given as integer ranging from 10 to 400)
+    # @return [Integer]
+    attr_reader :scale
+
+
+    # Creates a new PageSetup object
+    # @option options [Integer] fit_to_height Number of vertical pages to fit on
+    # @option options [Integer] fit_to_width Number of horizontal pages to fit on
+    # @option options [Symbol] orientation Orientation of the page (:default, :landscape, :portrait)
+    # @option options [String] paper_height Height of paper (number followed by unit identifier: "297mm", "11in")
+    # @option options [String] paper_width Width of paper (number followed by unit identifier: "210mm", "8.5in")
+    # @option options [Integer] scale Print scaling (percent value, integer ranging from 10 to 400)
+    def initialize(options = {})
+      set(options)
+    end
+
+    # Set some or all page settings at once.
+    # @param [Hash] options The page settings to set (possible keys are :fit_to_height, :fit_to_width, :orientation, :paper_height, :paper_width, and :scale).
+    def set(options)
+      options.each do |k, v|
+        send("#{k}=", v) if respond_to? "#{k}="
+      end
+    end
+
+    # @see fit_to_height
+    def fit_to_height=(v); Axlsx::validate_unsigned_int(v); @fit_to_height = v; end
+    # @see fit_to_width
+    def fit_to_width=(v); Axlsx::validate_unsigned_int(v); @fit_to_width = v; end
+    # @see orientation
+    def orientation=(v); Axlsx::validate_page_orientation(v); @orientation = v; end
+    # @see paper_height
+    def paper_height=(v); Axlsx::validate_number_with_unit(v); @paper_height = v; end
+    # @see paper_width
+    def paper_width=(v); Axlsx::validate_number_with_unit(v); @paper_width = v; end
+    # @see scale
+    def scale=(v); Axlsx::validate_page_scale(v); @scale = v; end
+
+    # Serializes the page settings element.
+    # @param [String] str
+    # @return [String]
+    def to_xml_string(str = '')
+      str << '<pageSetup '
+      str << instance_values.map{ |k,v| k.gsub(/_(.)/){ $1.upcase } << %{="#{v}"} }.join(' ')
+      str << '/>'
+    end
+  end
+end

data/lib/axlsx/workbook/worksheet/print_options.rb

@@ -0,0 +1,63 @@
+module Axlsx
+  # Options for printing a worksheet. All options are boolean and false by default.
+  #
+  # @note The recommended way to manage print options is via Worksheet#print_options
+  # @see Worksheet#print_options
+  # @see Worksheet#initialize
+  class PrintOptions
+
+    # Whether grid lines should be printed.
+    # @return [Boolean]
+    attr_reader :grid_lines
+
+    # Whether row and column headings should be printed.
+    # @return [Boolean]
+    attr_reader :headings
+
+    # Whether the content should be centered horizontally on the page.
+    # @return [Boolean]
+    attr_reader :horizontal_centered
+
+    # Whether the content should be centered vertically on the page.
+    # @return [Boolean]
+    attr_reader :vertical_centered
+
+    # Creates a new PrintOptions object
+    # @option options [Boolean] grid_lines Whether grid lines should be printed
+    # @option options [Boolean] headings Whether row and column headings should be printed
+    # @option options [Boolean] horizontal_centered Whether the content should be centered horizontally
+    # @option options [Boolean] vertical_centered  Whether the content should be centered vertically
+    def initialize(options = {})
+      @grid_lines = @headings = @horizontal_centered = @vertical_centered = false
+      set(options)
+    end
+
+    # Set some or all options at once.
+    # @param [Hash] options The options to set (possible keys are :grid_lines, :headings, :horizontal_centered, and :vertical_centered).
+    def set(options)
+      options.each do |k, v|
+        send("#{k}=", v) if respond_to? "#{k}="
+      end
+    end
+
+    # @see grid_lines
+    def grid_lines=(v); Axlsx::validate_boolean(v); @grid_lines = v; end
+    # @see headings
+    def headings=(v); Axlsx::validate_boolean(v); @headings = v; end
+    # @see horizontal_centered
+    def horizontal_centered=(v); Axlsx::validate_boolean(v); @horizontal_centered = v; end
+    # @see vertical_centered
+    def vertical_centered=(v); Axlsx::validate_boolean(v); @vertical_centered = v; end
+
+    # Serializes the page options element.
+    # @note As all attributes default to "false" according to the xml schema definition, the generated xml includes only those attributes that are set to true.
+    # @param [String] str
+    # @return [String]
+    def to_xml_string(str = '')
+      str << '<printOptions '
+      # 
+      str << instance_values.select{ |k,v| v == true }.map{ |k,v| k.gsub(/_(.)/){ $1.upcase } << %{="#{v}"} }.join(' ')
+      str << '/>'
+    end
+  end
+end

data/lib/axlsx/workbook/worksheet/row.rb

@@ -5,7 +5,9 @@ module Axlsx
   # @see Worksheet#add_row
   class Row
 
+    # A list of serilizable attributes.
     SERIALIZABLE_ATTRIBUTES = [:hidden, :outlineLevel, :collapsed, :style]
+
     # The worksheet this row belongs to
     # @return [Worksheet]
     attr_reader :worksheet
@@ -35,10 +37,8 @@ module Axlsx
     attr_reader :style
 
     # TODO  18.3.1.73
-    # # collapsed
     # customFormat
     # # hidden
-    # # outlineLevel
     # ph
     # # s (style)
     # spans

data/lib/axlsx/workbook/worksheet/worksheet.rb

@@ -16,6 +16,8 @@ module Axlsx
     # @return [Array] of Table
     attr_reader :tables
 
+    attr_reader :comments
+
     # The rows in this worksheet
     # @note The recommended way to manage rows is Worksheet#add_row
     # @return [SimpleTypedList]
@@ -81,6 +83,51 @@ module Axlsx
 
     end
 
+    # Page setup settings for printing the worksheet.
+    # @example
+    #      wb = Axlsx::Package.new.workbook
+    #
+    #      # using options when creating the worksheet.
+    #      ws = wb.add_worksheet :page_setup => {:fit_to_width => 1, :orientation => :landscape}
+    #
+    #      # use the set method of the page_setup object
+    #      ws.page_setup.set(:paper_width => "297mm", :paper_height => "210mm")
+    #
+    #      # setup page in a block
+    #      ws.page_setup do |page|
+    #        page.scale = 80
+    #        page.orientation = :portrait
+    #      end
+    # @see PageSetup#initialize
+    # @return [PageSetup]
+    def page_setup
+      @page_setup ||= PageSetup.new
+      yield @page_setup if block_given?
+      @page_setup
+    end
+
+    # Options for printing the worksheet.
+    # @example
+    #      wb = Axlsx::Package.new.workbook
+    #      # using options when creating the worksheet.
+    #      ws = wb.add_worksheet :print_options => {:gridLines => true, :horizontalCentered => true}
+    #
+    #      # use the set method of the page_margins object
+    #      ws.print_options.set(:headings => true)
+    #
+    #      # set page margins in a block
+    #      ws.print_options do |options|
+    #        options.horizontalCentered = true
+    #        options.verticalCentered = true
+    #      end
+    # @see PrintOptions#initialize
+    # @return [PrintOptions]
+    def print_options
+      @print_options ||= PrintOptions.new
+      yield @print_options if block_given?
+      @print_options
+    end
+
     # definition of characters which are less than the maximum width of 0-9 in the default font for use in String#count.
     # This is used for autowidth calculations
     # @return [String]
@@ -93,21 +140,23 @@ module Axlsx
     # @see Workbook#add_worksheet
     # @option options [String] name The name of this worksheet.
     # @option options [Hash] page_margins A hash containing page margins for this worksheet. @see PageMargins
+    # @option options [Hash] print_options A hash containing print options for this worksheet. @see PrintOptions
     # @option options [Boolean] show_gridlines indicates if gridlines should be shown for this sheet.
     def initialize(wb, options={})
       self.workbook = wb
       @workbook.worksheets << self
-
+      @page_marging = @page_setup = @print_options = nil
       @drawing = @page_margins = @auto_filter = nil
       @merged_cells = []
       @auto_fit_data = []
       @conditional_formattings = []
-
+      @comments = Comments.new(self)
       @selected = false
       @show_gridlines = true
       self.name = "Sheet" + (index+1).to_s
       @page_margins = PageMargins.new options[:page_margins] if options[:page_margins]
-
+      @page_setup = PageSetup.new options[:page_setup] if options[:page_setup]
+      @print_options = PrintOptions.new options[:print_options] if options[:print_options]
       @rows = SimpleTypedList.new Row
       @column_info = SimpleTypedList.new Col
       # @cols = SimpleTypedList.new Cell
@@ -394,6 +443,12 @@ module Axlsx
       table
     end
 
+
+    # Shortcut to comments#add_comment
+    def add_comment(options={})
+      @comments.add_comment(options)
+    end
+
     # Adds a media item to the worksheets drawing
     # @param [Class] media_type
     # @option options [] unknown
@@ -423,7 +478,9 @@ module Axlsx
       str.concat '</sheetData>'
       str.concat "<autoFilter ref='%s'></autoFilter>" % @auto_filter if @auto_filter
       str.concat "<mergeCells count='%s'>%s</mergeCells>" % [@merged_cells.size, @merged_cells.reduce('') { |memo, obj| memo += "<mergeCell ref='%s'></mergeCell>" % obj } ] unless @merged_cells.empty?
+      print_options.to_xml_string(str) if @print_options
       page_margins.to_xml_string(str) if @page_margins
+      page_setup.to_xml_string(str) if @page_setup
       str.concat "<drawing r:id='rId1'></drawing>" if @drawing
       unless @tables.empty?
         str.concat "<tableParts count='%s'>%s</tableParts>" % [@tables.size, @tables.reduce('') { |memo, obj| memo += "<tablePart r:id='%s'/>" % obj.rId }]
@@ -431,18 +488,24 @@ module Axlsx
       @conditional_formattings.each do |cf|
         str.concat cf.to_xml_string
       end
+      str << '<legacyDrawing r:id="rId1"/>' if @comments.size > 0
       str + '</worksheet>'
     end
 
     # The worksheet relationships. This is managed automatically by the worksheet
     # @return [Relationships]
     def relationships
-        r = Relationships.new
-        @tables.each do |table|
-          r << Relationship.new(TABLE_R, "../#{table.pn}")
-        end
-        r << Relationship.new(DRAWING_R, "../#{@drawing.pn}") if @drawing
-        r
+      r = Relationships.new
+      @tables.each do |table|
+        r << Relationship.new(TABLE_R, "../#{table.pn}")
+      end
+
+      r << Relationship.new(VML_DRAWING_R, "../#{@comments.vml_drawing.pn}") if @comments.size > 0
+      r << Relationship.new(COMMENT_R, "../#{@comments.pn}") if @comments.size > 0
+      r << Relationship.new(COMMENT_R_NULL, "NULL") if @comments.size > 0
+
+      r << Relationship.new(DRAWING_R, "../#{@drawing.pn}") if @drawing
+      r
     end
 
     # Returns the cell or cells defined using excel style A1:B3 references.