axlsx 1.0.12 → 1.0.14

data/lib/axlsx/drawing/axis.rb

@@ -0,0 +1,93 @@
+module Axlsx
+ # the access class defines common properties and values for a chart axis.
+  class Axis
+
+    # the id of the axis. 
+    # @return [Integer]
+    attr_reader :axId
+
+    # The perpendicular axis
+    # @return [Integer]
+    attr_reader :crossAx
+
+    # The scaling of the axis
+    # @see Scaling
+    # @return [Scaling]
+    attr_reader :scaling
+    
+    # The position of the axis
+    # must be one of [:l, :r, :t, :b]
+    # @return [Symbol]
+    attr_reader :axPos
+
+    # the position of the tick labels
+    # must be one of [:nextTo, :high, :low]
+    # @return [Symbol]
+    attr_reader :tickLblPos
+
+    # The number format format code for this axis
+    # default :General
+    # @return [String]
+    attr_reader :format_code
+
+    # specifies how the perpendicular axis is crossed
+    # must be one of [:autoZero, :min, :max]
+    # @return [Symbol]
+    attr_reader :crosses 
+
+    # Creates an Axis object
+    # @param [Integer] axId the id of this axis
+    # @param [Integer] crossAx the id of the perpendicular axis
+    # @option options [Symbol] axPos
+    # @option options [Symbol] crosses
+    # @option options [Symbol] tickLblPos
+    # @raise [ArgumentError] If axId or crossAx are not unsigned integers
+    def initialize(axId, crossAx, options={})
+      Axlsx::validate_unsigned_int(axId)
+      Axlsx::validate_unsigned_int(crossAx)
+      @axId = axId
+      @crossAx = crossAx
+      @format_code = "General"
+      @scaling = Scaling.new(:orientation=>:minMax)      
+      self.axPos = :b
+      self.tickLblPos = :nextTo
+      self.format_code = "General"
+      self.crosses = :autoZero
+      options.each do |o|
+        self.send("#{o[0]}=", o[1]) if self.respond_to? "#{o[0]}="
+      end
+    end
+    # The position of the axis
+    # must be one of [:l, :r, :t, :b]
+    def axPos=(v) RestrictionValidator.validate "#{self.class}.axPos", [:l, :r, :b, :t], v; @axPos = v; end
+
+    # the position of the tick labels
+    # must be one of [:nextTo, :high, :low1]
+    def tickLblPos=(v) RestrictionValidator.validate "#{self.class}.tickLblPos", [:nextTo, :high, :low], v; @tickLblPos = v; end
+
+    # The number format format code for this axis
+    # default :General
+    def format_code=(v) Axlsx::validate_string(v); @format_code = v; end
+
+    # specifies how the perpendicular axis is crossed
+    # must be one of [:autoZero, :min, :max]
+    def crosses=(v) RestrictionValidator.validate "#{self.class}.crosses", [:autoZero, :min, :max], v; @crosses = v; end
+
+    # Serializes the common axis
+    # @param [Nokogiri::XML::Builder] xml The document builder instance this objects xml will be added to.
+    # @return [String]
+    def to_xml(xml)
+      xml.axId :val=>@axId
+      @scaling.to_xml(xml)
+      xml.delete :val=>0
+      xml.axPos :val=>@axPos
+      xml.majorGridlines
+      xml.numFmt :formatCode => @format_code, :sourceLinked=>"1"
+      xml.majorTickMark :val=>"none"
+      xml.minorTickMark :val=>"none"
+      xml.tickLblPos :val=>@tickLblPos
+      xml.crossAx :val=>@crossAx
+      xml.crosses :val=>@crosses
+    end    
+  end
+end

data/lib/axlsx/drawing/bar_3D_chart.rb

@@ -0,0 +1,136 @@
+module Axlsx
+
+  # The Bar3DChart is a three dimentional barchart (who would have guessed?) that you can add to your worksheet.
+  # @see Worksheet#add_chart
+  # @see Chart#add_series
+  # @see Package#serialize
+  # @see README for an example
+  class Bar3DChart < Chart
+
+    # the category axis
+    # @return [CatAxis]
+    attr_reader :catAxis
+
+    # the valueaxis
+    # @return [ValAxis]
+    attr_reader :valAxis
+
+    # The direction of the bars in the chart
+    # must be one of [:bar, :col]
+    # @return [Symbol]
+    attr_reader :barDir
+
+    # space between bar or column clusters, as a percentage of the bar or column width.
+    # @return [String]
+    attr_reader :gapDepth
+
+    # space between bar or column clusters, as a percentage of the bar or column width.
+    # @return [String]
+    attr_reader :gapWidth
+
+    #grouping for a column, line, or area chart.
+    # must be one of  [:percentStacked, :clustered, :standard, :stacked]
+    # @return [Symbol]
+    attr_reader :grouping
+
+    # The shabe of the bars or columns
+    # must be one of  [:cone, :coneToMax, :box, :cylinder, :pyramid, :pyramidToMax]
+    # @return [Symbol]
+    attr_reader :shape
+
+    # validation regex for gap amount percent
+    GAP_AMOUNT_PERCENT = /0*(([0-9])|([1-9][0-9])|([1-4][0-9][0-9])|500)%/
+    
+    # Creates a new bar chart object
+    # @param [GraphicFrame] frame The workbook that owns this chart.
+    # @option options [Cell, String] title
+    # @option options [Boolean] show_legend
+    # @option options [Symbol] barDir
+    # @option options [Symbol] grouping
+    # @option options [String] gapWidth
+    # @option options [String] gapDepth
+    # @option options [Symbol] shape
+    # @option options [Integer] rotX
+    # @option options [String] hPercent
+    # @option options [Integer] rotY
+    # @option options [String] depthPercent
+    # @option options [Boolean] rAngAx
+    # @option options [Integer] perspective
+    # @see Chart
+    # @see View3D
+    def initialize(frame, options={})
+      @barDir = :bar
+      @grouping = :clustered
+      @gapWidth, @gapDepth, @shape = nil, nil, nil
+      @catAxId = rand(8 ** 8)
+      @valAxId = rand(8 ** 8)
+      @catAxis = CatAxis.new(@catAxId, @valAxId)
+      @valAxis = ValAxis.new(@valAxId, @catAxId, :tickLblPos => :low)
+      super(frame, options)      
+      @series_type = BarSeries
+      @view3D = View3D.new({:rAngAx=>1}.merge(options))
+    end
+
+    # The direction of the bars in the chart
+    # must be one of [:bar, :col]
+    def barDir=(v) 
+      RestrictionValidator.validate "Bar3DChart.barDir", [:bar, :col], v
+      @barDir = v
+    end
+
+    #grouping for a column, line, or area chart.
+    # must be one of  [:percentStacked, :clustered, :standard, :stacked]
+    def grouping=(v)
+      RestrictionValidator.validate "Bar3DChart.grouping", [:percentStacked, :clustered, :standard, :stacked], v
+      @grouping = v
+    end
+
+    # space between bar or column clusters, as a percentage of the bar or column width.
+    def gapWidth=(v)
+      RegexValidator.validate "Bar3DChart.gapWidth", GAP_AMOUNT_PERCENT, v
+      @gapWidth=(v)
+    end
+
+    # space between bar or column clusters, as a percentage of the bar or column width.
+    def gapDepth=(v)
+      RegexValidator.validate "Bar3DChart.gapWidth", GAP_AMOUNT_PERCENT, v
+      @gapDepth=(v)
+    end
+
+    # The shabe of the bars or columns
+    # must be one of  [:cone, :coneToMax, :box, :cylinder, :pyramid, :pyramidToMax]
+    def shape=(v) 
+      RestrictionValidator.validate "Bar3DChart.shape", [:cone, :coneToMax, :box, :cylinder, :pyramid, :pyramidToMax], v
+      @shape = v
+    end
+    
+    # Serializes the bar chart
+    # @return [String]
+    def to_xml
+      super() do |xml|
+        xml.bar3DChart {
+          xml.barDir :val => barDir
+          xml.grouping :val=>grouping
+          xml.varyColors :val=>1
+          @series.each { |ser| ser.to_xml(xml) }
+          xml.dLbls {
+            xml.showLegendKey :val=>0
+            xml.showVal :val=>0
+            xml.showCatName :val=>0
+            xml.showSerName :val=>0
+            xml.showPercent :val=>0
+            xml.showBubbleSize :val=>0            
+          }
+          xml.gapWidth :val=>@gapWidth unless @gapWidth.nil?
+          xml.gapDepth :val=>@gapDepth unless @gapDepth.nil?
+          xml.shape :val=>@shape unless @shape.nil?
+          xml.axId :val=>@catAxId
+          xml.axId :val=>@valAxId
+          xml.axId :val=>0
+        }
+        @catAxis.to_xml(xml)
+        @valAxis.to_xml(xml)        
+      end
+    end    
+  end  
+end

data/lib/axlsx/drawing/bar_series.rb

@@ -0,0 +1,64 @@
+module Axlsx
+  # A BarSeries defines the title, data and labels for bar charts
+  # @note The recommended way to manage series is to use Chart#add_series
+  # @see Worksheet#add_chart
+  # @see Chart#add_series
+  class BarSeries < Series
+
+  
+    # The data for this series. 
+    # @return [Array, SimpleTypedList]
+    attr_reader :data
+
+    # The labels for this series.
+    # @return [Array, SimpleTypedList]
+    attr_reader :labels
+
+    # The shabe of the bars or columns
+    # must be one of  [:percentStacked, :clustered, :standard, :stacked]
+    # @return [Symbol]
+    attr_reader :shape
+
+    # Creates a new series
+    # @option options [Array, SimpleTypedList] data
+    # @option options [Array, SimpleTypedList] labels
+    # @option options [String] title
+    # @option options [String] shape
+    # @param [Chart] chart
+    def initialize(chart, options={})
+      @shape = :box
+      super(chart, options)
+      self.labels = CatAxisData.new(options[:labels]) unless options[:labels].nil?
+      self.data = ValAxisData.new(options[:data]) unless options[:data].nil?
+    end 
+
+    # The shabe of the bars or columns
+    # must be one of  [:percentStacked, :clustered, :standard, :stacked]
+    def shape=(v) 
+      RestrictionValidator.validate "BarSeries.shape", [:cone, :coneToMax, :box, :cylinder, :pyramid, :pyramidToMax], v
+      @shape = v
+    end
+
+    # Serializes the series
+    # @param [Nokogiri::XML::Builder] xml The document builder instance this objects xml will be added to.
+    # @return [String]
+    def to_xml(xml)
+      super(xml) do |xml_inner|
+        @labels.to_xml(xml_inner) unless @labels.nil?
+        @data.to_xml(xml_inner) unless @data.nil?
+        xml_inner.shape :val=>@shape
+      end      
+    end
+
+    
+    private 
+
+    # assigns the data for this series
+    def data=(v) DataTypeValidator.validate "Series.data", [SimpleTypedList], v; @data = v; end
+
+    # assigns the labels for this series
+    def labels=(v) DataTypeValidator.validate "Series.labels", [SimpleTypedList], v; @labels = v; end
+
+  end
+
+end

data/lib/axlsx/drawing/cat_axis.rb

@@ -0,0 +1,63 @@
+module Axlsx
+  #A CatAxis object defines a chart category axis
+  class CatAxis < Axis
+
+    # From the docs: This element specifies that this axis is a date or text axis based on the data that is used for the axis labels, not a specific choice.
+    # @return [Boolean]
+    attr_reader :auto
+
+    # specifies how the perpendicular axis is crossed
+    # must be one of [:ctr, :l, :r]
+    # @return [Symbol]
+    attr_reader :lblAlgn 
+
+    # The offset of the labels
+    # must be between a string between 0 and 1000
+    # @return [Integer]
+    attr_reader :lblOffset
+
+    # regex for validating label offset
+    LBL_OFFSET_REGEX = /0*(([0-9])|([1-9][0-9])|([1-9][0-9][0-9])|1000)%/
+
+    # Creates a new CatAxis object    
+    # @param [Integer] axId the id of this axis. Inherited
+    # @param [Integer] crossAx the id of the perpendicular axis. Inherited
+    # @option options [Symbol] axPos. Inherited
+    # @option options [Symbol] tickLblPos. Inherited
+    # @option options [Symbol] crosses. Inherited
+    # @option options [Boolean] auto
+    # @option options [Symbol] lblAlgn
+    # @option options [Integer] lblOffset    
+    def initialize(axId, crossAx, options={})
+      self.auto = 1
+      self.lblAlgn = :ctr
+      self.lblOffset = "100%"
+      super(axId, crossAx, options)
+    end 
+
+    # From the docs: This element specifies that this axis is a date or text axis based on the data that is used for the axis labels, not a specific choice.
+    def auto=(v) Axlsx::validate_boolean(v); @auto = v; end
+
+    # specifies how the perpendicular axis is crossed
+    # must be one of [:ctr, :l, :r]
+    def lblAlgn=(v) RestrictionValidator.validate "#{self.class}.lblAlgn", [:ctr, :l, :r], v; @lblAlgn = v; end
+
+    # The offset of the labels
+    # must be between a string between 0 and 1000
+    def lblOffset=(v) RegexValidator.validate "#{self.class}.lblOffset", LBL_OFFSET_REGEX, v; @lblOffset = v; end
+
+    # Serializes the category axis
+    # @param [Nokogiri::XML::Builder] xml The document builder instance this objects xml will be added to.
+    # @return [String]
+    def to_xml(xml)
+      xml.catAx {
+        super(xml)
+        xml.auto :val=>@auto
+        xml.lblAlgn :val=>@lblAlgn
+        xml.lblOffset :val=>@lblOffset
+      }
+    end
+  end
+  
+
+end

data/lib/axlsx/drawing/cat_axis_data.rb

@@ -0,0 +1,35 @@
+module Axlsx
+  # The CatAxisData class serializes the category axis data for a chart
+  class CatAxisData < SimpleTypedList
+
+    # Create a new CatAxisData object
+    # @param [Array, SimpleTypedList] data the data for this category axis. This can be a simple array or a simple typed list of cells.
+    def initialize(data=[])
+      super Object
+      @list.concat data if data.is_a?(Array)
+      data.each { |i| @list << i } if data.is_a?(SimpleTypedList)
+    end
+
+    # Serializes the category axis data
+    # @param [Nokogiri::XML::Builder] xml The document builder instance this objects xml will be added to.
+    # @return [String]
+    def to_xml(xml)
+      xml.cat {
+        xml.strRef {
+          xml.f Axlsx::cell_range(@list)
+          xml.strCache {
+            xml.ptCount :val=>size
+            each_with_index do |item, index|
+              v = item.is_a?(Cell) ? item.value : item
+              xml.pt(:idx=>index) {
+                xml.v v
+              }                          
+            end
+          }
+        }
+      }
+    end
+
+  end
+  
+end

data/lib/axlsx/drawing/chart.rb

@@ -0,0 +1,193 @@
+# -*- coding: utf-8 -*-
+module Axlsx
+  # A Chart is the superclass for specific charts
+  # @note Worksheet#add_chart is the recommended way to create charts for your worksheets.
+  # @see README for examples
+  class Chart
+
+
+    # The 3D view properties for the chart
+    attr_reader :view3D
+
+    # A reference to the graphic frame that owns this chart
+    # @return [GraphicFrame]
+    attr_reader :graphic_frame
+
+    # A collection of series objects that are applied to the chart
+    # @return [SimpleTypedList]
+    attr_reader :series
+
+    # The type of series to use for this chart.
+    # @return [Series]
+    attr_reader :series_type
+
+    #TODO data labels!
+    #attr_reader :dLabls
+
+    # The title object for the chart.
+    # @return [Title]
+    attr_reader :title
+
+    # The style for the chart. 
+    # see ECMA Part 1 §21.2.2.196
+    # @return [Integer]
+    attr_reader :style
+
+    # Show the legend in the chart
+    # @return [Boolean]
+    attr_reader :show_legend
+   
+    # Creates a new chart object
+    # @param [GraphicalFrame] frame The frame that holds this chart.
+    # @option options [Cell, String] title
+    # @option options [Boolean] show_legend
+    def initialize(frame, options={})
+      @style = 2
+      @graphic_frame=frame
+      @graphic_frame.anchor.drawing.worksheet.workbook.charts << self
+      @series = SimpleTypedList.new Series
+      @show_legend = true
+      @series_type = Series
+      @title = Title.new
+      options.each do |o|
+        self.send("#{o[0]}=", o[1]) if self.respond_to? "#{o[0]}="
+      end
+      start_at *options[:start_at] if options[:start_at]
+      end_at *options[:end_at] if options[:start_at]
+      yield self if block_given?
+    end
+
+    # The index of this chart in the workbooks charts collection
+    # @return [Integer]
+    def index
+      @graphic_frame.anchor.drawing.worksheet.workbook.charts.index(self)
+    end
+
+    # The part name for this chart
+    # @return [String]
+    def pn
+      "#{CHART_PN % (index+1)}"
+    end
+
+    # The title object for the chart.
+    # @param [String, Cell] v
+    # @return [Title]
+    def title=(v) 
+      DataTypeValidator.validate "#{self.class}.title", [String, Cell], v
+      if v.is_a?(String)
+        @title.text = v
+      elsif v.is_a?(Cell)
+        @title.cell = v
+      end
+    end
+    
+    # Show the legend in the chart
+    # @param [Boolean] v
+    # @return [Boolean]
+    def show_legend=(v) Axlsx::validate_boolean(v); @show_legend = v; end
+
+
+    # The style for the chart. 
+    # see ECMA Part 1 §21.2.2.196
+    # @param [Integer] v must be between 1 and 48
+    def style=(v) DataTypeValidator.validate "Chart.style", Integer, v, lambda { |arg| arg >= 1 && arg <= 48 }; @style = v; end
+
+    # backwards compatibility to allow chart.to and chart.from access to anchor markers
+    # @note This will be disconinued in version 2.0.0. Please use the end_at method
+    def to
+      @graphic_frame.anchor.to
+    end
+
+    # backwards compatibility to allow chart.to and chart.from access to anchor markers
+    # @note This will be disconinued in version 2.0.0. please use the start_at method
+    def from
+      @graphic_frame.anchor.from
+    end
+
+    # Adds a new series to the chart's series collection.
+    # @return [Series]
+    # @see Series
+    def add_series(options={})
+      @series_type.new(self, options)
+      @series.last
+    end
+
+    # Chart Serialization
+    # serializes the chart
+    def to_xml
+      builder = Nokogiri::XML::Builder.new(:encoding => ENCODING) do |xml|
+        xml.send('c:chartSpace', :'xmlns:c' => XML_NS_C, :'xmlns:a' => XML_NS_A) {
+          xml[:c].date1904 :val => Axlsx::Workbook.date1904
+          xml[:c].style :val=>style
+          xml[:c].chart {
+            @title.to_xml(xml)
+            xml.autoTitleDeleted :val=>0
+            @view3D.to_xml(xml) unless @view3D.nil?
+            
+            xml.floor { xml.thickness(:val=>0) }
+            xml.sideWall { xml.thickness(:val=>0) }
+            xml.backWall { xml.thickness(:val=>0) }
+            xml.plotArea {
+              xml.layout
+              yield xml if block_given?
+            }
+            if @show_legend
+                xml.legend {
+                xml.legendPos :val => "r"
+                xml.layout
+                xml.overlay :val => 0                  
+              }
+              end
+            xml.plotVisOnly :val => 1
+            xml.dispBlanksAs :val => :zero
+            xml.showDLblsOverMax :val => 1
+          }
+          
+        }
+      end
+      builder.to_xml
+    end
+
+    # This is a short cut method to set the start anchor position
+    # If you need finer granularity in positioning use
+    # graphic_frame.anchor.from.colOff / rowOff
+    # @param [Integer] x The column
+    # @param [Integer] y The row
+    # @return [Marker]
+    def start_at(x, y=0)
+      x, y = *parse_coord_args(x, y)
+      @graphic_frame.anchor.from.col = x
+      @graphic_frame.anchor.from.row = y
+    end
+
+    # This is a short cut method to set the end anchor position
+    # If you need finer granularity in positioning use
+    # graphic_frame.anchor.to.colOff / rowOff
+    # @param [Integer] x The column
+    # @param [Integer] y The row
+    # @return [Marker]
+    def end_at(x, y=0)
+      x, y = *parse_coord_args(x, y)
+      @graphic_frame.anchor.to.col = x
+      @graphic_frame.anchor.to.row = y
+    end
+
+    private
+
+    def parse_coord_args(x, y=0)
+      if x.is_a?(String)
+        x, y = *Axlsx::name_to_indices(x)
+      end
+      if x.is_a?(Cell)
+        x, y = *x.pos
+      end
+      if x.is_a?(Array)
+        x, y = *x
+      end
+      [x, y]
+    end
+
+    def view3D=(v) DataTypeValidator.validate "#{self.class}.view3D", View3D, v; @view3D = v; end
+
+  end
+end