axlsx 1.0.6 → 1.0.7

data/lib/axlsx/drawing/chart.rb

@@ -2,19 +2,12 @@
 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 title object for the chart.
-    # @return [Title]
-    attr_accessor :title
-
-    # The style for the chart. 
-    # see ECMA Part 1 §21.2.2.196
-    # @return [Integer]
-    attr_accessor :style
 
     # The 3D view properties for the chart
-    attr_accessor :view3D
+    attr_reader :view3D
 
     # A reference to the graphic frame that owns this chart
     # @return [GraphicFrame]
@@ -24,7 +17,7 @@ module Axlsx
     # @return [SimpleTypedList]
     attr_reader :series
 
-    # The type of series to use for this chart
+    # The type of series to use for this chart.
     # @return [Series]
     attr_reader :series_type
 
@@ -39,13 +32,14 @@ module Axlsx
     #TODO data labels!
     #attr_accessor :dLabls
 
-    # The starting marker for this chart
-    # @return [Marker]
-    attr_reader :start_at
+    # The title object for the chart.
+    # @return [Title]
+    attr_accessor :title
 
-    # The ending marker for this chart
-    # @return [Marker]
-    attr_reader :end_at
+    # The style for the chart. 
+    # see ECMA Part 1 §21.2.2.196
+    # @return [Integer]
+    attr_accessor :style
 
     # Show the legend in the chart
     # @return [Boolean]
@@ -65,6 +59,8 @@ module Axlsx
       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
 
@@ -76,8 +72,6 @@ module Axlsx
       "#{CHART_PN % (index+1)}"
     end
 
-    def view3D=(v) DataTypeValidator.validate "#{self.class}.view3D", View3D, v; @view3D = v; end
-
     def title=(v) 
       v = Title.new(v) if v.is_a?(String) || v.is_a?(Cell)
       DataTypeValidator.validate "#{self.class}.title", Title, v
@@ -88,6 +82,19 @@ module Axlsx
 
     def style=(v) DataTypeValidator.validate "Chart.style", Integer, v, lambda { |v| v >= 1 && v <= 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
@@ -122,10 +129,30 @@ module Axlsx
       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)
+      @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)
+      @graphic_frame.anchor.to.col = x
+      @graphic_frame.anchor.to.row = y
+    end
+
     private
-    
-    def start_at=(v) DataTypeValidator.validate "#{self.class}.start_at", Marker, v; @start_at = v; end
-    def end_at=(v) DataTypeValidator.validate "#{self.class}.end_at", Marker, v; @end_at = v; end
+    def view3D=(v) DataTypeValidator.validate "#{self.class}.view3D", View3D, v; @view3D = v; end
 
   end
 end

data/lib/axlsx/drawing/drawing.rb

@@ -6,35 +6,39 @@ module Axlsx
   require 'axlsx/drawing/bar_series.rb'  
   require 'axlsx/drawing/line_series.rb'  
 
+  require 'axlsx/drawing/scaling.rb'
   require 'axlsx/drawing/axis.rb'
   require 'axlsx/drawing/ser_axis.rb'
   require 'axlsx/drawing/cat_axis.rb'
   require 'axlsx/drawing/val_axis.rb'
-  require 'axlsx/drawing/view_3D.rb'
-  require 'axlsx/drawing/scaling.rb'
 
-  require 'axlsx/drawing/graphic_frame.rb'
+  require 'axlsx/drawing/cat_axis_data.rb'
+  require 'axlsx/drawing/val_axis_data.rb'
+
   require 'axlsx/drawing/marker.rb'
   require 'axlsx/drawing/two_cell_anchor.rb'
+  require 'axlsx/drawing/graphic_frame.rb'
 
+  require 'axlsx/drawing/view_3D.rb'
   require 'axlsx/drawing/chart.rb'
   require 'axlsx/drawing/pie_3D_chart.rb'
   require 'axlsx/drawing/bar_3D_chart.rb'
   require 'axlsx/drawing/line_3D_chart.rb'
 
-  # A Drawing is a canvas for charts. Each worksheet has a single drawing that can specify multiple anchors which reference charts.
-  # @note The recommended way to manage drawings is to use the Worksheet.add_chart method, specifying the chart class, start and end marker locations. 
+  # A Drawing is a canvas for charts. Each worksheet has a single drawing that manages anchors.
+  # The anchors reference the charts via graphical frames. This is not a trivial relationship so please do follow the advice in the note.
+  # @note The recommended way to manage drawings is to use the Worksheet.add_chart method.
   # @see Worksheet#add_chart
-  # @see TwoCellAnchor
   # @see Chart
+  # see README for an example of how to create a chart.
   class Drawing
 
     # The worksheet that owns the drawing
     # @return [Worksheet]
     attr_reader :worksheet
-
    
     # A collection of anchors for this drawing
+    # only TwoCellAnchors are supported in this version
     # @return [SimpleTypedList]
     attr_reader :anchors
 
@@ -72,12 +76,10 @@ module Axlsx
     end
     
 
-    # Adds a chart to the drawing. 
-    # @note The recommended way to manage charts is to use Worksheet.add_chart.
-    # @param [Chart] chart_type The class of the chart to be added to the drawing
-    # @param [Hash] options
+    # Adds a chart to the drawing.
+    # @note The recommended way to manage charts is to use Worksheet.add_chart. Please refer to that method for documentation.
+    # @see Worksheet#add_chart
     def add_chart(chart_type, options={})
-      DataTypeValidator.validate "Drawing.chart_type", Chart, chart_type 
       TwoCellAnchor.new(self, chart_type, options)
       @anchors.last.graphic_frame.chart
     end

data/lib/axlsx/drawing/graphic_frame.rb

@@ -22,6 +22,7 @@ module Axlsx
     # @param [TwoCellAnchor] anchor
     # @param [Class] chart_type
     def initialize(anchor, chart_type, options)
+      DataTypeValidator.validate "Drawing.chart_type", Chart, chart_type 
       @anchor = anchor
       @chart = chart_type.new(self, options)
     end

data/lib/axlsx/drawing/line_3D_chart.rb

@@ -46,8 +46,18 @@ module Axlsx
     
     # Creates a new line chart object
     # @param [GraphicFrame] frame The workbook that owns this chart.
+    # @option options [Cell, String] title
+    # @option options [Boolean] show_legend    
     # @option options [Symbol] grouping
     # @option options [String] gapDepth
+    # @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={})
       @grouping = :standard
       @catAxId = rand(8 ** 8)
@@ -56,9 +66,9 @@ module Axlsx
       @catAxis = CatAxis.new(@catAxId, @valAxId)
       @valAxis = ValAxis.new(@valAxId, @catAxId)
       @serAxis = SerAxis.new(@serAxId, @valAxId)
-      @view3D = View3D.new(:perspective=>30)
       super(frame, options)      
       @series_type = LineSeries
+      @view3D = View3D.new({:perspective=>30}.merge(options))
     end
 
     def grouping=(v)

data/lib/axlsx/drawing/line_series.rb

@@ -6,11 +6,11 @@ module Axlsx
   class LineSeries < Series
   
     # The data for this series. 
-    # @return [Array, SimpleTypedList]
+    # @return [ValAxisData]
     attr_reader :data
 
     # The labels for this series.
-    # @return [Array, SimpleTypedList]
+    # @return [CatAxisData]
     attr_reader :labels
 
     # Creates a new series
@@ -19,58 +19,28 @@ module Axlsx
     # @param [Chart] chart
     def initialize(chart, options={})
       super(chart, options)
-      self.data = options[:data]  || []
-      self.labels = options[:labels] || []
+      self.labels = CatAxisData.new(options[:labels]) unless options[:labels].nil?
+      self.data = ValAxisData.new(options[:data]) unless options[:data].nil?
     end 
 
     # Serializes the series
     # @param [Nokogiri::XML::Builder] xml The document builder instance this objects xml will be added to.
     # @return [String]
+    # TODO create series_cat and series_val classes as this serialization is duplicated
     def to_xml(xml)
       super(xml) do |xml|
-        if !labels.empty?
-          xml.send('c:cat') {
-            xml.send('c:strRef') {
-              xml.send('c:f', Axlsx::cell_range(labels))
-              xml.send('c:strCache') {
-                xml.send('c:ptCount', :val=>labels.size)
-                labels.each_with_index do |cell, index|
-                  v = cell.is_a?(Cell) ? cell.value : cell
-                  xml.send('c:pt', :idx=>index) {
-                    xml.send('c:v', v)
-                  }                          
-                end
-              }
-            }
-          }
-        end
-        xml.send('c:val') {
-          xml.send('c:numRef') {
-            xml.send('c:f', Axlsx::cell_range(data))
-            xml.send('c:numCache') {
-              xml.send('c:formatCode', 'General')
-              xml.send('c:ptCount', :val=>data.size)
-              data.each_with_index do |cell, index|
-                v = cell.is_a?(Cell) ? cell.value : cell
-                xml.send('c:pt', :idx=>index) {
-                  xml.send('c:v', v) 
-                }
-              end
-            }                        
-          }
-        }
+        @labels.to_xml(xml) unless @labels.nil?
+        @data.to_xml(xml) unless @data.nil?
       end      
     end
-   
-    private 
 
+    private 
 
     # assigns the data for this series
-    def data=(v) DataTypeValidator.validate "Series.data", [Array, SimpleTypedList], v; @data = v; end
+    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", [Array, SimpleTypedList], v; @labels = v; end
+    def labels=(v) DataTypeValidator.validate "Series.labels", [SimpleTypedList], v; @labels = v; end
 
   end
-
 end

data/lib/axlsx/drawing/pie_3D_chart.rb

@@ -2,47 +2,30 @@ module Axlsx
 
 
   # The Pie3DChart is a three dimentional piechart (who would have guessed?) that you can add to your worksheet.
-  # @example Creating a chart
-  #   # This example creates two charts in a single sheet.
-  #   # The first uses data directly fed to the sheet, while the second references cells withing the worksheet for data.
-  #
-  #   require "rubygems" # if that is your preferred way to manage gems!
-  #   require "axlsx"
-  #
-  #   p = Axlsx::Package.new
-  #   ws = p.workbook.add_worksheet
-  #   ws.add_row :values => ["This is a chart with no data in the sheet"]
-  #
-  #   chart = ws.add_chart(Axlsx::Pie3DChart, :start_at=> [0,1], :end_at=>[0,6], :title=>"Most Popular Pets")
-  #   chart.add_series :data => [1, 9, 10], :labels => ["Slimy Reptiles", "Fuzzy Bunnies", "Rottweiler"]
-  # 
-  #   ws.add_row :values => ["This chart uses the data below"]
-  #   title_row = ws.add_row :values => ["Least Popular Pets"]
-  #   label_row = ws.add_row :values => ["", "Dry Skinned Reptiles", "Bald Cats", "Violent Parrots"]
-  #   data_row = ws.add_row :values => ["Votes", 6, 4, 1]
-  #   
-  #   chart = ws.add_chart(Axlsx::Pie3DChart, :start_at => [0,11], :end_at =>[0,16], :title => title_row.cells.last)
-  #   chart.add_series :data => data_row.cells[(1..-1)], :labels => label_row.cells  
-  #
-  #   f = File.open('example_pie_3d_chart.xlsx', 'w')
-  #   p.serialize(f)
-  #
   # @see Worksheet#add_chart
-  # @see Worksheet#add_row
   # @see Chart#add_series
-  # @see Series
-  # @see Package#serialize
+  # @see README for an example
   class Pie3DChart < Chart
 
-
     # Creates a new pie chart object
-    # @param [Workbook] workbook The workbook that owns this chart.
+    # @param [GraphicFrame] frame The workbook that owns this chart.
     # @option options [Cell, String] title
-    def initialize(workbook, options={})
-      # this charts series type
-      super(workbook, options)
+    # @option options [Boolean] show_legend    
+    # @option options [Symbol] grouping
+    # @option options [String] gapDepth
+    # @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={})
+      super(frame, options)
       @series_type = PieSeries
-      @view3D = View3D.new(:rotX => 30, :perspective => 30)
+      @view3D = View3D.new({:rotX=>30, :perspective=>30}.merge(options))
+
     end
 
     # Serializes the pie chart

data/lib/axlsx/drawing/pie_series.rb

@@ -1,22 +1,20 @@
 module Axlsx
-  # A PieSeries defines the title, data and labels for pie charts
+  # A PieSeries defines the data and labels and explosion for pie charts series.
   # @note The recommended way to manage series is to use Chart#add_series
   # @see Worksheet#add_chart
   # @see Chart#add_series
   class PieSeries < Series
 
     # The data for this series. 
-    # @return [Array, SimpleTypedList]
+    # @return [SimpleTypedList]
     attr_reader :data
 
-
     # The labels for this series.
-    # @return [Array, SimpleTypedList]
+    # @return [SimpleTypedList]
     attr_reader :labels
 
-
     # The explosion for this series
-    # @return [Array, SimpleTypedList]
+    # @return [Integert]
     attr_accessor :explosion
 
     # Creates a new series
@@ -27,61 +25,29 @@ module Axlsx
     # @param [Chart] chart
     def initialize(chart, options={})
       super(chart, options)
-      self.data = options[:data]  || []
-      self.labels = options[:labels] || []
+      self.labels = CatAxisData.new(options[:labels]) unless options[:labels].nil?
+      self.data = ValAxisData.new(options[:data]) unless options[:data].nil?
     end 
     
     def explosion=(v) Axlsx::validate_unsigned_int(v); @explosion = 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|
         xml.send('c:explosion', :val=>@explosion) unless @explosion.nil?
-        if !labels.empty?
-          xml.send('c:cat') {
-            xml.send('c:strRef') {
-              xml.send('c:f', Axlsx::cell_range(labels))
-              xml.send('c:strCache') {
-                xml.send('c:ptCount', :val=>labels.size)
-                labels.each_with_index do |cell, index|
-                  v = cell.is_a?(Cell) ? cell.value : cell
-                  xml.send('c:pt', :idx=>index) {
-                    xml.send('c:v', v)
-                  }                          
-                end
-              }
-            }
-          }
-        end
-        xml.send('c:val') {
-          xml.send('c:numRef') {
-            xml.send('c:f', Axlsx::cell_range(data))
-            xml.send('c:numCache') {
-              xml.send('c:formatCode', 'General')
-              xml.send('c:ptCount', :val=>data.size)
-              data.each_with_index do |cell, index|
-                v = cell.is_a?(Cell) ? cell.value : cell
-                xml.send('c:pt', :idx=>index) {
-                  xml.send('c:v', v) 
-                }
-              end
-            }                        
-          }
-        }
-        
+        @labels.to_xml(xml) unless @labels.nil?
+        @data.to_xml(xml) unless @data.nil?
       end      
     end
-    
-    
     private 
 
-
     # assigns the data for this series
-    def data=(v) DataTypeValidator.validate "Series.data", [Array, SimpleTypedList], v; @data = v; end
+    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", [Array, SimpleTypedList], v; @labels = v; end
+    def labels=(v) DataTypeValidator.validate "Series.labels", [SimpleTypedList], v; @labels = v; end
 
   end