axlsx 1.0.12 → 1.0.13

data/lib/axlsx/drawing/bar_3D_chart.rb

@@ -0,0 +1,128 @@
+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)
+      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.send('c:bar3DChart') {
+          xml.send('c:barDir', :val => barDir)
+          xml.send('c:grouping', :val=>grouping)
+          xml.send('c:varyColors', :val=>1)
+          @series.each { |ser| ser.to_xml(xml) }
+          xml.send('c:gapWidth', :val=>@gapWidth) unless @gapWidth.nil?
+          xml.send('c:gapDepth', :val=>@gapDepth) unless @gapDepth.nil?
+          xml.send('c:shape', :val=>@shape) unless @shape.nil?
+          xml.send('c:axId', :val=>@catAxId)
+          xml.send('c:axId', :val=>@valAxId)
+          xml.send('c: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.send('c: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 = true
+      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.send('c:catAx') {
+        super(xml)
+        xml.send('c:auto', :val=>@auto)
+        xml.send('c:lblAlgn', :val=>@lblAlgn)
+        xml.send('c: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.send('c:cat') {
+        xml.send('c:strRef') {
+          xml.send('c:f', Axlsx::cell_range(@list))
+          xml.send('c:strCache') {
+            xml.send('c:ptCount', :val=>size)
+            each_with_index do |item, index|
+              v = item.is_a?(Cell) ? item.value : item
+              xml.send('c:pt', :idx=>index) {
+                xml.send('c:v', v)
+              }                          
+            end
+          }
+        }
+      }
+    end
+
+  end
+  
+end

data/lib/axlsx/drawing/chart.rb

@@ -0,0 +1,179 @@
+# -*- 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
+      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) 
+      v = Title.new(v) if v.is_a?(String) || v.is_a?(Cell)
+      DataTypeValidator.validate "#{self.class}.title", Title, v
+      @title = v
+    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.send('c:date1904', :val=>Axlsx::Workbook.date1904)
+          xml.send('c:style', :val=>style)
+          xml.send('c:chart') {
+            @title.to_xml(xml) unless @title.nil?
+            @view3D.to_xml(xml) unless @view3D.nil?
+            xml.send('c:plotArea') {
+              xml.send('c:layout')
+              yield xml if block_given?
+            }
+            if @show_legend
+              xml.send('c:legend') {
+                xml.send('c:legendPos', :val => "r")
+                xml.send('c:layout')
+              }
+            end
+          }
+        }
+      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