axlsx 1.0.0

data/lib/axlsx/drawing/marker.rb

@@ -0,0 +1,57 @@
+module Axlsx
+  # The Marker class defines a point in the worksheet that drawing anchors attach to.
+  # @note The recommended way to manage markers is Worksheet#add_chart Markers are created for a two cell anchor based on the :start and :end options.
+  # @see Worksheet#add_chart
+  class Marker
+
+    # The column this marker anchors to
+    # @return [Integer]
+    attr_accessor :col
+
+    # The offset distance from this marker's column
+    # @return [Integer]
+    attr_accessor :colOff
+
+    # The row this marker anchors to
+    # @return [Integer]
+    attr_accessor :row
+
+    # The offset distance from this marker's row
+    # @return [Integer]
+    attr_accessor :rowOff
+
+    # Creates a new Marker object
+    # @option options [Integer] col
+    # @option options [Integer] colOff
+    # @option options [Integer] row
+    # @option options [Integer] rowOff
+    def initialize(options={})
+      @col, @colOff, @row, @rowOff = 0, 0, 0, 0
+      options.each do |o|
+        self.send("#{o[0]}=", o[1]) if self.respond_to? o[0]
+      end      
+    end
+    
+    def col=(v) Axlsx::validate_unsigned_int v; @col = v end
+    def colOff=(v) Axlsx::validate_int v; @colOff = v end
+    def row=(v) Axlsx::validate_unsigned_int v; @row = v end
+    def rowOff=(v) Axlsx::validate_int v; @rowOff = v end
+
+    # shortcut to set the column, row position for this marker
+    # @param col the column for the marker
+    # @param row the row of the marker
+    def coord(col, row)
+      self.col = col
+      self.row = row
+    end
+    # Serializes the marker
+    # @param [Nokogiri::XML::Builder] xml The document builder instance this objects xml will be added to.
+    # @return [String]
+    def to_xml(xml)
+      [:col, :colOff, :row, :rowOff].each do |k|
+        xml.send("xdr:#{k.to_s}", self.send(k))
+      end      
+    end
+  end
+
+end

data/lib/axlsx/drawing/pie_3D_chart.rb

@@ -0,0 +1,59 @@
+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
+  class Pie3DChart < Chart
+
+
+    # Creates a new pie chart object
+    # @param [Workbook] workbook The workbook that owns this chart.
+    # @option options [Cell, String] title
+    def initialize(workbook, options={})
+      super(workbook, options)
+      # this charts series type
+      @series_type = PieSeries
+      @view3D = View3D.new(:rotX => 30, :perspective => 30)
+    end
+
+    # Serializes the pie chart
+    # @return [String]
+    def to_xml
+      super() do |xml|
+        xml.send('c:pie3DChart') {
+          xml.send('c:varyColors', :val=>1)
+          @series.each { |ser| ser.to_xml(xml) }
+        }                      
+      end
+    end
+  end
+end

data/lib/axlsx/drawing/pie_series.rb

@@ -0,0 +1,88 @@
+module Axlsx
+  # A PieSeries defines the title, data and labels for pie charts
+  # @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]
+    attr_reader :data
+
+
+    # The labels for this series.
+    # @return [Array, SimpleTypedList]
+    attr_reader :labels
+
+
+    # The explosion for this series
+    # @return [Array, SimpleTypedList]
+    attr_accessor :explosion
+
+    # Creates a new series
+    # @option options [Array, SimpleTypedList] data
+    # @option options [Array, SimpleTypedList] labels
+    # @option options [String] title
+    # @option options [Integer] explosion
+    # @param [Chart] chart
+    def initialize(chart, options={})
+      super(chart, options)
+      self.data = options[:data]  || []
+      self.labels = options[:labels] || []
+    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
+            }                        
+          }
+        }
+        
+      end      
+    end
+    
+    
+    private 
+
+
+    # assigns the data for this series
+    def data=(v) DataTypeValidator.validate "Series.data", [Array, SimpleTypedList], v; @data = v; end
+
+    # assigns the labels for this series
+    def labels=(v) DataTypeValidator.validate "Series.labels", [Array, SimpleTypedList], v; @labels = v; end
+
+  end
+
+end

data/lib/axlsx/drawing/scaling.rb

@@ -0,0 +1,53 @@
+module Axlsx
+  # The Scaling class defines axis scaling
+  class Scaling
+
+    # logarithmic base for a logarithmic axis.
+    # must be between 2 and 1000
+    # @return [Integer]
+    attr_accessor :logBase
+
+    # the orientation of the axis
+    # must be one of [:minMax, :maxMin]
+    # @return [Symbol]
+    attr_accessor :orientation
+
+    # the maximum scaling
+    # @return [Float]
+    attr_accessor :max
+
+    # the minimu scaling
+    # @return [Float]
+    attr_accessor :min
+
+    # creates a new Scaling object
+    # @option options [Integer, Fixnum] logBase
+    # @option options [Symbol] orientation
+    # @option options [Float] max
+    # @option options [Float] min
+    def initialize(options={})
+      @orientation = :minMax
+      options.each do |o|
+        self.send("#{o[0]}=", o[1]) if self.respond_to? "#{o[0]}="
+      end
+    end
+    
+    def logBase=(v) DataTypeValidator.validate "Scaling.logBase", [Integer, Fixnum], v, lambda { |v| v >= 2 && v <= 1000}; @logBase = v; end
+    def orientation=(v) RestrictionValidator.validate "Scaling.orientation", [:minMax, :maxMin], v; @orientation = v; end
+    def max=(v) DataTypeValidator.validate "Scaling.max", Float, v; @max = v; end
+    def min=(v) DataTypeValidator.validate "Scaling.min", Float, v; @min = v; end
+
+    # Serializes the axId
+    # @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:scaling') {
+        xml.send('c:logBase', :val=> @logBase) unless @logBase.nil?
+        xml.send('c:orientation', :val=> @orientation) unless @orientation.nil?
+        xml.send('c:min', :val => @min) unless @min.nil?
+        xml.send('c:max', :val => @max) unless @max.nil?
+      }
+    end
+
+  end
+end

data/lib/axlsx/drawing/series.rb

@@ -0,0 +1,70 @@
+module Axlsx
+  # A Series defines the title, data and labels for chart data.
+  # @note The recommended way to manage series is to use Chart#add_series
+  # @see Worksheet#add_chart
+  # @see Chart#add_series
+  class Series
+
+    # The chart that owns this series
+    # @return [Chart]
+    attr_reader :chart
+
+    # The index of this series in the chart's series.
+    # @return [Integer]
+    attr_reader :index
+
+    # The order of this series in the chart's series.
+    # @return [Integer]
+    attr_accessor :order
+
+    # The title of the series
+    # @return [String]
+    attr_accessor :title
+
+    # Creates a new series
+    # @param [Chart] chart
+    # @option options [Integer] order
+    # @option options [String] title
+    def initialize(chart, options={})
+      self.chart = chart
+      @chart.series << self
+      options.each do |o|
+        self.send("#{o[0]}=", o[1]) if self.respond_to? "#{o[0]}="
+      end
+    end    
+    
+    # retrieves the series index in the chart's series collection
+    def index
+      @chart.series.index(self)
+    end
+
+    def order=(v)  Axlsx::validate_unsigned_int(v); @order = v; end
+
+    def order
+      @order || index
+    end
+
+    def title=(v)  Axlsx::validate_string(v); @title = v; end
+    
+    private 
+    
+    # assigns the chart for this series
+    def chart=(v)  DataTypeValidator.validate "Series.chart", Chart, v; @chart = 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)
+      xml.send('c:ser') {
+        xml.send('c:idx', :val=>index)
+        xml.send('c:order', :val=>order || index)
+        xml.send('c:tx') {
+          xml.send('c:v', self.title)
+        }
+        yield xml if block_given?
+      }
+    end
+
+  end
+
+end

data/lib/axlsx/drawing/title.rb

@@ -0,0 +1,69 @@
+module Axlsx
+  # A Title stores information about the title of a chart
+  class Title
+    
+    # The text to be shown. Setting this property directly with a string will remove the cell reference.
+    # @return [String]
+    attr_accessor :text
+
+    # The cell that holds the text for the title. Setting this property will automatically update the text attribute.
+    # @return [Cell]
+    attr_accessor :cell
+
+    # Creates a new Title object
+    # @param [String, Cell] title The cell or string to be used for the chart's title
+    def initialize(title="")
+      self.cell = title if title.is_a?(Cell)
+      self.text = title.to_s unless title.is_a?(Cell)
+    end
+    
+    def text=(v) 
+      DataTypeValidator.validate 'Title.text', String, v
+      @text = v
+      @cell = nil
+      v
+    end
+
+    def cell=(v)
+      DataTypeValidator.validate 'Title.text', Cell, v
+      @cell = v
+      @text = v.value.to_s      
+      v
+    end
+
+    # Not implemented at this time.
+    #def tx=(v) DataTypeValidator.validate 'Title.tx', Tx, v; @tx=v; end
+    #def layout=(v) DataTypeValidator.validate 'Title.layout', Layout, v; @layout = v; end
+    #def overlay=(v) Axlsx::validate_boolean v; @overlay=v; end
+    #def spPr=(v) DataTypeValidator.validate 'Title.spPr', SpPr, v; @spPr = v; end
+    
+    # Serializes the chart title
+    # @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:title') {
+        xml.send('c:tx') {
+          xml.send('c:strRef') {
+            xml.send('c:f', range)
+            xml.send('c:strCache') {
+              xml.send('c:ptCount', :val=>1)
+              xml.send('c:pt', :idx=>0) {
+                xml.send('c:v', @text)
+              }
+            }
+          }
+        }
+      }      
+    end
+
+    private 
+
+    # returns the excel style abslute reference for the title when title is a Cell object
+    # @return [String]
+    def range
+      return "" unless @data.is_a?(Cell)
+      "#{@data.row.worksheet.name}!#{data.row.r_abs}"
+    end
+
+  end
+end

data/lib/axlsx/drawing/two_cell_anchor.rb

@@ -0,0 +1,88 @@
+module Axlsx
+  # This class details the anchor points for drawings.
+  # @note The recommended way to manage drawings and charts is Worksheet#add_chart. Anchors are specified by the :start_at and :end_at options to that method.
+  # @see Worksheet#add_chart
+  class TwoCellAnchor
+
+    # A marker that defines the from cell anchor. The default from column and row are 0 and 0 respectively
+    # @return [Marker]
+    attr_reader :from
+    # A marker that returns the to cell anchor. The default to column and row are 5 and 10 respectively
+    # @return [Marker]
+    attr_reader :to
+
+    # The frame for your chart
+    # @return [GraphicFrame]
+    attr_reader :graphic_frame
+
+    # The drawing that holds this anchor
+    # @return [Drawing]
+    attr_reader :drawing
+
+    # The index of this anchor in the drawing
+    # @return [Integer]
+    attr_reader :index
+
+    # Creates a new TwoCellAnchor object
+    # @param [Drawing] drawing
+    # @param [Chart] chart
+    # @option options [Array] start_at
+    # @option options [Array] end_at
+    def initialize(drawing, chart_type, options)
+      @drawing = drawing
+      drawing.anchors << self      
+
+      @from, @to =  Marker.new, Marker.new(:col => 5, :row=>10)
+      @graphic_frame = GraphicFrame.new(self, chart_type, options)
+
+      self.start_at(options[:start_at][0], options[:start_at][1]) if options[:start_at].is_a?(Array)
+      self.end_at(options[:end_at][0], options[:end_at][1]) if options[:end_at].is_a?(Array)
+      # passing a reference to our start and end markers for convenience
+      # this lets us access the markers directly from the chart.
+      @graphic_frame.chart.send(:start_at=, @from)
+      @graphic_frame.chart.send(:end_at=, @to)
+    end
+
+    def index
+      @drawing.anchors.index(self)
+    end
+    
+   
+    # This is a short cut method to set the start anchor position
+    # @param [Integer] x The column
+    # @param [Integer] y The row
+    # @return [Marker]
+    def start_at(x, y)
+      @from.col = x
+      @from.row = y
+      @from
+    end
+
+    # This is a short cut method to set the end anchor position
+    # @param [Integer] x The column
+    # @param [Integer] y The row
+    # @return [Marker]
+    def end_at(x, y)
+      @to.col = x
+      @to.row = y
+      @to
+    end
+
+    # Serializes the two cell anchor
+    # @param [Nokogiri::XML::Builder] xml The document builder instance this objects xml will be added to.
+    # @return [String]
+    def to_xml(xml)
+      #build it for now, break it down later!
+      xml.send('xdr:twoCellAnchor') {
+        xml.send('xdr:from') {
+          from.to_xml(xml)
+        }
+        xml.send('xdr:to') {
+          to.to_xml(xml)
+        }
+        @graphic_frame.to_xml(xml)
+        xml.send('xdr:clientData')
+      }
+    end    
+  end
+end