axlsx 1.0.12 → 1.0.14

data/lib/axlsx/drawing/drawing.rb

@@ -0,0 +1,137 @@
+module Axlsx
+  require 'axlsx/drawing/title.rb'
+  require 'axlsx/drawing/series_title.rb'
+  require 'axlsx/drawing/series.rb'
+  require 'axlsx/drawing/pie_series.rb'
+  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/cat_axis_data.rb'
+  require 'axlsx/drawing/val_axis_data.rb'
+
+  require 'axlsx/drawing/marker.rb'
+ 
+  require 'axlsx/drawing/one_cell_anchor.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'
+
+  require 'axlsx/drawing/picture_locking.rb'
+  require 'axlsx/drawing/pic.rb'
+
+  # 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 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
+
+    # Creates a new Drawing object
+    # @param [Worksheet] worksheet The worksheet that owns this drawing
+    def initialize(worksheet)
+      DataTypeValidator.validate "Drawing.worksheet", Worksheet, worksheet
+      @worksheet = worksheet
+      @worksheet.workbook.drawings << self
+      @anchors = SimpleTypedList.new [TwoCellAnchor, OneCellAnchor]
+    end
+
+    # Adds an image to the chart
+    # @note The recommended way to manage images is to use Worksheet.add_image. Please refer to that method for documentation.
+    # @see Worksheet#add_image
+    def add_image(options={})
+      OneCellAnchor.new(self, options)
+      @anchors.last.object
+    end
+
+    # 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={})
+      TwoCellAnchor.new(self, options)
+      @anchors.last.add_chart(chart_type, options)
+    end
+
+    # An array of charts that are associated with this drawing's anchors
+    # @return [Array]
+    def charts
+      charts = @anchors.select { |a| a.object.is_a?(GraphicFrame) }
+      charts.map { |a| a.object.chart }
+    end
+
+    # An array of image objects that are associated with this drawing's anchors
+    # @return [Array]
+    def images
+      images = @anchors.select { |a| a.object.is_a?(Pic) }
+      images.map { |a| a.object }
+    end
+
+    # The index of this drawing in the owning workbooks's drawings collection.
+    # @return [Integer]
+    def index
+      @worksheet.workbook.drawings.index(self)
+    end
+
+    # The relation reference id for this drawing
+    # @return [String]
+    def rId
+      "rId#{index+1}"
+    end
+
+    # The part name for this drawing
+    # @return [String]
+    def pn
+      "#{DRAWING_PN % (index+1)}"
+    end
+
+    # The relational part name for this drawing
+    # @return [String]
+    def rels_pn
+      "#{DRAWING_RELS_PN % (index+1)}"
+    end
+
+    # The drawing's relationships.
+    # @return [Relationships]
+    def relationships
+      r = Relationships.new
+      charts.each do |chart|
+        r << Relationship.new(CHART_R, "../#{chart.pn}")
+      end
+      images.each do |image|
+        r << Relationship.new(IMAGE_R, "../#{image.pn}")
+      end
+      r
+    end
+
+    # Serializes the drawing
+    # @return [String]
+    def to_xml
+      builder = Nokogiri::XML::Builder.new(:encoding => ENCODING) do |xml|
+        xml.send('xdr:wsDr', :'xmlns:xdr'=>XML_NS_XDR, :'xmlns:a'=>XML_NS_A, :'xmlns:c'=>XML_NS_C) {
+          anchors.each {|anchor| anchor.to_xml(xml) }
+        }        
+      end
+      builder.to_xml
+    end
+  end
+end

data/lib/axlsx/drawing/graphic_frame.rb

@@ -0,0 +1,52 @@
+module Axlsx
+  # A graphic frame defines a container for a chart object
+  # @note The recommended way to manage charts is Worksheet#add_chart
+  # @see Worksheet#add_chart
+  class GraphicFrame
+
+    # A reference to the chart object associated with this frame
+    # @return [Chart]
+    attr_reader :chart
+
+    # A anchor that holds this frame
+    # @return [TwoCellAnchor]
+    attr_reader :anchor
+
+    # Creates a new GraphicFrame object
+    # @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
+
+    # The relationship id for this graphic
+    # @return [String]
+    def rId 
+      "rId#{@anchor.index+1}"
+    end
+
+    # Serializes the graphic frame
+    # @param [Nokogiri::XML::Builder] xml The document builder instance this objects xml will be added to.
+    # @return [String]
+    def to_xml(xml)
+      xml.graphicFrame {        
+        xml.nvGraphicFramePr {
+          xml.cNvPr :id=>2, :name=>chart.title
+          xml.cNvGraphicFramePr                
+        }
+        xml.xfrm {
+          xml[:a].off(:x=>0, :y=>0)
+          xml[:a].ext :cx=>0, :cy=>0
+        }
+        xml[:a].graphic {
+          xml.graphicData(:uri=>XML_NS_C) {
+            xml[:c].chart :'xmlns:c'=>XML_NS_C, :'xmlns:r'=>XML_NS_R, :'r:id'=>rId
+          }
+        }
+      }
+      
+    end
+  end
+end

data/lib/axlsx/drawing/line_3D_chart.rb

@@ -0,0 +1,114 @@
+module Axlsx
+
+  # The Line3DChart is a three dimentional line chart (who would have guessed?) that you can add to your worksheet.
+  # @example Creating a chart
+  #   # This example creates a line in a single sheet.
+  #   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::Line3DChart, :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"]
+  #
+  # @see Worksheet#add_chart
+  # @see Worksheet#add_row
+  # @see Chart#add_series
+  # @see Series
+  # @see Package#serialize
+  class Line3DChart < Chart
+
+    # the category axis
+    # @return [CatAxis]
+    attr_reader :catAxis
+
+    # the category axis
+    # @return [ValAxis]
+    attr_reader :valAxis
+
+    # the category axis
+    # @return [Axis]
+    attr_reader :serAxis
+
+    # space between bar or column clusters, as a percentage of the bar or column width.
+    # @return [String]
+    attr_reader :gapDepth
+
+    #grouping for a column, line, or area chart.
+    # must be one of  [:percentStacked, :clustered, :standard, :stacked]
+    # @return [Symbol]
+    attr_reader :grouping
+
+    # 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 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={})
+      @gapDepth = nil
+      @grouping = :standard
+      @catAxId = rand(8 ** 8)
+      @valAxId = rand(8 ** 8)
+      @serAxId = rand(8 ** 8)
+      @catAxis = CatAxis.new(@catAxId, @valAxId)
+      @valAxis = ValAxis.new(@valAxId, @catAxId)
+      @serAxis = SerAxis.new(@serAxId, @valAxId)
+      super(frame, options)      
+      @series_type = LineSeries
+      @view3D = View3D.new({:perspective=>30}.merge(options))
+    end
+
+    # @see grouping
+    def grouping=(v)
+      RestrictionValidator.validate "Bar3DChart.grouping", [:percentStacked, :standard, :stacked], v
+      @grouping = v
+    end
+
+    # @see gapDepth
+    def gapDepth=(v)
+      RegexValidator.validate "Bar3DChart.gapWidth", GAP_AMOUNT_PERCENT, v
+      @gapDepth=(v)
+    end
+
+    # Serializes the bar chart
+    # @return [String]
+    def to_xml
+      super() do |xml|
+        xml.line3DChart {
+          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.gapDepth :val=>@gapDepth unless @gapDepth.nil?
+          xml.axId :val=>@catAxId
+          xml.axId :val=>@valAxId
+          xml.axId :val=>@serAxId
+        }
+        @catAxis.to_xml(xml)
+        @valAxis.to_xml(xml)
+        @serAxis.to_xml(xml)
+      end
+    end    
+  end  
+end

data/lib/axlsx/drawing/line_series.rb

@@ -0,0 +1,46 @@
+module Axlsx
+  # A LineSeries defines the title, data and labels for line charts
+  # @note The recommended way to manage series is to use Chart#add_series
+  # @see Worksheet#add_chart
+  # @see Chart#add_series
+  class LineSeries < Series
+  
+    # The data for this series. 
+    # @return [ValAxisData]
+    attr_reader :data
+
+    # The labels for this series.
+    # @return [CatAxisData]
+    attr_reader :labels
+
+    # Creates a new series
+    # @option options [Array, SimpleTypedList] data
+    # @option options [Array, SimpleTypedList] labels
+    # @param [Chart] chart
+    def initialize(chart, options={})
+      @labels, @data = nil, nil
+      super(chart, options)
+      @labels = CatAxisData.new(options[:labels]) unless options[:labels].nil?
+      @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]
+    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?
+      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/marker.rb

@@ -0,0 +1,61 @@
+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_reader :col
+
+    # The offset distance from this marker's column
+    # @return [Integer]
+    attr_reader :colOff
+
+    # The row this marker anchors to
+    # @return [Integer]
+    attr_reader :row
+
+    # The offset distance from this marker's row
+    # @return [Integer]
+    attr_reader :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
+    
+    # @see col
+    def col=(v) Axlsx::validate_unsigned_int v; @col = v end
+    # @see colOff
+    def colOff=(v) Axlsx::validate_int v; @colOff = v end
+    # @see row
+    def row=(v) Axlsx::validate_unsigned_int v; @row = v end
+    # @see rowOff
+    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(k.to_sym, self.send(k))
+      end      
+    end
+  end
+
+end

data/lib/axlsx/drawing/one_cell_anchor.rb

@@ -0,0 +1,89 @@
+module Axlsx
+  # This class details a single cell anchor for drawings.
+  # @note The recommended way to manage drawings, images and charts is Worksheet#add_chart or Worksheet#add_image.
+  # @see Worksheet#add_chart
+  # @see Worksheet#add_image
+  class OneCellAnchor
+
+    # A marker that defines the from cell anchor. The default from column and row are 0 and 0 respectively
+    # @return [Marker]
+    attr_reader :from
+
+    # The object this anchor hosts
+    # @return [Pic]
+    attr_reader :object
+
+    # The drawing that holds this anchor
+    # @return [Drawing]
+    attr_reader :drawing
+
+    # the width of the graphic object in pixels.
+    # this is converted to EMU at a 92 ppi resolution
+    # @return [Integer]
+    attr_reader :width
+
+    # the height of the graphic object in pixels
+    # this is converted to EMU at a 92 ppi resolution
+    # @return [Integer]
+    attr_reader :height
+
+
+    # Creates a new OneCellAnchor object and an Pic associated with it.
+    # @param [Drawing] drawing
+    # @option options [Array] start_at the col, row to start at
+    # @option options [Integer] width
+    # @option options [Integer] height    
+    # @option options [String] image_src the file location of the image you will render
+    # @option options [String] name the name attribute for the rendered image
+    # @option options [String] descr the description of the image rendered    
+    def initialize(drawing, options={})
+      @drawing = drawing
+      @width = 0
+      @height = 0
+      drawing.anchors << self      
+      @from = Marker.new
+      options.each do |o|
+        self.send("#{o[0]}=", o[1]) if self.respond_to? "#{o[0]}="
+      end
+      @object = Pic.new(self, options)
+    end
+
+    # @see height
+    def height=(v) Axlsx::validate_unsigned_int(v); @height = v; end
+
+    # @see width
+    def width=(v) Axlsx::validate_unsigned_int(v); @width = v; end
+
+    # The index of this anchor in the drawing
+    # @return [Integer]
+    def index
+      @drawing.anchors.index(self)
+    end
+
+    # Serializes the anchor
+    # @param [Nokogiri::XML::Builder] xml The document builder instance this objects xml will be added to.
+    # @return [String]
+    def to_xml(xml)
+      xml[:xdr].oneCellAnchor {
+        xml.from {
+          from.to_xml(xml)
+        }
+        xml.ext ext
+        @object.to_xml(xml)
+        xml.clientData
+      }
+    end    
+
+    private
+
+    # converts the pixel width and height to EMU units and returns a hash of 
+    # !{:cx=>[Integer], :cy=>[Integer]
+    # @return [Hash]
+    def ext
+      cy = @height * 914400 / 96
+      cx = @width * 914400 / 96
+      {:cy=>cy, :cx=>cx}
+    end
+
+  end
+end

data/lib/axlsx/drawing/pic.rb

@@ -0,0 +1,153 @@
+# -*- coding: utf-8 -*-
+module Axlsx
+  # a Pic object represents an image in your worksheet
+  # Worksheet#add_image is the recommended way to manage images in your sheets
+  # @see Worksheet#add_image
+  class Pic
+
+    # allowed file extenstions
+    ALLOWED_EXTENSIONS = ['gif', 'jpeg', 'png', 'jpg']
+
+    # The name to use for this picture
+    # @return [String]
+    attr_reader :name
+
+
+    # A description of the picture
+    # @return [String]
+    attr_reader :descr
+
+    # The path to the image you want to include
+    # Only local images are supported at this time and only jpg support
+    # @return [String]
+    attr_reader :image_src
+
+    # The anchor for this image
+    # @return [OneCellAnchor]
+    attr_reader :anchor
+
+    # The picture locking attributes for this picture
+    attr_reader :picture_locking
+   
+    # Creates a new Pic(ture) object
+    # @param [Anchor] anchor the anchor that holds this image
+    # @option options [String] name
+    # @option options [String] descr
+    # @option options [String] image_src
+    # @option options [Array] start_at
+    # @option options [Intger] width
+    # @option options [Intger] height
+    def initialize(anchor, options={})
+      @anchor = anchor
+      @anchor.drawing.worksheet.workbook.images << self
+      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]
+      yield self if block_given?
+      @picture_locking = PictureLocking.new(options)
+    end
+    
+    def image_src=(v) 
+      Axlsx::validate_string(v)
+      RestrictionValidator.validate 'Pic.image_src', ALLOWED_EXTENSIONS, File.extname(v).delete('.')
+      raise ArgumentError, "File does not exist" unless File.exist?(v)
+      @image_src = v
+    end
+
+    # @see name
+    def name=(v) Axlsx::validate_string(v); @name = v; end
+
+    # @see descr
+    def descr=(v) Axlsx::validate_string(v); @descr = v; end
+
+
+    # The file name of image_src without any path information
+    # @return [String]
+    def file_name
+      File.basename(image_src) unless image_src.nil?
+    end    
+    
+    # returns the extension of image_src without the preceeding '.'
+    # @return [String]
+    def extname
+      File.extname(image_src).delete('.') unless image_src.nil?
+    end
+
+    # The index of this image in the workbooks images collections
+    # @return [Index]
+    def index
+      @anchor.drawing.worksheet.workbook.images.index(self)
+    end
+
+    # The part name for this image used in serialization and relationship building
+    # @return [String]
+    def pn
+      "#{IMAGE_PN % [(index+1), extname]}"
+    end
+
+    # providing access to the anchor's width attribute
+    # @param [Integer] v
+    # @see OneCellAnchor.width
+    def width
+      @anchor.width
+    end
+
+    # @see width
+    def width=(v)
+      @anchor.width = v
+    end
+    
+    # providing access to update the anchor's height attribute
+    # @param [Integer] v
+    # @see OneCellAnchor.width
+    def height
+      @anchor.height
+    end
+
+    # @see height
+    def height=(v)
+      @anchor.height = v
+    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)
+      @anchor.from.col = x
+      @anchor.from.row = y
+    end
+
+    # Serializes the picture
+    # @param [Nokogiri::XML::Builder] xml The document builder instance this objects xml will be added to.
+    # @return [String]
+    def to_xml(xml)
+      xml.pic {
+        xml.nvPicPr {
+          xml.cNvPr :id=>"2", :name=>name, :descr=>descr
+          xml.cNvPicPr {
+            picture_locking.to_xml(xml)
+          }
+        }
+        xml.blipFill {
+          xml[:a].blip :'xmlns:r' => XML_NS_R, :'r:embed'=>"rId1"
+          xml[:a].stretch {
+            xml.fillRect
+          }
+        }
+        xml.spPr {
+          xml[:a].xfrm {
+            xml.off :x=>0, :y=>0
+            xml.ext :cx=>2336800, :cy=>2161540
+          }
+          xml[:a].prstGeom(:prst=>:rect) {
+            xml.avLst
+          }
+        }
+      }
+    end
+  end
+end