axlsx-alt 3.0.0

data/lib/axlsx/drawing/area_series.rb

@@ -0,0 +1,110 @@
+# encoding: UTF-8
+module Axlsx
+  # A AreaSeries 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 AreaSeries < Series
+
+    # The data for this series.
+    # @return [ValAxisData]
+    attr_reader :data
+
+    # The labels for this series.
+    # @return [CatAxisData]
+    attr_reader :labels
+
+    # The fill color for this series.
+    # Red, green, and blue is expressed as sequence of hex digits, RRGGBB. A perceptual gamma of 2.2 is used.
+    # @return [String]
+    attr_reader :color
+
+    # show markers on values
+    # @return [Boolean]
+    attr_reader :show_marker
+
+    # custom marker symbol
+    # @return [String]
+    attr_reader :marker_symbol
+
+    # line smoothing on values
+    # @return [Boolean]
+    attr_reader :smooth
+
+    # Creates a new series
+    # @option options [Array, SimpleTypedList] data
+    # @option options [Array, SimpleTypedList] labels
+    # @param [Chart] chart
+    def initialize(chart, options={})
+      @show_marker = false
+      @marker_symbol = options[:marker_symbol] ? options[:marker_symbol] : :default
+      @smooth = false
+      @labels, @data = nil, nil
+      super(chart, options)
+      @labels = AxDataSource.new(:data => options[:labels]) unless options[:labels].nil?
+      @data = NumDataSource.new(options) unless options[:data].nil?
+    end
+
+    # @see color
+    def color=(v)
+      @color = v
+    end
+
+    # @see show_marker
+    def show_marker=(v)
+      Axlsx::validate_boolean(v)
+      @show_marker = v
+    end
+
+    # @see marker_symbol
+    def marker_symbol=(v)
+      Axlsx::validate_marker_symbol(v)
+      @marker_symbol = v
+    end
+
+    # @see smooth
+    def smooth=(v)
+      Axlsx::validate_boolean(v)
+      @smooth = v
+    end
+
+    # Serializes the object
+    # @param [String] str
+    # @return [String]
+    def to_xml_string(str = '')
+      super(str) do
+        if color
+          str << '<c:spPr><a:solidFill>'
+          str << ('<a:srgbClr val="' << color << '"/>')
+          str << '</a:solidFill>'
+          str << '<a:ln w="28800">'
+          str << '<a:solidFill>'
+          str << ('<a:srgbClr val="' << color << '"/>')
+          str << '</a:solidFill>'
+          str << '</a:ln>'
+          str << '<a:round/>'
+          str << '</c:spPr>'
+        end
+
+        if !@show_marker
+          str << '<c:marker><c:symbol val="none"/></c:marker>'
+        elsif @marker_symbol != :default
+          str << '<c:marker><c:symbol val="' + @marker_symbol.to_s + '"/></c:marker>'
+        end
+
+        @labels.to_xml_string(str) unless @labels.nil?
+        @data.to_xml_string(str) unless @data.nil?
+        str << ('<c:smooth val="' << ((smooth) ? '1' : '0') << '"/>')
+      end
+    end
+
+    private
+
+    # assigns the data for this series
+    def data=(v) DataTypeValidator.validate "Series.data", [NumDataSource], v; @data = v; end
+
+    # assigns the labels for this series
+    def labels=(v) DataTypeValidator.validate "Series.labels", [AxDataSource], v; @labels = v; end
+
+  end
+end

data/lib/axlsx/drawing/ax_data_source.rb

@@ -0,0 +1,26 @@
+module Axlsx
+
+  # An axis data source that can contain referenced or literal strings or numbers
+  # @note only string data types are supported - mainly because we have not implemented a chart type that requires a numerical axis value
+  class AxDataSource < NumDataSource
+
+    # creates a new NumDataSource object
+    # @option options [Array] data An array of Cells or Numeric objects
+    # @option options [Symbol] tag_name see tag_name
+    def initialize(options={})
+      @tag_name = :cat
+      @data_type = StrData
+      @ref_tag_name = :strRef
+      super(options)
+    end
+
+    # allowed element tag names for serialization
+    # @return [Array]
+    def self.allowed_tag_names
+      [:xVal, :cat]
+    end
+
+  end
+
+end
+

data/lib/axlsx/drawing/axes.rb

@@ -0,0 +1,61 @@
+module Axlsx
+  
+  # The Axes class creates and manages axis information and
+  # serialization for charts.
+  class Axes
+
+    # @param [Hash] options options used to generate axis each key
+    # should be an axis name like :val_axis and its value should be the
+    # class of the axis type to construct. The :cat_axis, if there is one,
+    # must come first (we assume a Ruby 1.9+ Hash or an OrderedHash).
+    def initialize(options={})
+      raise(ArgumentError, "CatAxis must come first") if options.keys.include?(:cat_axis) && options.keys.first != :cat_axis
+      options.each do |name, axis_class|
+        add_axis(name, axis_class)
+      end
+    end
+
+    # [] provides assiciative access to a specic axis store in an axes
+    # instance. 
+    # @return [Axis]
+    def [](name)
+      axes.assoc(name)[1]
+    end
+
+    # Serializes the object
+    # @param [String] str
+    # @param [Hash] options
+    # @option options ids
+    # If the ids option is specified only the axis identifier is
+    # serialized. Otherwise, each axis is serialized in full. 
+    def to_xml_string(str = '', options = {})
+      if options[:ids]
+        # CatAxis must come first in the XML (for Microsoft Excel at least)
+        sorted = axes.sort_by { |name, axis| axis.kind_of?(CatAxis) ? 0 : 1 }
+        sorted.each { |axis| str << ('<c:axId val="' << axis[1].id.to_s << '"/>') }        
+      else
+        axes.each { |axis| axis[1].to_xml_string(str) }
+      end
+    end
+
+    # Adds an axis to the collection
+    # @param [Symbol] name The name of the axis
+    # @param [Axis] axis_class The axis class to generate
+    def add_axis(name, axis_class)
+      axis = axis_class.new
+      set_cross_axis(axis)
+      axes << [name, axis]
+    end
+
+    private
+
+    def axes
+      @axes ||= []
+    end
+
+    def set_cross_axis(axis)
+      axes.first[1].cross_axis = axis if axes.size == 1
+      axis.cross_axis = axes.first[1] unless axes.empty?
+    end
+  end
+end

data/lib/axlsx/drawing/axis.rb

@@ -0,0 +1,190 @@
+# encoding: UTF-8
+module Axlsx
+
+  # the access class defines common properties and values for a chart axis.
+  class Axis
+
+    include Axlsx::OptionsParser
+
+    # Creates an Axis object
+    # @option options [Axis] cross_axis the perpendicular axis
+    # @option options [Symbol] ax_pos
+    # @option options [Symbol] crosses
+    # @option options [Symbol] tick_lbl_pos
+    # @raise [ArgumentError] If axi_id or cross_ax are not unsigned integers
+    def initialize(options={})
+      @id = rand(8 ** 8)
+      @format_code = "General"
+      @delete = @label_rotation = 0
+      @scaling = Scaling.new(:orientation=>:minMax)
+      @title = @color = nil
+      self.ax_pos = :b
+      self.tick_lbl_pos = :nextTo
+      self.format_code = "General"
+      self.crosses = :autoZero
+      self.gridlines = true
+      parse_options options
+    end
+
+    # the fill color to use in the axis shape properties. This should be a 6 character long hex string
+    # e.g. FF0000 for red
+    # @return [String]
+    attr_reader :color
+
+    # the id of the axis.
+    # @return [Integer]
+    attr_reader :id
+    alias :axID :id
+
+    # The perpendicular axis
+    # @return [Integer]
+    attr_reader :cross_axis
+    alias :crossAx :cross_axis
+
+    # 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 :ax_pos
+    alias :axPos :ax_pos
+
+    # the position of the tick labels
+    # must be one of [:nextTo, :high, :low]
+    # @return [Symbol]
+    attr_reader :tick_lbl_pos
+    alias :tickLblPos :tick_lbl_pos
+
+    # 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
+
+    # specifies how the degree of label rotation
+    # @return [Integer]
+    attr_reader :label_rotation
+
+    # specifies if gridlines should be shown in the chart
+    # @return [Boolean]
+    attr_reader :gridlines
+
+    # specifies if gridlines should be shown in the chart
+    # @return [Boolean]
+    attr_reader :delete
+
+    # the title for the axis. This can be a cell or a fixed string.
+    attr_reader :title
+
+    # The color for this axis. This value is used when rendering the axis line in the chart. 
+    # colors should be in 6 character rbg format
+    # @return [String] the rbg color assinged.
+    # @see color
+    def color=(color_rgb)
+      @color = color_rgb
+    end
+    
+    # The crossing axis for this axis
+    # @param [Axis] axis
+    def cross_axis=(axis)
+       DataTypeValidator.validate "#{self.class}.cross_axis", [Axis], axis
+       @cross_axis = axis
+    end
+
+    # The position of the axis
+    # must be one of [:l, :r, :t, :b]
+    def ax_pos=(v) RestrictionValidator.validate "#{self.class}.ax_pos", [:l, :r, :b, :t], v; @ax_pos = v; end
+    alias :axPos= :ax_pos=
+
+    # the position of the tick labels
+    # must be one of [:nextTo, :high, :low1]
+    def tick_lbl_pos=(v) RestrictionValidator.validate "#{self.class}.tick_lbl_pos", [:nextTo, :high, :low, :none], v; @tick_lbl_pos = v; end
+    alias :tickLblPos= :tick_lbl_pos=
+
+    # The number format format code for this axis
+    # default :General
+    def format_code=(v) Axlsx::validate_string(v); @format_code = v; end
+
+    # Specify if gridlines should be shown for this axis
+    # default true
+    def gridlines=(v) Axlsx::validate_boolean(v); @gridlines = v; end
+
+    # Specify if axis should be removed from the chart
+    # default false
+    def delete=(v) Axlsx::validate_boolean(v); @delete = 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
+
+    # Specify the degree of label rotation to apply to labels
+    # default true
+    def label_rotation=(v)
+      Axlsx::validate_int(v)
+      adjusted = v.to_i * 60000
+      Axlsx::validate_angle(adjusted)
+      @label_rotation = adjusted
+    end
+
+    # The title object for the chart.
+    # @param [String, Cell] v
+    # @return [Title]
+    def title=(v)
+      DataTypeValidator.validate "#{self.class}.title", [String, Cell], v
+      @title ||= Title.new
+      if v.is_a?(String)
+        @title.text = v
+      elsif v.is_a?(Cell)
+        @title.cell = v
+      end
+    end
+
+    # Serializes the object
+    # @param [String] str
+    # @return [String]
+    def to_xml_string(str = '')
+      str << ('<c:axId val="' << @id.to_s << '"/>')
+      @scaling.to_xml_string str
+      str << ('<c:delete val="' << @delete.to_s << '"/>')
+      str << ('<c:axPos val="' << @ax_pos.to_s << '"/>')
+      str << '<c:majorGridlines>'
+      # TODO shape properties need to be extracted into a class
+      if gridlines == false
+        str << '<c:spPr>'
+        str << '<a:ln>'
+        str << '<a:noFill/>'
+        str << '</a:ln>'
+        str << '</c:spPr>'
+      end
+      str << '</c:majorGridlines>'
+      @title.to_xml_string(str) unless @title == nil
+      # Need to set sourceLinked to 0 if we're setting a format code on this row
+      # otherwise it will never take, as it will always prefer the 'General' formatting
+      # of the cells themselves
+      str << ('<c:numFmt formatCode="' << @format_code << '" sourceLinked="' << (@format_code.eql?('General') ? '1' : '0') << '"/>')
+      str << '<c:majorTickMark val="none"/>'
+      str << '<c:minorTickMark val="none"/>'
+      str << ('<c:tickLblPos val="' << @tick_lbl_pos.to_s << '"/>')
+      # TODO - this is also being used for series colors
+      # time to extract this into a class spPr - Shape Properties
+      if @color
+        str << '<c:spPr><a:ln><a:solidFill>'
+        str << ('<a:srgbClr val="' << @color << '"/>')
+        str << '</a:solidFill></a:ln></c:spPr>'
+      end
+      # some potential value in implementing this in full. Very detailed!
+      str << ('<c:txPr><a:bodyPr rot="' << @label_rotation.to_s << '"/><a:lstStyle/><a:p><a:pPr><a:defRPr/></a:pPr><a:endParaRPr/></a:p></c:txPr>')
+      str << ('<c:crossAx val="' << @cross_axis.id.to_s << '"/>')
+      str << ('<c:crosses val="' << @crosses.to_s << '"/>')
+    end
+
+  end
+
+end

data/lib/axlsx/drawing/bar_3D_chart.rb

@@ -0,0 +1,151 @@
+# encoding: UTF-8
+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]
+    def cat_axis
+      axes[:cat_axis]
+    end
+    alias :catAxis :cat_axis
+
+    # the value axis
+    # @return [ValAxis]
+    def val_axis
+      axes[:val_axis]
+    end
+    alias :valAxis :val_axis
+
+    # The direction of the bars in the chart
+    # must be one of [:bar, :col]
+    # @return [Symbol]
+    def bar_dir
+      @bar_dir ||= :bar
+    end
+    alias :barDir :bar_dir
+
+    # space between bar or column clusters, as a percentage of the bar or column width.
+    # @return [String]
+    attr_reader :gap_depth
+    alias :gapDepth :gap_depth
+
+    # space between bar or column clusters, as a percentage of the bar or column width.
+    # @return [String]
+    def gap_width
+      @gap_width ||= 150
+    end
+    alias :gapWidth :gap_width
+    
+    #grouping for a column, line, or area chart.
+    # must be one of  [:percentStacked, :clustered, :standard, :stacked]
+    # @return [Symbol]
+    def grouping
+      @grouping ||= :clustered
+    end
+
+    # The shabe of the bars or columns
+    # must be one of  [:cone, :coneToMax, :box, :cylinder, :pyramid, :pyramidToMax]
+    # @return [Symbol]
+    def shape
+      @shape ||= :box
+    end
+
+    # 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] bar_dir
+    # @option options [Symbol] grouping
+    # @option options [String] gap_width
+    # @option options [String] gap_depth
+    # @option options [Symbol] shape
+    # @option options [Integer] rot_x
+    # @option options [String] h_percent
+    # @option options [Integer] rot_y
+    # @option options [String] depth_percent
+    # @option options [Boolean] r_ang_ax
+    # @option options [Integer] perspective
+    # @see Chart
+    # @see View3D
+    def initialize(frame, options={})
+      @vary_colors = true
+      @gap_width, @gap_depth, @shape = nil, nil, nil
+      super(frame, options)
+      @series_type = BarSeries
+      @view_3D = View3D.new({:r_ang_ax=>1}.merge(options))
+      @d_lbls = nil
+    end
+
+    # The direction of the bars in the chart
+    # must be one of [:bar, :col]
+    def bar_dir=(v)
+      RestrictionValidator.validate "Bar3DChart.bar_dir", [:bar, :col], v
+      @bar_dir = v
+    end
+    alias :barDir= :bar_dir=
+
+    #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 gap_width=(v)
+      RegexValidator.validate "Bar3DChart.gap_width", GAP_AMOUNT_PERCENT, v
+      @gap_width=(v)
+    end
+    alias :gapWidth= :gap_width=
+
+    # space between bar or column clusters, as a percentage of the bar or column width.
+    def gap_depth=(v)
+      RegexValidator.validate "Bar3DChart.gap_didth", GAP_AMOUNT_PERCENT, v
+      @gap_depth=(v)
+    end
+    alias :gapDepth= :gap_depth=
+
+    # 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 object
+    # @param [String] str
+    # @return [String]
+    def to_xml_string(str = '')
+      super(str) do
+        str << '<c:bar3DChart>'
+        str << ('<c:barDir val="' << bar_dir.to_s << '"/>')
+        str << ('<c:grouping val="' << grouping.to_s << '"/>')
+        str << ('<c:varyColors val="' << vary_colors.to_s << '"/>')
+        @series.each { |ser| ser.to_xml_string(str) }
+        @d_lbls.to_xml_string(str) if @d_lbls
+        str << ('<c:gapWidth val="' << @gap_width.to_s << '"/>') unless @gap_width.nil?
+        str << ('<c:gapDepth val="' << @gap_depth.to_s << '"/>') unless @gap_depth.nil?
+        str << ('<c:shape val="' << @shape.to_s << '"/>') unless @shape.nil?
+        axes.to_xml_string(str, :ids => true)
+        str << '</c:bar3DChart>'
+        axes.to_xml_string(str)
+      end
+    end
+
+    # A hash of axes used by this chart. Bar charts have a value and
+    # category axes specified via axes[:val_axes] and axes[:cat_axis]
+    # @return [Axes]
+    def axes
+     @axes ||= Axes.new(:cat_axis => CatAxis, :val_axis => ValAxis)
+    end
+  end
+end