axlsx 1.1.0 → 1.2.0

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

@@ -0,0 +1,83 @@
+module Axlsx
+  # Conditional Format Rule icon sets
+  # Describes an icon set conditional formatting rule.
+
+  # @note The recommended way to manage these rules is via Worksheet#add_conditional_formatting
+  # @see Worksheet#add_conditional_formatting
+  # @see ConditionalFormattingRule#initialize
+  class IconSet
+
+    # instance values that must be serialized as their own elements - e.g. not attributes.
+    CHILD_ELEMENTS = [:value_objects]
+
+    # The icon set to display.
+    # Allowed values are: 3Arrows, 3ArrowsGray, 3Flags, 3TrafficLights1, 3TrafficLights2, 3Signs, 3Symbols, 3Symbols2, 4Arrows, 4ArrowsGray, 4RedToBlack, 4Rating, 4TrafficLights, 5Arrows, 5ArrowsGray, 5Rating, 5Quarters
+    # The default value is 3TrafficLights1
+    # @return [String]
+    attr_reader :iconSet
+
+    # Indicates whether the thresholds indicate percentile values, instead of number values.
+    # The default falue is true
+    # @return [Boolean]
+    attr_reader :percent
+
+    # If true, reverses the default order of the icons in this icon set.maxLength attribute
+    # The default value is false
+    # @return [Boolean]
+    attr_reader :reverse
+
+    # Indicates whether to show the values of the cells on which this data bar is applied.
+    # The default value is true
+    # @return [Boolean]
+    attr_reader :showValue
+
+    # Creates a new icon set object
+    # @option options [String] iconSet
+    # @option options [Boolean] reverse
+    # @option options [Boolean] percent
+    # @option options [Boolean] showValue
+    def initialize(options = {})
+      @percent = @showValue = true
+      @reverse = false
+      @iconSet = "3TrafficLights1"
+      initialize_value_objects
+      options.each do |o|
+        self.send("#{o[0]}=", o[1]) if self.respond_to? "#{o[0]}="
+      end
+      yield self if block_given?
+    end
+
+    # @see iconSet
+    def iconSet=(v); Axlsx::validate_icon_set(v); @iconSet = v end
+
+    # @see showValue
+    def showValue=(v); Axlsx.validate_boolean(v); @showValue = v end
+
+    # @see percent
+    def percent=(v); Axlsx.validate_boolean(v); @percent = v end
+
+    # @see reverse
+    def reverse=(v); Axlsx.validate_boolean(v); @reverse = v end
+
+    # Serialize this object to an xml string
+    # @param [String] str
+    # @return [String]
+    def to_xml_string(str="")
+      str << '<iconSet '
+      str << instance_values.map { |key, value| '' << key << '="' << value.to_s << '"' unless CHILD_ELEMENTS.include?(key.to_sym) }.join(' ')
+      str << '>'
+      @value_objects.each { |cfvo| cfvo.to_xml_string(str) }
+      str << '</iconSet>'
+    end
+
+    private
+
+    # Initalize the simple typed list of value objects
+    # I am keeping this private for now as I am not sure what impact changes to the required two cfvo objects will do.
+    def initialize_value_objects
+      @value_objects = SimpleTypedList.new Cfvo
+      @value_objects.concat [Cfvo.new(:type => :percent, :val => 0), Cfvo.new(:type => :percent, :val => 33), Cfvo.new(:type => :percent, :val => 67)]
+      @value_objects.lock
+    end
+  end
+end

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

@@ -0,0 +1,35 @@
+module Axlsx
+
+  # A simple list of merged cells
+  class MergedCells < SimpleTypedList
+
+    # creates a new MergedCells object
+    # @param [Worksheet] worksheet
+    def initialize(worksheet)
+      raise ArgumentError, 'you must provide a worksheet' unless worksheet.is_a?(Worksheet)
+      super String
+    end
+
+    # adds cells to the merged cells collection
+    # @param [Array||String] cells The cells to add to the merged cells
+    # collection. This can be an array of actual cells or a string style
+    # range like 'A1:C1'
+    def add(cells)
+      @list << if cells.is_a?(String)
+                 cells
+               elsif cells.is_a?(Array)
+                 Axlsx::cell_range(cells, false)
+               end
+    end
+
+    # serialize the object
+    # @param [String] str
+    # @return [String]
+    def to_xml_string(str = '')
+      return if @list.empty?
+      str << "<mergeCells count='#{size}'>"
+      each { |merged_cell| str << "<mergeCell ref='#{merged_cell}'></mergeCell>" }
+      str << '</mergeCells>'
+    end
+  end
+end

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

@@ -0,0 +1,113 @@
+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.
+    # @note PageSetup#fit_to is the recomended way to manage page fitting as only specifying one of fit_to_width/fit_to_height will result in the counterpart
+    # being set to 1.
+     # @return [Integer]
+    attr_reader :fit_to_height
+
+    # Number of horizontal pages to fit on.
+    # @note PageSetup#fit_to is the recomended way to manage page fitting as only specifying one of width/height will result in the counterpart
+    # being set to 1. 
+    # @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_scale_10_400(v); @scale = v; end
+    
+    # convenience method to achieve sanity when setting fit_to_width and fit_to_height 
+    # as they both default to 1 if only their counterpart is specified.
+    # @note This method will overwrite any value you explicitly set via the fit_to_height or fit_to_width methods.
+    # @option options [Integer] width The number of pages to fit this worksheet on horizontally. Default 9999
+    # @option options [Integer] height The number of pages to fit this worksheet on vertically. Default 9999
+    def fit_to(options={})
+      self.fit_to_width = options[:width] || 9999
+      self.fit_to_height = options[:height] || 9999
+      [@fit_to_width, @fit_to_height]
+    end
+
+
+    # helper method for worksheet to determine if the page setup is configured for fit to page printing
+    # We treat any page set up that has a value set for fit_to_width or fit_to_height value as fit_to_page. 
+    # @return [Boolean]
+    def fit_to_page?
+       # is there some better what to express this?
+       (fit_to_width != nil || fit_to_height != nil)
+    end
+
+    # Serializes the page settings element.
+    # @param [String] str
+    # @return [String]
+    def to_xml_string(str = '')
+      str << '<pageSetup '
+      str << instance_values.reject{ |k, v| k == 'worksheet' }.map{ |k,v| k.gsub(/_(.)/){ $1.upcase } << %{="#{v}"} }.join(' ')
+      str << '/>'
+    end
+  end
+end

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

@@ -0,0 +1,144 @@
+# encoding: UTF-8
+module Axlsx
+  # Pane options for a worksheet.
+  #
+  # @note The recommended way to manage the pane options is via SheetView#pane
+  # @see SheetView#pane
+  class Pane
+    
+    # Active Pane
+    # The pane that is active.
+    # Options are 
+    #  * bottom_left:  Bottom left pane, when both vertical and horizontal
+    #                  splits are applied. This value is also used when only
+    #                  a horizontal split has been applied, dividing the pane 
+    #                  into upper and lower regions. In that case, this value 
+    #                  specifies the bottom pane.
+    #  * bottom_right: Bottom right pane, when both vertical and horizontal
+    #                  splits are applied.
+    #  * top_left:     Top left pane, when both vertical and horizontal splits
+    #                  are applied. This value is also used when only a horizontal 
+    #                  split has been applied, dividing the pane into upper and lower
+    #                  regions. In that case, this value specifies the top pane.
+    #                  This value is also used when only a vertical split has
+    #                  been applied, dividing the pane into right and left
+    #                  regions. In that case, this value specifies the left pane
+    #  * top_right:    Top right pane, when both vertical and horizontal
+    #                  splits are applied. This value is also used when only
+    #                  a vertical split has been applied, dividing the pane 
+    #                  into right and left regions. In that case, this value 
+    #                  specifies the right pane.
+    # @see type
+    # @return [Symbol]
+    # default nil
+    attr_reader :active_pane
+    
+    
+    # Split State
+    # Indicates whether the pane has horizontal / vertical 
+    # splits, and whether those splits are frozen.
+    # Options are 
+    #  * frozen:       Panes are frozen, but were not split being frozen. In
+    #                  this state, when the panes are unfrozen again, a single
+    #                  pane results, with no split. In this state, the split 
+    #                  bars are not adjustable.
+    #  * frozen_split: Panes are frozen and were split before being frozen. In
+    #                  this state, when the panes are unfrozen again, the split
+    #                  remains, but is adjustable.
+    #  * split:        Panes are split, but not frozen. In this state, the split
+    #                  bars are adjustable by the user.
+    # @see type
+    # @return [Symbol]
+    # default nil
+    attr_reader :state
+    
+    
+    # Top Left Visible Cell
+    # Location of the top left visible cell in the bottom 
+    # right pane (when in Left-To-Right mode).
+    # @see type
+    # @return [String]
+    # default nil
+    attr_reader :top_left_cell
+    
+    
+    # Horizontal Split Position
+    # Horizontal position of the split, in 1/20th of a point; 0 (zero)
+    # if none. If the pane is frozen, this value indicates the number 
+    # of columns visible in the top pane.
+    # @see type
+    # @return [Integer]
+    # default 0
+    attr_reader :x_split
+    
+    
+    # Vertical Split Position
+    # Vertical position of the split, in 1/20th of a point; 0 (zero) 
+    # if none. If the pane is frozen, this value indicates the number
+    # of rows visible in the left pane.
+    # @see type
+    # @return [Integer]
+    # default 0
+    attr_reader :y_split
+    
+    
+    # Creates a new {Pane} object
+    # @option options [Symbol] active_pane Active Pane
+    # @option options [Symbol] state Split State
+    # @option options [Cell, String] top_left_cell Top Left Visible Cell
+    # @option options [Integer] x_split Horizontal Split Position
+    # @option options [Integer] y_split Vertical Split Position
+    def initialize(options={})
+      #defaults
+      @active_pane = @state = @top_left_cell = nil
+      @x_split = @y_split = 0
+      
+      # write options to instance variables
+      options.each do |o|
+        self.send("#{o[0]}=", o[1]) if self.respond_to? "#{o[0]}="
+      end
+    end
+    
+    
+    # @see active_pane
+    def active_pane=(v); Axlsx::validate_pane_type(v); @active_pane = v end
+    
+    
+    # @see state
+    def state=(v); Axlsx::validate_split_state_type(v); @state = v end
+    
+    
+    # @see top_left_cell
+    def top_left_cell=(v)
+      cell = (v.class == Axlsx::Cell ? v.r_abs : v)
+      Axlsx::validate_string(cell)  
+      @top_left_cell = cell 
+    end
+    
+    
+    # @see x_split
+    def x_split=(v); Axlsx::validate_unsigned_int(v); @x_split = v end
+    
+    
+    # @see y_split
+    def y_split=(v); Axlsx::validate_unsigned_int(v); @y_split = v end
+    
+    
+    # Serializes the data validation
+    # @param [String] str
+    # @return [String]
+    def to_xml_string(str = '')
+      if @state == :frozen && @top_left_cell.nil?
+        row = @y_split || 0
+        column = @x_split || 0
+        
+        @top_left_cell = "#{('A'..'ZZ').to_a[column]}#{row+1}"
+      end
+      
+      str << '<pane '
+      str << instance_values.map { |key, value| '' << key.gsub(/_(.)/){ $1.upcase } << 
+        %{="#{[:active_pane, :state].include?(key.to_sym) ? value.to_s.gsub(/_(.)/){ $1.upcase } : value}"} unless value.nil? }.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/protected_range.rb

@@ -0,0 +1,46 @@
+module Axlsx
+  # The Protected Range class represents a set of cells in the worksheet
+  # @note the recommended way to manage protected ranges with via Worksheet#protect_range
+  # @see Worksheet#protect_range
+  class ProtectedRange
+
+    # The reference for the protected range
+    # @return [String]
+    attr_reader :sqref
+
+    # The name of the protected range
+    # @return [String]
+    attr_reader :name
+
+    # Initializes a new protected range object
+    # @option [String] sqref The cell range reference to protect. This can be an absolute or a relateve range however, it only applies to the current sheet.
+    # @option [String] name An optional name for the protected name.
+    def initialize(options={})
+      options.each do |o|
+        self.send("#{o[0]}=", o[1]) if self.respond_to? "#{o[0]}="
+      end
+      yield self if block_given?
+    end
+    
+    # @see sqref
+    def sqref=(v)
+      Axlsx.validate_string(v)
+      @sqref = v
+    end
+
+    # @see name
+    def name=(v)
+      Axlsx.validate_string(v)
+      @name = v
+    end
+   
+    # serializes the proteted range
+    # @param [String] str if this string object is provided we append
+    # our output to that object. Use this - it helps limit the number of
+    # objects created during serialization
+    def to_xml_string(str="")
+      attrs = self.instance_values.reject{ |key, value| value == nil }
+      str << '<protectedRange ' << attrs.map { |key, value| '' << key << '="' << value.to_s << '"' }.join(' ') << '/>'
+    end 
+  end
+end

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

@@ -0,0 +1,34 @@
+module Axlsx
+
+  # A self serializing collection of ranges that should be protected in
+  # the worksheet
+  class ProtectedRanges < SimpleTypedList
+
+    attr_reader :worksheet
+
+    def initialize(worksheet)
+      raise ArgumentError, 'You must provide a worksheet' unless worksheet.is_a?(Worksheet)
+      super ProtectedRange
+      @worksheet = worksheet
+    end
+
+    # Adds a protected range
+    # @param [Array|String] cells A string range reference or array of cells that will be protected
+    def add_range(cells)
+     sqref = if cells.is_a?(String)
+               cells
+             elsif cells.is_a?(SimpleTypedList) || cells.is_a?(Array)
+               Axlsx::cell_range(cells, false)
+             end
+     @list << ProtectedRange.new(:sqref => sqref, :name => "Range#{size}")
+     last
+    end
+
+    def to_xml_string(str = '')
+      return if empty?
+      str << '<protectedRanges>'
+      each { |range| range.to_xml_string(str) }
+      str << '</protectedRanges>' 
+    end
+  end
+end

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

@@ -5,6 +5,16 @@ module Axlsx
   # @see Worksheet#add_row
   class Row
 
+    # No support is provided for the following attributes
+    # spans
+    # thickTop
+    # thickBottom
+
+
+    # A list of serilizable attributes.
+    # @note height(ht) and customHeight are manages separately for now. Have a look at Row#height
+    SERIALIZABLE_ATTRIBUTES = [:hidden, :outlineLevel, :collapsed, :s, :customFormat, :ph]
+    
     # The worksheet this row belongs to
     # @return [Worksheet]
     attr_reader :worksheet
@@ -13,22 +23,40 @@ module Axlsx
     # @return [SimpleTypedList]
     attr_reader :cells
 
-    # The height of this row in points, if set explicitly.
+    # Row height measured in point size. There is no margin padding on row height.
     # @return [Float]
     attr_reader :height
 
-    # TODO  18.3.1.73
-    # collapsed
-    # customFormat
-    # hidden
-    # outlineLevel
-    # ph
-    # s (style)
-    # spans
-    # thickTop
-    # thickBottom
+    # Flag indicating if the outlining of row.
+    # @return [Boolean]
+    attr_reader :collapsed
+
+    # Flag indicating if the the row is hidden.
+    # @return [Boolean]
+    attr_reader :hidden
 
+    # Outlining level of the row, when outlining is on
+    # @return [Integer]
+    attr_reader :outlineLevel
 
+    # The style applied ot the row. This affects the entire row.
+    # @return [Integer]
+    attr_reader :s
+
+    # indicates that a style has been applied directly to the row via Row#s
+    # @return [Boolean]
+    attr_reader :customFormat
+
+    # indicates if the row should show phonetic
+    # @return [Boolean]
+    attr_reader :ph
+
+    # NOTE removing this from the api as it is actually incorrect. 
+    # having a method to style a row's cells is fine, but it is not an attribute on the row. 
+    # The proper attribute is ':s'
+    # attr_reader style
+    #
+    
     # Creates a new row. New Cell objects are created based on the values, types and style options.
     # A new cell is created for each item in the values array. style and types options are applied as follows:
     #   If the types option is defined and is a symbol it is applied to all the cells created.
@@ -53,6 +81,30 @@ module Axlsx
       array_to_cells(values, options)
     end
 
+    # @see Row#collapsed
+    def collapsed=(v)
+      Axlsx.validate_boolean(v)
+      @collapsed = v
+    end
+
+    # @see Row#hidden
+    def hidden=(v)
+      Axlsx.validate_boolean(v)
+      @hidden = v
+    end
+   
+    # @see Row#ph
+    def ph=(v) Axlsx.validate_boolean(v); @ph = v end
+
+    # @see Row#s
+    def s=(v) Axlsx.validate_unsigned_numeric(v); @s = v; @customFormat = true end
+
+    # @see Row#outline
+    def outlineLevel=(v)
+      Axlsx.validate_unsigned_numeric(v)
+      @outlineLevel = v
+    end
+
     # The index of this row in the worksheet
     # @return [Integer]
     def index
@@ -65,6 +117,9 @@ module Axlsx
     # @return [String]
     def to_xml_string(r_index, str = '')
       str << '<row r="' << (r_index + 1 ).to_s << '" '
+      instance_values.select { |key, value| SERIALIZABLE_ATTRIBUTES.include? key.to_sym }.each do |key, value|
+        str << key << '="' << value.to_s << '" '
+      end
       if custom_height?
         str << 'customHeight="1" ht="' << height.to_s << '">'
       else
@@ -79,7 +134,7 @@ module Axlsx
     # @return [Cell]
     def add_cell(value="", options={})
       c = Cell.new(self, value, options)
-      worksheet.send(:update_column_info, self.cells, self.cells.map(&:style))
+      worksheet.send(:update_column_info, self.cells, [])
       c
     end
 
@@ -132,6 +187,8 @@ module Axlsx
         cell_type = types.is_a?(Array)? types[index] : types
         options[:type] = cell_type if cell_type
         Cell.new(self, value, options)
+        options.delete(:style)
+        options.delete(:type)
       end
     end
   end